Instrument class

hardware_control.base.Instrument module

class hardware_control.base.Instrument.Instrument(instrument_name: str, connection_addr: str | None = 'None', default_port: int = None, pyvisa_backend: str = '@py')

Bases: object

Base class and helper functions for all physical instrument drivers.

Instrument drivers implement the actual communications between the user and the instrument. The class supports several connection modes out of the box: pyvisa, sockets, and modbus. For other types of communication protocols, the try_connect function must be overwritten.

An instrument driver should be very basic, such that one can use it in a terminal. A driver should neither have any GUI elements nor any references to Qt.

When initializing an instrument, the user inherits from this base class and then calls add_parameter and/or add_command several times. These define ‘read only’ commands (e.g. to start collecting data) and/or ‘read and write’ parameters (e.g. to read or set a voltage), which are linked to the actual message that needs to be sent to the physical instrument. We also overwrite __getitem__, __getattr__, and the corresponding set functions to allow for a more pythonic way of reading and writing these parameters.

An instrument can also be used in dummy mode. In this mode, python will not try to connect to the physical instrument; it will instead return pre-defined data or call a user-defined function to generate the return value. This can be handy for creating and debugging an app when one does not have access to the hardware.

When creating an instrument one can pick the pyvisa driver to be either the pure python pyvisa one (default or pyvisa_backend= “@py” or use the National Instrument one by setting pyvisa_backend = “”.

online

Online/Offline status of the instrument

Type:: bool

dummy

Whether instrument is in dummy mode (no commands are sent to the instrument) or normal mode; this parameter is set for all an app’s instruments when an app is initialized

Type:: bool

MODBUS = 'modbus': Class variable that can be used to specify a modbus connection.

SOCKET = 'socket': Class variable that can be used to specify a socket connection.

VISA = 'visa': Class variable that can be used to specify a pyvisa connection.

add_command(command_name: str, command: str | Callable) → None: Add a command to an instrument.

add_lookup(parameter: str, lookuptable: dict) → None

Add a pre- and a post-hook to convert values according to a lookup table.

The lookup table will be used in the pre-hook, and an inverse of the lookup table will be created for the post-hook.

Add a new parameter to the instrument.

One has the option of initializing parameters without either a read_command or a set_command, but at least one must be specified. For reading and setting capability, one must specify both a read_command and a set_command.

Parameters:

parameter – This parameter name must be unique and will be used within hardware control to access this setting.
read_command – The control characters that need to be sent to the instrument to read the parameter
set_command – The control characters that need to be sent to the instrument to set the parameter. This string can include ‘{}’ to indicate where the set_value should be place in the control command.
dummy_return – A value or a user-defined function that will be returned in dummy mode. These can easily be overwritten in an app in order to be customized.

add_post_hook(parameter: str, function: Callable) → None: Add a ‘hook function’ to be exectued after reading a parameter.

add_pre_hook(parameter: str, function: Callable) → None: Add a ‘hook function’ to be exectued prior to the setting of a parameter.

check_connection() → bool

Check if the instrument is reachable.

The function runs the commands in self.check_connection_commands.

Returns:: True if the instrument is reachable or no test have been done, False if not.
Return type:: bool

close() → None: Close connection to the instrument.

command(command_name: str) → None

Execute an instrument command.

Example Usage: b = certain_instrument() b.command(‘trigger’)

config_serial(baud_rate: int | None = None, stop_bits: StopBits | None = None, data_bits: int | None = None, parity: int | None = None) → None: Configure a serial port.

get_value(parameter: str)

Get the value of a parameter from the physical instrument.

This function also handles the special cases of querying the _online and _dummy variable values.

Note: User-defined functions in dummy mode should not return None, since None indicates that a parameter does not exist.

list_parameters() → list[str]

List all instrument commands, parameter read_commands, and parameter set_commands.

This is mostly used so that the main app can know what commands are available.

parse_connection_addr() → None

Determine the connection protocol to be used.

Currently pyvisa addresses are automatically recognised; everything else is assumed to be in the form of either an IP address or an IP address and a port number seperated by a “:”. For these cases, sockets are automatically assumed. If modbus should be used, the user needs to overwrite this in the init function of the instrument driver.

query(command: str, delay: float | None = None): Query the insturment directly.

query_serial(command, delay)

set_value(parameter: str, value) → None: Call all of an instrument parameter’s pre-hooks, then set the value of the parameter.

try_connect() → bool

Checks if the instrument is in communication with the driver and tries to re-establish communication if it not.

Certain instruments require that this function be overwritten.

write(command: str) → None: Write a command directly to the insturment.

hardware_control.base.Instrument.ensure_online(f)

Proceed only if the instrument is online.

This decorator assumes that the first argument of the decorated function is an instrument class object.