openflexure_stage.basic_serial_instrument module

This module defines a chopped-out class from nplab. It is a basic 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 BasicSerialInstrument and provide methods to control the hardware, which will mostly consist of self.query() commands.

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).

class openflexure_stage.basic_serial_instrument.BasicSerialInstrument(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.

close()

Release the serial port

communications_lock

A lock object used to protect access to the communications bus

find_port()

Iterate through the available serial ports and query them to see if our instrument is there.

float_query(query_string, **kwargs)

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

flush_input_buffer()

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

ignore_echo = False

int_query(query_string, **kwargs)

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

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.

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).

port_settings = {}

query(queryString, 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.

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().

readline(timeout=None)

Read one line from the serial port.

termination_character = '\n'

All messages to or from the instrument end with this character.

termination_line = None

If multi-line responses are recieved, they must end with this string

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.

write(query_string)

Write a string to the serial port

class openflexure_stage.basic_serial_instrument.OptionalModule(available, parent=None, module_type='Undefined', model='Generic')

Bases: object

This allows a BasicSerialInstrument 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.

available

confirm_available()

Check if module is available, no return, will raise exception if not available!

describe()

Consistently spaced desciption for listing modules

class openflexure_stage.basic_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 BasicSerialInstrument.parsed_query to set or get the value of the property.

QueriedProperty can be used to define properties on a BasicSerialInstrument or an OptionalModule (in which case the BasicSerialInstrument.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 BasicSerialInstrument.parsed_query) Ack_writes:set to “readline” to discard a line of input after writing.