plesty.lib.device.base_apt_device

Base device for Thorlabs motion controllers speaking the APT protocol.

BaseAptDevice wires the Plesty device model to plesty.lib.traffic.apt.AptTrafficManager. It provides the standard lifecycle (init/connect/disconnect), identity and error reporting from the APT status word, and single-channel motor operations in raw device counts.

Concrete device classes (e.g. a K10CR1 rotation stage) subclass this, define the count-per-unit scale factors of their hardware, and register their configuration parameters against the count-domain helpers via register_apt_param().

Attributes

_COMPLETION_FALLBACK_S

Classes

BaseAptDevice

Base class for single-channel Thorlabs APT motion devices.

Functions

_descriptor_serial(→ str | None)

Return the USB descriptor serial of the port a manager is open on.

Module Contents

plesty.lib.device.base_apt_device._COMPLETION_FALLBACK_S = 10.0
class plesty.lib.device.base_apt_device.BaseAptDevice(port: str, dest: plesty.lib.traffic.apt_protocol.AptAxis = AptAxis.GENERIC, channel: int = 1, timeout: int = 5, move_timeout: int = 60, op_schema: Any = None, param_schema: Any = None, transport: Any | None = None)

Bases: plesty.lib.device.base_device_sync.BaseDeviceSyncModel

Base class for single-channel Thorlabs APT motion devices.

Subclasses register their parameter keys with register_apt_param() so the generic config system can read and write them, and use the count-domain motion helpers (home(), move_absolute_counts(), …) to implement user-facing operations in physical units.

Initialize with the serial port and APT addressing.

Parameters:

  • port (str) – Serial port of the controller (e.g. ‘COM3’ or ‘/dev/ttyUSB0’).

  • dest (plesty.lib.traffic.apt_protocol.AptAxis) – APT destination address of the controller.

  • channel (int) – Motor channel number (APT channels are 1-based).

  • timeout (int) – Reply timeout for parameter traffic in seconds.

  • move_timeout (int) – Timeout for homing and move completion in seconds.

  • op_schema (Any) – Optional operation schema forwarded to the function system.

  • param_schema (Any) – Optional parameter schema forwarded to the config system.

  • transport (Any | None) – Optional serial-like object (e.g. plesty.lib.sim.apt.AptMotorSimulator) replacing the real serial port — used for hardware-free operation and tests.

port
dest
channel = 1
timeout = 5
move_timeout = 60
_transport = None
traffic_manager: plesty.lib.traffic.apt.AptTrafficManager | None = None
_param_handlers: dict[str, tuple[collections.abc.Callable[[], Any], collections.abc.Callable[[Any], None] | None]]
init(main: Any = None) → None

Create the APT traffic manager for the configured port.

Parameters:

main (Any)

Return type:

None

connect() → bool

Open the serial connection and put the controller into remote mode.

The configured address may be a serial number rather than a port name, in which case it is resolved first: a COM number is assigned per USB port and moves when a controller is replugged, so an address that survives that has to identify the controller itself.

Return type:

bool

_start_session() → bool

Open the port and bring the controller into a known state.

Returns:

True once the controller is ready for commands.

Return type:

bool

disconnect() → None

Close the serial connection.

Return type:

None

command(message_id: plesty.lib.traffic.apt_protocol.AptMessageId, payload: bytes | None = None) → None

Send a fire-and-forget message to the controller.

Parameters:

  • message_id (plesty.lib.traffic.apt_protocol.AptMessageId) – The message to send.

  • payload (bytes | None) – Long-packet payload; when omitted, a short packet with the channel number as its first parameter byte is sent.

Return type:

None

request(message_id: plesty.lib.traffic.apt_protocol.AptMessageId, reply_id: plesty.lib.traffic.apt_protocol.AptMessageId, payload: bytes | None = None, timeout: float | None = None) → plesty.lib.traffic.apt_protocol.AptMessage

Send a message and return the matching reply.

Parameters:
Returns:

The reply message.

Return type:

plesty.lib.traffic.apt_protocol.AptMessage

_build(message_id: plesty.lib.traffic.apt_protocol.AptMessageId, payload: bytes | None) → plesty.lib.traffic.apt_protocol.AptMessage

Build a short (channel-addressed) or long message for this device.

Parameters:
Return type:

plesty.lib.traffic.apt_protocol.AptMessage

hw_info() → plesty.lib.traffic.apt_protocol.HwInfo

Query the controller hardware information block.

Return type:

plesty.lib.traffic.apt_protocol.HwInfo

identity() → str

