Instrument Communication

This section describes the main concepts in LabOne software that allow high-speed data acquisition and guides the user to the best acquisition method for their measurement task.

Data Server’s Node Tree

This section provides an overview of how an instrument’s configuration and output is organized by the Data Server.

All communication with an instrument occurs via the Data Server program the instrument is connected to (see LabOne Software Architecture). for an overview of LabOne’s software components). Although the instrument’s settings are stored locally on the device, it is the Data Server’s task to ensure it maintains the values of the current settings and makes these settings (and any subscribed data) available to all its current clients. A client may be the LabOne User Interface or a user’s own program implemented using one of the LabOne Application Programming Interfaces, e.g., Python.

The instrument’s settings and data are organized by the Data Server in a file-system-like hierarchical structure called the node tree. When an instrument is connected to a Data Server, it’s device ID becomes a top-level branch in the Data Server’s node tree. The features of the instrument are organized as branches underneath the top-level device branch and the individual instrument settings are leaves of these branches.

For example, the auxiliary outputs of the instrument with device ID "dev2006" are located in the tree in the branch:

/DEV2006/AUXOUTS/

In turn, each individual auxiliary output channel has it’s own branch underneath the "AUXOUTS" branch.

/DEV2006/AUXOUTS/0/
/DEV2006/AUXOUTS/1/
/DEV2006/AUXOUTS/2/
/DEV2006/AUXOUTS/3/

Whilst the auxiliary outputs and other channels are labelled on the instrument’s panels and the User Interface using 1-based indexing, the Data Server’s node tree uses 0-based indexing. Individual settings (and data) of an auxiliary output are available as leaves underneath the corresponding channel’s branch:

/DEV2006/AUXOUTS/0/DEMODSELECT
/DEV2006/AUXOUTS/0/LIMITLOWER
/DEV2006/AUXOUTS/0/LIMITUPPER
/DEV2006/AUXOUTS/0/OFFSET
/DEV2006/AUXOUTS/0/OUTPUTSELECT
/DEV2006/AUXOUTS/0/PREOFFSET
/DEV2006/AUXOUTS/0/SCALE
/DEV2006/AUXOUTS/0/VALUE

These are all individual node paths in the node tree; the lowest-level nodes which represent a single instrument setting or data stream. Whether the node is an instrument setting or data-stream and which type of data it contains or provides is well-defined and documented on a per-node basis in the Reference Node Documentation section in the relevant instrument-specific user manual. The different properties and types are explained in Node Properties and Data Types .

For instrument settings, a Data Server client modifies the node’s value by specifying the appropriate path and a value to the Data Server as a (path, value) pair. When an instrument’s setting is changed in the LabOne User Interface, the path and the value of the node that was changed are displayed in the Status Bar in the bottom of the Window. This is described in more detail in Node Properties and Data Types.

Module Parameters

LabOne Core Modules, such as the Sweeper, also use a similar tree-like structure to organize their parameters. Please note, however, that module nodes are not visible in the Data Server’s node tree; they are local to the instance of the module created in a LabOne client and are not synchronized between clients.

Node Properties and Data Types

A node may have one or more of the following properties:

Read

Data can be read from the node.

Write

Data can be written to the node.

Setting

A node with write attribute corresponding to an instrument configuration. The data in these nodes will be saved to and loaded from LabOne XML settings files.

Streaming

A node with the read attribute that provides instrument data, typically at a user-configured rate. The data is usually a more complex data type, for example demodulator data is returned as ZIDemodSample. A full list of streaming nodes is available in Table 1. Their availability depends on the device class (e.g. MF) and the option set installed on the device.

A node may contain data of the following types:

Integer

Integer data.

Double

Double precision floating point data. Note that the actual value on the device may only be calculated in single precision.

String

A string array.

Enumerated (integer)

As for Integer, but the node only allows certain values.

Composite data type

