thorlabs_apt_device.devices.aptdevice_motor module

class thorlabs_apt_device.devices.aptdevice_motor.APTDevice_BayUnit(serial_port=None, vid=None, pid=None, manufacturer=None, product=None, serial_number=None, location=None, x=1, home=True, invert_direction_logic=False, swap_limit_switches=True, status_updates='none')[source]

Bases: APTDevice_Motor_Trigger

A class for ThorLabs APT bay-type device models BBD10x, BBD20x, BSC10x, BSC20x, where x is the number of channels (1, 2 or 3).

It is based off APTDevice_Motor_Trigger with some customisation for the specifics of the device.

Note that the bay-type devices such as BBD and BSCs are referred to as a x-channel controllers, but the actual device layout is that the controller is a “rack” system with three bays, where x number of single-channel controller cards may be installed. In other words, the BBD203 “3 channel” controller actually has 3 populated bays (bays=(EndPoint.BAY0, EndPoint.BAY1, EndPoint.BAY2)), each of which only controls a single channel (channels=(1,)).

The parameter x configures the number of channels. If x=1 it is a single bay/channel controller, and aliases of status = status_[0][0] etc are created for convenience.

Parameters:

  • x – Number of channels the device controls.

  • serial_port – Serial port device the device is connected to.

  • vid – Numerical USB vendor ID to match.

  • pid – Numerical USB product ID to match.

  • manufacturer – Regular expression to match to a device manufacturer string.

  • product – Regular expression to match to a device product string.

  • serial_number – Regular expression to match to a device serial number.

  • home – Perform a homing operation on initialisation.

  • invert_direction_logic – Invert the meaning of “forward” and “reverse” directions.

  • swap_limit_switches – Swap “forward” and “reverse” limit switch values.

  • status_updates – Set to "auto", "polled" or "none" (default).

genmoveparams

Alias to first bay/channel of genmoveparams_

homeparams

Alias to first bay/channel of homeparams_

jogparams

Alias to first bay/channel of jogparams_

status

Alias to first bay/channel of status_.

trigger

Alias to first bay/channel of trigger_

velparams

Alias to first bay/channel of velparams_

class thorlabs_apt_device.devices.aptdevice_motor.APTDevice_Motor(serial_port=None, vid=None, pid=None, manufacturer=None, product=None, serial_number=None, location=None, home=True, invert_direction_logic=False, swap_limit_switches=False, status_updates='none', controller=EndPoint.RACK, bays=(EndPoint.BAY0,), channels=(1,))[source]

Bases: APTDevice

Initialise and open serial device for a ThorLabs APT controller based on a DC motor drive, such as a linear translation stage.

Parameters:

  • serial_port – Serial port device the device is connected to.

  • vid – Numerical USB vendor ID to match.

  • pid – Numerical USB product ID to match.

  • manufacturer – Regular expression to match to a device manufacturer string.

  • product – Regular expression to match to a device product string.

  • serial_number – Regular expression to match to a device serial number.

  • location – Regular expression to match to a device bus location.

  • home – Perform a homing operation on initialisation.

  • invert_direction_logic – Invert the meaning of “forward” and “reverse”.

  • swap_limit_switches – Swap “forward” and “reverse” limit switch values.

  • status_updates – Set to "auto", "polled" or "none".

  • controller – The destination EndPoint for the controller.

  • bays – Tuple of EndPoint(s) for the populated controller bays.

  • channels – Tuple of indices (1-based) for the controller bay’s channels.

close()[source]

Stop the device and close the serial connection to the ThorLabs APT controller.

home(bay=0, channel=0)[source]

Home the device.

Parameters:

  • bay – Index (0-based) of controller bay to send the command.

  • channel – Index (0-based) of controller bay channel to send the command.

move_absolute(position=None, now=True, bay=0, channel=0)[source]

Perform an absolute move.

Parameters:

  • position – Movement destination in encoder steps.

  • now – Perform movement immediately, or wait for subsequent trigger.

  • bay – Index (0-based) of controller bay to send the command.

  • channel – Index (0-based) of controller bay channel to send the command.

move_jog(direction='forward', bay=0, channel=0)[source]

Start a jog movement in the specified direction.

Direction can be specified as boolean, string or numerical:

  • False is reverse and True is forward.

  • reverse is reverse and any other string is forward.

  • 0 or 2 (or any even number) is reverse and 1 (or any odd number) is forward.

