Communicating with Machines

Access and addressing

Connections to a machine are handled through the Machine class, or a MachineReference, which may be a Machine or, if the machine has no password or other requirements, just the hostname string.

Machine(host[, password, automatic, ...])

A connection to a QuantStudio machine.

Connections, Access Levels, and Passwords

By default, as of 0.5.0, Machine automatically handles connections, disconnections, and, when possible (eg, for commands within qslib, rather than an arbitrary Machine.run_command()), access levels.

The QuantStudio SCPI interface controls access through passwords, which have no username associated; these passwords are each associated with a maximum access level. Each connection type (usually ethernet) also has an associated default and maximum access level with no password.

The recommended settings for QSLib, which can be set through the QSLib CLI, has a connection granted Observer access by default, and Controller access without a password.

When automatic=True, which is the default, whenever code needing a connection is run, a connection will be made, then disconnected as soon as the code is finished, if the machine wasn’t already connected. When automatic=False, connections can be handled manually through either context managers (safer) or individual commands. For clean access, the class provides a context manager for the connection, and the Machine.at_level() method provides a context manager for access level:

>>> with Machine('machine', 'password', max_access_level="Controller") as m:
>>>     # Now connected
>>>     print(m.run_status())  # runs at Observer level
>>>     with m.at_level("Controller", exclusive=True):
>>>         # Runs as Controller, and fails if another Controller is connected (exclusive)
>>>         m.abort_run()
>>>         m.drawer_open()
>>>     # Now back to Observer
>>>     print(m.status())
>>> # Now disconnected.

There is also the Machine.ensured_connection context manager, which will ensure that a connection exists at a particular access level, or arrange one if it does not. The connection context manager can also be used with with m: form for a Machine instance m that already exists, in which case it will connect and disconnect.

If you don’t want to use these, you can also use manual methods:

Machine.connect()

Open the connection manually.

Machine.set_access_level(access_level[, ...])

rtype:

None

Machine.disconnect()

Cleanly disconnect from the machine.

Note that there is no supported method on the machine’s server for removing hanging connections other than a reboot, and AB’s software will not start runs when other connections hold Controller level. To correct this, you can restart the machine with Machine.restart_system.

Utility commands

Machine.drawer_open()

Open the machine drawer using the OPEN command.

Machine.drawer_close([lower_cover, check])

Close the machine drawer using the OPEN command.

Machine.drawer_position

Return the drawer position from the DRAW? command.

Machine.cover_lower([check, ensure_drawer])

Lower/engage the plate cover, closing the drawer if needed.

Machine.cover_position

Return the cover position from the ENG? command.

Machine.status

Return the current status of the run.

Machine.run_status()

Return information on the status of any run.

Machine.access_level

rtype:

AccessLevel

Machine.current_run_name

Name of current run, or None if no run is active.

Machine.abort_current_run()

Abort (stop immediately) the current run.

Machine.stop_current_run()

Stop (stop after cycle end) the current run.

Machine.pause_current_run()

Pause the current run now.

Machine.pause_current_run_at_temperature()

rtype:

None

Machine.resume_current_run()

Resume the current run.

Machine.power

Get and set the machine's operational power (lamp, etc) as a bool.

Lower-level commands

Machine.run_command(command)

Run a SCPI command, and return the response as a string.

Machine.run_command_to_ack(command)

Run an SCPI command, and return the response as a string.