For example, ZIDemodSample. These custom data types are structures whose fields contain the instrument output, a timestamp and other relevant instrument settings such as the demodulator oscillator frequency. Documentation of custom data types is available in C Programming. the C Programming Chapter in the LabOne Programming manual.

Exploring the Node Tree

In the LabOne User Interface

A convenient method to learn which node is responsible for a specific instrument setting is to check the Command Log history in the bottom of the LabOne User Interface. The command in the Status Bar gets updated every time a configuration change is made. Figure 1 shows how the equivalent Matlab command is displayed after modifying the value of the auxiliary output 1’s offset. The format of the LabOne UI’s command history can be configured in the Config Tab (Matlab, Python and .NET are available). The entire history generated in the current UI session can be viewed by clicking the "Show Log" button.

NodeTreeDescription LabOneUILogStatusBar
Figure 1. When a device’s configuration is modified in the LabOne User Interface, the Status Bar displays the equivalent command to perform the same configuration via a LabOne programming interface. Here, the Matlab code to modify auxiliary output 1’s offset value is provided. When "Show Log" is clicked the entire configuration history is displayed in a new browser tab.
In the Instrument-specific User Manual

Each instrument user manual has a "Device Node Tree" chapter that contains complete reference documentation of every node available on the device. This documentation may be explored by branch to obtain a complete overview of which settings are available on the instrument.

In a LabOne Programming Interface

A list of nodes (under a specific branch) can be requested from the Data Server in an API client using the listNodes command (Matlab, Python, .NET) or ziAPIListNodes() function (C API). Please see each API’s command reference for more help using the listNodes command. To obtain a list of all the nodes that provide data from an instrument at a high rate, so-called streaming nodes, the streamingonly flag can be provided to listNodes. More information on data streaming and streaming nodes is available in in Data Streaming ).

The detailed descriptions of nodes that is provided in the instrument-specific user manual section "Reference Node Documentation" is accessible directly in the LabOne Matlab or Python programming interfaces using the "help" command. The help command is daq.help(path) in Python and ziDAQ('help', path) in Matlab. The command returns a description of the instrument node including access properties, data type, units and available options. The "help" command also handles wildcards to return a detailed description of all nodes matching the path. An example is provided below.

daq = zhinst.ziPython.ziDAQServer('localhost', 8004, 6)
daq.help('/dev2006/auxouts/0/offset')
# Out:
# /DEV2006/AUXOUTS/0/OFFSET#
# Add the specified offset voltage to the signal after scaling. Auxiliary Output
# Value = (Signal+Preoffset)*Scale + Offset
# Properties: Read, Write, Setting
# Type: Double
# Unit: V

Data Server Nodes

The Data Server has nodes in the node tree available under the top-level /ZI/ branch. These nodes give information about the version and state of the Data Server the client is connected to. For example, the nodes:

  • /ZI/ABOUT/VERSION

  • /ZI/ABOUT/REVISION

are read-only nodes that contain information about the release version and revision of the Data Server. The nodes under the /ZI/DEVICES/ list which devices are connected, discoverable and visible to the Data Server.

The nodes:

  • /ZI/CONFIG/OPEN

  • /ZI/CONFIG/PORT

are settings nodes that can be used to configure which port the Data Server listens to for incoming client connections and whether it may accept connections from clients on hosts other than the localhost. See Initializing a Connection to a Data Server for more information about specifying the Data Server host and port.

Nodes that are of particular use to programmers are:

  • /ZI/DEBUG/LOGPATH - the location of the Data Server’s log in the PC’s file system,

  • /ZI/DEBUG/LEVEL - the current log-level of the Data Server (configurable; has the Write attribute),

  • /ZI/DEBUG/LOG - the last Data Server log entries as a string array.

For documentation of all Data Server nodes see the /ZI/ section in the Reference Node Documentation section in the instrument-specific user manual.

Data Streaming

Zurich Instrument’s Data Servers and devices allow high-speed data acquisition using the "data streaming" concept. The term "data streaming" refers to the fact that the discrete values of a device’s output are continuously pushed at a high rate from the device to an API client (via the device’s physical connection and Data Server) analogously to media streaming where, for example, video is continuously streamed from one computer to another over the internet.

