Welcome to TigerASI’s documentation!#

class tigerasi.tiger_controller.TigerController(com_port: str)#

Tiger Box Serial Port Abstraction.

Init. Creates serial port connection and connects to hardware.

Parameters:

com_port – serial com port.

box = TigerController('COM4')
halt(wait: bool = True)#

stop any moving axis.

move_relative(wait: bool = True, **axes: int)#

Move the axes specified by a corresponding relative amount (in tenths of microns). Unspecified axes will not be moved. Implements MOVEREL command.

Parameters:

axes – one or more axes specified by name where the value is the relative position (in steps) to move to.

box.move_relative(x=10, y=20)  # Move 1 micron in x and 2 in y
box.move_relative(z=100)  # Move 10 microns in z
move_absolute(wait: bool = True, **axes: int)#

move the axes specified by a corresponding absolute amount. (in tenths of microns). Unspecified axes will not be moved. Implements MOVE command.

Parameters:

axes – one or more axes specified by name where the value is the absolute position (in steps) to move to.

box.move_absolute(x=0, y=100)  # Move x and y axes to absolute location.
home(*axes: str, wait: bool = True)#

Move to the preset home position (or hard axis travel limit) for the specified axes. If the preset position is not reachable, move until a hardware stage limit is reached. Implements HOME command.

Note: Because the homing procedure may either reach the specified software limit or a hardware limit, it is not safe to assume that a stage axis is in the prespecified homing position upon finishing this routine.

box.home('x', 'y', 'z')  # home the specified axes.
set_home(*axes: str, wait: bool = True, **kwd_axes: float)#

Set the current or specified position to home to in [mm]. Implements SETHOME command.

Note: the values written here will persist across power cycles and adjust automatically such that the physical location remains constant.

Parameters:

  • axes – axes for which to specify the current position as home.

  • kwd_axes – axes for which to specify a particular position as home.

  • wait – wait until the reply has been received.

box.set_home('x', 'y', 'z')  # current position set as home OR
box.set_home(x=100, y=20.5, z=0)  # specific positions for home OR
box.set_home('x', y=20.5)  # mix of both.
reset_home(*axes: str, wait: bool = True)#

Restore home values of the axes specified to firmware defaults. Implements SETHOME command.

Note: the firmware default is intentionally an unreachable stage position such that each axis triggers its hardware stage limit.

get_home(*axes: str)#

Return the position to home to in [mm] for the specified axes or all axes if none are specified. Implements SETHOME command.

Note: the returned value will adjust automatically such that the physical location remains constant.

Parameters:

axes – the axes to get the machine frame home value for.

zero_in_place(*axes: str, wait: bool = True)#

Zero out the specified axes. (i.e: Set the specified axes current location to zero.)

Note: the returned value will adjust automatically such that the physical location remains constant.

box.zero_in_place('x', 'y')  # x and y axis' current locations are now zero.
set_position(wait: bool = True, **axes: float)#

Set the specified axes to the specified positions. Similar to zero_in_place(), but axes’ current location can be specified to any location.

Parameters:

axes – one or more axes specified by name where the value is the new absolute position (in steps).

box.set_position(x=10, y=50)  # Current position is now (x=10, y=50).
set_lower_travel_limit(*axes: str, wait: bool = True, **kwd_axes: float)#

Set the specified axes lower travel limits to the current position or to a specified position in [mm].

Note: the values written here will persist across power cycles and adjust automatically such that the physical location remains constant.

Parameters:

  • axes – axes to specify the current position as lower limit.

  • kwd_axes – axes to specify input position (in [mm]) as the lower limit.

  • wait – wait until the reply has been received.

box.set_lower_travel_limit('x', 'y')  # current positions as limit OR
box.set_lower_travel_limit(x=50, y=4.0)  # specific positions as limit OR
box.set_lower_travel_limit('x', y=20.5)  # mix of both.
get_lower_travel_limit(*axes: str)#

Get the specified axes’ lower travel limits in [mm] as a dict.

Note: the returned value will adjust automatically such that the physical location remains constant.

Note: dict keys for lettered axes are uppercase.

reset_lower_travel_limits(*axes: str, wait: bool = True)#

Restore lower travel limit on specified axes (or all if none are specified) to firmware defaults.

