Low-level LabOne API Commands
This section describes the API commands
poll(). For continuous data acquisition, however, it is recommended to
use the Data Acquisition Module in continuous mode.
For one-shot measurement demodulator data
The simplest function to obtain demodulator data is the
command. It returns a single sample from one demodulator channel, i.e.,
it returns the sample fields (not only the demodulator outputs X and Y)
Demodulator Sample Data Structure
at one timestamp. The
getSample function returns the last sample for the specified
demodulator that the Data Server has received from the instrument.
Please note, the
getSample function only works with the demodulator
data type. It does not work with other data types such as impedance or
auxiliary input samples. For non-demodulator sample types the
recommended way to get data is via the subscribe and poll commands.
getSample command raises a
ZIAPITimeoutException if no
demodulator data is received from the device within 5 seconds. This is
the case if the requested demodulator is not enabled. As
only returns data from a single demodulator, wildcard path specification
/devn/demods/*/sample) is not supported.
For high-performance continuous or block streaming data
The subscribe and poll functions are low-level commands that allow high-speed data transfer from the instrument to the API. The idea is as follows: The user may subscribe to one or more nodes in the API session by calling subscribe for each node. This tells the Data Server to create a buffer for each subscribed node and to start accumulating the data corresponding to the node that is streamed from the instrument (or instruments, as the case may be). The user can then call poll (in the same API session) to transfer the data from the Data Server’s buffers to the API’s client code. If poll is not called within 5 seconds of either subscribing, the last call to poll or calling the sync command (more information on sync below), the Data Server clears its buffers for the subscribed nodes and starts accumulating data again. This means that for continuous transfer of data, the user must regularly poll data from the Data Server to ensure that no data is lost in between polls.
For example, the following Python code subscribes to the first and fifth demodulator sample streaming nodes on a lock-in amplifier:
The subscribe and poll commands return data from streaming nodes as sent from the instrument’s firmware at the configured data rate. The data returned is the discrete device data as sampled or calculated by the digital signal processing algorithms on the instrument. As explained in Section Streaming Nodes the data from multiple nodes may not be aligned due to different sampling rates or different streaming node sources.
When you call subscribe on a node the Data Server starts accumulating data in a dedicated buffer (for that node and the API session from which subscribe was called). When the buffer becomes full, then the data is discarded by the Data Server (poll must be called frequently enough to ensure that data is not lost in between multiple poll calls). When you call poll, then all the data that has accumulated in the Data Server’s buffers (of subscribed nodes) is returned (it is transferred to the API client) and is deleted from the Data Server’s buffers. The Data Server continues to accumulate new data sent from the device for the subscribed nodes after polling and will continue to do so until unsubscribe is called for that node. It is good practice to call unsubscribe on the nodes when you no longer want to poll data from them so that the Data Server stops accumulating data and can free up the system’s memory.
If you would like to continue recording new data for a subscribed node, but discard older data, then either poll can be called (and the returned older data simply discarded) or the sync command can be used. Sync clears the Data Server’s buffers of subscribed data but has an additional function. Additionally, the sync command blocks (it is a synchronous command) until all set commands have been sent to the device and have taken effect. E.g., if you enable the instrument’s signal output and want to ensure that you only receive data from poll after the setting has taken effect the device, then sync should be called after calling set and before calling poll.
The first two mandatory parameters to poll are the "poll duration" and the "poll timeout" parameters: Poll is also a synchronous command and will block for the specified poll duration. It will return the data accumulated during the time in seconds specified by the poll duration, and as mentioned above, it will also return the data previously accumulated data before calling poll. If you would like to poll data continuously in a loop, then a very small poll duration should be used, e.g., 0.05 seconds, so that it only blocks for this time. The poll timeout parameter typically must not be set very carefully and a value of 100 ms is sufficient. It is indeed only relevant if set to a larger value than poll duration. In this case, if no data arrives from the instrument, poll will wait for poll timeout milliseconds before returning. If data does arrive after poll duration but before the poll timeout, poll returns immediately. It is recommended to simply use a poll timeout of 100 ms (or if poll_duration is smaller, to set it equal to the poll_duration). Unfortunately, the units of poll duration and poll timeout differ: The poll duration is in seconds, whereas poll timeout is in milliseconds.
Ensure synchronization of settings before streaming data (sync)
To ensure that any settings have taken effect on the instrument before streaming data is processed, a special sync command is provided which ensures that the API blocks during the full command execution of sending down a marker to the device and receiving it again over the API. During that time all buffers are cleaned. Therefore, after the sync command the newly recorded poll data will be later in time than the previous set commands. Be aware that this command is quite expensive ~100ms.
Asking poll to always return a value for a settings node (getAsEvent)
The poll command only returns value changes for subscribed nodes; no
data will be returned for the node if it has not changed since
subscribing to it. If poll should also return the value of a node that
has not changed since subscribing, then
If no data was stored in the Data Server’s data buffer after issuing a
poll, the command will wait for the data until the timeout time. If
the buffer is empty after the timeout time passed,
poll will either
simply return an empty data structure (for example, an empty dictionary
in Python) or throw an error, depending which flags it have been
Often one of the LabOne
The following graphics illustrate how data are stored and transferred
between the Instrument, the Data Server, and the API session in the case
when the API session is the only client of the Data Server.
Figure 1 shows the
situation when the API session has subscribed to a node, but no
command is being sent.
Figure 2 corresponds to the
situation when the
poll command with a recording time of 0 is sent at
regular intervals, and illustrates the moment just before the last
poll command. Figure 3 then
illustrates the moment just after the last
pollcommand. The data are stored in the Data Server’s buffer for a certain time and dumped afterwards.
pollcommand. The Data Server holds only the data in the memory that were accumulated since the last
pollcommand. Upon a new
pollcommand, all data accumulated in the Data Server buffer are transferred to the API Session and subsequently cleared from the Data Server buffer.
In the following cases, the picture above needs to be modified:
Multiple Data Server clients: in case multiple clients (API sessions, Web Server) are subscribed to the same node, the Data Server will keep the corresponding data in the buffer until all clients have polled the data (or until it’s older than the buffer length). This means different clients will not interfere with each other.
LabVIEW, C, and .NET APIs: in these APIs (unlike in MATLAB and Python), it’s not guaranteed that a single
pollcommand leads to the transfer of all data in the Data Server buffer because the block size of transferred data is limited. Nonetheless, by calling
pollfrequently enough, a gapless stream of data can be obtained.
HF2 Series instruments: the buffer Data Server for HF2 Series instruments is defined by its memory size rather than by its length in units of time. This means that the duration for which the Data Server will store data depends on the sampling rate.