Data streaming is only available for device outputs such as demodulator and pulse counters, where it is relevant to acquire the instrument’s discrete data at a very high time resolution. Settings nodes, for example, are not streamed but rather sent upon request. Some device outputs additionally allow their data stream to be gated based on the value of another device signal, such as a trigger input, for example. This allows even higher data transfer rates for short bursts, that would otherwise not be possible when data is continuously sent from the device.

To optimize the bandwidth of the instrument’s physical connection to the Data Server (e.g. USB, Ethernet), streaming data for all 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. It is not sent from the Data Server to the client, however, until the API client explicitly requests the data by "subscribing" to the data server node providing the streaming data.

The advantage of Zurich Instruments' streaming concept is that it allows extremely high data acquisition rates. Whereas "fixed rate" data transfer or "fixed-buffer size" data transfer (for all nodes) allows very simple interfaces for data acquisition, it does not optimize the available interface bandwidth since low update rates must be imposed to ensure that data loss does not occur in all situations. Users who prefer a fixed rate or fixed-size buffer transfer may use the Data Acquisition Module, which adds an additional layer of software on top of data streaming that emulates these kinds of transfer.

In general, unless extremely fast update rates or high performance data transfer is required by the client, the Data Acquisition Module is the recommended method to obtain data (as opposed to the low-level subscribe and poll commands). This is due to the additional complexities involved when working directly with "raw" streaming data, since users must:

  • Be aware that data loss may occur and must be correctly handled in their API client program.

  • Organize data that may be split across subsequent poll commands.

  • Align/interpolate streaming data from multiple nodes onto a common time grid if required.

The following sections explain these points in further detail, users who acquire the data from Data Acquisition Module may prefer to skip ahead Comparison of Data Acquisition Methods.

Streaming Nodes

When streaming nodes are recorded directly via the the low-level subscribe and poll commands they continuously deliver either:

  • Continuous equidistantly spaced data in time, e.g., DEMODS/0/SAMPLE or CNTS/0/SAMPLE,

  • Continuous non-equidistantly spaced data in time, e.g., BOXCARS/0/SAMPLE when the boxcar is configured with an external reference-controlled oscillator (but this is somewhat of a special case).

  • Non-continuous framed "block" data that consist of chunks of data, e.g., SCOPES/0/WAVE.

The qualifier "continuous" deserves further explanation. Each sample point is a discrete data point sent from the device. Continuous means that the samples are not only continually sent, but also that all the data from that device unit/output is sent without gaps in time. Block data on the other hand is not continuous; it is a single burst of data from a device unit (e.g. scope) that provides data at a very high data rate.

Nodes that deliver high-speed streaming data have the streaming property set (see Node Properties and Data Types). This property can be used with the listNodes command in order to list all the streaming nodes available on a particular device. For example, in Python:

daq = zhinst.ziPython.ziDAQServer('localhost', 8004, 6)
from zhinst.ziPython import ziListEnum
flags = ziListEnum.recursive | ziListEnum.absolute | ziListEnum.streamingonly
print(int(ziListEnum.streamingonly), flags)
# Out:
# 16, 19
daq.connectDevice('dev2006', 'usb')
daq.listNodes('/dev2006/*/0', flags)
# Out:
# ['/DEV2006/AUCARTS/0/SAMPLE',
#  '/DEV2006/AUPOLARS/0/SAMPLE',
#  '/DEV2006/AUXINS/0/SAMPLE',
#  '/DEV2006/BOXCARS/0/SAMPLE',
#  '/DEV2006/CNTS/0/SAMPLE',
#  '/DEV2006/DEMODS/0/SAMPLE',
#  '/DEV2006/DIOS/0/INPUT',
#  '/DEV2006/INPUTPWAS/0/WAVE',
#  '/DEV2006/OUTPUTPWAS/0/WAVE',
#  '/DEV2006/PIDS/0/STREAM/ERROR',
#  '/DEV2006/PIDS/0/STREAM/SHIFT',
#  '/DEV2006/PIDS/0/STREAM/VALUE',
#  '/DEV2006/SCOPES/0/STREAM/SAMPLE',
#  '/DEV2006/SCOPES/0/WAVE']

