{"id":10366,"library":"zhinst-core","title":"Zurich Instruments Core Python API","description":"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.","status":"active","version":"26.1.3.9","language":"en","source_language":"en","source_url":"https://github.com/zhinst/zhinst-core-python","tags":["measurement","instrument-control","scientific","zurich-instruments","hardware"],"install":[{"cmd":"pip install zhinst-core","lang":"bash","label":"Install `zhinst-core`"}],"dependencies":[],"imports":[{"note":"ziDAQServer is the primary entry point for connecting to the LabOne Data Acquisition (DAQ) server and controlling devices.","symbol":"ziDAQServer","correct":"from zhinst.core import ziDAQServer"},{"note":"Import specific error types for robust error handling, e.g., errors.CoreError.","symbol":"errors","correct":"from zhinst.core import errors"}],"quickstart":{"code":"import zhinst.core\nimport os\n\n# Configuration for connecting to the DAQ server\n# The LabOne Data Acquisition (DAQ) server must be running on your system.\n# Use environment variables or modify these values if your server is not on localhost:8004.\nDAQ_SERVER_HOST = os.getenv('ZHINST_DAQLOGIN', 'localhost')\nDAQ_SERVER_PORT = int(os.getenv('ZHINST_DAQPORT', '8004'))\nAPI_LEVEL = 6 # zhinst-core typically uses API level 6\n\ntry:\n    # Establish a connection to the DAQ server\n    daq = zhinst.core.ziDAQServer(DAQ_SERVER_HOST, DAQ_SERVER_PORT, API_LEVEL)\n    print(f\"Successfully connected to DAQ server at {DAQ_SERVER_HOST}:{DAQ_SERVER_PORT}.\")\n\n    # Ping the server to confirm active communication\n    daq.ping()\n    print(\"DAQ server ping successful.\")\n\n    # List all devices currently connected to the DAQ server\n    devices = daq.listDevices()\n    if devices:\n        print(f\"Connected Zurich Instruments devices: {devices}\")\n        # Example: Read a property from the first connected device\n        # Note: Replace 'first_device' and the node path with actual values if needed\n        first_device = devices[0]\n        try:\n            device_model = daq.getString(f'/{first_device}/type')\n            print(f\"Model of first device ({first_device}): {device_model}\")\n        except zhinst.core.errors.CoreError as e:\n            print(f\"Warning: Could not read device type for {first_device}. Error: {e}\")\n            print(\"Ensure the device is online and the node path is valid for your device.\")\n    else:\n        print(\"No Zurich Instruments devices are currently connected to the DAQ server.\")\n        print(\"Ensure devices are powered on, connected, and recognized by LabOne.\")\n\nexcept ConnectionRefusedError:\n    print(f\"Error: Connection refused. Please ensure the Zurich Instruments LabOne DAQ Server is running and accessible at {DAQ_SERVER_HOST}:{DAQ_SERVER_PORT}.\")\n    print(\"Refer to the LabOne documentation for starting the DAQ server.\")\nexcept zhinst.core.errors.CoreError as e:\n    print(f\"A zhinst.core API error occurred: {e}\")\n    print(\"This could be due to an API level mismatch, invalid node path, or a server issue.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consult the LabOne web interface (or `daq.listNodes('*')`) to verify correct device IDs and node paths for your specific instrument and its configuration.","message":"Incorrect node paths (e.g., '/devxxxx/sigins/0/range') are a common source of `CoreError` exceptions. Node paths are case-sensitive and device-specific.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"zhinst-core requires Python 3.10 or newer.","severity":"breaking","affected_versions":"<26.0.0.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Start the LabOne DAQ server. Verify the `DAQ_SERVER_HOST` and `DAQ_SERVER_PORT` match your server's configuration (default is 'localhost', 8004).","cause":"The LabOne Data Acquisition (DAQ) server is not running or is not accessible at the specified host and port.","error":"ConnectionRefusedError: [Errno 111] Connection refused"},{"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.","cause":"The API level specified when creating the `ziDAQServer` object does not match the API level supported by the running LabOne DAQ server.","error":"zhinst.core.errors.CoreError: API level mismatch detected."},{"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.","cause":"The specified node path does not exist on the connected device, is misspelled, or the device ID is incorrect.","error":"zhinst.core.errors.CoreError: node '/devXXXX/path/to/node' not found"}]}