msl.equipment.resources.thorlabs.kinesis.benchtop_stepper_motor module

This module provides all the functionality required to control a Benchtop Stepper Motor including:

  • BSC101

  • BSC102

  • BSC103

  • BSC201

  • BSC202

  • BSC203

class msl.equipment.resources.thorlabs.kinesis.benchtop_stepper_motor.BenchtopStepperMotor(record)[source]

Bases: MotionControl

A wrapper around Thorlabs.MotionControl.Benchtop.StepperMotor.dll.

The properties for a BenchtopStepperMotor connection supports the following key-value pairs in the Connections Database:

'device_name': str, the device name found in ThorlabsDefaultSettings.xml [default: None]

Do not instantiate this class directly. Use the connect() method to connect to the equipment.

Parameters

record (EquipmentRecord) – A record from an Equipment-Register Database.

can_home(channel)[source]

Can the device perform a home()?

Parameters

channel (int) – The channel number (1 to n).

Returns

boolTrue if the device can perform a home.

can_move_without_homing_first(channel)[source]

Does the device need to be home()’d before a move can be performed?

Parameters

channel (int) – The channel number (1 to n).

Returns

boolTrue if the device does not need to be home()’d before a move can be commanded.

check_connection()[source]

Check connection.

Returns

boolTrue if the USB is listed by the FTDI controller.

clear_message_queue(channel)[source]

Clears the device message queue.

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

close()[source]

Disconnect and close the device.

Raises

ThorlabsError – If not successful.

disable_channel(channel)[source]

Disable the channel so that the motor can be moved by hand.

When disabled, power is removed from the motor and it can be freely moved.

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

enable_channel(channel)[source]

Enable channel for computer control.

When enabled, power is applied to the motor so it is fixed in position.

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

enable_last_msg_timer(channel, enable, last_msg_timeout)[source]

Enables the last message monitoring timer.

This can be used to determine whether communications with the device is still good.

Parameters
  • channel (int) – The channel number (1 to n).

  • enable (bool) – True to enable monitoring otherwise False to disable.

  • last_msg_timeout (int) – The last message error timeout in ms. Set to 0 to disable.

get_backlash(channel)[source]

Get the backlash distance setting (used to control hysteresis).

See get_real_value_from_device_unit() for converting from a DeviceUnit to a RealValue.

Parameters

channel (int) – The channel number (1 to n).

Returns

int – The backlash distance in DeviceUnits (see manual).

get_bow_index(channel)[source]

Gets the stepper motor bow index.

Parameters

channel (int) – The channel number (1 to n).

Returns

int – The bow index.

get_calibration_file(channel)[source]

Get the calibration file for this motor.

Parameters

channel (int) – The channel number (1 to n).

Returns

str – The filename of the calibration file.

Raises

ThorlabsError – If not successful.

get_device_unit_from_real_value(channel, real_value, unit_type)[source]

Converts a real-world value to a device value.

Either load_settings(), load_named_settings() or set_motor_params_ext() must be called before calling this function, otherwise the returned value will always be 0.

Parameters
  • channel (int) – The channel number (1 to n).

  • real_value (float) – The real-world value.

  • unit_type (enums.UnitType) – The unit of the real-world value.

Returns

int – The device value.

Raises

ThorlabsError – If not successful.

get_digital_outputs(channel)[source]

Gets the digital output bits.

Parameters

channel (int) – The channel number (1 to n).

Returns

int – Bit mask of states of the 4 digital output pins.

get_encoder_counter(channel)[source]

Get the Encoder Counter.

For devices that have an encoder, the current encoder position can be read.

Parameters

channel (int) – The channel number (1 to n).

Returns

int – Encoder count of encoder units.

get_firmware_version(channel)[source]

Gets the version number of the device firmware.

Returns

str – The firmware version.

get_hardware_info(channel)[source]

Gets the hardware information from the device.

Parameters

channel (int) – The channel number (1 to n).

Returns

structs.TLI_HardwareInformation – The hardware information.

Raises

ThorlabsError – If not successful.

get_hardware_info_block(channel)[source]

Gets the hardware information in a block.

Parameters

channel (int) – The channel number (1 to n).