The table below gives an overview of the available streaming nodes on different devices.

Table 1. Device streaming nodes. Their availability depends on the device class(e.g. MF) and the option set installed on the device.
Device Node Path Availability Type Description

AUCARTS/n/SAMPLE

UHF

Continuous

The output samples of a Cartesian Arithmetic Unit

AUPOLARS/n/SAMPLE

UHF

Continuous

The output samples of a Polar Arithmetic Unit

AUXINS/n/SAMPLE

All instruments

Continuous

The auxiliary input samples. Typically not used; these values are included as fields in demodulator samples where available.

BOXCARS/n/SAMPLE

UHF with Box Option

Continuous

The output samples of a boxcar.

CNTS/n/SAMPLE

UHF or HDAWG with CNT Option

Continuous

The output samples of a counter unit.

DEMODS/n/SAMPLE

UHFLI, HF2LI, MFLI

Continuous

The output samples of a demodulator.

DIOS/n/INPUT

All instruments

Continuous

The DIO connector input values. Rarely used; the input values are included as a field in demodulator samples where available.

IMPS/n/SAMPLE

MFIA, MFLI with IA Option

Continuous

The output samples of an impedance channel.

INPUTPWAS/n/WAVE

UHF with BOX Option

Block

The value of the input PWA.

OUTPUTPWAS/n/WAVE

UHF with BOX Option

Block

The value of the output PWA.

PIDS/n/STREAM/ERROR

UHF or MF with PID Option

Continuous

The error value of a PID.

PIDS/n/STREAM/SHIFT

UHF or MF with PID Option

Continuous

The shift of a PID; the difference between the center and the the output value.

PIDS/n/STREAM/VALUE

UHF or MF with PID Option

Continuous

The output value of the PID.

SCOPES/n/STREAM/SAMPLE

UHF or MF with DIG Option

Block

Scope values as a continuous block streaming node.

SCOPES/n/WAVE

All instruments

Block

Scope values as a triggered block streaming node.

TRIGGERS/STREAMS/n/SAMPLE

HDAWG

Block

Trigger values.

Alignment of Streaming Node Data

In general, streaming nodes deliver equidistantly-spaced samples in time (assuming no sample loss has occurred). However, different streaming nodes have different timestamp grids. This is best explained in Figure 2.

streaming data different rates
Figure 2. Samples from different streaming nodes configured with different rates: Demod 1 at 2N kSamples/s, Demod 2 at N kSamples/s and PID Error 1 at M kSample/s (N not divisible by M). Although each stream consists of equidistantly samples in time, the sample timestamps from different streams are not necessarily aligned due to the different sampling rates.

Data Loss

While streaming nodes deliver equidistantly sampled data in time (with the exception of a boxcar output based on an external reference controlled oscillator), they may be subject to data loss (also called "sample loss"). This refers to the loss of data between instrument and Data Server over the physical interface. Since data streaming is optimized for transfer speed, there is no resend mechanism available that would automatically request that missing data be transferred again to the Data Server; the data is lost and this case must be handled appropriately in API programs. In the case of data loss, the returned data will simply be missing, i.e. data will no longer be equidistantly sampled in time due to to the missing samples. As such, to check for data loss on streaming node data, the user is advised to calculate the difference between timestamps and verify that all differences correspond to the expected difference as defined by the configured data streaming rate.

