Low Level API Commands¶
This page describes the different API commands available to read/write settings and data from and to the connected device(s).
All data and settings are organized, by the LabOne Data Server, in a file system like structure called the node tree. Each parameter can be identified through a path. All configuration and acquisition is done by reading or changing the values of these nodes. To allow an efficient communication with the device, LabOne exposes a set of different operations for this.
Get And Set Node Values¶
The most basic command is to get and set a value directly from and to the device. This kind of operation is called synchronous, since it blocks until the value was acknowledged by or fetched from the device.
In case of a set operation, the device acknowledges the request with the value it applied.
NOTE: The acknowledged value can differ from the send one, e.g., due to upper and lower limits or the applied bit resolution.
Although these commands can be considered the most basic and intuitive ones, they should be used only when needed. The reason is that they are, compared to the other option, very slow.
| API | Get Command | Set Command |
|---|---|---|
| Python | get |
syncSetInt, syncSetDouble, syncSetString, syncSetByte, setVector |
| C | - | ziAPISyncSetValueB, ziAPISyncSetValueD, ziAPISyncSetValueI, ziAPISyncSetValueString, ziAPISyncSetValueStringUnicode, ziAPISetVector |
| Matlab | get |
syncSetInt, syncSetDouble, syncSetString, syncSetByte, setVector |
| .NET | - | syncSetInt, syncSetDouble, syncSetString, syncSetByte, setVector |
Note
The synchronous get command is not implemented on all API. In these cases, the shallow get or a get as event command is the proper replacement.
Single Shallow Set¶
The client does not directly communicate with the device. The central place is the data server. This allows an efficient communication with one or multiple instruments. Each data server can connect to one or multiple devices. Each data server can also server one or multiple clients.
Instead of waiting for the device to acknowledge a set request, the client can also rely on the data server and only wait for its acknowledgement. The data server then ensures by its own that the request is sent to the device correctly. The advantage of this so-called shallow set is that it is, compared to the synchronous operation, considerable faster.
Important
Before acknowledging a shallow set request, the data server validates the node path, but not the value. Meaning a none existing node will cause an immediate error, an invalid value not.
Warning
Currently the error handling is done in such a way that errors from the device, or from within the data server, are simply raised with the next client request. E.g., if the device reports an error for the requested node change, it will cause an exception with the next client request.
Tip
All requests are processed in a sequential order, meaning they are sent to the device in the same order as they were sent by the client. A shallow set followed by a synchronous set therefore ensures that both values are received by the device correctly.
| API | Shallow Set Command |
|---|---|
| Python | setInt, setDouble, setString, setByte, set |
| C | ziAPISyncSetValueI, ziAPISyncSetValueD, ziAPISyncSetValueString, ziAPISetValueB |
| Matlab | setInt, setDouble, setString, setByte |
| .NET | setInt, setDouble, setString, setByte |
Send and Forget¶
Taking the shallow set one step further, instead of waiting for the data server to acknowledge the set request, the client could just send the value and then return without waiting for the response of the data server. This is a “send and forget” command and is the fastest way of setting device nodes. However, it comes at the cost of no error handling. One needs to be sure that the node exists and that the path is spelled correctly, you won't get any feedback if you have made a mistake.
Tip
A typical scheme for setting a batch of nodes in a time-critical setup is to set all the nodes except the last one using asyncSet. The last node then is sent through a syncSet to flush all the set node values to the device. However, a transactional set is much more suited for this kind of scheme.
| API | Send And Forget Set Command |
|---|---|
| Python | asyncSetInt, asyncSetDouble, asyncSetString, asyncSetByte |
| C | ziAPIAsyncSetIntegerData, ziAPIAsyncSetDoubleData, ziAPIAsyncSetString, ziAPIAsyncSetByteArray |
| Matlab | asyncSetString |
| .NET | - |
Warning
Although the commands are named async they are not! They are really just a “send and forget” operation.
Transactional Set¶
Often not only a single value needs to be changed. Instead of issuing multiple independent requests, the preferred operation is a transactional set. This reduces the network overhead and enables the data server to optimize the device communication. It is especially useful to speed up the transfer of many smaller vectors. Closing a transaction will block until the device acknowledges all transactional requests.
Warning
Similar to the “Send and Forget” commands, a transaction is currently missing proper error handling. For example, misspelled or no invalid nodes will not cause an error.
| API | Send And Forget Set Command |
|---|---|
| Python | set |
| C | ziAPIBeginTransaction, ziAPITransactionalSetInt, ziAPITransactionalSetDouble, ziAPITransactionalSetComplex, ziAPITransactionalSetBytes, ziAPITransactionalSetVector, ziAPIEndTransaction |
| Matlab | set |
| .NET | - |
Single Shallow Get¶
The device propagates all node changes through update messages to the data server. This enables the data server to hold a shallow copy of the node tree for each connected device. Every time the data server receives an update message, it stores the latest value in its shallow copy. For a connected client, this means that instead of fetching a value directly from the device, one can use the shallow copy from the data server. This reduces the latency of a get command, especially if the data server is on the same machine as the client, and apart from a few edge cases is considered stable.
Warning
The shallow copy of the node tree is only updated through update messages from the device. A shallow get directly after a shallow set will most likely result in the get request returning the old value instead of the recently changed.
| API | Send And Forget Set Command |
|---|---|
| Python | getInt, getDouble, getString, getComplex, getByte |
| C | ziAPIGetValueI, ziAPIGetValueD, ziAPIGetValueString, ziAPIGetValueB |
| Matlab | getInt, getDouble, getString, getComplex, getByte |
| .NET | getInt, getDouble, getString, getComplex, getByte |
Subscribe And Poll¶
For high-performance continuous or block streaming data
Similar to the shallow get the subscribe and poll mechanism is based on the update message that the device sends for every node change. A client can subscribe to the changes of one or more nodes.
This tells the Data Server to create a buffer for each subscribed node and to buffer each update message received for the subscribed nodes. 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.
Warning
If poll is not called within 5 seconds, 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 is one of the most powerful low level commands. It primary use case is to retrieve streaming data, e.g demodulator samples, without any sample loss from a connected device. But is also can be used to stay updated on the value change of a setting node. It is for example used by the LabOne UI to ensure that the displayed settings are always up-to-date.
For streaming data the data returned is the discrete device data as sampled or calculated by the digital signal processing algorithms on the instrument.
Warning
The data from multiple nodes may not be aligned due to different sampling rates or
different streaming node sources. Therefore the LabOne Modules often provide an
easier and more efficient choice for data acquisition than the comparably low-level
poll command.
Note
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.
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. It also is a global operation and the marker is send to all connected devices and can cause unwanted side effects. The sync command should therefore only be used with care.
Manually trigger an update Event¶
In addition to the synchronous and shallow get, there is a third option to get the
value of a node. By using the poll command, one can stay informed about every update
message for all subscribed nodes. As already explained, the device sends an update
message for every node value change (or every new sample in case of a streaming node).
The LabOne API also offers a way to trigger an update message even though the value
did not change. This command is called getAsEvent.
The data server automatically stores the update message in the client buffer. This does not require a subscription to the node itself. With the next poll command the client receives the update message automatically.
Conclusion¶
In the above sections give a complete overview over all available commands to get and set a node values through the LabOne API. It should now be clearer which command is suited best for your application.
Generally speaking, the following rules can be applied:
- For most cases, the shallow get and set are the go-to commands. They offer the best ratio between performance and error handling.
- To validate, a new value is applied/accepted by the device the synchronous set command is optimal since it returns the acknowledged value and does not need a second command for validation.
- Streaming nodes, such as demodulator samples, are best handled through the subscribe and poll mechanism, or a LabOne Module.
- The transactional set offers a lot of convenience and can improve the setup speed. However, for debugging or exploring, the normal set and get commands offer better error handling.