openflexure_stage.stage module

OpenFlexure Stage module

This Python code deals with the computer (Raspberry Pi) side of communicating with the OpenFlexure Motor Controller.

It is (c) Richard Bowman 2017 and released under GNU GPL v3

class openflexure_stage.stage.Endstops(available, parent=None, model='min')

Bases: openflexure_stage.basic_serial_instrument.OptionalModule

An optional module for use with endstops.

If endstops are installed in the firmware the openflexure_stage.OpenFlexureStage will gain an optional module which is an instance of this class. It can be used to retrieve the type, state of the endstops, read and write maximum positions, and home.

home(direction='min', axes=['x', 'y', 'z'])

Home given/all axes in the given direction (min/max/both)

Parameters:

• direction – one of {min,max,both}
• axes – list of axes e.g. [‘x’,’y’]

installed = []

maxima

Vector of maximum positions, homing to max endstops will measure this, can be set to a known value for use with max only and min+soft endstops

status

Get endstops status as {-1,0,1} for {min,no,max} endstop triggered for each axis

test_mode = False

List of installed endstop types (min, max, soft)

class openflexure_stage.stage.LightSensor(available, parent=None, model='Generic')

Bases: openflexure_stage.basic_serial_instrument.OptionalModule

An optional module giving access to the light sensor.

If a light sensor is enabled in the motor controller’s firmware, then the openflexure_stage.OpenFlexureStage will gain an optional module which is an instance of this class. It can be used to access the light sensor (usually via the I2C bus).

gain

“Get or set the current gain value of the light sensor.

Valid gain values are defined in the valid_gains property, and should be floating-point numbers.

integration_time

Get or set the integration time of the light sensor in milliseconds.

intensity

Read the current intensity measured by the light sensor (arbitrary units).

valid_gains = None

class openflexure_stage.stage.OpenFlexureStage(*args, **kwargs)

Bases: openflexure_stage.basic_serial_instrument.BasicSerialInstrument

Class managing serial communications with an Openflexure Motor Controller

The OpenFlexureStage class handles setting up communications with the stage, wraps the various serial commands in Python methods, and provides iterators and context managers to simplify opening/closing the hardware connection and some other tasks like conducting a linear scan.

Arguments to the constructor are passed to the constructor of openflexure_stage.basic_serial_instrument.BasicSerialInstrument, most likely the only one necessary is port which should be set to the serial port you will use to communicate with the motor controller.

This class can be used as a context manager, i.e. it’s encouraged to use it as:

with OpenFlexureStage() as stage:
    stage.move_rel([1000,0,0])

In that case, the serial port will automatically be closed at the end of the block, even if an error occurs. Otherwise, be sure to call the close() method to release the serial port.

axis_names = ('x', 'y', 'z')

The names of the stage’s axes. NB this also defines the number of axes.

backlash

The distance used for backlash compensation.

Software backlash compensation is enabled by setting this property to a value other than None. The value can either be an array-like object (list, tuple, or numpy array) with one element for each axis, or a single integer if all axes are the same.

The property will always return an array with the same length as the number of axes.

The backlash compensation algorithm is fairly basic - it ensures that we always approach a point from the same direction. For each axis that’s moving, the direction of motion is compared with backlash. If the direction is opposite, then the stage will overshoot by the amount in -backlash[i] and then move back by backlash[i]. This is computed per-axis, so if some axes are moving in the same direction as backlash, they won’t do two moves.

board = None

Once initialised, board is a string that identifies the firmware version.

focus_rel(z)

Move the stage in the Z direction by z micro steps.

list_modules()

Return a list of strings detailing optional modules.

Each module will correspond to a string of the form Module Name: Model

move_abs(final, **kwargs)

Make an absolute move to a position

NB the stage only accepts relative move commands, so this first queries the stage for its position, then instructs it to make about relative move.

move_rel(displacement, axis=None, backlash=True)

Make a relative move, optionally correcting for backlash.

displacement: integer or array/list of 3 integers axis: None (for 3-axis moves) or one of ‘x’,’y’,’z’ backlash: (default: True) whether to correct for backlash.

n_axes

The number of axes this stage has.

port_settings = {'baudrate': 115200, 'bytesize': 8, 'parity': 'N', 'stopbits': 1}

These are the settings for the stage’s serial port, and can usually be left as default.

position

Get the position of the stage as a tuple of 3 integers.

print_help()

Print the stage’s built-in help message.

query(message, *args, **kwargs)

Send a message and read the response. See BasicSerialInstrument.query()

ramp_time

Get or set the acceleration time in microseconds.

The stage will accelerate/decelerate between stationary and maximum speed over ramp_time microseconds. Zero means the stage runs at full speed initially, with no accleration control. Small moves may last less than 2*ramp_time, in which case the acceleration will be the same, but the stage will never reach full speed. It is saved to EEPROM on the Arduino, so it will be persistent even if the motor controller is turned off.

release_motors()

De-energise the stepper motor coils

scan_linear(rel_positions, backlash=True, return_to_start=True)

Scan through a list of (relative) positions (generator fn)

rel_positions should be an nx3-element array (or list of 3 element arrays). Positions should be relative to the starting position - not a list of relative moves.

backlash argument is passed to move_rel

if return_to_start is True (default) we return to the starting position after a successful scan. NB we always attempt to return to the starting position if an exception occurs during the scan..

scan_z(dz, **kwargs)

Scan through a list of (relative) z positions (generator fn)

This function takes a 1D numpy array of Z positions, relative to the position at the start of the scan, and converts it into an array of 3D positions with x=y=0. This, along with all the keyword arguments, is then passed to scan_linear.

step_time

Get or set the minimum time between steps of the motors in microseconds.

The step time is 1000000/max speed in steps/second. It is saved to EEPROM on the Arduino, so it will be persistent even if the motor controller is turned off.

supported_light_sensors = ['TSL2591', 'ADS1115']

This is a list of the supported light sensor module types.

test_mode

Get or set test mode

In test mode

• Stage may return extra information
• When homing, the stage will remain at the 0 position
• Position will not be reset when an endstop is hit