Introduction

This chapter briefly describes the different possibilities to interface with a Zurich Instruments device, other than via the LabOne User Interface. Zurich Instruments devices are designed with the concept that "the computer is the cockpit"; there are no controls on the front panel of the instrument, instead the user can configure their instrument from and stream data directly to their computer. The aim of this approach is to give the user the freedom to choose where they connect to, and how they control their instrument.

Instrument Specifics

The LabOne Programming Manual is intended to be used in parallel to the corresponding user manual for the instrument you are using. Please refer to the instrument-specific manual for comprehensive documentation of its functionality and settings; a full list of settings can be found in the "Device Node Tree" Chapter.

HF2 Real-time Option

The Real-time Option (RTK) for the HF2 Series is not a PC-based interface for controlling an instrument and is documented in the HF2 User Manual.

LabOne Programming Quick Start Guide

This section contains a collection of tips to help you get started programming with your instrument as quickly as possible.

Use the LabOne User Interface to develop measurement methods

LabOne’s high-level measurement tools, such as the Sweeper Module are available in the LabOne User Interface (UI) and APIs. Since they use the same internal library, these tools have consistent behavior across all interfaces; their parameters may first be tuned in the UI before transferring them to the API. Documentation for all the available high-level tools are provided in LabOne API Programming.

Let the LabOne User Interface write code for you

Use the command logging functionality of the the UI to copy code from the UI’s log to your MATLAB, Python or .NET program. When you change a setting in the UI the corresponding API command is displayed in the status bar. If "Show Log" is clicked, then the full history of corresponding API commands is displayed. More information on finding settings is given in Exploring the Node Tree.

Use Device Discovery to connect to your device

Device Discovery is included in every API and provides information on all the devices connected via USB or that are visible on your local network. For example, from Python: Import the module, create an instance of the Discovery tool and request discovery information on a specific device:

import zhinst.core
dev = 'dev2006'
d = zhinst.core.ziDiscovery()
props = d.get(d.find(dev))

Device Discovery returns a dictionary that contains connectivity information for the specified device; we can use this information to create an API session (connect to a Data Server) and subsequently connect the device on a physical interface (e.g. USB, ethernet) and start communicating with the device:

api_session = zhinst.core.ziDAQServer(props['serveraddress'], props['serverport'], props['apilevel'])
api_session.connectDevice(dev, props['interfaces'][0])
api_session.getDouble('/{}/demods/0/rate'.format(dev))
# Out: 1.81e3

Further explanation about creating an API session with the appropriate the Data Server is provided in Specifying the Data Server Hostname and Port.

Use the distributed examples as a base for your program

Each LabOne API contains many examples to help you get started. Our public GitHub repository provides a constantly updated collection of examples for the different APIs.

The following APIs provide built-in examples: MATLAB, LabVIEW, .NET, C.

Use the API’s logging capabilities

The LabOne APIs write log files containing useful debugging and status information. Enable the API log to monitor the behavior of your program and add your own log entries with the writeDebugLog() command. For example, in Python: Import the zhinst.core module, create an API session and enable logging with the setDebugLevel() command:

import zhinst.core
api_session = zhinst.core.ziDAQServer('localhost', 8004, 6)
api_session.setDebugLevel(0)

Then create an instance of the Sweeper and write to the log:

h = api_session.sweep()
api_session.writeDebugLog(0, 'Will now configure and start the sweeper...')
h.set('sweep/device', 'dev2006')
h.execute()

These commands generate the log:

Will log to directory '/tmp/ziPythonLog_danielw'
11:55.25.805 [0] [status] Opening session: 127.0.0.1
11:55.25.805 [1] [trace] Will now configure and start the sweeper...
11:55.30.877 [2] [debug] Sweep execute, averaging 1 samples 0.001 s or 5 x tc, settling 0s or 5 x tc (0.01)
11:55.30.886 [3] [debug] Oscillator index 0 for path oscs/0/freq
11:55.30.887 [4] [warning] Sweeper will run in slower synchronous set mode. Enable controlled demodulators to get fast mode.
11:55.30.888 [5] [debug] Sweep fast: false, bandwidth control: 2, bw: 2000
11:55.30.889 [6] [debug] Used settlingTimeFactor 9.99805

See the API-specific chapter for more details:

Use the API utility functions

The APIs are distributed with utility functions that replicate functionality incorporated in the UI. For example, the MATLAB and Python APIs have utility functions to convert a demodulator’s time constant to its corresponding 3dB bandwidth (tc2bw).

Load LabOne User Interface settings files from the APIs

The XML files used for device settings can not only be loaded and saved from the LabOne User Interface but from any of the APIs. See Device Settings Module for more information.

LabOne Software Architecture

