plesty.lib.traffic.apt_protocol
===============================

.. py:module:: plesty.lib.traffic.apt_protocol

.. autoapi-nested-parse::

   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 :data:`LONG_PACKET_FLAG` and appends a payload whose
   length is stored in the header.



Attributes
----------

.. autoapisummary::

   plesty.lib.traffic.apt_protocol.HEADER_SIZE
   plesty.lib.traffic.apt_protocol.LONG_PACKET_FLAG
   plesty.lib.traffic.apt_protocol.APT_ERROR_BITS
   plesty.lib.traffic.apt_protocol.APT_MOTION_BITS
   plesty.lib.traffic.apt_protocol.APT_DECODERS


Classes
-------

.. autoapisummary::

   plesty.lib.traffic.apt_protocol.AptAxis
   plesty.lib.traffic.apt_protocol.AptMessageId
   plesty.lib.traffic.apt_protocol.AptStatusBits
   plesty.lib.traffic.apt_protocol.AptMessage
   plesty.lib.traffic.apt_protocol._AptHeader
   plesty.lib.traffic.apt_protocol.AptRecvState
   plesty.lib.traffic.apt_protocol.AptPayload
   plesty.lib.traffic.apt_protocol.HwInfo
   plesty.lib.traffic.apt_protocol.VelParams
   plesty.lib.traffic.apt_protocol.LimSwitchParams
   plesty.lib.traffic.apt_protocol.HomeParams
   plesty.lib.traffic.apt_protocol.PowerParams
   plesty.lib.traffic.apt_protocol.ButtonParams
   plesty.lib.traffic.apt_protocol.MoveParams
   plesty.lib.traffic.apt_protocol.PosCounter
   plesty.lib.traffic.apt_protocol.GenMoveParams
   plesty.lib.traffic.apt_protocol.JogParams
   plesty.lib.traffic.apt_protocol.Status
   plesty.lib.traffic.apt_protocol.StatusUpdate
   plesty.lib.traffic.apt_protocol.UStatusUpdate


Module Contents
---------------

.. py:data:: HEADER_SIZE
   :value: 6


   Size of the fixed APT packet header in bytes.

.. py:data:: LONG_PACKET_FLAG
   :value: 128


   Flag set on the destination byte when a packet carries a long payload.

.. py:class:: AptAxis

   Bases: :py:obj:`enum.IntEnum`


   Axis or device address (manual pp. 36).

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


   .. py:attribute:: NO_AXIS
      :value: 0



   .. py:attribute:: HOST
      :value: 1



   .. py:attribute:: RACK
      :value: 17



   .. py:attribute:: BAY_0
      :value: 33



   .. py:attribute:: BAY_1
      :value: 34



   .. py:attribute:: BAY_2
      :value: 35



   .. py:attribute:: BAY_3
      :value: 36



   .. py:attribute:: BAY_4
      :value: 37



   .. py:attribute:: BAY_5
      :value: 38



   .. py:attribute:: BAY_6
      :value: 39



   .. py:attribute:: BAY_7
      :value: 40



   .. py:attribute:: BAY_8
      :value: 41



   .. py:attribute:: BAY_9
      :value: 42



   .. py:attribute:: GENERIC
      :value: 80



   .. py:attribute:: U
      :value: 84



   .. py:attribute:: X
      :value: 33



   .. py:attribute:: Y
      :value: 34



   .. py:attribute:: Z
      :value: 35



