sangaboard.extensible_serial_instrument module

This module has been modified from the chopped-out of class from nplab_. It is a serial instrument class to simplify the process of interfacing with equipment that talks on a serial port. The idea is that your instrument can subclass ExtensibleSerialInstrument and provide methods to control the hardware, which will mostly consist of self.query() commands. It also has options for adding OptionalModules so that you don’t have to have multiple classes for lots of instruments with different configurations

The QueriedProperty class is a convenient shorthand to create a property that is read and/or set with a single serial query (i.e. a read followed by a write).

sangaboard.extensible_serial_instrument.list_serial_ports()

List available serial ports, including a workaround for Raspberry Pi

The built-in list of com ports misses the RPi hardware serial port. This workaround explicitly checks for it, and includes it if present.

class sangaboard.extensible_serial_instrument.ExtensibleSerialInstrument(port=None, **kwargs)

Bases: object

An instrument that communicates by sending strings back and forth over serial

This base class provides commonly-used mechanisms that support the use of serial instruments. Most interactions with this class involve a call to the query method. This writes a message and returns the reply. This has been hacked together from the nplab_ MessageBusInstrument and SerialInstrument classes.

Threading Notes

The message bus protocol includes a property, communications_lock. All commands that use the communications bus should be protected by this lock. It’s also permissible to use it to protect sequences of calls to the bus that must be atomic (e.g. a multi-part exchange of messages). However, try not to hold it too long - or odd things might happen if other threads are blocked for a long time. The lock is reentrant so there’s no issue with acquiring it twice.

termination_character = '\n'

termination_line = None

ignore_echo = False

port_settings = {}

port_settings_list = None

open(port=None, quiet=True)

Open communications with the serial port.

If no port is specified, it will attempt to autodetect. If quiet=True then we don’t warn when ports are opened multiple times.

close()

Cleanly close the device. Includes proper logging statements.

write(query_string)

Write a string to the serial port

flush_input_buffer()

Clear the input buffer.

Make sure there’s nothing waiting to be read, and clear the buffer if there is.

readline(timeout=None)

Read one line from the serial port.

property communications_lock

A lock object used to protect access to the communications bus

read_multiline(termination_line=None, timeout=None)

Read one line from the underlying bus. Must be overriden.

This should not need to be reimplemented unless there’s a more efficient way of reading multiple lines than multiple calls to readline().

query(query_string, multiline=False, termination_line=None, timeout=None)

Write a string to the stage controller and return its response.

It will block until a response is received. The multiline and termination_line commands will keep reading until a termination phrase is reached.

parsed_query(query_string, response_string='%d', re_flags=0, parse_function=None, **kwargs)

Perform a query, returning a parsed form of the response.

First query the instrument with the given query string, then compare the response against a template. The template may contain text and placeholders (e.g. %i and %f for integer and floating point values respectively). Regular expressions are also allowed - each group is considered as one item to be parsed. However, currently it’s not supported to use both % placeholders and regular expressions at the same time.

If placeholders %i, %f, etc. are used, the returned values are automatically converted to integer or floating point, otherwise you must specify a parsing function (applied to all groups) or a list of parsing functions (applied to each group in turn).

int_query(query_string, **kwargs)

Perform a query and return the result(s) as integer(s) (see parsedQuery)

float_query(query_string, **kwargs)

Perform a query and return the result(s) as float(s) (see parsedQuery)

test_communications()

Check if the device is available on the current port.

This should be overridden by subclasses. Assume the port has been successfully opened and the settings are as defined by self.port_settings. Usually this function sends a command and checks for a known reply.

find_port()

Find the first serial port where we can establish communications.

Iterate through the available serial ports and query them to see if our instrument is there. If a list of settings is provided in self.port_settings_list we will try each configuration in turn.

class sangaboard.extensible_serial_instrument.OptionalModule(available, parent=None, module_type='Undefined', model='Generic')

Bases: object

This allows a ExtensibleSerialInstrument to have optional features.

OptionalModule is designed as a base class for interfacing with optional modules which may or may not be included with the serial instrument, and can be added or removed at run-time.

property available

confirm_available()

Check if module is available.

Raises exception if not available.

describe()

Consistently spaced desciption for listing modules

class sangaboard.extensible_serial_instrument.QueriedProperty(get_cmd=None, set_cmd=None, validate=None, valrange=None, fdel=None, doc=None, response_string=None, ack_writes='no')

Bases: object

A Property interface that reads and writes from the instrument on the bus.

This returns a property-like (i.e. a descriptor) object. You can use it in a class definition just like a property. The property it creates will interact with the instrument over the communication bus to set and retrieve its value. It uses calls to ExtensibleSerialInstrument.parsed_query to set or get the value of the property.

QueriedProperty can be used to define properties on a ExtensibleSerialInstrument or an OptionalModule (in which case the ExtensibleSerialInstrument.parsed_query method of the parent object will be used).

Arguments:

Get_cmd:

the string sent to the instrument to obtain the value

Set_cmd:

the string used to set the value (use {} or % placeholders)

Validate:

a list of allowable values

Valrange:

a maximum and minimum value

Fdel:

a function to call when it’s deleted

Doc:

the docstring

Response_string:

supply a % code (as you would for response_string in a ExtensibleSerialInstrument.parsed_query)

Ack_writes:

set to “readline” to discard a line of input after writing.