Zurich Instruments devices use a server-based connectivity methodology. Server-based means that all communication between the user and the instrument takes place via a computer program called a server, the Data Server. The Data Server recognizes available instruments and manages all communication between the instrument and the host computer on one side, and communication to all the connected clients on the other side. This allows for:

A multi-client configuration: Multiple interfaces (even from multiple computers on the network) can access the settings and data on an instrument. Settings are synchronized between all interfaces by the single instance of the Data Server.
A multi-device setup: Any of the Data Server’s clients can access multiple devices simultaneously.

This software architecture is organized in layers, see Figure 1 for a schematic of the software layers.

Figure 1. LabOne Software Architecture. The above diagram depicts the software architecture when using Zurich Instruments. In the case of MFLI and MFIA instruments the Data Server and/or the Web Server can also run on the device itself instead of on a host computer (see MFLI /MFIA Software Configuration).

First, we briefly explain some terminology that is used throughout this manual.

Host computer: The computer where the Data Server is running and that is directly connected to the instrument. Multiple remote computers on a local area network can access the instrument by creating an API connection to the Data Server running on the host computer.
Data Server: A computer program that runs on the host computer and manages settings on, and data transfer to and from instruments by receiving commands from clients. It always has the most up-to-date configuration of the device and ensures that the configuration is synchronized between different clients.
ziServer.exe: The Data Server that handles communication with HF2 Instruments.
ziDataServer.exe: The Data Server that handles communication with instruments other than HF2. Note, in the case of MFLI Instruments the Data Server runs on the instrument itself.
Remote computer: A computer, available on the same network as the host computer, that can communicate with an instrument via the Data Server program running on the host.
Client: A computer program that communicates with an instrument via the Data Server. The client can be running either on the host or the remote computer.
API (Application Programming Interface): a collection of functions and data structures which enable communication between software components. In our case, the various APIs (e.g., LabVIEW, MATLAB®) provide functions to configure instruments and receive measured experimental data.
Interface: Either a client or an API.
GUI (Graphical User Interface): A computer program that the user can operate via images as opposed to text-based commands.
LabOne User Interface: The browser-based user interface that connects to the Web Server.
LabOne Web Server: The program that generates the browser-based LabOne User Interface.
ziControl: The standard GUI shipped for use with HF2 Instruments (before software release 15.11). HF2 support was added to the LabOne User Interface for devices with the WEB Option installed in LabOne software release 15.11 .
ziCore: The internal core library upon which many APIs are based, see LabOne API Programming for more information.
Modules: ziCore software components that provide a unified interface to APIs to perform a specific high-level common task such as sweeping data.

MFLI /MFIA Software Configuration

In their simplest form, The MFLI/MFIA instruments are self contained. The LabOne Web Server and Data Server run on the instrument itself. Only the LabOne APIs run on an external PC.

However, to improve performance, other software configurations are possible. By installing the LabOne software on an external PC, the MFLI/MFIA instrument can be accessed via a LabOne Web Server running there. This gives advantages due to the improved computing power and the greater memory resources of the external PC. Moreover, if performing measurements with two or more synchronized MFLI/MFIA instruments, a LabOne Data Server running on the external PC can also be used. Indeed, to synchronize multiple MFLI/MFIA instruments, this software configuration is mandatory.

Figure 2. LabOne Software Configuration MFLI/MFIA. The above diagram shows the simplest software configuration for the MFLI/MFIA instruments. The Data Server and Web Server run on the device itself (devXXXX represents the serial number of the instrument).

Figure 3. LabOne Software Configuration for the MFLI with the LabOne Web Server running on an external PC (devXXXX represents the serial number of the instrument).

Figure 4. LabOne Software Configuration for the MFLI with LabOne Web Server and Data Server running on an external PC. This software configuration is mandatory when synchronizing multiple MFLI/MFIA instruments.

Comparison of the LabOne APIs

The various software interfaces available in LabOne allow the user to pick a programming environment they are familiar with to achieve fast results. All other things being equal, here is a brief discussion of the merits of each interface.

The LabVIEW Programming allows for quick and efficient implementation of virtual instruments that run independently. These can easily be integrated in existing experiment control performed in LabVIEW. This interface requires a National Instruments LabVIEW license and LabVIEW 2009 (or higher).
The MATLAB Programming allows the user to directly obtain measurement data within the MATLAB programming environment, where they can make use of the many built-in functions available. This interface requires a MathWorks MATLAB license, but no additional MATLAB Toolboxes.
The Python Programming allows the user to directly obtain measurement data within python. Python is available as free and open source software; no license is required to use it.
The .NET Programming allows the user to directly obtain measurement data within the .NET programming framework using the C#, Visual Basic or #F programming languages. To use the .NET API a Microsoft Visual Studio installation is required.
The C API is a very versatile interface that will run on most platforms. However, since C is a low-level programming language, the development cycle is slower than with the other programming environments.
The text-based interface (HF2 Series only) allows the user to manually connect to the HF2 Data Server in a console via telnet. While this interface is a very useful tool for HF2 programmers to verify instrument configuration set by other interfaces, it is limited in terms of performance and maximum demodulator sample rate. See the HF2 User Manual for more details.

