qontrol module

Hardware interfacing for Qontrol modules.

This module lets you control Qontrol hardware modules, natively in Python. It provides a main Qontroller class which handles enumeration, low-level communications, sequencing, error-handling, and log maintenance. Subclasses of Qontroller implement module-specific features (e.g. DC current or voltage interfaces, positional interfaces).

Learn more, at www.qontrol.co.uk/support, or get in touch with us at support@qontrol.co.uk. Contribute at github.com/takeqontrol/api.

3. 2021 Qontrol Ltd.

class qontrol.MXMotor(*args, **kwargs)

Bases: Qontroller

Motor controller module class. Provides channel vectors for speed (v), maximum speed (vmax), maximum winding current (imax), position (x) and associated minimum (xmin) and maximum (xmax), power-of-two microsteps (ustep), and motor mode (mode).

Compatible modules: - M2

error_desc_dict = {0: 'Unknown error.', 1: 'Out-of-range error on channel {ch}.', 3: 'Power error.', 4: 'Calibration error.', 5: 'Output error.', 10: 'Unrecognised command.', 11: 'Unrecognised input parameter.', 12: 'Unrecognised channel, {ch}.', 13: 'Operation forbidden.', 14: 'Serial buffer overflow.', 15: 'Serial communication error.', 16: 'Command timed out.', 17: 'SPI error.', 18: 'ADC error.', 19: 'I2C error.', 20: 'Interlock triggered on channel {ch}.', 30: 'Too many errors, some have been suppressed.', 31: 'Firmware trap.', 90: 'Powered up.'}

get_all_values(para='V')

All-channel value getter.

get_value(ch, para='X')

Single-channel value getter.

set_all_values(para='V', values=0)

Slice up set commands into vectors for each module, and transmit.

para: Parameter to set {‘X’,’XMIN’,’XMAX’,’VMAX’,’IMAX’,’MODE’} values: Either float/int or list of float/int of length n_chs

set_value(ch, para='X', new=0)

Single-channel value setter.

wait_until_stopped(channels=None, timeout=inf, t_poll=0.05)

Block execution until all motors are not in motion.

channels Wait for channels in this list to stop. None for all channels. timeout Max time before breaking. t_poll Motor state polling time, seconds. Larger numbers give less polling.

class qontrol.QXOutput(*args, **kwargs)

Bases: Qontroller

Output module class. Provides channel vectors for voltage (v), current (i), maximum voltage (vmax), and maximum current (imax).

Compatible modules: - Q8iv - Q8b

error_desc_dict = {0: 'Unknown error.', 1: 'Over-voltage error on channel {ch}.', 2: 'Over-current error on channel {ch}.', 3: 'Power error.', 4: 'Calibration error.', 5: 'Output error.', 10: 'Unrecognised command.', 11: 'Unrecognised input parameter.', 12: 'Unrecognised channel, {ch}.', 13: 'Operation forbidden.', 14: 'Serial buffer overflow.', 15: 'Serial communication error.', 16: 'Command timed out.', 17: 'SPI error.', 18: 'ADC error.', 19: 'I2C error.', 30: 'Too many errors, some have been suppressed.', 31: 'Firmware trap.', 90: 'Powered up.'}

get_all_values(para='V')

get_value(ch, para='V')

set_all_values(para='V', values=0)

Slice up set commands into vectors for each module, and transmit.

para: Parameter to set {‘V’ or ‘I’} values: Either float/int or list of float/int of length n_chs

set_value(ch, para='V', new=0)

class qontrol.Qontroller(*args, **kwargs)

Bases: object

Superclass which handles communication, enumeration, and logging.

device_id = None Device ID serial_port = None Serial port object serial_port_name = None Name of port, (eg ‘COM1’, ‘/dev/tty1’) error_desc_dict = Q8x_ERRORS Error code descriptions log = fifo(maxlen = 256) Log FIFO of communications log_handler = None Function which catches log dictionaries log_to_stdout = True Copy new log entries to stdout response_timeout = 0.100 Timeout for response to commands inter_response_timeout = 0.050 Timeout for response to get commands

Log handler:

The log handler may be used to catch and dynamically handle certain errors, as they arise. It is a function with a single dict argument. The dict contains details of the log entry, with keys ‘timestamp’, ‘proctime’, ‘type’, ‘id’, ‘ch’, ‘value’, ‘desc’, ‘raw’. In the following example, the handler is set to raise a

RuntimeError upon reception of errors E01, E02, and E03:

q = Qontroller()

fatal_errors = [1, 2, 3]

def my_log_handler(err_dict):

if err_dict[‘type’] is ‘err’ and err_dict[‘id’] in fatal_errors:

