Zurich Instruments Core Python API

26.1.3.9 · active · verified Fri Apr 17

zhinst-core is the core Python API for communicating with Zurich Instruments devices, providing low-level control and data acquisition capabilities. It is currently at version 26.1.3.9 and typically releases new versions in sync with Zurich Instruments LabOne software and device firmware updates, often multiple times a year, ensuring compatibility with the latest features.

Common errors

```
ConnectionRefusedError: [Errno 111] Connection refused
```
cause The LabOne Data Acquisition (DAQ) server is not running or is not accessible at the specified host and port.

fix Start the LabOne DAQ server. Verify the `DAQ_SERVER_HOST` and `DAQ_SERVER_PORT` match your server's configuration (default is 'localhost', 8004).
```
zhinst.core.errors.CoreError: API level mismatch detected.
```
cause The API level specified when creating the `ziDAQServer` object does not match the API level supported by the running LabOne DAQ server.

fix Ensure the `api_level` parameter in `zhinst.core.ziDAQServer(host, port, api_level)` matches the DAQ server's API level (typically 6 for recent zhinst-core versions). Update LabOne software if necessary.
```
zhinst.core.errors.CoreError: node '/devXXXX/path/to/node' not found
```
cause The specified node path does not exist on the connected device, is misspelled, or the device ID is incorrect.

fix Check the LabOne web interface for the correct device ID ('devXXXX') and the exact, case-sensitive node path. Use `daq.listNodes('*')` to explore available nodes dynamically.

Warnings

gotcha zhinst-core requires the Zurich Instruments LabOne Data Acquisition (DAQ) Server to be running separately. The Python library acts as a client to this server.
Fix: Ensure the LabOne software is installed and the DAQ server is running before attempting to connect with `zhinst-core`. Check task manager/services or start it via the LabOne web interface.
gotcha API level mismatches between the `ziDAQServer` constructor (e.g., `ziDAQServer(..., api_level=6)`) and the DAQ server can lead to connection failures or unexpected behavior.
Fix: Use the recommended API level (often 6) for `zhinst-core`. If issues persist, verify the API level supported by your LabOne DAQ server installation and adjust accordingly.
gotcha Incorrect node paths (e.g., '/devxxxx/sigins/0/range') are a common source of `CoreError` exceptions. Node paths are case-sensitive and device-specific.
Fix: Consult the LabOne web interface (or `daq.listNodes('*')`) to verify correct device IDs and node paths for your specific instrument and its configuration.
breaking zhinst-core requires Python 3.10 or newer.
Fix: Upgrade your Python environment to version 3.10 or higher. Older zhinst-core versions may support earlier Python versions, but it's recommended to stay current.

Install

pip install zhinst-core Install `zhinst-core`

Imports

ziDAQServer
```
from zhinst.core import ziDAQServer
```
ziDAQServer is the primary entry point for connecting to the LabOne Data Acquisition (DAQ) server and controlling devices.
errors
```
from zhinst.core import errors
```
Import specific error types for robust error handling, e.g., errors.CoreError.

Quickstart

This quickstart demonstrates how to connect to the Zurich Instruments LabOne Data Acquisition (DAQ) server using `zhinst-core`, ping the server, list connected devices, and attempt to read a basic property from the first device. It includes error handling for common connection and API issues. The DAQ server, part of the LabOne software, must be running for this code to connect successfully.

import zhinst.core
import os

# Configuration for connecting to the DAQ server
# The LabOne Data Acquisition (DAQ) server must be running on your system.
# Use environment variables or modify these values if your server is not on localhost:8004.
DAQ_SERVER_HOST = os.getenv('ZHINST_DAQLOGIN', 'localhost')
DAQ_SERVER_PORT = int(os.getenv('ZHINST_DAQPORT', '8004'))
API_LEVEL = 6 # zhinst-core typically uses API level 6

try:
    # Establish a connection to the DAQ server
    daq = zhinst.core.ziDAQServer(DAQ_SERVER_HOST, DAQ_SERVER_PORT, API_LEVEL)
    print(f"Successfully connected to DAQ server at {DAQ_SERVER_HOST}:{DAQ_SERVER_PORT}.")

    # Ping the server to confirm active communication
    daq.ping()
    print("DAQ server ping successful.")

    # List all devices currently connected to the DAQ server
    devices = daq.listDevices()
    if devices:
        print(f"Connected Zurich Instruments devices: {devices}")
        # Example: Read a property from the first connected device
        # Note: Replace 'first_device' and the node path with actual values if needed
        first_device = devices[0]
        try:
            device_model = daq.getString(f'/{first_device}/type')
            print(f"Model of first device ({first_device}): {device_model}")
        except zhinst.core.errors.CoreError as e:
            print(f"Warning: Could not read device type for {first_device}. Error: {e}")
            print("Ensure the device is online and the node path is valid for your device.")
    else:
        print("No Zurich Instruments devices are currently connected to the DAQ server.")
        print("Ensure devices are powered on, connected, and recognized by LabOne.")

except ConnectionRefusedError:
    print(f"Error: Connection refused. Please ensure the Zurich Instruments LabOne DAQ Server is running and accessible at {DAQ_SERVER_HOST}:{DAQ_SERVER_PORT}.")
    print("Refer to the LabOne documentation for starting the DAQ server.")
except zhinst.core.errors.CoreError as e:
    print(f"A zhinst.core API error occurred: {e}")
    print("This could be due to an API level mismatch, invalid node path, or a server issue.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

view raw JSON →