From LabOne Release 15.05 onwards the Sweeper and DAQ (formerly called Software Trigger) Modules are also available in the LabVIEW and C APIs and from 16.12 onwards all Modules are available. All modules were previously available in the MATLAB and Python LabOne APIs.

Initializing a Connection to a Data Server

As described in LabOne Software Architecture an API client communicates with an instrument via a data server over a TCP/IP socket connection. As such, the first step towards communicating with an instrument is initializing an API session to the correct data server for the target device.

The choice of data server depends on the device class and the network topology. HF2 instruments operate via a different data server program than other instruments. Users of MF Instruments should be aware that the data server runs on the MF Instrument itself and not on a separate PC. Finally, in the case of MF Instruments, the way to connect to the data server depends on the interface (USB or 1GbE). In all cases, the desired data server is specified by providing three parameters:

the data server host’s address (hostname),
the data server port,
the API level to use for the session.

Specifying the Data Server Hostname and Port

For users working with a single device, this section describes how to quickly connect to the correct data server by manually specifying the required data server’s hostname and port and the required API Level. Each API has a connect function which takes these three parameters in order to initialize an API session, for example, in the LabOne MATLAB API:

>>> ziDAQ('connect', serverHostname, serverPort, apiLevel);

Data Server Port

A LabOne API client connects to the correct Data Server for their instrument by specifying the appropriate port. By default, the data server program for HF2 instruments listens to port 8005, whereas the data server programs for all other instruments listen to port 8004 for API connections. Ports 8001 to 8003 are used internally for those instruments and must be accessible, too.

The value of the port that the data server listens to can be changed using the --port N command-line option when starting the data server. In this case, the ports N-3 to N must be accessible from the API client when connecting to any instruments except for HF2 devices. The ports 41000 to 41032 must be accessible when connecting to SHFLI or GHFLI devices, too.

Data Server Hostname (All Instruments except MF)

In the simplest configuration for instruments other than MF, the instrument is attached to the same PC where both the data server and API client are running. Since the API client is running on the same PC as the data server, the 'localhost' (equivalently, '127.0.0.1') should be specified as the data server address, Figure 5.

The API client may also connect to a data server running on a different PC from the client. In this case, the data server address should be the IP address (or hostname, if available) of the PC where the data server is running. Note, remote data server access is not enabled by default and the data server must be configured in order to listen to non-localhost connections by either enabling the --open-override command-line option when starting the data server or by setting the value of the server node /zi/config/open to 1 on a running data server (clearly only possible from a client running on the localhost). See Exploring the Node Tree for more information on nodes.

Figure 5. Server address and port handling for all instruments except MF for the case where the API client and data server are running on the same PC. In this case, the server hostname is localhost, and the default port value is 8004 for all instruments except HF2, where the port is 8005.

Data Server Hostname (MF Instruments)

In the case of MF instruments the data server runs on the instrument itself and as such an API client from a PC always accesses the data server remotely. Thus, in this case the data server hostname is that of the instrument itself. This will be the same hostname (but not port) that is used to run the LabOne User Interface in a web browser (when the Web Server is running on the MF instrument), see Figure 6.

As described in more detailed in the Getting Started chapter of the MFLI User Manual, the MF instrument hostname can either be its instrument serial of the form mf-dev3001, or its IP address. The former is however only valid if the MF instrument is connected to a LAN with domain name system via 1GbE. If it’s connected via the USB interface, finding out the IP address is easiest by using the Start Menu Entry "LabOne User Interface MF USB" and then copying the IP address from the browser’s address bar.

Figure 6. Server address and port handling on MF Instruments. The data server runs on the instrument and the server hostname is the same as the instrument’s hostname. Using a hostname of the form mf-dev3001 is only applicable when using the 1GbE interface. The default data server port is 8004 for MF Instruments.

API Level and Connectivity Examples

The last parameter to specify, the API level, specifies the version of the API to use for the session. In short, an API Level of 1 must be used for HF2 devices, and an API Level 6 is recommended for other instruments. Since the default API Level is 1, specifying this parameter for the other instruments is necessary. A more detailed explanation of API Levels is provided in LabOne API Levels .

