plesty.lib.traffic.apt_protocol

Primitives of the Thorlabs APT communications protocol.

Message framing, identifiers, and payload structures for the binary APT protocol spoken by Thorlabs motion controllers (K10CR1, KDC101, benchtop racks, …). Page numbers in docstrings refer to the Thorlabs APT Communications Protocol manual.

The wire format (manual pp. 34) uses a fixed 6-byte header. A short packet carries two parameter bytes inside the header; a long packet flags the destination byte with LONG_PACKET_FLAG and appends a payload whose length is stored in the header.

Attributes

`HEADER_SIZE`	Size of the fixed APT packet header in bytes.
`LONG_PACKET_FLAG`	Flag set on the destination byte when a packet carries a long payload.
`APT_ERROR_BITS`	Status bits that indicate an error condition.
`APT_MOTION_BITS`	Status bits that indicate the motor is moving.
`APT_DECODERS`	Mapping of message ids to their payload structure types.

Classes

`AptAxis`	Axis or device address (manual pp. 36).
`AptMessageId`	Message identification number (not exhaustive; extend as needed).
`AptStatusBits`	Motor status bits (manual pp. 126).
`AptMessage`	One APT protocol message (manual pp. 34).
`_AptHeader`	Decoded fixed-size packet header.
`AptRecvState`	Framing state machine that reassembles APT messages from a byte stream.
`AptPayload`	Base class for fixed-format payload structures.
`HwInfo`	Hardware info (manual pp. 52).
`VelParams`	Velocity parameters (manual pp. 66).
`LimSwitchParams`	Limit switch parameters (manual pp. 78).
`HomeParams`	Homing parameters (manual pp. 76).
`PowerParams`	Motor power parameters (manual pp. 71).
`ButtonParams`	Button handling parameters (manual pp. 100).
`MoveParams`	Single-channel move payload (manual pp. 74, 75, 81, 84).
`PosCounter`	Position counter (manual pp. 63).
`GenMoveParams`	General move parameters (manual pp. 73).
`JogParams`	Jogging parameters (manual pp. 68).
`Status`	Status bits report (manual pp. 63).
`StatusUpdate`	Single-channel status report (manual pp. 123).
`UStatusUpdate`	User status report (manual pp. 125).

Module Contents

plesty.lib.traffic.apt_protocol.HEADER_SIZE = 6: Size of the fixed APT packet header in bytes.

plesty.lib.traffic.apt_protocol.LONG_PACKET_FLAG = 128: Flag set on the destination byte when a packet carries a long payload.

class plesty.lib.traffic.apt_protocol.AptAxis

Bases: enum.IntEnum

Axis or device address (manual pp. 36).

Initialize self. See help(type(self)) for accurate signature.

NO_AXIS = 0

HOST = 1

RACK = 17

BAY_0 = 33

BAY_1 = 34

BAY_2 = 35

BAY_3 = 36

BAY_4 = 37

BAY_5 = 38

BAY_6 = 39

BAY_7 = 40

BAY_8 = 41

BAY_9 = 42

GENERIC = 80

U = 84

X = 33

Y = 34

Z = 35

class plesty.lib.traffic.apt_protocol.AptMessageId

Bases: enum.IntEnum

Message identification number (not exhaustive; extend as needed).

Initialize self. See help(type(self)) for accurate signature.

NO_MESSAGE = 0

HW_DISCONNECT = 2

HW_REQ_INFO = 5

HW_GET_INFO = 6

HW_STOP_UPDATEMSGS = 18

HW_NO_FLASH_PROGRAMMING = 24

MOD_SET_CHANENABLESTATE = 528

MOD_REQ_CHANENABLESTATE = 529

MOD_GET_CHANENABLESTATE = 530

MOD_IDENTIFY = 547

MOT_SET_ENCCOUNTER = 1033

MOT_REQ_ENCCOUNTER = 1034

MOT_GET_ENCCOUNTER = 1035

MOT_SET_POSCOUNTER = 1040

MOT_REQ_POSCOUNTER = 1041

MOT_GET_POSCOUNTER = 1042

MOT_SET_VELPARAMS = 1043

MOT_REQ_VELPARAMS = 1044

MOT_GET_VELPARAMS = 1045

MOT_SET_JOGPARAMS = 1046

MOT_REQ_JOGPARAMS = 1047

MOT_GET_JOGPARAMS = 1048

MOT_SET_LIMSWITCHPARAMS = 1059

MOT_REQ_LIMSWITCHPARAMS = 1060

MOT_GET_LIMSWITCHPARAMS = 1061

MOT_SET_POWERPARAMS = 1062

MOT_REQ_POWERPARAMS = 1063

MOT_GET_POWERPARAMS = 1064

MOT_REQ_STATUSBITS = 1065

MOT_GET_STATUSBITS = 1066

MOT_SET_GENMOVEPARAMS = 1082

MOT_REQ_GENMOVEPARAMS = 1083

MOT_GET_GENMOVEPARAMS = 1084

MOT_SET_HOMEPARAMS = 1088