Returns

structs.TLI_HardwareInformation – The hardware information.

Raises

ThorlabsError – If not successful.

get_homing_params_block(channel)[source]

Get the homing parameters.

Parameters

channel (int) – The channel number (1 to n).

Returns

structs.MOT_HomingParameters – The homing parameters.

Raises

ThorlabsError – If not successful.

get_homing_velocity(channel)[source]

Gets the homing velocity.

See get_real_value_from_device_unit() for converting from a DeviceUnit to a RealValue.

Parameters

channel (int) – The channel number (1 to n).

Returns

int – The homing velocity in DeviceUnits (see manual).

get_input_voltage(channel)[source]

Gets the analogue input voltage reading.

Parameters

channel (int) – The channel number (1 to n).

Returns

int – The input voltage 0-32768 corresponding to 0-5V.

get_jog_mode(channel)[source]

Gets the jog mode.

Parameters

channel (int) – The channel number (1 to n).

Returns

Raises

ThorlabsError – If not successful.

get_jog_params_block(channel)[source]

Get the jog parameters.

Parameters

channel (int) – The channel number (1 to n).

Returns

structs.MOT_JogParameters – The jog parameters.

Raises

ThorlabsError – If not successful.

get_jog_step_size(channel)[source]

Gets the distance to move when jogging.

See get_real_value_from_device_unit() for converting from a DeviceUnit to a RealValue.

Parameters

channel (int) – The channel number (1 to n).

Returns

int – The step size in DeviceUnits (see manual).

get_jog_vel_params(channel)[source]

Gets the jog velocity parameters.

See get_real_value_from_device_unit() for converting from a DeviceUnit to a RealValue.

Parameters

channel (int) – The channel number (1 to n).

Returns

  • int – The maximum velocity in DeviceUnits (see manual).

  • int – The acceleration in DeviceUnits (see manual).

Raises

ThorlabsError – If not successful.

get_joystick_params(channel)[source]

Gets the joystick parameters.

Parameters

channel (int) – The channel number (1 to n).

Returns

structs.MOT_JoystickParameters – The joystick parameters.

Raises

ThorlabsError – If not successful.

get_limit_switch_params(channel)[source]

Gets the limit switch parameters.

Parameters

channel (int) – The channel number (1 to n).

Returns

Raises

ThorlabsError – If not successful.

get_limit_switch_params_block(channel)[source]

Get the limit switch parameters.

Parameters

channel (int) – The channel number (1 to n).

Returns

structs.MOT_LimitSwitchParameters – The limit switch parameters.

Raises

ThorlabsError – If not successful.

get_motor_params(channel)[source]

Gets the motor stage parameters.

Deprecated: calls get_motor_params_ext()

get_motor_params_ext(channel)[source]

Gets the motor stage parameters.

These parameters, when combined define the stage motion in terms of RealWorldUnits [millimeters or degrees]. The real-world unit is defined from steps_per_rev * gear_box_ratio / pitch.

Parameters

channel (int) – The channel number (1 to n).

Returns

  • float – The steps per revolution.

  • float – The gear box ratio.

  • float – The pitch.

Raises

ThorlabsError – If not successful.

get_motor_travel_limits(channel)[source]

Gets the motor stage min and max position.

These define the range of travel for the stage.

Parameters

channel (int) – The channel number (1 to n).

Returns

  • float – The minimum position in RealWorldUnits [millimeters or degrees].

  • float – The maximum position in RealWorldUnits [millimeters or degrees].

Raises

ThorlabsError – If not successful.

get_motor_travel_mode(channel)[source]

Get the motor travel mode.

Parameters

channel (int) – The channel number (1 to n).

Returns

enums.MOT_TravelModes – The travel mode.

get_motor_velocity_limits(channel)[source]

Gets the motor stage maximum velocity and acceleration.

Parameters

channel (int) – The channel number (1 to n).

Returns

  • float – The maximum velocity in RealWorldUnits [millimeters or degrees].

  • float – The maximum acceleration in RealWorldUnits [millimeters or degrees].

Raises

ThorlabsError – If not successful.

get_move_absolute_position(channel)[source]