Parameters:

  • direction – Direction to move (forward or reverse).

  • bay – Index (0-based) of controller bay to send the command.

  • channel – Index (0-based) of controller bay channel to send the command.

move_relative(distance=None, now=True, bay=0, channel=0)[source]

Perform a relative move.

Parameters:

  • distance – Movement amount in encoder steps.

  • now – Perform movement immediately, or wait for subsequent trigger.

  • bay – Index (0-based) of controller bay to send the command.

  • channel – Index (0-based) of controller bay channel to send the command.

move_velocity(direction='forward', bay=0, channel=0)[source]

Start a movement at constant velocity in the specified direction.

Direction can be specified as boolean, string or numerical:

  • False is reverse and True is forward.

  • reverse is reverse and any other string is forward.

  • 0 or 2 (or any even number) is reverse and 1 (or any odd number) is forward.

Parameters:

  • direction – Direction to move (forward or reverse).

  • bay – Index (0-based) of controller bay to send the command.

  • channel – Index (0-based) of controller bay channel to send the command.

set_enabled(state=True, bay=0, channel=0)[source]

Enable or disable a device.

Parameters:

  • state – Set to True for enable, False for disabled.

  • bay – Index (0-based) of controller bay to send the command.

  • channel – Index (0-based) of controller bay channel to send the command.

set_home_params(velocity, offset_distance, direction='reverse', bay=0, channel=0)[source]

Set parameters for homing commands.

Parameters:

  • velocity – Velocity for homing operations.

  • offset_distance – Distance of home position from the home limit switch.

  • direction – Direction for homing movement. Set to "forward" or "reverse".

  • bay – Index (0-based) of controller bay to send the command.

  • channel – Index (0-based) of controller bay channel to send the command.

set_jog_params(size, acceleration, max_velocity, continuous=False, immediate_stop=False, bay=0, channel=0)[source]

Configure the parameters for jogging movements.

Parameters:

  • size – Size of movement in encoder counts.

  • acceleration – Acceleration in counts/second/second.

  • max_velocity – Maximum velocity in counts/second.

  • continuous – Continuous movement, or single step.

  • immediate_stop – Stop immediately, or using the profiled velocity curves.

  • bay – Index (0-based) of controller bay to send the command.

  • channel – Index (0-based) of controller bay channel to send the command.

set_move_params(backlash_distance, bay=0, channel=0)[source]

Set parameters for generic move commands, currently only the backlash compensation distance.

Parameters:

  • backlash_distance – Backlash compensation distance in encoder counts.

  • bay – Index (0-based) of controller bay to send the command.

  • channel – Index (0-based) of controller bay channel to send the command.

set_velocity_params(acceleration, max_velocity, bay=0, channel=0)[source]

Configure the parameters for movement velocity.

Parameters:

  • acceleration – Acceleration in counts/second/second.

  • max_velocity – Maximum velocity in counts/second.

  • bay – Index (0-based) of controller bay to send the command.

  • channel – Index (0-based) of controller bay channel to send the command.

stop(immediate=False, bay=0, channel=0)[source]

Stop any current movement.

Parameters:

  • immediate – Stop immediately, or using the profiled velocity curves.

  • bay – Index (0-based) of controller bay to send the command.

  • channel – Index (0-based) of controller bay channel to send the command.

genmoveparams_

Array of dictionaries of general move parameters.

As a device may have multiple card bays, each with multiple channels, this data structure is an array of array of dicts. The first axis of the array indexes the bay, the second indexes the channel.

The only documented parameter is the backlash compensation move distance, "backlash_distance", measured in encoder counts.

homeparams_

Array of dictionaries of jog parameters.

As a device may have multiple card bays, each with multiple channels, this data structure is an array of array of dicts. The first axis of the array indexes the bay, the second indexes the channel.

Keys are "home_dir", "limit_switch", "home_velocity", and "offset_distance".

invert_direction_logic

On some devices, “forward” velocity moves towards negative encoder counts. If that seems opposite to what is expected, this flag allows inversion of that logic. This will also swap the meaning of the "moving_forward" and "moving_reverse" fields in the status_ flags.

jogparams_

Array of dictionaries of jog parameters.

As a device may have multiple card bays, each with multiple channels, this data structure is an array of array of dicts. The first axis of the array indexes the bay, the second indexes the channel.

Keys are "jog_mode", "step_size", "min_velocity", "acceleration", "max_velocity", and "stop_mode".