set_upper_travel_limit(*axes: str, wait: bool = True, **kwd_axes: float)#

Set the specified axes upper travel limits to the current position or to a specified position in [mm].

Note: the values written here will persist across power cycles and adjust automatically such that the physical location remains constant.

Parameters:

  • axes – axes to specify the current position as upper limit.

  • kwd_axes – axes to specify input position as the upper limit.

  • wait – wait until the reply has been received.

box.set_upper_travel_limit('x', 'y')  # current positions as limit OR
box.set_upper_travel_limit(x=50, y=4.0)  # specific positions as limit OR
box.set_upper_travel_limit('x', y=20.5)  # mix of both.
get_upper_travel_limit(*axes: str)#

Get the specified axes’ upper travel limits in [mm] as a dict.

Note: the returned value will adjust automatically such that the physical location remains constant.

Note: dict keys for lettered axes are uppercase.

reset_upper_travel_limits(*axes: str, wait: bool = True)#

Restore upper travel limit on specified axes (or all axes if none are specified) to firmware defaults.

set_axis_backlash(wait: bool = True, **axes: float)#

Set the backlash compensation value for one or more axes. Clear (i.e: disable) backlash compensation by writing 0 to that axis. A nonzero setting causes the corresponding axis to apply a backlash compensation routine where the axis oversteps by the specified amount such that the leadscrew is always being engaged from the same direction. The result is that a move will take ~25 extra milliseconds to complete.

Parameters:

  • axes – one or more axes specified by name where the value is the absolute position (in steps) to move to.

  • wait – wait until the reply has been received.

get_position(*axes: str)#

Return the controller’s locations for lettered (non-numeric) axes. Note: filter wheel positions are not accessible this way.

Parameters:

axes – one or more axes to request the current position from.

Returns:

a dict keyed by uppercase lettered axis whose value is the position (float).

box.get_position('x')  # returns: {'X': 10}
box.get_position('x', 'y')  # returns: {'X': 10, 'Y': 50}
set_speed(wait: bool = True, **axes: float)#

Set one or more axis speeds to a value in [mm/sec]. Implements SPEED command.

Parameters:

  • axes – one or more axes specified by name where the value is the speed in [mm/sec].

  • wait – wait until the reply has been received.

box.set_speed(x=50.5, y=10)
get_speed(*axes: str)#

return the speed from the specified axis in [mm/s] or all axes if none are specified.

Parameters:

axes – one or more lettered axes (case insensitive).

Returns:

speed of requested axes in dict form (upper case).

box.get_speed('x', 'z')  # returns: {'X': 50.5, 'Y': 10}
set_acceleration(**axes: float)#

Set one or more axis accelerations to a value in [ms]. Implements ACCEL command.

Parameters:

  • axes – one or more axes specified by name where the value is the acceleration in [ms].

  • wait – wait until the reply has been received.

box.set_acceleration(x=100, y=70)
get_acceleration(*axes: str)#

return the acceleration from the specified axis in [ms] or all axes if none are specified.

Parameters:

axes – one or more lettered axes (case insensitive).

Returns:

speed of requested axes in dict form (upper case).

box.get_acceleration('x', 'z')  # returns: {'X': 100, 'Y': 70}
bind_axis_to_joystick_input(**axes: JoystickInput)#

Map a tiger axis to a joystick input. Implements J command.

Note: binding a tigerbox stage axis to a joystick input does not affect the direction of the input. To change the direction, you must use the physical DIP switches on the back of the Tigerbox card.

Note: binding a tigerbox stage axis to a joystick input also enables it.

Parameters:

axes – one or more (case-insensitive) axes where the values are JoystickInput enums.

from tigerasi.device_codes import JoystickInput

box.bind_axis_to_joystick(x=JoystickInput.Y,
                          y=JoystickInput.CONTROL_KNOB)
get_joystick_axis_mapping(*axes: str)#

Get the axis mapping currently set on the joystick for the requested axes (or all if none are requested). Implements. J command.

Returns:

a dict, keyed by (upper-case) axis, who’s values are of type JoystickInput representing the assigned joystick input.

set_joystick_axis_polarity(**axes: JoystickPolarity)#

Set the joystick polarity of the axes specified. Implements J command.

