This chapter contains reference documentation for the settings and
measurement data available on SHFLI 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 SHFLI 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
"dev1000" 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:
Property
Description
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.
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('/dev1000/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
This node sets the compensation for signal propagation delays to achieve a flatter phase response. The default value compensates for the propagation delay resulting from the signal output to the auxiliary input with a short cable in between. Every additional meter of cable would add ~5 ns propagation delay, which can be compensated using this node.
Indicates the maximum normalized voltage measured on this channel. It can be between -1 and 1. To prevent signal clipping and overvoltage, it is advised to keep it between -0.9 and 0.9.
Indicates the minimum normalized voltage measured on this channel. It can be between -1 and 1. To prevent signal clipping and overvoltage, it is advised to keep it between -0.9 and 0.9.
Indicates the number of times the Auxiliary Input was in an overrange condition within the last 200 ms. It is checked for an overrange condition every 10 ms.
Sets the range of the Auxiliary Input power. The instrument has a fixed number of ranges with 5 dBm steps and will round the entered value to the closest available range.
Indicates the maximum normalized voltage generated on this channel. It can be between -1 and 1. To prevent signal clipping and overvoltage, it is advised to keep it between -0.9 and 0.9.
Indicates the minimum normalized voltage generated on this channel. It can be between -1 and 1. To prevent signal clipping and overvoltage, it is advised to keep it between -0.9 and 0.9.
Indicates the maximum normalized voltage generated on this channel. It can be between -1 and 1. To prevent signal clipping and overvoltage, it is advised to keep it between -0.9 and 0.9.
Indicates the minimum normalized voltage generated on this channel. It can be between -1 and 1. To prevent signal clipping and overvoltage, it is advised to keep it between -0.9 and 0.9.
Enables the data acquisition for the corresponding demodulator. Note: increasing number of active demodulators increases load on the physical connection to the host computer.
Indicates the frequency used for demodulation and for output generation. The demodulation frequency is calculated with oscillator frequency times the harmonic factor. When the MOD option is used linear combinations of oscillator frequencies including the harmonic factors define the demodulation frequencies.
Multiplies the demodulator's reference frequency by an integer factor. If the demodulator is used as a phase detector in external reference mode (PLL), the effect is that the internal oscillator locks to the external frequency divided by the integer factor.
Defines the demodulator sampling rate, the number of samples that are sent to the host computer per second. A rate of about 7-10 higher as compared to the filter bandwidth usually provides sufficient aliasing suppression. This is also the rate of data received by LabOne Data Server and saved to the computer hard disk. This setting has no impact on the sample rate on the auxiliary outputs connectors. Note: the value inserted by the user may be approximated to the nearest value supported by the instrument.
When on (1), the corresponding 8-bit bus is in output mode. When off (0), it is in input mode. Bit 0 corresponds to the least significant byte. For example, the value 1 drives the least significant byte, the value 8 drives the most significant byte.
Selects the interface standard to use on the 32-bit DIO interface. A value of 0 means that a 3.3 V CMOS interface is used. A value of 1 means that an LVDS compatible interface is used.
This defines the type of automatic adaptation of parameters in the PID used for Ext Ref.
2
"low_bandwidth", "pid_coeffs_filter_low_bw": The PID coefficients, the filter bandwidth and the output limits are automatically set using a low bandwidth.
3
"high_bandwidth", "pid_coeffs_filter_high_bw": The PID coefficients, the filter bandwidth and the output limits are automatically set using a high bandwidth.
4
"all", "pid_coeffs_filter_auto_bw": The PID coefficient, the filter bandwidth and the output limits are dynamically adapted.
If enabled, the accumulated integral error is maintained upon restart of the PID. If is disabled, the integral error is set to zero when the PID is disabled.
Target Rate for PID output data sent to PC. This value defines the applied decimation for sending data to the PC. It does not affect any other place where PID data are used.
Specifies the number of segments to be recorded in device memory. The maximum scope shot size is given by the available memory divided by the number of segments. This functionality requires the DIG option.
Enable segmented scope recording. This allows for full bandwidth recording of scope shots with a minimum dead time between individual shots. This functionality requires the DIG option.
This node sets the compensation for signal propagation delays to achieve a flatter phase response when using the baseband path. The default value compensates for the propagation delay resulting from the signal input and output and a short cable in between. Every additional meter of cable would add ~5 ns propagation delay, which can be compensated using this node.
This node sets the compensation for signal propagation delays to achieve a flatter phase response when using the RF path. The default value compensates for the propagation delay resulting from the signal input and output and a short cable in between. Every additional meter of cable would add ~5 ns propagation delay, which can be compensated using this node.
Indicates the maximum normalized voltage measured on this channel. It can be between -1 and 1. To prevent signal clipping and overvoltage, it is advised to keep it between -0.9 and 0.9.
Indicates the minimum normalized voltage measured on this channel. It can be between -1 and 1. To prevent signal clipping and overvoltage, it is advised to keep it between -0.9 and 0.9.
Indicates the number of times the Signal Input was in an overrange condition within the last 200 ms. It is checked for an overrange condition every 10 ms.
Sets the range of the Signal Input power. The instrument has a fixed number of ranges with 5 dBm steps and will round the entered value to the closest available range.
Indicates the number of times the Signal Output was in an overrange condition within the last 200 ms. It is checked for an overrange condition every 10 ms.
Sets the range of the Signal Output power. The instrument has a fixed number of ranges with 5 dBm steps and will round the entered value to the closest available range.
Enables (1) or disables (0) the RF interlock between input and output of the same channel. If enabled, the output is always configured according to the input.
The intended reference clock source. When the source is changed, all the instruments connected with ZSync links will be disconnected. The connection should be re-established manually.
0
"internal": The internal clock is intended to be used as the frequency and time base reference.
1
"external": An external clock is intended to be used as the frequency and time base reference. Provide a clean and stable 10 MHz or 100 MHz reference to the appropriate back panel connector.
"disabled": If disabled, the instrument does not automatically reset NCOs when switching a channel between BB and RF modes.
1
"enabled": If enabled, the instrument automatically resets the NCOs of all channels whenever a channel is switched between BB and RF, in order to restore alignment.
Sending a '1' to this node initiates a shutdown of the operating system on the device. It is recommended to trigger this shutdown before switching the device off with the hardware switch at the back side of the device.
Trigger voltage level at which the trigger input toggles between low and high. Use 50% amplitude for digital input and consider the trigger hysteresis.
Shows the value of the digital Trigger Input. The value is integrated over a period of 100 ms. Values are: 1: low; 2: high; 3: was low and high in the period.