.. py:class:: AptMessageId

   Bases: :py:obj:`enum.IntEnum`


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

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


   .. py:attribute:: NO_MESSAGE
      :value: 0



   .. py:attribute:: HW_DISCONNECT
      :value: 2



   .. py:attribute:: HW_REQ_INFO
      :value: 5



   .. py:attribute:: HW_GET_INFO
      :value: 6



   .. py:attribute:: HW_STOP_UPDATEMSGS
      :value: 18



   .. py:attribute:: HW_NO_FLASH_PROGRAMMING
      :value: 24



   .. py:attribute:: MOD_SET_CHANENABLESTATE
      :value: 528



   .. py:attribute:: MOD_REQ_CHANENABLESTATE
      :value: 529



   .. py:attribute:: MOD_GET_CHANENABLESTATE
      :value: 530



   .. py:attribute:: MOD_IDENTIFY
      :value: 547



   .. py:attribute:: MOT_SET_ENCCOUNTER
      :value: 1033



   .. py:attribute:: MOT_REQ_ENCCOUNTER
      :value: 1034



   .. py:attribute:: MOT_GET_ENCCOUNTER
      :value: 1035



   .. py:attribute:: MOT_SET_POSCOUNTER
      :value: 1040



   .. py:attribute:: MOT_REQ_POSCOUNTER
      :value: 1041



   .. py:attribute:: MOT_GET_POSCOUNTER
      :value: 1042



   .. py:attribute:: MOT_SET_VELPARAMS
      :value: 1043



   .. py:attribute:: MOT_REQ_VELPARAMS
      :value: 1044



   .. py:attribute:: MOT_GET_VELPARAMS
      :value: 1045



   .. py:attribute:: MOT_SET_JOGPARAMS
      :value: 1046



   .. py:attribute:: MOT_REQ_JOGPARAMS
      :value: 1047



   .. py:attribute:: MOT_GET_JOGPARAMS
      :value: 1048



   .. py:attribute:: MOT_SET_LIMSWITCHPARAMS
      :value: 1059



   .. py:attribute:: MOT_REQ_LIMSWITCHPARAMS
      :value: 1060



   .. py:attribute:: MOT_GET_LIMSWITCHPARAMS
      :value: 1061



   .. py:attribute:: MOT_SET_POWERPARAMS
      :value: 1062



   .. py:attribute:: MOT_REQ_POWERPARAMS
      :value: 1063



   .. py:attribute:: MOT_GET_POWERPARAMS
      :value: 1064



   .. py:attribute:: MOT_REQ_STATUSBITS
      :value: 1065



   .. py:attribute:: MOT_GET_STATUSBITS
      :value: 1066



   .. py:attribute:: MOT_SET_GENMOVEPARAMS
      :value: 1082



   .. py:attribute:: MOT_REQ_GENMOVEPARAMS
      :value: 1083



   .. py:attribute:: MOT_GET_GENMOVEPARAMS
      :value: 1084



   .. py:attribute:: MOT_SET_HOMEPARAMS
      :value: 1088



   .. py:attribute:: MOT_REQ_HOMEPARAMS
      :value: 1089



   .. py:attribute:: MOT_GET_HOMEPARAMS
      :value: 1090



   .. py:attribute:: MOT_MOVE_HOME
      :value: 1091



   .. py:attribute:: MOT_MOVE_HOMED
      :value: 1092



   .. py:attribute:: MOT_SET_MOVERELPARAMS
      :value: 1093



   .. py:attribute:: MOT_REQ_MOVERELPARAMS
      :value: 1094



   .. py:attribute:: MOT_GET_MOVERELPARAMS
      :value: 1095



   .. py:attribute:: MOT_MOVE_RELATIVE
      :value: 1096



   .. py:attribute:: MOT_SET_MOVEABSPARAMS
      :value: 1104



   .. py:attribute:: MOT_REQ_MOVEABSPARAMS
      :value: 1105



   .. py:attribute:: MOT_GET_MOVEABSPARAMS
      :value: 1106



   .. py:attribute:: MOT_MOVE_ABSOLUTE
      :value: 1107



   .. py:attribute:: MOT_MOVE_VELOCITY
      :value: 1111



   .. py:attribute:: MOT_MOVE_COMPLETED
      :value: 1124



   .. py:attribute:: MOT_MOVE_STOP
      :value: 1125



   .. py:attribute:: MOT_MOVE_STOPPED
      :value: 1126



   .. py:attribute:: MOT_MOVE_JOG
      :value: 1130



   .. py:attribute:: MOT_GET_STATUSUPDATE
      :value: 1153



   .. py:attribute:: MOT_REQ_USTATUSUPDATE
      :value: 1168



   .. py:attribute:: MOT_GET_USTATUSUPDATE
      :value: 1169



   .. py:attribute:: MOT_ACK_USTATUSUPDATE
      :value: 1170



   .. py:attribute:: MOT_SET_BUTTONPARAMS
      :value: 1206



   .. py:attribute:: MOT_REQ_BUTTONPARAMS
      :value: 1207



   .. py:attribute:: MOT_GET_BUTTONPARAMS
      :value: 1208



   .. py:attribute:: MOT_SET_POTPARAMS
      :value: 1200



   .. py:attribute:: MOT_REQ_POTPARAMS
      :value: 1201



   .. py:attribute:: MOT_GET_POTPARAMS
      :value: 1202



   .. py:attribute:: MOT_SET_BOWINDEX
      :value: 1268



   .. py:attribute:: MOT_REQ_BOWINDEX
      :value: 1269



   .. py:attribute:: MOT_GET_BOWINDEX
      :value: 1270