Gets the move absolute position.

See get_real_value_from_device_unit() for converting from a DeviceUnit to a RealValue.

Parameters

channel (int) – The channel number (1 to n).

Returns

int – The move absolute position in DeviceUnits (see manual).

get_move_relative_distance(channel)[source]

Gets the move relative distance.

See get_real_value_from_device_unit() for converting from a DeviceUnit to a RealValue.

Parameters

channel (int) – The channel number (1 to n).

Returns

int – The move relative position in DeviceUnits (see manual).

get_next_message(channel)[source]

Get the next Message Queue item, if it is available. See messages.

Parameters

channel (int) – The channel number (1 to n).

Returns

  • int – The message type.

  • int – The message ID.

  • int – The message data.

Raises

ThorlabsError – If not successful.

get_num_channels()[source]

Gets the number of channels in the device.

Returns

int – The number of channels.

get_number_positions(channel)[source]

Get the number of positions.

This function will get the maximum position reachable by the device. The motor may need to be set to its home() position before this parameter can be used.

Parameters

channel (int) – The channel number (1 to n).

Returns

int – The number of positions.

get_pid_loop_encoder_coeff(channel)[source]

Gets the Encoder PID loop encoder coefficient.

Parameters

channel (int) – The channel number (1 to n).

Returns

float – The Encoder PID loop encoder coefficient.

get_pid_loop_encoder_params(channel)[source]

Gets the Encoder PID loop parameters.

Parameters

channel (int) – The channel number (1 to n).

Returns

structs.MOT_PIDLoopEncoderParams – The parameters used to define the Encoder PID Loop.

Raises

ThorlabsError – If not successful.

get_position(channel)[source]

Get the current position.

The current position is the last recorded position. The current position is updated either by the polling mechanism or by calling request_position().

See get_real_value_from_device_unit() for converting from a DeviceUnit to a RealValue.

Parameters

channel (int) – The channel number (1 to n).

Returns

index (int) – The current position in DeviceUnits (see manual).

get_position_counter(channel)[source]

Get the position counter.

The position counter is identical to the position parameter. The position counter is set to zero when homing is complete. The position counter can also be set using set_position_counter() if homing is not to be performed.

See get_real_value_from_device_unit() for converting from a DeviceUnit to a RealValue.

Parameters

channel (int) – The channel number (1 to n).

Returns

int – The position counter in DeviceUnits (see manual).

get_power_params(channel)[source]

Gets the power parameters for the stepper motor.

Parameters

channel (int) – The channel number (1 to n).

Returns

structs.MOT_PowerParameters – The power parameters.

Raises

ThorlabsError – If not successful.

get_rack_digital_outputs()[source]

Gets the rack digital output bits.

Returns

int – Bit mask of states of the 4 digital output pins.

get_rack_status_bits()[source]

Gets the Rack status bits.

Returns

int – The status bits including 4 with one per electronic input pin.

get_real_value_from_device_unit(channel, device_value, unit_type)[source]

Converts a device value to a real-world value.

Either load_settings(), load_named_settings() or set_motor_params_ext() must be called before calling this function, otherwise the returned value will always be 0.0.

Parameters
  • channel (int) – The channel number (1 to n).

  • device_value (int) – The device value.

  • unit_type (enums.UnitType) – The unit of the device value.

Returns

float – The real-world value.

Raises

ThorlabsError – If not successful.

get_soft_limit_mode(channel)[source]

Gets the software limits mode.

Parameters

channel (int) – The channel number (1 to n).

Returns

enums.MOT_LimitsSoftwareApproachPolicy – The software limits mode.

get_software_version()[source]

Gets version number of the device software.

Returns

str – The device software version.

get_stage_axis_max_pos(channel)[source]

Gets the Stepper Motor maximum stage position.

See get_real_value_from_device_unit() for converting from a DeviceUnit to a RealValue.

Parameters

channel (int) – The channel number (1 to n).

Returns

int – The maximum position in DeviceUnits (see manual).

get_stage_axis_min_pos(channel)[source]

Gets the Stepper Motor minimum stage position.

See get_real_value_from_device_unit() for converting from a DeviceUnit to a RealValue.