raise RuntimeError(‘Caught Qontrol error “{1}” at {0}

ms’.format(1000*err_dict[‘proctime’], err_dict[‘desc’]))

q.log_handler = my_log_handler

or more simply

q.log_handler = generic_log_handler(fatal_errors)

close()

Release resources

error_desc_dict = {0: 'Unknown error.', 3: 'Power error.', 4: 'Calibration error.', 5: 'Output error.', 10: 'Unrecognised command.', 11: 'Unrecognised input parameter.', 12: 'Unrecognised channel, {ch}.', 13: 'Operation forbidden.', 14: 'Serial buffer overflow.', 15: 'Serial communication error.', 16: 'Command timed out.', 17: 'SPI error.', 18: 'ADC error.', 19: 'I2C error.', 30: 'Too many errors, some have been suppressed.', 31: 'Firmware trap.', 90: 'Powered up.'}

issue_binary_command(command_id, ch=None, BCAST=0, ALLCH=0, ADDM=0, RW=0, ACT=0, DEXT=0, value_int=0, addr_id_num=0, n_lines_requested=2147483648, target_errors=None, output_regex='(.*)', special_timeout=None)

Transmit command to device, get response.

command_id: Command ID, either int (command index) or str (command name) ch: Channel address (max 0xFFFF for ADDM=0, 0xFF for ADDM=1) BCAST, ALLCH, ADDM, RW, ACT, DEXT: Header bits. See Programming Manual for full description value_int: Data, either int (DEXT=0) or list of int (DEXT=1) addr_id_num Device ID code (ADDM=1 only)

Other arguments are as described for issue_command().

issue_command(command_id, ch=None, operator='', value=None, n_lines_requested=2147483648, target_errors=None, output_regex='(.*)', special_timeout=None)

Transmit command to device, get response.

Command format is [command_id][ch][operator][value].

command_id Command header ch Channel index to apply command to operator Type of command in {?, =} value Value of set command n_lines_requested Lines of data (not error) to wait for, or timeout target_errors Error numbers which will be raised as RuntimeError special_timeout Timeout to use for this command only

log_append(type='err', id='', ch=0, value=0, desc='', raw='')

Log an event; add both a calendar- and process-timestamp.

parse_error(error_str)

Parse an error into its code, channel, and human-readable description.

print_log(n=None)

Print the n last log entries. If n == None, print all log entries.

receive()

Low-level receive data method which also checks for errors.

transmit(command_string, binary_mode=False)

Low-level transmit data method.

command_string – str or bytearray

wait(seconds=0.0)

Do nothing while watching for errors on the serial bus.

class qontrol.SXInput(*args, **kwargs)

Bases: Qontroller

Input module class. Provides channel vectors for current (i).

Arguments inherited from Qontroller:

device_id = None Device ID serial_port = None Serial port object serial_port_name = None Name of port, (eg ‘COM1’, ‘/dev/tty1’) error_desc_dict Error code descriptions log = fifo(maxlen = 256) Log FIFO of communications log_handler = None Function which catches log dictionaries log_to_stdout = True Copy new log entries to stdout response_timeout = 0.050 Timeout for response to commands inter_response_timeout = 0.020 Timeout for response to get commands

Compatible modules: - S8i

error_desc_dict = {0: 'Unknown error.', 1: 'Over-voltage error on channel {ch}.', 2: 'Over-current error on channel {ch}.', 3: 'Power error.', 4: 'Calibration error.', 5: 'Output error.', 10: 'Unrecognised command.', 11: 'Unrecognised input parameter.', 12: 'Unrecognised channel, {ch}.', 13: 'Operation forbidden.', 14: 'Serial buffer overflow.', 15: 'Serial communication error.', 16: 'Command timed out.', 17: 'SPI error.', 18: 'ADC error.', 19: 'I2C error.', 30: 'Too many errors, some have been suppressed.', 31: 'Firmware trap.', 90: 'Powered up.'}

get_all_values(para='V')

get_value(ch, para='I')

set_all_values(para='V', values=0)

Slice up set commands into vectors for each module, and transmit.

para: Parameter to set {‘V’ or ‘I’} values: Either float/int or list of float/int of length n_chs

set_value(ch, para='V', new=0)

qontrol.generic_log_handler(fatal_errors='all')

A generic log handler which can be passed to Qontroller instances to generate a RuntimeError every time an error in the list fatal_errors is reported by the hardware.

fatal_errors List of errors that should be raised.

‘all’ will raise every error encountered (default).

qontrol.run_interactive_shell(serial_port_name=None)

Shell for interacting directly with Qontrol hardware.