.. py:class:: AptStatusBits

   Bases: :py:obj:`enum.IntFlag`


   Motor status bits (manual pp. 126).

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


   .. py:attribute:: CWHARDLIMIT
      :value: 1



   .. py:attribute:: CCWHARDLIMIT
      :value: 2



   .. py:attribute:: CWSOFTLIMIT
      :value: 4



   .. py:attribute:: CCWSOFTLIMIT
      :value: 8



   .. py:attribute:: INMOTIONCW
      :value: 16



   .. py:attribute:: INMOTIONCCW
      :value: 32



   .. py:attribute:: JOGGINGCW
      :value: 64



   .. py:attribute:: JOGGINGCCW
      :value: 128



   .. py:attribute:: CONNECTED
      :value: 256



   .. py:attribute:: HOMING
      :value: 512



   .. py:attribute:: HOMED
      :value: 1024



   .. py:attribute:: INITIALIZING
      :value: 2048



   .. py:attribute:: TRACKING
      :value: 4096



   .. py:attribute:: SETTLED
      :value: 8192



   .. py:attribute:: POSITIONERROR
      :value: 16384



   .. py:attribute:: INSTRERROR
      :value: 32768



   .. py:attribute:: INTERLOCK
      :value: 65536



   .. py:attribute:: OVERTEMP
      :value: 131072



   .. py:attribute:: BUSVOLTFAULT
      :value: 262144



   .. py:attribute:: COMMUTATIONERROR
      :value: 524288



   .. py:attribute:: DIGIP1
      :value: 1048576



   .. py:attribute:: DIGIP2
      :value: 2097152



   .. py:attribute:: DIGIP3
      :value: 4194304



   .. py:attribute:: DIGIP4
      :value: 8388608



   .. py:attribute:: OVERLOAD
      :value: 16777216



   .. py:attribute:: ENCODERFAULT
      :value: 33554432



   .. py:attribute:: OVERCURRENT
      :value: 67108864



   .. py:attribute:: BUSCURRENTFAULT
      :value: 134217728



   .. py:attribute:: POWEROK
      :value: 268435456



   .. py:attribute:: ACTIVE
      :value: 536870912



   .. py:attribute:: ERROR
      :value: 1073741824



   .. py:attribute:: ENABLED
      :value: 2147483648



.. py:data:: APT_ERROR_BITS

   Status bits that indicate an error condition.

.. py:data:: APT_MOTION_BITS

   Status bits that indicate the motor is moving.

.. py:class:: 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.


   .. py:attribute:: message_id
      :type:  AptMessageId


   .. py:attribute:: dest
      :type:  AptAxis


   .. py:attribute:: source
      :type:  AptAxis


   .. py:attribute:: payload
      :type:  bytes


   .. py:method:: from_short(message_id: AptMessageId, param_1: int = 0, param_2: int = 0, dest: AptAxis = AptAxis.GENERIC, source: AptAxis = AptAxis.HOST) -> Self
      :classmethod:


      Create a message from short packet parts.



   .. py:method:: from_long(message_id: AptMessageId, payload: bytes, dest: AptAxis = AptAxis.GENERIC, source: AptAxis = AptAxis.HOST) -> Self
      :classmethod:


      Create a message from long packet parts.



   .. py:method:: __str__() -> str

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



   .. py:method:: to_bytes() -> bytes

      Serialize the message to on-wire bytes.