box.set_joystick_polarity(x=JoystickPolarity.DEFAULT,
                          y=JoystickPolarity.INVERTED)
enable_joystick_inputs(*axes: str)#

Enable specified (or all if none are specified) axis control through the joystick. Implements J command.

Parameters:

axes – one or more axes to re-enable joystick control for (or all if none are specified).

box.enable_joystick_inputs('y')  # Enable joystick control of y axis.
box.enable_joystick_inputs()  # Enable joystick control of all axes.

Note: enabling joystick inputs will re-apply their default axis mapping. To disable/enable joystick inputs with a custom axis mapping, you must save the current axis mapping before disabling joystick inputs and then reapply it after enabling joystick inputs.

axis_map = box.get_joystick_axis_mapping()  # Get current axis map for all axes.
box.disable_joystick_inputs()  # Disable all joystick inputs.
box.enable_joystick_inputs()  # Enable all joystick inputs. Default axis map is applied.
box.bind_axis_to_joystick_input(**axis_map)  # Reapply original axis map for all axes.
disable_joystick_inputs(*axes: str)#

Disable specified (or all if none are specified) axis control through the joystick. Implements J command.

Parameters:

args – one or more axes to disable joystick control for (or all if none are specified).

get_encoder_ticks_per_mm(axis: str)#

Get <encoder ticks> / <mm of travel> for the specified axis. Implements CNTS command.

get_axis_id(axis: str)#

Get the hardware’s axis id for a given axis.

Note: some methods require that the axis is specified by id.

Parameters:

axis – the axis of interest.

Returns:

the axis id of the specified axis.

set_axis_control_mode(wait: bool = True, **axes: MicroMirrorControlMode | PiezoControlMode | TunableLensControlMode | int | str)#

Set an axis to a particular control mode. Implements PM command.

Note: Setting an axis to external control enables control from the external TTL input port on the device hardware.

Parameters:

  • axes – one or more axis control modes specified by key where the values are either a string, int, or one of these three enum types: MicroMirrorControlMode, PiezoControlMode, or TunableLensControlMode.

  • wait – wait until the reply has been received.

get_axis_control_mode(axis: str)#

Get axis control mode. Implements PM command.

Parameters:

axis – the axis of interest.

Returns:

control mode (as a string) of the specified axis.

setup_scan(fast_axis: str, slow_axis: str, pattern: ScanPattern = ScanPattern.RASTER, wait: bool = True)#

setup scan pattern and define axes used for scanning. See ASI SCAN Implementation for more details.

Note: fast and slow scan axes must be on the same tiger card.

Parameters:

  • fast_axis – the axis declared as the fast-scan axis.

  • slow_axis – the axis declared as the slow-scan axis.

  • pattern – ScanPattern enum. If unspecified, defaults to RASTER.

  • wait – wait until the reply has been received.

scanr(scan_start_mm: float, pulse_interval_um: float, scan_stop_mm: float | None = None, num_pixels: int | None = None, retrace_speed_percent: int = 67.0, wait: bool = True)#

Setup the fast scanning axis start position and distance OR start position and number of pixels. To setup a scan, either scan_stop_mm or num_pixels must be specified, but not both. See ASI SCANR Implementation for more details.

Note: setup_scan() must be run first.

Parameters:

  • scan_start_mm – absolute position to start the scan.

  • pulse_interval_um – spacing (in [um]) between output pulses. i.e: a pulse will output every pulse_interval_um. Note that this value will be rounded to the nearest encoder tick. To set scan spacing to an exact encoder tick value, check get_encoder_ticks_per_mm(). The logger will log a warning if the actual value in [um] was rounded.

  • scan_stop_mm – absolute position to stop the scan. If unspecified, num_pixels is required.

  • num_pixels – number of pixels to output a pulse for. If unspecified, scan_stop_mm is required.

  • retrace_speed_percent – percentage (0-100) of how fast to backtract to the scan start position after finishing a scan.

  • wait – wait until the reply has been received.

scanv(scan_start_mm: float, scan_stop_mm: float, line_count: int, overshoot_time_ms: int | None = None, overshoot_factor: float | None = None, wait: bool = True)#

Setup the slow scanning axis.

Behavior is equivalent to: numpy.linspace(scan_start_mm, scan_stop_mm, line_count, endpoint=False). See ASI SCANV Implementation for more details.