For example, to initialize a session to the HF2’s data server running on the localhost with the LabOne Python API, the following commands should be used:

>>> import zhinst.core
>>> daq = zhinst.core.ziDAQServer('localhost', 8005, 1)

and in order to connect to the data server running on the MF instrument connected via 1GbE with device serial 'dev3001' with the LabOne MATLAB API:

>> ziDAQ('connect', 'mf-dev3001', 8004, 6)

On an MF instrument connected via USB, the device serial cannot be directly used as the hostname, instead one needs to use the instrument’s IP address. Unless this is known beforehand, it can be determined by the network discovery functionality of the API. The following python example shows how this can be done:

>>> import zhinst.core
>>> d = zhinst.core.ziDiscovery()
>>> d.find('mf-dev3001')
>>> devProp = d.get('mf-dev3001')
>>> daq = zhinst.core.ziDAQServer(devProp['serveraddress'], devProp['serverport'], 6)

Working in a Multi-threaded Program

It is important to note that API session objects are not thread-safe, i.e. a single API session cannot be shared between multiple client threads. If you want to use a LabOne API in a multi-threaded program, for each client thread, use a separate API session.

LabOne API Levels

All of the LabOne APIs are based on an internal core API. Needless to say, we try as hard as possible to make any improvements in our core API backwards compatible for the convenience of our users. We take care that existing programs do not need to be changed upon a new software release. Occasionally, however, we do have to make a breaking change in our API by removing some old functionality. This old functionality is, however, phased out over several software releases. First, the functionality is marked as deprecated and the user is informed via a deprecation warning (this can be turned off). This indicator warns that this function may be unsupported in the future. If we have to break some functionality we use a so-called API level.

With support of new devices and features we need to break functionality on the ziAPI.h e.g. data returned by poll commands. In order to still support the old functionality we introduced API levels. If a program only uses old functionality the API level 1 (default) can be used. If a user needs new functionality, they need to use a higher API level. This will usually need some changes to the existing code.

The current available API levels are:

API Level 1: HF2 support, basic UHF support.
API Level 4: UHF support, timestamp support in poll, PWA, name clean-up.
API Level 5: Introduction of scope offset for extended (non-hardware) scope inputs (UHF, MF Instruments).
API Level 6: Timestamp support in poll for nodes that return a byte array.

Note that Levels 2 and 3 are used only internally and are not available to the general public.

The HF2 Series only supports API Level 1.

New API users are recommended to use API Level 6 for all other instruments. API Level 6 is required for SHFLI and GHFLI Instruments.

API Level 4 Features

The new features in API Level 4 are:

Timestamps are available for any settings or data node (that is either integer or float).
Greatly improved Scope data transfer rates (and new Scope data structure).
Greatly improved UHF Boxcar and PWA support.

API Level 5 Features

API Level 5 was introduced in LabOne Release 15.01 to accommodate a necessary change in the Scope data structure:

The Scope data structure was extended with the new field "channeloffset" which contains the offset value that must be added to the scaled wave value in order to obtain the physical value recorded by the scope. For previous hardware scope "inputselects" there is essentially no change, since their offset is always zero. However, for the extended values of "inputselects", such as PID Out value, (available with the DIG option) the offset is determined by the values of "limitlower" and "limitupper" configured by the user.

API Level 6 Features

API Level 6 was introduced in LabOne Release 17.06 to make the behavior of poll for nodes that return a byte array consistent with nodes that return integer and float data:

Timestamps are returned for all byte array nodes.
New commands setString and getString are available and should be used instead of setByte and getByte.

Compatibility

Controlling an instrument requires the combination of several software components: The instrument’s firmware, a Data Server and an API. In general, whenever possible, it is recommended to use the latest (and same) software release version (e.g., "20.01") of all these components. If you are bound to a certain version for technical reasons, then it is recommended to use the same version of all components. However, this is not strictly necessary in all cases. If it is absolutely necessary to mix versions, this section explains how to verify whether different versions of various software components may be mixed with each other.

API and Data Server Compatibility

Although it is recommended to use the same software release version (e.g. "20.01") of both API and Data Server, it is not strictly necessary. The interface between API and Data Server remains the same between versions. However, there may be a change in some Exploring the Node Tree that effects specific functionality.

If you do need to mix versions, then please check the Release Notes (included in a LabOne installation) to see if the functionality you require has changed. If so, then the same version of API and Data Server must be used. Otherwise, it is possible to mix versions. If after checking the Release Notes you are still not sure, then please contact Zurich Instruments customer support.

All the LabOne APIs have a utility function to check whether the API being used is the same version as the Data Server it is connected to, e.g., api_server_version_check() in the Python API and ziApiServerVersionCheck() in the MATLAB API.