.. py:class:: _AptHeader

   Decoded fixed-size packet header.


   .. py:attribute:: message_id
      :type:  AptMessageId


   .. py:attribute:: dest
      :type:  AptAxis


   .. py:attribute:: source
      :type:  AptAxis


   .. py:attribute:: length
      :type:  int | None


   .. py:attribute:: params
      :type:  bytes | None


   .. py:method:: from_bytes(raw: bytes) -> Self
      :classmethod:


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



.. py:class:: AptRecvState

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

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


   .. py:attribute:: _buffer


   .. py:attribute:: _header
      :type:  _AptHeader | None
      :value: None



   .. py:method:: put_some(buffer: bytes) -> None

      Append received raw bytes to the internal buffer.



   .. py:method:: _take(length: int) -> bytes | None

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



   .. py:method:: messages() -> collections.abc.Iterator[AptMessage]

      Yield every complete message currently in the buffer.



.. py:class:: AptPayload

   Base class for fixed-format payload structures.

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


   .. py:attribute:: _format
      :type:  ClassVar[str]


   .. py:method:: from_bytes(raw: bytes) -> Self
      :classmethod:


      Parse the payload from raw bytes.



   .. py:method:: to_bytes() -> bytes

      Serialize the payload to raw bytes.



.. py:class:: HwInfo

   Bases: :py:obj:`AptPayload`


   Hardware info (manual pp. 52).


   .. py:attribute:: serial_number
      :type:  int


   .. py:attribute:: model
      :type:  bytes


   .. py:attribute:: hw_type
      :type:  int


   .. py:attribute:: firmware_minor
      :type:  int


   .. py:attribute:: firmware_interim
      :type:  int


   .. py:attribute:: firmware_major
      :type:  int


   .. py:attribute:: firmware_unused
      :type:  int


   .. py:attribute:: reserved
      :type:  bytes


   .. py:attribute:: hw_version
      :type:  int


   .. py:attribute:: mod_state
      :type:  int


   .. py:attribute:: num_channels
      :type:  int


   .. py:attribute:: _format
      :type:  ClassVar[str]
      :value: '<I8sHBBBB60sHHH'



   .. py:property:: model_name
      :type: str


      Return the model as a printable string.


   .. py:property:: firmware_version
      :type: str


      Return the firmware version as ``major.interim.minor``.


.. py:class:: VelParams

   Bases: :py:obj:`AptPayload`


   Velocity parameters (manual pp. 66).


   .. py:attribute:: channel
      :type:  int


   .. py:attribute:: min_velocity
      :type:  int


   .. py:attribute:: acceleration
      :type:  int


   .. py:attribute:: max_velocity
      :type:  int


   .. py:attribute:: _format
      :type:  ClassVar[str]
      :value: '<Hiii'



.. py:class:: LimSwitchParams

   Bases: :py:obj:`AptPayload`


   Limit switch parameters (manual pp. 78).


   .. py:attribute:: channel
      :type:  int


   .. py:attribute:: cw_hard_limit
      :type:  int


   .. py:attribute:: ccw_hard_limit
      :type:  int


   .. py:attribute:: cw_soft_limit
      :type:  int


   .. py:attribute:: ccw_soft_limit
      :type:  int


   .. py:attribute:: limit_mode
      :type:  int


   .. py:attribute:: _format
      :type:  ClassVar[str]
      :value: '<HHHiiH'



.. py:class:: HomeParams

   Bases: :py:obj:`AptPayload`


   Homing parameters (manual pp. 76).


   .. py:attribute:: channel
      :type:  int


   .. py:attribute:: direction
      :type:  int


   .. py:attribute:: limit_switch
      :type:  int


   .. py:attribute:: velocity
      :type:  int


   .. py:attribute:: offset_distance
      :type:  int


   .. py:attribute:: _format
      :type:  ClassVar[str]
      :value: '<HHHii'