MOT_REQ_HOMEPARAMS = 1089

MOT_GET_HOMEPARAMS = 1090

MOT_MOVE_HOME = 1091

MOT_MOVE_HOMED = 1092

MOT_SET_MOVERELPARAMS = 1093

MOT_REQ_MOVERELPARAMS = 1094

MOT_GET_MOVERELPARAMS = 1095

MOT_MOVE_RELATIVE = 1096

MOT_SET_MOVEABSPARAMS = 1104

MOT_REQ_MOVEABSPARAMS = 1105

MOT_GET_MOVEABSPARAMS = 1106

MOT_MOVE_ABSOLUTE = 1107

MOT_MOVE_VELOCITY = 1111

MOT_MOVE_COMPLETED = 1124

MOT_MOVE_STOP = 1125

MOT_MOVE_STOPPED = 1126

MOT_MOVE_JOG = 1130

MOT_GET_STATUSUPDATE = 1153

MOT_REQ_USTATUSUPDATE = 1168

MOT_GET_USTATUSUPDATE = 1169

MOT_ACK_USTATUSUPDATE = 1170

MOT_SET_BUTTONPARAMS = 1206

MOT_REQ_BUTTONPARAMS = 1207

MOT_GET_BUTTONPARAMS = 1208

MOT_SET_POTPARAMS = 1200

MOT_REQ_POTPARAMS = 1201

MOT_GET_POTPARAMS = 1202

MOT_SET_BOWINDEX = 1268

MOT_REQ_BOWINDEX = 1269

MOT_GET_BOWINDEX = 1270

class plesty.lib.traffic.apt_protocol.AptStatusBits

Bases: enum.IntFlag

Motor status bits (manual pp. 126).

Initialize self. See help(type(self)) for accurate signature.

CWHARDLIMIT = 1

CCWHARDLIMIT = 2

CWSOFTLIMIT = 4

CCWSOFTLIMIT = 8

INMOTIONCW = 16

INMOTIONCCW = 32

JOGGINGCW = 64

JOGGINGCCW = 128

CONNECTED = 256

HOMING = 512

HOMED = 1024

INITIALIZING = 2048

TRACKING = 4096

SETTLED = 8192

POSITIONERROR = 16384

INSTRERROR = 32768

INTERLOCK = 65536

OVERTEMP = 131072

BUSVOLTFAULT = 262144

COMMUTATIONERROR = 524288

DIGIP1 = 1048576

DIGIP2 = 2097152

DIGIP3 = 4194304

DIGIP4 = 8388608

OVERLOAD = 16777216

ENCODERFAULT = 33554432

OVERCURRENT = 67108864

BUSCURRENTFAULT = 134217728

POWEROK = 268435456

ACTIVE = 536870912

ERROR = 1073741824

ENABLED = 2147483648

plesty.lib.traffic.apt_protocol.APT_ERROR_BITS: Status bits that indicate an error condition.

plesty.lib.traffic.apt_protocol.APT_MOTION_BITS: Status bits that indicate the motor is moving.

class plesty.lib.traffic.apt_protocol.AptMessage

One APT protocol message (manual pp. 34).

A message with a 2-byte payload is serialized as a short packet (the two bytes travel inside the header); any other payload length produces a long packet.

message_id: AptMessageId

dest: AptAxis

source: AptAxis

payload: bytes

classmethod from_short(message_id: AptMessageId, param_1: int = 0, param_2: int = 0, dest: AptAxis = AptAxis.GENERIC, source: AptAxis = AptAxis.HOST) → Self

Create a message from short packet parts.

Parameters:

message_id (AptMessageId)
param_1 (int)
param_2 (int)
dest (AptAxis)
source (AptAxis)

Return type:

Self

classmethod from_long(message_id: AptMessageId, payload: bytes, dest: AptAxis = AptAxis.GENERIC, source: AptAxis = AptAxis.HOST) → Self

Create a message from long packet parts.

Parameters:

message_id (AptMessageId)
payload (bytes)
dest (AptAxis)
source (AptAxis)

Return type:

Self

__str__() → str

Render as message name, route, and hex payload for readable logs.

Return type:: str

to_bytes() → bytes

Serialize the message to on-wire bytes.

Return type:: bytes

class plesty.lib.traffic.apt_protocol._AptHeader

Decoded fixed-size packet header.

message_id: AptMessageId

dest: AptAxis

source: AptAxis

length: int | None

params: bytes | None

classmethod from_bytes(raw: bytes) → Self

Decode the 6-byte header of a short or long packet.

Parameters:: raw (bytes)
Return type:: Self

class plesty.lib.traffic.apt_protocol.AptRecvState

Framing state machine that reassembles APT messages from a byte stream.

Start with an empty receive buffer, waiting for a header.

_buffer

_header: _AptHeader | None = None

put_some(buffer: bytes) → None

Append received raw bytes to the internal buffer.

Parameters:: buffer (bytes)
Return type:: None

_take(length: int) → bytes | None

Remove exactly the requested number of bytes from the buffer, or none.

