This chapter contains reference documentation for the settings and
measurement data available on HF2LI Instruments. Whilst
Functional Description
describes many of these settings in terms of the features available in
the LabOne User Interface, this chapter describes them on the device
level and provides a hierarchically organized and comprehensive list of
device functionality.
Since these settings and data streams may be written and read using the
LabOne APIs (Application Programming Interfaces) this chapter is of
particular interest to users who would like to perform measurements
programmatically via LabVIEW, Python, MATLAB, .NET or C.
Please see:
Introduction for an introduction of how the
instrument’s settings and measurement data are organized
hierarchically in the Data Server’s so-called "Node Tree".
Reference Node Documentation for a reference list of the settings and
measurement data available on HF2 Instruments, organized by branch
in the Node Tree.
This chapter 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, its 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:
/dev1000/auxouts/
In turn, each individual auxiliary output channel has its own branch
underneath the "AUXOUTS" branch.
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:
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 Exploring the Node Tree.
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.
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
The node corresponds to a writable instrument configuration. The data of these nodes are persisted in snapshots of the instrument and stored in the 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 the Programming Manual in the Chapter Instrument Communication. 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.
String
A string array.
Integer (enumerated)
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
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.
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 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 the LabOne Programming Manual.
The detailed descriptions of nodes that is provided in
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.core.ziDAQServer('localhost',8004,6)daq.help('/dev2006/auxouts/0/offset')# Out:# /dev1000/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
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.
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.
The Global nodes of the LabOne Data Server are listed in the Instrument Communication
chapter of the LabOne Programming Manual
Sets the time constant of the low-pass filter. The time constant is set for each stage of the low-pass filter. The total time constant and bandwidth depends on the selected order.
Sets the trigger- and gating-functionality of the demodulator. The triggers are configured by the bits of an integer. When multiple bits/triggers are set, they are or-ed. If trigger is set to 0 then demodulator data is sent continuously.
Sets the time constant of the carrier low-pass filter. The time constant is set for each stage of the low-pass filter. The total time constant and bandwidth depends on the selected order.
Sets the time constant of the sideband low-pass filter. The time constant is set for each stage of the low-pass filter. The total time constant and bandwidth depends on the selected order.
Proportional gain for differentiator. Sets the proportional gain for the differentiated error signal. Negative feedback corresponds to a negative gain.
Sets the time constant of the low-pass filter. The time constant is set for each stage of the low-pass filter. The total time constant and bandwidth depends on the selected order.
Proportional gain for integrator. Sets the proportional gain for the integrated (accumulated) error signal. Negative feedback corresponds to a negative gain.
If applicable, selects the channel of the selected INPUT. Sets the input channel index for the selected INPUT, i.e. 0,1,2 etc.. The available channels depend on the input type.
If applicable, selects the channel of the selected OUTPUT. Sets the input channel index for the selected OUTPUT, i.e. 0,1,2 etc.. The available channels depend on the output type
Time constant when TipProtect is active. Time constant for low-pass filtering the PLL error² when TipProtect is active, i.e. when waiting to re-enable the PID controller.
Time constant when TipProtect is inactive. Time constant for low-pass filtering the PLL error² when TipProtect is inactive, i.e. when waiting to disable the PID controller.
Timescale of the scope wave (logarithmic decimation). Determines the decimation of the sample
rate. The following formulas apply: span = 2^val * 10 us, sample rate =
210 MSamples/2^val
Boolean value switching from internal to external clock. When using external clock, make sure that a clock generator is connected to the Clock In connector.
Boolean value enabling multi-device timestamp synchronization over ZSync. When synchronizing timestamps between devices make sure that an appropriate cable is connected between the ZSync ports of the leader and follower devices.
Boolean value activating timestamp reset over ZSync. When synchronizing timestamps between devices make sure that an appropriate cable is connected between the ZSync ports of the leader and follower devices.