status_

Array of dictionaries of status information for the bays and channels of the device.

As a device may have multiple card bays, each with multiple channels, this data structure is an array of array of dicts. The first axis of the array indexes the bay, the second indexes the channel. For example, stage.status_[0][1] will return the status dictionary for the first bay, second channel.

Keys for the dictionary are "position", "velocity", "forward_limit_switch", "reverse_limit_switch", "moving_forward", "moving_reverse", "jogging_forward", "jogging_reverse", "motor_connected", "homing", "homed", "tracking", "interlock", "settled", "motion_error", "motor_current_limit_reached", and "channel_enabled". Note that not all keys are relevant to every device.

The documentation states that position is measured in encoder counts, but velocity is returned in real units of mm/second.

Additionally, information about the most recent status message which updated the dictionary are also available as "msgid", "source", "dest", and "chan_ident".

swap_limit_switches

On some devices, the “forward” limit switch triggers when hitting the limit in the negative encoder count direction, and the “reverse” limit switch triggers towards positive encoder counts. If that seems opposite to what is expected, this flag swaps the values of the "forward_limit_switch" and "reverse_limit_switch" fields in the status flags.

Note that this is independent of invert_direction_logic. A stage may report it is “moving forward” (towards either positive or negative encoder counts), and then trigger the “reverse” limit switch.

velparams_

Array of dictionaries of velocity parameters.

As a device may have multiple card bays, each with multiple channels, this data structure is an array of array of dicts. The first axis of the array indexes the bay, the second indexes the channel.

Keys are "min_velocity", "max_velocity", and "acceleration". Units are encoder counts/second for velocities and counts/second/second for acceleration.

class thorlabs_apt_device.devices.aptdevice_motor.APTDevice_Motor_Trigger(serial_port=None, vid=None, pid=None, manufacturer=None, product=None, serial_number=None, location=None, home=True, invert_direction_logic=False, swap_limit_switches=False, status_updates='none', controller=EndPoint.RACK, bays=(EndPoint.BAY0,), channels=(1,))[source]

Bases: APTDevice_Motor

A class for the ThorLabs APT device motor-driven families BSC, BBD, TBD and KBD.

It is based off APTDevice_Motor, but adds the trigger control capabilities.

Parameters:

  • serial_port – Serial port device the device is connected to.

  • vid – Numerical USB vendor ID to match.

  • pid – Numerical USB product ID to match.

  • manufacturer – Regular expression to match to a device manufacturer string.

  • product – Regular expression to match to a device product string.

  • serial_number – Regular expression to match to a device serial number.

  • home – Perform a homing operation on initialisation.

  • invert_direction_logic – Invert the meaning of “forward” and “reverse” directions.

  • swap_limit_switches – Swap “forward” and “reverse” limit switch values.

  • status_updates – Set to "auto", "polled" or "none".

set_trigger(input_edge=None, input_mode=None, output_logic=None, output_mode=None, bay=0, channel=0)[source]

Configure the external input and/or output triggering modes for the device.

The input triggering logic is selected with input_edge:

  • "rising" : Trigger on rising edge (low to high transition).

  • "falling" : Trigger on falling edge (high to low transition).

On detection of the input trigger, either a relative, absolute, or homing move can be started. For the moves, the movement parameters should have been pre-configured using the relevant move_relative() or move_absolute() methods, passing the now=False parameter to indicate the move should be delayed until a subsequent trigger. The movement type once triggered is selected with input_mode:

  • "move_relative" : Perform a relative move.

  • "move_absolute" : Perform an absolute move.

  • "home" : Perform a homing operation.

  • "disabled" : Do nothing.

The output triggering logic is selected with output_logic:

  • "high" : Output is high during the event.

  • "low" : Output is low during the event.

The event for which the output trigger signal is sent is selected by output_mode:

  • "in_motion" : Trigger activated during motion.

  • "motion_complete" : Trigger activated when motion is completed.

  • "max_velocity" : Trigger activated when movement reaches full speed.

  • "disabled" : Don’t activate trigger.

Parameters:

  • input_edge – Signal edge for input triggering.

  • input_mode – Action to take on input trigger.

  • output_logic – Output trigger logic level.

  • output_mode – Event for which output trigger is activated.

trigger_

Input and output triggering configuration.

Fields are "input_edge", "input_mode", "output_logic", and "output_mode". Additionally, "mode" stores the raw bit field data from the device as an integer.