Note: setup_scan() must be run first.

Parameters:

  • scan_start_mm – absolute position to start the scan in the slow axis dimension.

  • scan_stop_mm – absolute position to stop the scan in the slow axis dimension.

  • line_count – how many lines to scan on the slow axis.

  • overshoot_time_ms – extra time (in ms) for the stage to settle (in addition to the current time set by the AC command.)

  • overshoot_factor – scalar multiplier (default: 1.0) to add distance to the start and stop of a scan before initiating the starting of pulses.

  • wait – wait until the reply has been received.

start_scan(wait: bool = True)#

Start a scan that has been previously setup with scanr() scanv() and setup_scan().

stop_scan(wait: bool = True)#

Stop an active scan.

setup_array_scan(x_points: int = 0, delta_x_mm: float = 0, y_points: int = 0, delta_y_mm: float = 0, theta_deg: float = 0, x_start_mm: int | None = None, y_start_mm: int | None = None, pattern: ScanPattern = ScanPattern.RASTER, card_address: int | None = None, wait: bool = True)#

Configure Tiger-based grid-like array scan. See ASI ARRAY Implementation and supplement for more details.

Note: ASI docs recommend turning off backlash compensation on the scan axes, which can be done by setting compensation to zero (per axis) via the set_axis_backlash() method.

Parameters:

  • x_points – number of x points to visit including the start location. Zero if left unspecified.

  • delta_x_mm – spacing (in [mm]) between movements. Zero if left unspecified.

  • y_points – number of y points to visit including the start location. Zero if left unspecified.

  • delta_y_mm – spacing (in [mm]) between movements. Zero if left unspecified.

  • theta_deg – rotation from the x axis in [degrees] to rotate the array scan pivoting from the start position.

  • x_start_mm – starting x axis location in [mm]. Current x position if left unspecified.

  • y_start_mm – starting y axis location in [mm]. Current y position if left unspecified

  • pattern – ScanPattern enum. If unspecified, defaults to RASTER.

  • card_address – The card hex address on which to specify the move. If unspecified, defaults to the only card with an x and y axis or throws a RuntimeError if multiple xy cards or no xy cards exist.

  • wait – wait until the reply has been received.

start_array_scan(wait: bool = True)#

Start an array scan with parameters set by setup_array_scan(). Note that this command is not needed if the scan is setup for external TTL pin triggering.

Note: setup_array_scan() must be run first.

Parameters:

wait – wait until the reply has been received.

reset_ring_buffer(wait: bool = True)#

Clear the ring buffer contents.

setup_ring_buffer(*axes: str, mode: RingBufferMode = RingBufferMode.TTL, wait: bool = True)#

Setup the ring buffer. Implements RBMODE command.

Parameters:

  • axes – any number of axis names which will be enabled to move via moves queued into the ring buffer.

  • mode – ring buffer mode specified as a RingBufferMode enum.

  • wait – wait until the reply has been received.

queue_buffered_move(wait: bool = True, **axes: float)#

Push a move (relative or absolute depends on context) into the ring buffer.

Note: if using TTL external input triggering, the TTL pin mode dictates whether the moves are absolute or relative. Mode can be set via: set_ttl_pin_modes(). MOVE_TO_NEXT_ABS_POSITION will interpret stored moves in the buffer as absolute moves while MOVE_TO_NEXT_REL_POSITION will interpret stored moves in the buffer as relative moves.

Note: the ‘axis_byte’ parameter must be set correctly such that the axes specified in the move are enabled to move.

Parameters:

  • axes – one or more axes specified by name where the value is the absolute position (in steps) to move to.

  • wait – wait until the reply has been received.

set_ttl_pin_modes(in0_mode: TTLIn0Mode | None = None, out0_mode: TTLOut0Mode | None = None, reverse_output_polarity: bool = False, aux_io_state: int | None = None, aux_io_mask: int | None = None, aux_io_mode: int | None = None, card_address: int | None = None, wait: bool = True)#

Setup ttl external IO modes or query the external output state (if the card specified without any additional arguments).

See ASI TTL Implementation for more details.

