Python Toolkit API Session¶
zhinst.toolkit.session.Session(server_host, server_port=None, *, hf2=None, connection=None, allow_version_mismatch=False)
¶
Bases: Node
Session to a 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 sever. The data sever 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.
The entry point into for any connection is therefore a client session to a existing data sever. This class represents a single client session to a data server. The session enables the user to connect to one or multiple instruments (also creates the dedicated objects for each device), access the LabOne modules and poll data. In short it is the only object the user need to create by himself.
Info
Except for the HF2 a single session can be used to connect to all devices from Zurich Instruments. Since the HF2 is historically based on another data server called the hf2 data server it is not possible to connect HF2 devices a "normal" data server and also not possible to connect devices apart from HF2 to the hf2 data server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
server_host |
str
|
Host address of the data server (e.g. localhost) |
required |
server_port |
Optional[int]
|
Port number of the data server. If not specified the session uses the default port 8004 (8005 for HF2 if specified). (default = None) |
None
|
hf2 |
Optional[bool]
|
Flag if the session should be established with an HF2 data sever or the "normal" one for all other devices. If not specified the session will detect the type of the data server based on the port. (default = None) |
None
|
connection |
Optional[ziDAQServer]
|
Existing DAQ server object. If specified the session will not create a new session to the data server but reuse the passed one. (default = None) |
None
|
allow_version_mismatch |
bool
|
if set to True, the connection to the data-server will succeed even if the data-server is on a different version of LabOne. If False, an exception will be raised if the data-server is on a different version. (default = False) |
False
|
daq_server: core.ziDAQServer
property
¶
Managed instance of the core.ziDAQServer.
Returns:
| Type | Description |
|---|---|
ziDAQServer
|
Instance of the core.ziDAQServer. |
devices: Devices
property
¶
Mapping for the connected devices.
Returns:
| Type | Description |
|---|---|
Devices
|
mapping for the connected devices. |
is_hf2_server: bool
property
¶
Flag if the data server is a HF2 Data Server.
modules: ModuleHandler
property
¶
multi_transaction: Transaction
property
¶
Flag if a session wide transaction is in progress.
Returns:
| Type | Description |
|---|---|
Transaction
|
Flag if a session wide transaction is in progress. |
server_host: str
property
¶
server_port: int
property
¶
clone_underlying_session()
¶
Create a new session to the data server.
Create a new core.ziDAQServer connected to the same data-server this session is connected to.
Returns:
| Type | Description |
|---|---|
ziDAQServer
|
New instance of the core.ziDAQServer. |
connect_device(serial, *, interface=None)
¶
Establish a connection to a device.
Info
It is allowed to call this function for an already connected device. In that case the function simply returns the device object of the device.
If the interface is not specified the interface will be auto detected. Meaning one of the available interfaces will be selected, prioritizing 1GbE over USB.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
serial |
str
|
Serial number of the device, e.g. 'dev12000'. The serial number can be found on the back panel of the instrument. |
required |
interface |
Optional[str]
|
Device interface (e.g. = "1GbE"). If not specified the default interface from the discover is used. |
None
|
Returns:
| Type | Description |
|---|---|
DeviceType
|
Device object |
Raises:
| Type | Description |
|---|---|
KeyError
|
Device is not found. |
RuntimeError
|
Connection failed. |
disconnect_device(serial)
¶
Disconnect a device.
Warning
This function will return immediately. The disconnection of the device may not yet finished.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
serial |
str
|
Serial number of the device, e.g. 'dev12000'. The serial number can be found on the back panel of the instrument. |
required |
from_existing_connection(connection)
classmethod
¶
Initialize Session from an existing connection.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
connection |
ziDAQServer
|
Existing connection. |
required |
Returns:
| Type | Description |
|---|---|
Session
|
Session object |
poll(recording_time=0.1, *, timeout=0.5, flags=PollFlags.DEFAULT)
¶
Polls all subscribed data from the data server.
Poll the value changes in all subscribed nodes since either subscribing or the last poll (assuming no buffer overflow has occurred on the Data Server).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
recording_time |
float
|
Defines the duration of the poll in seconds. (Note that not only the newly recorded values are polled but all values since either subscribing or the last poll). Needs to be larger than zero. (default = 0.1) |
0.1
|
timeout |
float
|
Adds an additional timeout in seconds on top of
|
0.5
|
flags |
PollFlags
|
Flags for the polling (see :class |
DEFAULT
|
Returns:
| Type | Description |
|---|---|
dict[Node, dict[str, Any]]
|
Polled data in a dictionary. The key is a |
dict[Node, dict[str, Any]]
|
value is a dictionary with the raw data from the device |
raw_path_to_node(raw_path, *, module=None)
¶
Converts a raw node path string into a Node object.
The device that this strings belongs to must be connected to the Data Server. Optionally a module can be specified to which the node belongs to. (The module is only an additional search path, meaning even if a module is specified the node can belong to a connected device.)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
raw_path |
str
|
Raw node path (e.g. /dev1234/relative/path/to/node). |
required |
Returns:
| Type | Description |
|---|---|
Node
|
Corresponding toolkit node object. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the |
ToolkitError
|
If the node does not belong to the optional module or to a connected device. |
set_transaction()
¶
Context manager for a transactional set.
Can be used as a context in a with statement and bundles all node set commands into a single transaction. This reduces the network overhead and often increases the speed.
In comparison to the device level transaction manager this manager affects all devices that are connected to the Session and bundles all set commands into a single transaction.
Within the with block a set commands to a node will be buffered and bundled into a single command at the end automatically. (All other operations, e.g. getting the value of a node, will not be affected)
Warning
The set is always performed as deep set if called on device nodes.
Example
with session.set_transaction(): device1.test[0].a(1) device2.test[0].a(2)
sync()
¶
Synchronize all connected devices.
Synchronization in this case means creating a defined state.
The following steps are performed
- Ensures that all set commands have been flushed to the device
- Ensures that get and poll commands only return data which was recorded after the sync command. (ALL poll buffers are cleared!)
- Blocks until all devices have cleared their busy flag.
Warning
The sync is performed for all devices connected to the DAQ server
Warning
This command is a blocking command that can take a substantial amount of time.
Raises:
| Type | Description |
|---|---|
RuntimeError
|
ZIAPIServerException: Timeout during sync of device |
zhinst.toolkit.session.PollFlags
¶
Bases: IntFlag
Flags for polling Command.
Attributes:
| Name | Type | Description |
|---|---|---|
DETECT_AND_THROW |
int
|
Detect data loss holes and throw EOFError exception |
DETECT |
int
|
Detect data loss holes |
FILL |
int
|
Fill holes |
DEFAULT |
int
|
No Flags |
Can be combined with bitwise operations
PollFlags.FILL | PollFlags.DETECT
<PollFlags.DETECT|FILL: 9>