Parameters

channel (int) – The channel number (1 to n).

Returns

int – The minimum position in DeviceUnits (see manual).

get_status_bits(channel)[source]

Get the current status bits.

This returns the latest status bits received from the device. To get new status bits, use request_status_bits() or use the polling function, start_polling().

Parameters

channel (int) – The channel number (1 to n).

Returns

int – The status bits from the device.

get_trigger_switches(channel)[source]

Gets the trigger switch parameter.

Parameters

channel (int) – The channel number (1 to n).

Returns

int – Trigger mask where:

  • Bit 0 - Input trigger enabled.

  • Bit 1 - Output trigger enabled.

  • Bit 2 - Output Passthrough mode enabled where Output Trigger mirrors Input Trigger.

  • Bit 3 - Output trigger high when moving.

  • Bit 4 - Performs relative move when input trigger goes high.

  • Bit 5 - Performs absolute move when input trigger goes high.

  • Bit 6 - Perfgorms home when input trigger goes high.

  • Bit 7 - Output triggers when motor moved by software command.

get_vel_params(channel)[source]

Gets the move velocity parameters.

See get_real_value_from_device_unit() for converting from a DeviceUnit to a RealValue.

Parameters

channel (int) – The channel number (1 to n).

Returns

  • max_velocity (int) – The maximum velocity in DeviceUnits (see manual).

  • acceleration (int) – The acceleration in DeviceUnits (see manual).

Raises

ThorlabsError – If not successful.

get_vel_params_block(channel)[source]

Get the move velocity parameters.

Parameters

channel (int) – The channel number (1 to n).

Returns

structs.MOT_VelocityParameters – The velocity parameters.

Raises

ThorlabsError – If not successful.

has_last_msg_timer_overrun(channel)[source]

Queries if the time since the last message has exceeded the lastMsgTimeout set by enable_last_msg_timer().

This can be used to determine whether communications with the device is still good.

Parameters

channel (int) – The channel number (1 to n).

Returns

boolTrue if last message timer has elapsed, False if monitoring is not enabled or if time of last message received is less than lastMsgTimeout.

home(channel)[source]

Home the device.

Homing the device will set the device to a known state and determine the home position.

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

identify(channel)[source]

Sends a command to the device to make it identify itself.

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

is_calibration_active(channel)[source]

Is a calibration file active for this motor?

Parameters

channel (int) – The channel number (1 to n).

Returns

bool – Whether a calibration file is active.

is_channel_valid(channel)[source]

Verifies that the specified channel is valid.

Parameters

channel (int) – The requested channel number (1 to n).

Returns

bool – Whether the channel is valid.

load_settings(channel)[source]

Update device with stored settings.

The settings are read from ThorlabsDefaultSettings.xml, which gets created when the Kinesis software is installed.

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

load_named_settings(channel, settings_name)[source]

Update device with named settings.

