Quickstart

Eager to get started? This page gives a good introduction to zhinst-toolkit. Follow Installation to install zhinst-toolkit first.

Preparation

LabOne® needs to installed and running before using zhinst-toolkit. For a complete reference see the dedicated user manual page for your instrument(s).

Before continuing, make sure a LabOne® data server is running in your network and all of your devices are visible.

Session To The Data Server

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. (see Architecture in the LabOne Programming Manual)

The entry point into toolkit is therefore a API client session to a data server:

>>> from zhinst.toolkit import Session
>>> session = Session("localhost")

(if your data server runs on a remote computer (e.g. an MFLI directly) replace localhost with the correct address.)

Node Tree

All settings and data in LabOne® are organized by the Data Server in a file-system-like hierarchical structure called the node tree. zhinst-toolkit implements the node tree in a nested dictionary like structure. The interface of that dictionary also supports accessing the nodes by attribute, making it more readable and simpler to write. (For an in-depth introduction into the node tree structure in zhinst-toolkit take a look at Node Tree)

>>> session.debug.level()
'status'

So what did that code do?

1. The session represents the session to the data server and gives access to its nodes (/zi/* in the core API).

2. One of these nodes is zi/debug/level. The Node Tree allows it to access that node by attributes.

3. To get the current value of the node simply make a call operation.

Changing the value of a node can be done in a similar way. Simply add the value to the call operation.

>>> session.debug.level('warning')
>>> session.debug.level()
'warning'

Device communication

The data server can be connected to one or multiple devices. By connecting or accessing an already connected device a new device object for that device is created by zhinst-toolkit.

>>> session.devices.visible()
['dev1234', 'dev5678']
>>> session.devices.connected()
['dev1234']
>>> session.devices['dev1234']
BaseInstrument(DEMO,dev1234)
>>> session.connect_device('dev5678')
BaseInstrument(DEMO,dev5678)

The created device object holds all device specific nodes and depending on the device type also implements additional functionalities (e.g. exposes the zhinst.utils functions).

>>> device = session.devices['dev1234']
>>> device.demods[0].freq()
10e6
>>> dir(device.demods[0])
['adcselect',
'bypass',
'enable',
'freq',
'sample',
'trigger']

To see an overview of the device specific functionalities take a look at the dedicated examples.

LabOne® modules

In addition to the usual API commands available for instrument configuration and data retrieval the LabOne® API also provides a number of so-called modules: high-level interfaces that perform common tasks such as sweeping data or performing FFTs. (See the LabOne Programming Manual For a complete documentation of all modules available)

In zhinst-toolkit these modules can be accessed through the session. Similar to the devices, each module can be controlled through a node tree. Some of the modules have toolkit specific functionalities (e.g. reading the acquired data automatically). To see an overview of the module specific functionalities, take a look at the dedicated examples.

Note

The underlying LabOne® module (zhinst.core object) can be accessed with the raw_module property

>>> daq_module = session.modules.daq
>>> daq_module.grid.mode()
4
>>> daq_module.raw_module
<zhinst.core.DataAcquisitionModule at 0x10edc5630>