.. py:class:: PowerParams

   Bases: :py:obj:`AptPayload`


   Motor power parameters (manual pp. 71).


   .. py:attribute:: channel
      :type:  int


   .. py:attribute:: rest_factor
      :type:  int


   .. py:attribute:: move_factor
      :type:  int


   .. py:attribute:: _format
      :type:  ClassVar[str]
      :value: '<HHH'



.. py:class:: ButtonParams

   Bases: :py:obj:`AptPayload`


   Button handling parameters (manual pp. 100).


   .. py:attribute:: channel
      :type:  int


   .. py:attribute:: mode
      :type:  int


   .. py:attribute:: position1
      :type:  int


   .. py:attribute:: position2
      :type:  int


   .. py:attribute:: timeout1
      :type:  int


   .. py:attribute:: timeout2
      :type:  int


   .. py:attribute:: _format
      :type:  ClassVar[str]
      :value: '<HHiiHH'



.. py:class:: MoveParams

   Bases: :py:obj:`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).


   .. py:attribute:: channel
      :type:  int


   .. py:attribute:: position
      :type:  int


   .. py:attribute:: _format
      :type:  ClassVar[str]
      :value: '<Hi'



.. py:class:: PosCounter

   Bases: :py:obj:`AptPayload`


   Position counter (manual pp. 63).


   .. py:attribute:: channel
      :type:  int


   .. py:attribute:: position
      :type:  int


   .. py:attribute:: _format
      :type:  ClassVar[str]
      :value: '<Hi'



.. py:class:: GenMoveParams

   Bases: :py:obj:`AptPayload`


   General move parameters (manual pp. 73).


   .. py:attribute:: channel
      :type:  int


   .. py:attribute:: backlash_distance
      :type:  int


   .. py:attribute:: _format
      :type:  ClassVar[str]
      :value: '<Hi'



.. py:class:: JogParams

   Bases: :py:obj:`AptPayload`


   Jogging parameters (manual pp. 68).


   .. py:attribute:: channel
      :type:  int


   .. py:attribute:: mode
      :type:  int


   .. py:attribute:: step_size
      :type:  int


   .. py:attribute:: min_velocity
      :type:  int


   .. py:attribute:: acceleration
      :type:  int


   .. py:attribute:: max_velocity
      :type:  int


   .. py:attribute:: stop_mode
      :type:  int


   .. py:attribute:: _format
      :type:  ClassVar[str]
      :value: '<HHiiiiH'



.. py:class:: Status

   Bases: :py:obj:`AptPayload`


   Status bits report (manual pp. 63).


   .. py:attribute:: channel
      :type:  int


   .. py:attribute:: status
      :type:  int


   .. py:attribute:: _format
      :type:  ClassVar[str]
      :value: '<HI'



   .. py:property:: status_bits
      :type: AptStatusBits


      Return the status word as :class:`AptStatusBits` flags.


.. py:class:: StatusUpdate

   Bases: :py:obj:`AptPayload`


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

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


   .. py:attribute:: channel
      :type:  int


   .. py:attribute:: position
      :type:  int


   .. py:attribute:: encoder_count
      :type:  int


   .. py:attribute:: status
      :type:  int


   .. py:attribute:: _format
      :type:  ClassVar[str]
      :value: '<HiiI'



   .. py:property:: status_bits
      :type: AptStatusBits


      Return the status word as :class:`AptStatusBits` flags.


.. py:class:: UStatusUpdate

   Bases: :py:obj:`AptPayload`


   User status report (manual pp. 125).


   .. py:attribute:: channel
      :type:  int


   .. py:attribute:: position
      :type:  int


   .. py:attribute:: velocity
      :type:  int


   .. py:attribute:: current
      :type:  int


   .. py:attribute:: status
      :type:  int


   .. py:attribute:: _format
      :type:  ClassVar[str]
      :value: '<HiHHI'



   .. py:property:: status_bits
      :type: AptStatusBits


      Return the status word as :class:`AptStatusBits` flags.


.. py:data:: APT_DECODERS
   :type:  dict[AptMessageId, Any]

   Mapping of message ids to their payload structure types.