Parameters
  • channel (int) – The channel number (1 to n).

  • settings_name (str) – The name of the device to load the settings for. Examples for the value of setting_name can be found in ThorlabsDefaultSettings.xml`, which gets created when the Kinesis software is installed.

Raises

ThorlabsError – If not successful.

max_channel_count()[source]

Gets the number of channels available to this device.

This function returns the number of available bays, not the number of bays filled.

Returns

int – The number of channels available on this device.

message_queue_size(channel)[source]

Gets the size of the message queue.

Parameters

channel (int) – The channel number (1 to n).

Returns

int – The number of messages in the queue.

move_absolute(channel)[source]

Moves the device to the position defined in the set_move_absolute_position() command.

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

move_at_velocity(channel, direction)[source]

Start moving at the current velocity in the specified direction.

Parameters
Raises

ThorlabsError – If not successful.

move_jog(channel, jog_direction)[source]

Perform a jog.

Parameters
Raises

ThorlabsError – If not successful.

move_relative(channel, displacement)[source]

Move the motor by a relative amount.

See get_device_unit_from_real_value() for converting from a RealValue to a DeviceUnit.

Parameters
  • channel (int) – The channel number (1 to n).

  • displacement (int) – Signed displacement in DeviceUnits (see manual).

Raises

ThorlabsError – If not successful.

move_relative_distance(channel)[source]

Moves the device by a relative distance defined by set_move_relative_distance().

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

move_to_position(channel, index)[source]

Move the device to the specified position (index).

The motor may need to be set to its home() position before a position can be set.

See get_device_unit_from_real_value() for converting from a RealValue to a DeviceUnit.

Parameters
  • channel (int) – The channel number (1 to n).

  • index (int) – The position in DeviceUnits (see manual).

Raises

ThorlabsError – If not successful.

needs_homing(channel)[source]

Does the device need to be home()’d before a move can be performed?

Deprecated: calls can_move_without_homing_first() instead.

Returns

bool – Whether the device needs to be homed.

open()[source]

Open the device for communication.

Raises

ThorlabsError – If not successful.

persist_settings(channel)[source]

Persist device settings to device.

Parameters

channel (int) – The channel number (1 to n).

polling_duration(channel)[source]

Gets the polling loop duration.

Parameters

channel (int) – The channel number (1 to n).

Returns

int – The time between polls in milliseconds or 0 if polling is not active.

register_message_callback(channel, callback)[source]

Registers a callback on the message queue.

Parameters
  • channel (int) – The channel number (1 to n).

  • callback (MotionControlCallback) – A function to be called whenever messages are received.

Raises

ThorlabsError – If not successful.

request_backlash(channel)[source]

Requests the backlash.

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

request_bow_index(channel)[source]

Requests the stepper motor bow index.

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

request_digital_outputs(channel)[source]

Requests the digital output bits.

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

request_encoder_counter(channel)[source]

Requests the encoder counter.

For devices that have an encoder, the current encoder position can be read.

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

request_homing_params(channel)[source]

Requests the homing parameters.

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

request_input_voltage(channel)[source]

Requests the analogue input voltage reading.

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

request_jog_params(channel)[source]

Requests the jog parameters.

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

request_joystick_params(channel)[source]

Requests the joystick parameters.

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

request_limit_switch_params(channel)[source]

Requests the limit switch parameters.

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

request_move_absolute_position(channel)[source]

Requests the position of next absolute move.

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

request_move_relative_distance(channel)[source]

Requests the relative move distance.

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

request_pid_loop_encoder_params(channel)[source]

Requests the Encoder PID loop parameters.

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

request_position(channel)[source]

Requests the current position.

This needs to be called to get the device to send its current position. Note, this is called automatically if Polling is enabled for the device using start_polling().

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

request_power_params(channel)[source]

Requests the power parameters.

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

request_rack_digital_outputs()[source]

Requests the rack digital output bits.

Raises

ThorlabsError – If not successful.

request_rack_status_bits()[source]

Requests the Rack status bits be downloaded.

Raises

ThorlabsError – If not successful.

request_settings(channel)[source]

Requests that all settings are downloaded from the device.

This function requests that the device upload all its settings to the DLL.

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

request_status_bits(channel)[source]

Request the status bits which identify the current motor state.

This needs to be called to get the device to send its current status bits. Note, this is called automatically if Polling is enabled for the device using start_polling().

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

request_trigger_switches(channel)[source]

Requests the trigger switch parameter.

Warning

This function is currently not in the DLL, as of v1.14.8, but it is in the header file.

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

request_vel_params(channel)[source]

Requests the velocity parameters.

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

reset_rotation_modes(channel)[source]

Reset the rotation modes for a rotational device.

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

resume_move_messages(channel)[source]

Resume suspended move messages.

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

set_backlash(channel, distance)[source]

Sets the backlash distance (used to control hysteresis).

See get_device_unit_from_real_value() for converting from a RealValue to a DeviceUnit.

Parameters
  • channel (int) – The channel number (1 to n).

  • distance (int) – The backlash distance in DeviceUnits (see manual).

Raises

ThorlabsError – If not successful.

set_bow_index(channel, bow_index)[source]

Sets the stepper motor bow index.

Parameters
  • channel (int) – The channel number (1 to n).

  • bow_index (int) – The bow index.

Raises

ThorlabsError – If not successful.

set_calibration_file(channel, path, enabled)[source]

Set the calibration file for this motor.

Parameters
  • channel (int) – The channel number (1 to n).

  • path (str) – The path to a calibration file to load.

  • enabled (bool) – True to enable, False to disable.

Raises

OSError – If the path does not exist.

set_digital_outputs(channel, outputs_bits)[source]

Sets the digital output bits.

Parameters
  • channel (int) – The channel number (1 to n).

  • outputs_bits (int) – Bit mask to set states of the 4 digital output pins.

Raises

ThorlabsError – If not successful.

set_direction(channel, reverse)[source]

Sets the motor direction sense.

This function is used because some actuators use have directions of motion reversed. This parameter will tell the system to reverse the direction sense when moving, jogging etc.

Parameters
  • channel (int) – The channel number (1 to n).

  • reverse (bool) – If True then directions will be swapped on these moves.

Raises

ThorlabsError – If not successful.

set_encoder_counter(channel, count)[source]

Set the Encoder Counter values.

Setting the encoder counter to zero, effectively defines a home position on the encoder strip. Setting this value does not move the device.

Parameters
  • channel (int) – The channel number (1 to n).

  • count (int) – The encoder count in encoder units.

Raises

ThorlabsError – If not successful.

set_homing_params_block(channel, direction, limit, velocity, offset)[source]

Set the homing parameters.

Parameters
Raises

ThorlabsError – If not successful.

set_homing_velocity(channel, velocity)[source]

Sets the homing velocity.

See get_device_unit_from_real_value() for converting from a RealValue to a DeviceUnit.

Parameters
  • channel (int) – The channel number (1 to n).

  • velocity (int) – The homing velocity in DeviceUnits (see manual).

Raises

ThorlabsError – If not successful.

set_jog_mode(channel, mode, stop_mode)[source]

Sets the jog mode.

Parameters
Raises

ThorlabsError – If not successful.

set_jog_params_block(channel, jog_params)[source]

Set the jog parameters.

Parameters
Raises

ThorlabsError – If not successful.

set_jog_step_size(channel, step_size)[source]

Sets the distance to move on jogging.

See get_device_unit_from_real_value() for converting from a RealValue to a DeviceUnit.

Parameters
  • channel (int) – The channel number (1 to n).

  • step_size (int) – The step size in DeviceUnits (see manual).

Raises

ThorlabsError – If not successful.

set_jog_vel_params(channel, max_velocity, acceleration)[source]

Sets jog velocity parameters.

See get_device_unit_from_real_value() for converting from a RealValue to a DeviceUnit.

Parameters
  • channel (int) – The channel number (1 to n).

  • max_velocity (int) – The maximum velocity in DeviceUnits (see manual).

  • acceleration (int) – The acceleration in DeviceUnits (see manual).

Raises

ThorlabsError – If not successful.

set_joystick_params(channel, joystick_params)[source]

Sets the joystick parameters.

Parameters
Raises

ThorlabsError – If not successful.

set_limit_switch_params(channel, cw_lim, ccw_lim, cw_pos, ccw_pos, soft_limit_mode)[source]

Sets the limit switch parameters.

See get_device_unit_from_real_value() for converting from a RealValue to a DeviceUnit.

Parameters
Raises

ThorlabsError – If not successful.

set_limit_switch_params_block(channel, params)[source]

Set the limit switch parameters.

Parameters
Raises

ThorlabsError – If not successful.

set_limits_software_approach_policy(channel, policy)[source]

Sets the software limits policy.

Parameters
set_motor_params(channel, steps_per_rev, gear_box_ratio, pitch)[source]

Sets the motor stage parameters.

Deprecated: calls set_motor_params_ext()

set_motor_params_ext(channel, steps_per_rev, gear_box_ratio, pitch)[source]

Sets the motor stage parameters.

These parameters, when combined, define the stage motion in terms of RealWorldUnits [millimeters or degrees]. The real-world unit is defined from steps_per_rev * gear_box_ratio / pitch.

See get_real_value_from_device_unit() for converting from a DeviceUnit to a RealValue.

Parameters
  • channel (int) – The channel number (1 to n).

  • steps_per_rev (float) – The steps per revolution.

  • gear_box_ratio (float) – The gear box ratio.

  • pitch (float) – The pitch.

Raises

ThorlabsError – If not successful.

set_motor_travel_limits(channel, min_position, max_position)[source]

Sets the motor stage min and max position.

These define the range of travel for the stage.

See get_real_value_from_device_unit() for converting from a DeviceUnit to a RealValue.

Parameters
  • channel (int) – The channel number (1 to n).

  • min_position (float) – The minimum position in RealWorldUnits [millimeters or degrees].

  • max_position (float) – The maximum position in RealWorldUnits [millimeters or degrees].

Raises

ThorlabsError – If not successful.

set_motor_travel_mode(channel, travel_mode)[source]

Set the motor travel mode.

Parameters
Raises

ThorlabsError – If not successful.

set_motor_velocity_limits(channel, max_velocity, max_acceleration)[source]

Sets the motor stage maximum velocity and acceleration.

See get_real_value_from_device_unit() for converting from a DeviceUnit to a RealValue.

Parameters
  • channel (int) – The channel number (1 to n).

  • max_velocity (float) – The maximum velocity in RealWorldUnits [millimeters or degrees].

  • max_acceleration (float) – The maximum acceleration in RealWorldUnits [millimeters or degrees].

Raises

ThorlabsError – If not successful.

set_move_absolute_position(channel, position)[source]

Sets the move absolute position.

See get_device_unit_from_real_value() for converting from a RealValue to a DeviceUnit.

Parameters
  • channel (int) – The channel number (1 to n).

  • position (int) – The absolute position in DeviceUnits (see manual).

Raises

ThorlabsError – If not successful.

set_move_relative_distance(channel, distance)[source]

Sets the move relative distance.

See get_device_unit_from_real_value() for converting from a RealValue to a DeviceUnit.

Parameters
  • channel (int) – The channel number (1 to n).

  • distance (int) – The relative position in DeviceUnits (see manual).

Raises

ThorlabsError – If not successful.

set_pid_loop_encoder_coeff(channel, coeff)[source]

Sets the Encoder PID loop encoder coefficient.

Parameters
  • channel (int) – The channel number (1 to n).

  • coeff (float) – The Encoder PID loop encoder coefficient. Set to 0.0 to disable the encoder or if no encoder is present otherwise the positive encoder coefficient.

Raises

ThorlabsError – If not successful.

set_pid_loop_encoder_params(channel, mode, prop_gain, int_gain, diff_gain, limit, tol)[source]

Sets the Encoder PID loop parameters.

Parameters
  • channel (int) – The channel number (1 to n).

  • mode (enums.MOT_PID_LoopMode) – The Encoder PID loop mode as a enums.MOT_PID_LoopMode enum value or member name.

  • prop_gain (int) – The Encoder PID Loop proportional gain. Range 0 to 2^24.

  • int_gain (int) – The Encoder PID Loop integral gain. Range 0 to 2^24.

  • diff_gain (int) – The Encoder PID Loop differential gain. Range 0 to 2^24.

  • limit (int) – The Encoder PID Loop output limit. Range 0 to 2^15.

  • tol (int) – The Encoder PID Loop tolerance. Range 0 to 2^15.

Raises

ThorlabsError – If not successful.

set_position_counter(channel, count)[source]

Set the position counter.

Setting the position counter will locate the current position. Setting the position counter will effectively define the home position of a motor.

See get_device_unit_from_real_value() for converting from a RealValue to a DeviceUnit.

Parameters
  • channel (int) – The channel number (1 to n).

  • count (int) – The position counter in DeviceUnits (see manual).

Raises

ThorlabsError – If not successful.

set_power_params(channel, rest, move)[source]

Sets the power parameters for the stepper motor.

Parameters
  • channel (int) – The channel number (1 to n).

  • rest (int) – Percentage of full power to give while not moving (0 - 100).

  • move (int) – Percentage of full power to give while moving (0 - 100).

Raises

ThorlabsError – If not successful.

set_rack_digital_outputs(outputs_bits)[source]

Sets the rack digital output bits.

Parameters

outputs_bits (int) – Bit mask to set states of the 4 digital output pins.

Raises

ThorlabsError – If not successful.

set_rotation_modes(channel, mode, direction)[source]

Set the rotation modes for a rotational device.

Parameters
Raises

ThorlabsError – If not successful.

set_stage_axis_limits(channel, min_position, max_position)[source]

Sets the stage axis position limits.

See get_device_unit_from_real_value() for converting from a RealValue to a DeviceUnit.

Parameters
  • channel (int) – The channel number (1 to n).

  • min_position (int) – The minimum position in DeviceUnits (see manual).

  • max_position (int) – The maximum position in DeviceUnits (see manual).

Raises

ThorlabsError – If not successful.

set_trigger_switches(channel, indicator_bits)[source]

Sets the trigger switch bits.

Parameters
  • channel (int) – The channel number (1 to n).

  • indicator_bits (int) –

    Sets the 8 bits indicating action on trigger input and events to trigger electronic output.

    • Bit 0 - Input trigger enabled.

    • Bit 1 - Output trigger enabled.

    • Bit 2 - Output pass-through mode enabled where Output Trigger mirrors Input Trigger.

    • Bit 3 - Output trigger high when moving.

    • Bit 4 - Performs relative move when input trigger goes high.

    • Bit 5 - Performs absolute move when input trigger goes high.

    • Bit 6 - Performs home when input trigger goes high.

    • Bit 7 - Output triggers when motor moved by software command.

Raises

ThorlabsError – If not successful.

set_vel_params(channel, max_velocity, acceleration)[source]

Sets the move velocity parameters.

See get_device_unit_from_real_value() for converting from a RealValue to a DeviceUnit.

Parameters
  • channel (int) – The channel number (1 to n).

  • max_velocity (int) – The maximum velocity in DeviceUnits (see manual).

  • acceleration (int) – The acceleration in DeviceUnits (see manual).

Raises

ThorlabsError – If not successful.

set_vel_params_block(channel, min_velocity, max_velocity, acceleration)[source]

Set the move velocity parameters.

See get_device_unit_from_real_value() for converting from a RealValue to a DeviceUnit.

Parameters
  • channel (int) – The channel number (1 to n).

  • min_velocity (int) – The minimum velocity in DeviceUnits (see manual).

  • max_velocity (int) – The maximum velocity in DeviceUnits (see manual)..

  • acceleration (int) – The acceleration in DeviceUnits (see manual)..

Raises

ThorlabsError – If not successful.

start_polling(channel, milliseconds)[source]

Starts the internal polling loop.

This function continuously requests position and status messages.

Parameters
  • channel (int) – The channel number (1 to n).

  • milliseconds (int) – The polling rate, in milliseconds.

Raises

ThorlabsError – If not successful.

stop_immediate(channel)[source]

Stop the current move immediately (with the risk of losing track of the position).

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

stop_polling(channel)[source]

Stops the internal polling loop.

Parameters

channel (int) – The channel number (1 to n).

stop_profiled(channel)[source]

Stop the current move using the current velocity profile.

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

suspend_move_messages(channel)[source]

Suspend automatic messages at ends of moves.

Useful to speed up part of real-time system with lots of short moves.

Parameters

channel (int) – The channel number (1 to n).

Raises

ThorlabsError – If not successful.

time_since_last_msg_received(channel)[source]

Gets the time, in milliseconds, since the last message was received.

This can be used to determine whether communications with the device is still good.

Parameters

channel (int) – The channel number (1 to n).

Returns

  • int – The time, in milliseconds, since the last message was received.

  • boolTrue if monitoring is enabled otherwise False.

uses_pid_loop_encoding(channel)[source]

Determines if we can uses PID loop encoding.

This is true if the stage supports PID Loop Encoding. Requires get_pid_loop_encoder_coeff() to have a positive non-zero coefficient, see also set_pid_loop_encoder_coeff().

Parameters

channel (int) – The channel number (1 to n).

wait_for_message(channel)[source]

Wait for next Message Queue item if it is available. See messages.

Parameters

channel (int) – The channel number (1 to n).

Returns

  • int – The message type.

  • int – The message ID.

  • int – The message data.

Raises

ThorlabsError – If not successful.