Parameters:

  • in0_mode – Set behavior of “IN” external TTL input pin. Optional if in0_mode is set to REPEAT_LAST_MOVE.

  • out0_mode – Set behavior of “OUT” external TTL output pin. Optional if in0_mode is set to REPEAT_LAST_MOVE.

  • reverse_output_polarity – bool. If True, output goes logic low when the output is asserted. Optional. Defaults to False.

  • aux_io_state – Set to 0 if unused. Retains previous value if left unspecified. See ASI docs.

  • aux_io_mask – Set to 0 if unused. Retains previous value if left unspecified. See ASI docs.

  • aux_io_mode – Set what determines TTL value when set as outputs. Set to 0 if unused. Retains previous value if left unspecified. See ASI docs.

  • card_address – The card hex address for which to apply the settings. Optional if in0_mode is set to REPEAT_LAST_MOVE, ARRAY_MODE_MOVE_TO_NEXT_POSITION, MOVE_TO_NEXT_ABS_POSITION, or MOVE_TO_NEXT_REL_POSITION.

  • wait – wait until the reply has been received.

from tiger_controller.device_codes import TTLIN0Mode as IN0Mode
from tiger_controller.device_codes import TTLOUT0Mode as OUT0Mode

# Make the input ttl pin repeat the last move.
box.set_ttl_pin_modes(In0Mode.REPEAT_LAST_REL_MOVE,
                      Out0Mode.PULSE_AFTER_MOVING,
                      reverse_output_polarity=True)

# OR: make the input ttl pin trigger a predefined ARRAY movement.
box.set_ttl_pin_modes(IN0Mode.ARRAY_MODE_MOVE_TO_NEXT_POSITION,
                      Out0Mode.PULSE_AFTER_MOVING,
                      aux_io_state = 0, aux_io_mask = 0, aux_io_mode = 0)
get_ttl_pin_modes(card_address: int, wait: bool = True)#

Get the current TTL settings for a particular card.

get_ttl_output_state(wait: bool = True)#

Return the current state of the TTL output pin.

is_moving()#

True if any axes is moving. False otherwise. Blocks.

is_axis_moving(axis: str)#

True if the specified axis is moving. False otherwise. Blocks.

are_axes_moving(*axes: str)#

Return a dict of booleans, keyed by axis, indicating whether the specified axes are (True) or are not (False) moving. Defaults to all lettered axes if none are specified. Blocks. Implements RDSTAT command.

wait()#

Block until tigerbox is idle.

wait_on_axis(*axes: str)#

Block until specified axis is idle.

clear_incoming_message_queue()#

Clear input buffer and reset skipped replies.

send(cmd_str: str, read_until: str = '\r\n', wait: bool = True)#
Send a command; optionally wait for various conditions.
param cmd_str:

command string with parameters and the proper line termination (usually ‘

‘) to send to the tiger controller.
param read_until:

the specific string to read until when reading back the response. (Default is fine for Tiger-based devices, but some filter wheels have a different response termination.)

param wait:

wait until the reply has been received.

get_info(axis: str)#

Get the hardware’s axis info for a given axis. Implements INFO command.

Parameters:

axis – the axis of interest.

Returns:

the axis info of the specified axis.

get_etl_temp(axis: str, wait: bool = True)#

Get the etl temperature for a given axis.

Parameters:

axis – the axis of interest.

Returns:

etl temperature of the specified axis.

get_build_config()#

return the configuration of the Tiger Controller.

Returns:

a dict that looks like:

{'Axis Addr': [],
 'Axis Props': ['74', '10', '2', etc.], # these are positions
 'Axis Types': ['x', 'x', 'z', etc],
 'Hex Addr': [],
 'Motor Axes': ['X', 'Y', 'Z', etc]}
get_pzinfo(card_address: int)#

return the configuration of the specified card.

Returns:

a dict

static check_reply_for_errors(reply: str)#

Check if reply contains an error code; returns None or throws exception.

enum tigerasi.device_codes.Cmds(value)#

An enumeration.

Valid values are as follows:

