Low-level LabOne API Commands

For one-shot measurement demodulator data

The simplest function to obtain demodulator data is the getSample 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) described in 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.

The 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 getSample only returns data from a single demodulator, wildcard path specification (e.g., /devn/demods/*/sample) is not supported.

If multiple samples (even from one demodulator channel) are required, it is recommended to use either subscribe and poll (for high performance API applications) or Data Acquisition Module. Using getSample in anything other than low-speed loops data is not recommended.

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.

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.

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 provided.