Return an identity string built from the APT hardware info.

Two serial numbers exist and they need not agree: the one in the USB descriptor, which is how the controller is addressed and what is printed on the unit, and the one the firmware reports in HW_GET_INFO. On the K10CR1 here the descriptor gives 55001327 while the firmware gives 55000000, which looks like an unprogrammed default. Reporting only the firmware value would name the device something no one can find it by, so both appear when they differ.

Returns:

Model, serial number(s) and firmware version.

Return type:

str

get_status() → plesty.lib.traffic.apt_protocol.Status

Query the motor status bits.

Return type:

plesty.lib.traffic.apt_protocol.Status

check_errors() → list[str]

Return the names of all active error bits in the status word.

Return type:

list[str]

check_operatability() → bool

Return True if the controller answers a hardware info request.

Return type:

bool

property is_moving: bool

Return True while the motor reports any motion status bit.

Return type:

bool

property is_homed: bool

Return True once the motor has been homed.

Return type:

bool

_motion_request(message_id: plesty.lib.traffic.apt_protocol.AptMessageId, reply_id: plesty.lib.traffic.apt_protocol.AptMessageId, payload: bytes | None = None, settled: collections.abc.Callable[[], bool] | None = None) → None

Issue a motion command, tolerating a lost completion message.

The completion message is a single serial packet and can be lost; the stage state is the ground truth. When the completion wait times out, the motion is accepted anyway once the status bits report it settled — a lost packet must never hang the caller.

Parameters:
Return type:

None

home() → None

Home the stage and block until the controller reports completion.

Return type:

None

move_absolute_counts(position: int) → None

Move to an absolute position in device counts and block until done.

Parameters:

position (int)

Return type:

None

move_relative_counts(distance: int) → None

Move by a relative distance in device counts and block until done.

Parameters:

distance (int)

Return type:

None

stop(immediate: bool = False) → None

Stop any motion and block until the controller reports it stopped.

Parameters:

immediate (bool) – Stop abruptly instead of with a profiled deceleration.

Return type:

None

get_position_counts() → int

Return the current position counter in device counts.

Return type:

int

get_velocity_params() → plesty.lib.traffic.apt_protocol.VelParams

Query the trapezoidal velocity parameters (in device count units).

Return type:

plesty.lib.traffic.apt_protocol.VelParams

set_velocity_params(params: plesty.lib.traffic.apt_protocol.VelParams) → None

Set the trapezoidal velocity parameters (in device count units).

Parameters:

params (plesty.lib.traffic.apt_protocol.VelParams)

Return type:

None

set_params(message_id: plesty.lib.traffic.apt_protocol.AptMessageId, params: plesty.lib.traffic.apt_protocol.AptPayload) → None

Send any MOT_SET_* parameter structure to the controller.

Parameters:
Return type:

None

register_apt_param(key: str, query: collections.abc.Callable[[], Any], write: collections.abc.Callable[[Any], None] | None = None) → None

Bind a configuration key to device read/write callables.

Parameters:

  • key (str) – Full configuration key (e.g. "Motion.MaxVelocity").

  • query (collections.abc.Callable[[], Any]) – Callable returning the current device value for the key.

  • write (collections.abc.Callable[[Any], None] | None) – Callable applying a new value, or None for read-only.

Return type:

None

_resolve_handler_key(key: str) → str

Return the key a handler is registered under, for either spelling.

A grouped parameter has two names: the runtime key built from the group’s command_prefix (MO.MaxVelocity, which is what get_config_list reports) and the one built from the group name (Motion.MaxVelocity). The config system resolves both, so a module can register a handler under one and be called with the other — and the mismatch fails as “no handler registered” for a parameter that is plainly in the schema.

Parameters:

key (str) – The key as the caller wrote it.

Returns:

A key present in the handler map, or key unchanged when neither spelling matches.

Return type:

str

_write_(key: str, value: str | float | int | bool) → bool

Write a registered parameter to the device.

Parameters:

  • key (str)

  • value (str | float | int | bool)

Return type:

bool

_query_(key: str) → Any

Query a registered parameter from the device.

Parameters:

key (str)

Return type:

Any

plesty.lib.device.base_apt_device._descriptor_serial(manager: Any) → str | None

Return the USB descriptor serial of the port a manager is open on.

This is the serial printed on the unit and the one the controller is addressed by, which is not necessarily the one its firmware reports.

Parameters:

manager (Any) – The device’s traffic manager.

Returns:

The serial number, or None when the port cannot be identified.

Return type:

str | None