Data rates are not limited or throttled by the instrument to ensure that data loss does not occur; the user is responsible to configure streaming data rates for the required nodes such that data loss does not occur in their system. Data rates are not artificially limited due to the fact that continuous and hardware triggered data acquisition may be combined. If the cumulative data sent by the instrument over the physical interface exceeds the available bandwidth then data loss will occur. The maximum available bandwidth of the physical interface is influenced by the following factors:

  • Choice of physical interface (USB, 1GbE).

  • Additional load on the interface (Ethernet / USB hub) from other network traffic or devices.

  • Speed of the PC where the Data Server is running.

  • For the case of 1GbE interface only: The PC’s network card.

  • MF instruments only: Whether the Data and/or Web Servers are running on the instrument or on the PC.

Comparison of Data Acquisition Methods

In this section we briefly compare the methods available to obtain data from continuous streaming instrument nodes (not for block streaming nodes, see Scope Data). Which method is most appropriate depends on the requirements of the specific application. Table 2 provides a top-level overview.

Table 2. Comparison of data acquisition methods available in the LabOne APIs.
Method Good for Not appropriate for

The getSample function

  • Simple single-shot measurements of demodulator data.

  • Non-demodulator streaming nodes.

  • Continuous data acquisition.

  • Triggered data acquisition.

Data Acquisition Module in Triggered Mode

  • Triggered data acquisition.

  • Aligned data from multiple streams.

Data Acquisition Module in Continuous Mode

  • Continuous data acquisition.

  • Aligned data from multiple streams.

The subscribe and poll functions

  • Extremely high performance.

  • Data from between different streaming nodes may not be aligned by timestamp.

  • Data alignment between polls not guaranteed.

Scope Data

It is recommended to use the Scope Module for acquiring scope data (from the node SCOPES/n/WAVE). Although scope data can be acquired using the low-level subscribe and poll commands, the Scope Module provides additional functionality such as multiple block assembly (SCOPES/n/WAVE is a "block" streaming node, cf Node Properties and Data Types) and FFT of the data.

Demodulator Sample Data Structure

An instrument’s demodulator data is returned as a data structure (typically a struct) with the following fields (regardless of which API Level is used):

timestamp

The instrument’s timestamp of the measured demodulator data uint64. Divide by the instrument’s clockbase (/dev123/clockbase) to obtain the time in seconds.

x

The demodulator x value in Volts [double].

y

The demodulator y value in Volts [double].

frequency

The current frequency used by the demodulator in Hertz [double].

phase

The oscillator’s phase in Radians (not the demodulator phase) [double].

auxin0

The auxiliary input channel 0 value in Volts [double].

auxin1

The auxiliary input channel 1 value in Volts [double].

bits

The value of the digital input/output (DIO) connector.[integer].

time.dataloss

Indicator of sample loss (including block loss) [bool].

time.blockloss

Indication of data block loss over the socket connection. This may be the result of a too long break between subsequent poll commands [bool].

time.invalidtimestamp

Indication of invalid time stamp data as a result of a sampling rate change during the measurement [bool].

C Programming contains details of other data structures.

Instrument-Specific Considerations

This section describes some instrument-specific considerations when programming with the LabOne APIs.

MF-Specific Considerations

Identifying which Data Server the MF device is connected to

If /DEV…​./SYSTEM/ACTIVEINTERFACE has the value "pcie" the device is connected via the Data Server running locally on the MF instrument itself. If it has the value "1GbE" it is connected via a Data Server running on a PC.

UHF-Specific Considerations

UHF Lock-in Amplifiers perform an automatic calibration 10 minutes after power-up of the Instrument. This internal calibration is necessary to achieve the specifications of the system. However, if necessary, it can be ran manually by setting the device node /DEV…​./SYSTEM/CALIB/CALIBRATE to 1 and then disabled using the /DEV…​./SYSTEM/CALIB/AUTO node.

The calibration routine takes about 200 ms and during that time the transfer of measurement data will be stopped on the Data Server level. If a C Programming (LabOne C API) or LabVIEW Programming client is polling data during this time, the user will experience data loss; ziAPI has no functionality to deal with such a streaming interrupt. Clients polling data will be informed of data loss, which allows the user to ignore this data.

Please see the UHF User Manual for more information about device calibration.