qmi.instruments.thorlabs.k10crx

Instrument driver base class for the Thorlabs K10CRX/M motorized rotational mount.

This driver communicates with the device via a USB serial port, using the Thorlabs APT protocol. For details, see the document “Thorlabs APT Controllers Host-Controller Communications Protocol”, issue 25 from Thorlabs.

This driver has only been tested under Linux. In principle it should also work under Windows after creating a virtual COM port for the internal USB serial port in the instrument.

Classes

Thorlabs_K10CRxBase(context, name, transport)

Instrument driver for the Thorlabs K10CRX/M motorized rotational mount.

class qmi.instruments.thorlabs.k10crx.Thorlabs_K10CRxBase(context: QMI_Context, name: str, transport: str)

Instrument driver for the Thorlabs K10CRX/M motorized rotational mount.

RESPONSE_TIMEOUT: The default response timeout of 1.0 seconds for APT protocol queries.

MICROSTEPS_PER_DEGREE: Number of microsteps per degree of rotation. Full revolution is 409600 micro-steps with rotation of 3 degrees.

VELOCITY_FACTOR: Internal velocity factor for 1 degree/second.

MAX_VELOCITY: Maximum velocity in degrees/second. This set to 0 as it changes depending on the exact K10CRx model, and will be overriden in the respective child class.

ACCELERATION_FACTOR: Internal acceleration factor for 1 degree/second/second for the mount. The value is based on K10CR1 as no data for K10CR2 found.

MAX_ACCELERATION: Maximum acceleration in degrees/second^2.

open() → None

Connect to the instrument hardware.

When this method returns, the instrument must be ready for interaction via calls to instrument-specific methods.

Subclasses can extend this method to implement instrument-specific initialization. If they do, they should call super().open() as a last statement.

close() → None

Close the connection to the instrument hardware and release associated resources.

When this method returns, the instrument must not be used again unless it is first re-opened by calling the open() method.

Subclasses can extend this method if they have specific resources to close. If they do, they should call super().close() as a last statement.

get_idn() → QMI_InstrumentIdentification: Read instrument type and version and return QMI_InstrumentIdentification instance.

get_motor_status() → MotorStatus: Return the motor status bits.

identify() → None: Make the yellow LED on the instrument flash for a few seconds.

get_chan_enable_state() → bool: Return the enable state of the motor drive channel.

set_chan_enable_state(enable: bool) → None

Enable or disable the motor drive channel.

When the drive channel is disabled, the motor will not hold its position and can be moved through external force.

The drive channel is by default enabled at power-up.

get_absolute_position() → float

Return the absolute position of the stage in degrees.

After power-up, the absolute position of the stage will be unknown until the stage is homed. If the stage has not yet been homed, this function will return the current position relative to the position at power-up.

Note that the absolute position can exceed the range of -360 .. +360 degrees when the stage has rotated a full turn. The absolute position counter overflows after 43 full turns and may then return incorrect results.

get_velocity() → float: Return the current velocity.

get_acceleration() → float: Return the current acceleration.

set_velocity(max_velocity: float) → None

Set the maximum velocity for moves.

This setting will be applied for subsequent absolute and relative moves.

Parameters:: max_velocity – Maximum velocity in degrees/second (max 10).

set_acceleration(acceleration: float) → None

Set the maximum acceleration for moves.

This setting will be applied for subsequent absolute and relative moves.

Parameters:: acceleration – Maximum acceleration in degrees/second (max 10).

set_velocity_params(max_velocity: float, acceleration: float) → None

Set the maximum velocity and acceleration.

These settings will be applied for subsequent absolute and relative moves.

Parameters:

max_velocity – Maximum velocity in degrees/second (max 10).
acceleration – Acceleration in degree/second/second (max 20).

get_backlash_distance() → float: Return the backlash distance in degrees.

set_backlash_distance(backlash: float) → None

Set the backlash distance.

The backlash distance is used when the stage moves in reverse direction. While moving in reverse direction, the stage moves past its target position by the backlash distance, then moves back to the target in forward direction.