BUILD_X = <Cmds.BUILD_X: 'BU X'>#
CCA = <Cmds.CCA: 'CCA'>#
HALT = <Cmds.HALT: '\\'>#
STATUS = <Cmds.STATUS: '/'>#
RDSTAT = <Cmds.RDSTAT: 'RS'>#
MOVEREL = <Cmds.MOVEREL: 'R'>#
MOVEABS = <Cmds.MOVEABS: 'M'>#
HOME = <Cmds.HOME: '!'>#
HERE = <Cmds.HERE: 'H'>#
WHERE = <Cmds.WHERE: 'W'>#
BACKLASH = <Cmds.BACKLASH: 'B'>#
ARRAY = <Cmds.ARRAY: 'AR'>#
AHOME = <Cmds.AHOME: 'AH'>#
LOAD = <Cmds.LOAD: 'LD'>#
CNTS = <Cmds.CNTS: 'CNTS'>#
J = <Cmds.J: 'J'>#
JS = <Cmds.JS: 'JS'>#
RBMODE = <Cmds.RBMODE: 'RM'>#
SCAN = <Cmds.SCAN: 'SCAN'>#
SCANR = <Cmds.SCANR: 'SCANR'>#
SCANV = <Cmds.SCANV: 'SCANV'>#
SETHOME = <Cmds.SETHOME: 'HM'>#
SETLOW = <Cmds.SETLOW: 'SL'>#
SETUP = <Cmds.SETUP: 'SU'>#
SPEED = <Cmds.SPEED: 'S'>#
TTL = <Cmds.TTL: 'TTL'>#
PM = <Cmds.PM: 'PM'>#
PZINFO = <Cmds.PZINFO: 'PZINFO'>#
Z2B = <Cmds.Z2B: 'Z2B'>#
INFO = <Cmds.INFO: 'INFO'>#
ACCEL = <Cmds.ACCEL: 'AC'>#
enum tigerasi.device_codes.ErrorCodes(value)#

An enumeration.

Valid values are as follows:

UNKNOWN_CMD = <ErrorCodes.UNKNOWN_CMD: ':N-1'>#
UNRECOGNIZED_AXIS_PARAMETER = <ErrorCodes.UNRECOGNIZED_AXIS_PARAMETER: ':N-2'>#
MISSING_PARAMETERS = <ErrorCodes.MISSING_PARAMETERS: ':N-3'>#
PARAMETER_OUT_OF_RANGE = <ErrorCodes.PARAMETER_OUT_OF_RANGE: ':N-4'>#
OPERATION_FAILED = <ErrorCodes.OPERATION_FAILED: ':N-5'>#
UNDEFINED_ERROR = <ErrorCodes.UNDEFINED_ERROR: ':N-6'>#
INVALID_CARD_ADDRESS = <ErrorCodes.INVALID_CARD_ADDRESS: ':N-7'>#
RESERVED_8 = <ErrorCodes.RESERVED_8: ':N-8'>#
RESERVED_9 = <ErrorCodes.RESERVED_9: ':N-9'>#
RESERVED_10 = <ErrorCodes.RESERVED_10: ':N-10'>#
FILTERWHEEL_RESERVED_11 = <ErrorCodes.FILTERWHEEL_RESERVED_11: ':N-11'>#
FILTERWHEEL_RESERVED_12 = <ErrorCodes.FILTERWHEEL_RESERVED_12: ':N-12'>#
FILTERWHEEL_RESERVED_13 = <ErrorCodes.FILTERWHEEL_RESERVED_13: ':N-13'>#
FILTERWHEEL_RESERVED_14 = <ErrorCodes.FILTERWHEEL_RESERVED_14: ':N-14'>#
FILTERWHEEL_RESERVED_15 = <ErrorCodes.FILTERWHEEL_RESERVED_15: ':N-15'>#
FILTERWHEEL_RESERVED_16 = <ErrorCodes.FILTERWHEEL_RESERVED_16: ':N-16'>#
FILTERWHEEL_RESERVED_17 = <ErrorCodes.FILTERWHEEL_RESERVED_17: ':N-17'>#
FILTERWHEEL_RESERVED_18 = <ErrorCodes.FILTERWHEEL_RESERVED_18: ':N-18'>#
FILTERWHEEL_RESERVED_19 = <ErrorCodes.FILTERWHEEL_RESERVED_19: ':N-19'>#
FILTERWHEEL_RESERVED_20 = <ErrorCodes.FILTERWHEEL_RESERVED_20: ':N-20'>#
SERIAL_CMD_HALTED = <ErrorCodes.SERIAL_CMD_HALTED: ':N-21'>#

Indices and tables#