poll
Usage
>> poll [ channellist=<channel_label_list...> ] | [grouplist=<group_label_list...> ]
Security
Open.
Description
Requests an "on-demand" sample from the specified channel(s) in the instrument. If recent scheduled sample data is available for a channel, that value may also be returned to satisfy the poll request; "recent" in this context means less than one second old. If recent data is not available, a sample is explicitly acquired for the benefit of the poll. A sample acquired only for poll is never stored in memory. If the instrument is not actively logging, then all requested channels will be sampled explicitly for the poll request.
The instrument simply responds with the <sample-data>; depending on the configured settling time (or power-on settling delay) for the sensors sampled, there may be a noticeable delay before the <sample-data> appears. Refer to the channel command for details of access to the settling time of each channel.
The channel(s) to sample are specified by one of two methods; only one method may be used with any given instance of the poll command. Issuing the command without any channel specification has the same effect as specifying poll channellist=<all_channel_labels> - see below. The order in which the channel data is sent is the same as reported in response to the channel channellist command.
channellist=<channel_label_list…>, specifies the channels to poll from. Labels in the list must be separated by a pipe character ("|"), with no spaces. If the desire is to specify all the channels then just use the poll command by itself without any argument. The order in which the channel data is sent is the same as reported by the channellist.
channellist can only contain either one channel label or the ‘all’ keyword on the L3.5 platform.
grouplist=<group_label_list…>, specifies the groups of channels to be sampled. Labels in the list must be separated by a pipe character ("|"), with no spaces. Data will be returned for each group in the order they are specified. For a each group, the order in which the channel data is sent is the same as reported in response to the group <group_label> chanellist command. The specified groups must already exist; it can be one of the groups created for scheduled sampling, or it can be any one of a number of groups created by the user specifically for polling operations.
grouplist can only contain one group on the L3.5 platform.
The output format of the <sample-data> is determined by the instrument outputformat command.
The schedule label polling will be displayed if outputformat schedulelabel = on has been configured.
Once the polling operation has completed the sensors are left powered on for eight (8) seconds; this is to avoid excessive power cycling when multiple poll commands are sent within a short time. If power is of concern it is recommended to use the sleep command following a poll to perform a controlled power down of the system.
If a channel appears multiple times in the poll request, the same data reading will be returned at all the appropriate locations for that channel.
>> poll channellist=pressure_00|conductivity_00|temperature_00|pressure_00
<< 2024-10-21 11:51:58.000 12.7049270 35.3154081 18.1742890 12.7049270The reading for pressure_00 is returned at position 1 and position 4 as requested
>> group g_depth channellist
<< group g_depth channellist=pressure_00|seapressure_00|depth_00
>> group g_ctd channellist
<< group g_ctd channellist=conductivity_00|temperature_00|pressure_00
>> poll grouplist=g_depth|g_ctd
<< 2024-10-21 11:52:58.000 22.7035490 12.7035490 12.7035490 35.3154081 18.1742890 22.7049270The reading for pressure_00 is returned at position 1 and position 6 as requested from the specified groups.
Examples
The exact format of the response is determined by properties set with the outputformat command. For clarity, most examples are shown with all options turned off, but there is one example to illustrate that the word polling is always used as the <schedule_label> if that property is enabled. This allows polled samples to be identified amongst a sequence of scheduled samples being streamed in real time.
These examples use the following conditions in the outputformat.
>> instrument outputformat
<< instrument outputformat sn=off schedulelabel=off datetime=on crc=off encoding=ascii datatype=float32>> poll
<< 2024-10-21 11:50:49.000 18.1745130 12.7052970 2.69308210Poll a sample from all channels. Data will be returned in the order the channels are specified in channel list.
>> poll channellist=temperature_00
<< 2024-10-21 11:50:55.000 18.1742890Poll a single channel, temperature_00.
>> poll grouplist=g_depth
<< 2024-10-21 11:50:58.000 12.7049270 2.69273150Poll a single group of channels. The output of the readings are based on the order of channels in group g_depth channellist.
>> poll channellist=conductivity_00|temperature_00|pressure_00
<< 2024-10-21 11:51:58.000 35.3154081 18.1742890 12.7049270Poll from a list of channels. Data will be returned in the order the channels are specified in the list.
>> poll grouplist=g_depth|g_ctd
<< 2024-10-21 11:52:58.000 12.7035490 2.69152730,35.3154081 18.1742890 12.7049270Poll from a list of groups. In this example, data for g_depth will be returned, then data for g_ctd.
>> instrument outputformat
<< instrument outputformat sn=off schedulelabel=on datetime=on crc=off encoding=ascii datatype=float32
>> poll grouplist=g_depth
<< polling 2024-10-21 11:53:58.000 12.7035490 2.69152730Poll from a group when the <schedule_label> is enabled in the output formatting.