Parameters:: length (int)
Return type:: bytes | None

messages() → collections.abc.Iterator[AptMessage]

Yield every complete message currently in the buffer.

Return type:: collections.abc.Iterator[AptMessage]

class plesty.lib.traffic.apt_protocol.AptPayload

Base class for fixed-format payload structures.

Subclasses define _format (a struct format string) whose fields match the dataclass fields in declaration order.

_format: ClassVar[str]

classmethod from_bytes(raw: bytes) → Self

Parse the payload from raw bytes.

Parameters:: raw (bytes)
Return type:: Self

to_bytes() → bytes

Serialize the payload to raw bytes.

Return type:: bytes

class plesty.lib.traffic.apt_protocol.HwInfo

Bases: AptPayload

Hardware info (manual pp. 52).

serial_number: int

model: bytes

hw_type: int

firmware_minor: int

firmware_interim: int

firmware_major: int

firmware_unused: int

reserved: bytes

hw_version: int

mod_state: int

num_channels: int

_format: ClassVar[str] = '<I8sHBBBB60sHHH'

property model_name: str

Return the model as a printable string.

Return type:: str

property firmware_version: str

Return the firmware version as major.interim.minor.

Return type:: str

class plesty.lib.traffic.apt_protocol.VelParams

Bases: AptPayload

Velocity parameters (manual pp. 66).

channel: int

min_velocity: int

acceleration: int

max_velocity: int

_format: ClassVar[str] = '<Hiii'

class plesty.lib.traffic.apt_protocol.LimSwitchParams

Bases: AptPayload

Limit switch parameters (manual pp. 78).

channel: int

cw_hard_limit: int

ccw_hard_limit: int

cw_soft_limit: int

ccw_soft_limit: int

limit_mode: int

_format: ClassVar[str] = '<HHHiiH'

class plesty.lib.traffic.apt_protocol.HomeParams

Bases: AptPayload

Homing parameters (manual pp. 76).

channel: int

direction: int

limit_switch: int

velocity: int

offset_distance: int

_format: ClassVar[str] = '<HHHii'

class plesty.lib.traffic.apt_protocol.PowerParams

Bases: AptPayload

Motor power parameters (manual pp. 71).

channel: int

rest_factor: int

move_factor: int

_format: ClassVar[str] = '<HHH'

class plesty.lib.traffic.apt_protocol.ButtonParams

Bases: AptPayload

Button handling parameters (manual pp. 100).

channel: int

mode: int

position1: int

position2: int

timeout1: int

timeout2: int

_format: ClassVar[str] = '<HHiiHH'

class plesty.lib.traffic.apt_protocol.MoveParams

Bases: AptPayload

Single-channel move payload (manual pp. 74, 75, 81, 84).

Used both for the MOT_SET_MOVEABSPARAMS/MOT_SET_MOVERELPARAMS parameter messages and for single-channel MOT_MOVE_ABSOLUTE/ MOT_MOVE_RELATIVE commands (whose multi-channel form repeats this 6-byte block per channel).

channel: int

position: int

_format: ClassVar[str] = '<Hi'

class plesty.lib.traffic.apt_protocol.PosCounter

Bases: AptPayload

Position counter (manual pp. 63).

channel: int

position: int

_format: ClassVar[str] = '<Hi'

class plesty.lib.traffic.apt_protocol.GenMoveParams

Bases: AptPayload

General move parameters (manual pp. 73).

channel: int

backlash_distance: int

_format: ClassVar[str] = '<Hi'

class plesty.lib.traffic.apt_protocol.JogParams

Bases: AptPayload

Jogging parameters (manual pp. 68).

channel: int

mode: int

step_size: int

min_velocity: int

acceleration: int

max_velocity: int

stop_mode: int

_format: ClassVar[str] = '<HHiiiiH'

class plesty.lib.traffic.apt_protocol.Status

Bases: AptPayload

Status bits report (manual pp. 63).

channel: int

status: int

_format: ClassVar[str] = '<HI'

property status_bits: AptStatusBits

Return the status word as AptStatusBits flags.

Return type:: AptStatusBits

class plesty.lib.traffic.apt_protocol.StatusUpdate

Bases: AptPayload

Single-channel status report (manual pp. 123).

The multi-channel form of MOT_GET_STATUSUPDATE repeats this 14-byte block per channel.

channel: int

position: int

encoder_count: int

status: int

_format: ClassVar[str] = '<HiiI'

property status_bits: AptStatusBits

Return the status word as AptStatusBits flags.

Return type:: AptStatusBits

class plesty.lib.traffic.apt_protocol.UStatusUpdate

Bases: AptPayload

User status report (manual pp. 125).

channel: int

position: int

velocity: int

current: int

status: int

_format: ClassVar[str] = '<HiHHI'

property status_bits: AptStatusBits

Return the status word as AptStatusBits flags.

Return type:: AptStatusBits

plesty.lib.traffic.apt_protocol.APT_DECODERS: dict[AptMessageId, Any]: Mapping of message ids to their payload structure types.