How To Stream Data¶
This guide shows you how to stream data from the device at the maximal available data rate. An analogy is media streaming where, for example, video is continuously streamed through a network from a single source to one or multiple endpoints.
Subscribe¶
Available streaming data is continuously pushed from the device to the data server. However, this data is not automatically pushed to the client. If a client wants to receive the streaming data, it needs to tell the data server. This is done by subscribing to a node, which tells the Data Server to buffer every update message from device for this particular node. The client can then poll the buffered data asynchronously.
Note
The subscribe command can be used on all nodes and not just streaming nodes. Non streaming nodes are however not constantly pushed by the device but only when their value changes.
daq.subscribe("/DEV2345/DIOS/0/INPUT")
device.dios[0].input.subscribe()
checkError(ziAPISubscribe(conn, "/DEV2345/DIOS/0/INPUT"));
ziDAQ('subscribe', '/DEV2345/DIOS/0/INPUT')
daq.subscribe("/DEV2345/DIOS/0/INPUT");
Look at the tutorial VIs 203_SubscribePoll_NonStreamingNode.vi and 204_SubscribePoll_StreamingNode.vi as well as the example VIs ziExample-PollData.vi and ziExample-PollDemod.vi provided with the LabVIEW driver for LabOne to learn about node subscription.
The subscribe command is available on all APIs and takes the absolute path that should be subscribed.
Important
Unless unsubscribed the data server will buffer all update messages for the node. It is therefore good practice to unsubscribe from a node if the data is no longer needed.
Info
To optimize the bandwidth of the instrument’s physical connection to the Data Server (e.g. USB, Ethernet), streaming data for most nodes is, by default, not sent by the device, rather each node must be enabled at the desired rate by a client. When streaming data from a device output is enabled, then it is always sent from the device to the Data Server.
Polling Data¶
To get the buffered data from the data server to the client a poll command is used.
data = daq.pollEvent(<timeout_ms>)
The returned value is a dictionary containing a single node:poll_event pair.
A poll event is a dictionary that holds, besides some additional optional type
specific properties one or multiple value(s). How many value updates an event
contains is non deterministic and depends on the inner workings of the data server.
The timeout parameter defines how long the command should wait for a poll event. If the timeout expires an empty dictionary is returned.
Tip
The Python API offers also a higher level poll command (daq.poll) which
accumulates multiple poll events over a defined interval.
data = session.poll(<duration_s>, <timeout_s>)
The returned value is a dictionary of node:poll_event pair(s) that happened
within the specified duration. A poll event holds,
besides some additional optional type specific properties one or multiple value(s).
Tip
The elements in the dictionary can be accessed through the toolkit node object.
data[device.dios[0].input]
ZIEvent* event;
if ((event = ziAPIAllocateEventEx()) == NULL)
{
throw(std::runtime_error("[ERROR] Can't allocate memory for Event.\n"));
}
checkError(ziAPIPollDataEx(conn, event, 1000));
Compared to the other LabOne API the output is not a dictionary but a ZIEvent
instead. A ZIEvent holds the path to the node from which the event originates,
the type (valueType) of the event and the data. For convenience the ZIEvent
holds a pointer to the first entry in the data using the correct type according to
ZIEvent.valueType field. How many value updates an event contains is non
deterministic and depends on the inner workings of the data server.
It is good practice to allocate ZIEvent in heap memory instead on the stack.
This will secure against stack overflows especially in windows. For this two
functions ziAPIAllocateEventEx and ziAPIDeallocateEventEx are exposed
in the LabOne C API.
Info
Unlike the other LabOne APIs there is no higher level poll command which accumulates multiple events over a defined interval.
ziDAQ('pollEvent', <timeout_ms>)
The returned value is a dictionary containing a single node:poll_event pair.
A poll event is a dictionary that holds, besides some additional optional type
specific properties one or multiple value(s). How many value updates an event
contains is non deterministic and depends on the inner workings of the data server.
The timeout parameter defines how long the command should wait for a poll event. If the timeout expires an empty dictionary is returned.
Tip
The MATLAB API offers also a higher level poll command (poll) which
accumulates multiple poll events over a defined interval.
daq.poll(<duration_s>, <timeout_ms>, 0, 1));
The returned value is a Lookup of node:poll_event pair(s) that happened
within the specified duration. A poll event holds, besides some additional optional
type specific properties one or multiple value(s).
Important
It’s not guaranteed that a single poll command leads to the transfer of all data in the Data Server buffer because the block size of transferred data is limited. Nonetheless, by calling poll frequently enough, a gapless stream of data can be obtained.
Look at the tutorial VIs 203_SubscribePoll_NonStreamingNode.vi and 204_SubscribePoll_StreamingNode.vi as well as the example VIs ziExample-PollData.vi and ziExample-PollDemod.vi provided with the LabVIEW driver for LabOne to learn about data polling.
Warning
The data server clears the buffer when it becomes full, but latest after 5 seconds. The Client must therefore poll frequent enough to ensure that data is not lost in between multiple poll calls.
Tip
Often one of the LabOne ziCore Modules provide an easier and more efficient choice for data acquisition than the comparably low-level poll command. Each ziCore Module is a software component that performs a specific high-level measurement task, for example, the Data Acquisition Module can be used to record bursts of data when a defined trigger condition is fulfilled or the Sweeper Module can be used to perform a frequency response analysis. The modules also take care of the data alignment, which is not done by the poll commands.