Parameters:: backlash – Backlash distance in degrees, or 0 to disable.

get_home_params() → HomeParams: Return the homing parameters.

set_home_params(home_direction: AptChannelHomeDirection, limit_switch: AptChannelHomeLimitSwitch, home_velocity: float, offset_distance: float) → None

Set the homing parameters.

WARNING: The K10CR1 manual recommends that these settings should not be adjusted from the factory defaults.

Parameters:

home_direction – Direction of moving to home (should be HomeDirection.REVERSE).
limit_switch – Limit switch to use for homing (should be HomeLimitSwitch.REVERSE).
home_velocity – Homing velocity in degrees/second (max 5).
offset_distance – Distance of home position from home limit switch (in degrees).

move_stop(immediate_stop: bool = False) → None

Stop any ongoing move operation.

This function returns immediately while the stage may still be moving. Use wait_move_complete() to wait until the stage has stopped.

Parameters:: immediate_stop – True to stop abruptly, False to perform a profiled stop.

move_home() → None

Start a homing move.

This function returns immediately while homing is still in progress. Use wait_move_complete() to wait until the move is finished.

move_relative(distance: float) → None

Start a relative move.

This function returns immediately while homing is still in progress. Use wait_move_complete() to wait until the move is finished.

Parameters:: distance – Relative move distance in degrees.

move_absolute(position: float) → None

Start a move to an absolute position.

This function returns immediately while homing is still in progress. Use wait_move_complete() to wait until the move is finished.

After power-up, the absolute position of the stage will be unknown until the stage is homed. If the stage has not yet been homed, the position parameter of this function will be interpreted relative to the position at power-up.

Note that the stage supports absolute positions above 360 degrees and will not automatically reduce such positions module 360. It is therefore possible that the stage must rotate more than a full turn in order to reach a specific absolute position.

Parameters:: position – Absolute target position in degrees.

wait_move_complete(timeout: float) → None

Wait until the motor has stopped moving.

If the motor is not currently moving, this function returns immediately. Otherwise, this function wait (blocks) until the motor has stopped moving or until the specified timeout expires.

Parameters:: timeout – Maximum time to wait in seconds.
Raises:: QMI_TimeoutException – If the motor is still moving when the timeout expires.

force_unlock() → None

Forcefully unlock the remote object.

This unlocks the object, regardless of who owns the lock. This allows you to unlock an object if the locking proxy has been destroyed without unlocking.

Use this with care.

Do not override this stub method in subclasses. It has already been implemented in QMI_RpcProxy.

classmethod get_category() → str | None

Return the optional name of the category this object belongs to.

A category name is a free-form string that has no special significance. Its purpose is to distinguish between groups of RPC objects that fulfill similar roles.

get_name() → str

Return the name of this object.

Returns:: name attribute.

get_signals() → list[SignalDescription]

Return a list of signals that can be published by this object.

Returns:: List consisting of qmi_signals attributes.

is_locked() → bool

Query if the remote object is locked.

Do not override this stub method in subclasses. It has already been implemented in QMI_RpcProxy.

is_open() → bool: Return True if the instrument is open (ready for interaction).

lock(timeout: float = 0.0, lock_token: str | None = None) → bool

Lock the remote object. If timeout is given, try every 0.1s within the given timeout value. The remote object can be locked with an optional custom lock token by giving a string into lock_token keyword argument.

If successful, this proxy is the only proxy that can invoke RPC methods on the remote object; other proxies will receive an “object is locked” response. The return value indicates if the lock was granted; a denied lock means the object was already locked by another proxy.

Do not override this stub method in subclasses. It has already been implemented in QMI_RpcProxy.

release_rpc_object() → None: Give a warning if the instrument is removed while still open.

unlock(lock_token: str | None = None) → bool

Unlock the remote object.

Without optional parameters, this is only allowed by the proxy that initially locked the object. By giving the lock token as an input parameter, the specific object locked by this token can be unlocked. The return value indicates if the unlocking was successful.

Do not override this stub method in subclasses. It has already been implemented in QMI_RpcProxy.