bread-crumbs-contracts 0.5.0__py3-none-any.whl

bread_crumbs_contracts/__init__.py

@@ -0,0 +1,34 @@
+"""Pure-Python codec for the BREAD CRUMBS contracts.
+
+Mirrors ``include/bread/*.h``: one module per header, functions named after
+the C helpers. Encoders return the payload bytes a ``*_send_*`` or
+``*_query_*`` helper puts on the wire; parsers turn a reply payload into a
+frozen dataclass named after the C result struct. Framing, CRC and I2C
+belong to the transport.
+
+The constants and every encoder and parser are checked against
+``tests/golden_vectors/vectors.json``, which the C program
+``tests/golden_vectors/gen_vectors.c`` writes from the real headers.
+"""
+
+from importlib.metadata import version as _distribution_version
+
+from . import bread_caps, bread_version_helpers, bread_watchdog, crumbs, dcmt_ops, rlht_ops
+from .bread_caps import *  # noqa: F403
+from .bread_version_helpers import *  # noqa: F403
+from .bread_watchdog import *  # noqa: F403
+from .crumbs import *  # noqa: F403
+from .dcmt_ops import *  # noqa: F403
+from .rlht_ops import *  # noqa: F403
+
+#: The installed distribution's version, which ``pyproject.toml`` sets and the
+#: tests hold equal to the header package's ``library.json`` version.
+__version__ = _distribution_version("bread-crumbs-contracts")
+
+__all__: list[str] = []
+__all__ += crumbs.__all__
+__all__ += bread_caps.__all__
+__all__ += bread_watchdog.__all__
+__all__ += bread_version_helpers.__all__
+__all__ += rlht_ops.__all__
+__all__ += dcmt_ops.__all__

bread_crumbs_contracts/_wire.py

@@ -0,0 +1,64 @@
+"""Argument range checks and payload length checks shared by the codec modules.
+
+CRUMBS payload fields are little-endian; each module packs them with
+``struct`` using explicit ``<`` format strings. The checks here turn an
+out-of-range argument into a ``ValueError`` before ``struct`` could wrap or
+reject it, and a reply of the wrong length into a ``ValueError`` before
+``struct`` could raise its own error type.
+
+The two length rules mirror the C parsers as they are today, not a single
+policy: ``dcmt_parse_state_payload()`` and ``bread_watchdog_parse_payload()``
+reject any length other than the fixed one, while
+``rlht_parse_state_payload()``, ``bread_caps_parse_payload()`` and
+``bread_parse_version()`` read a fixed prefix and ignore trailing bytes.
+feastorg/bread-crumbs-contracts#18 is where the rule becomes uniform; each
+Python parser follows its C namesake until then, and the golden vectors
+record which lengths the C accepts.
+"""
+
+U8_MIN, U8_MAX = 0, 0xFF
+U16_MIN, U16_MAX = 0, 0xFFFF
+I16_MIN, I16_MAX = -0x8000, 0x7FFF
+
+
+def _check_int(name: str, value: int, lo: int, hi: int) -> int:
+    if not isinstance(value, int):  # pyright: ignore[reportUnnecessaryIsInstance]
+        raise TypeError(f"{name} must be an int, got {type(value).__name__}")
+    if not lo <= value <= hi:
+        raise ValueError(f"{name} must be in {lo}..{hi}, got {value}")
+    return value
+
+
+def u8(name: str, value: int) -> int:
+    """Return ``value`` if it fits a ``uint8_t``, else raise."""
+    return _check_int(name, value, U8_MIN, U8_MAX)
+
+
+def u16(name: str, value: int) -> int:
+    """Return ``value`` if it fits a ``uint16_t``, else raise."""
+    return _check_int(name, value, U16_MIN, U16_MAX)
+
+
+def i16(name: str, value: int) -> int:
+    """Return ``value`` if it fits an ``int16_t``, else raise."""
+    return _check_int(name, value, I16_MIN, I16_MAX)
+
+
+def require_exact_len(name: str, payload: bytes, fixed_len: int) -> None:
+    """Reject a payload whose length is not exactly ``fixed_len``.
+
+    The C check is ``data_len != FIXED_LEN``: a short payload and one with
+    trailing bytes are both rejected.
+    """
+    if len(payload) != fixed_len:
+        raise ValueError(f"{name} payload must be {fixed_len} bytes, got {len(payload)}")
+
+
+def require_min_len(name: str, payload: bytes, fixed_len: int) -> None:
+    """Reject a payload shorter than ``fixed_len``; trailing bytes are ignored.
+
+    The C check is ``len < FIXED_LEN`` (or a field-by-field read that stops
+    at the last fixed offset), so a longer payload parses as its prefix.
+    """
+    if len(payload) < fixed_len:
+        raise ValueError(f"{name} payload needs {fixed_len} bytes, got {len(payload)}")

bread_crumbs_contracts/bread_caps.py

@@ -0,0 +1,66 @@
+"""Shared sentinels and the capability query (``bread_caps.h``)."""
+
+import struct
+from dataclasses import dataclass
+
+from ._wire import require_min_len
+
+__all__ = [
+    "BREAD_CAPS_SCHEMA_V1",
+    "BREAD_CAPS_V1_PAYLOAD_LEN",
+    "BREAD_INVALID_I16",
+    "BREAD_INVALID_U8",
+    "BREAD_OP_GET_CAPS",
+    "BreadCapsResult",
+    "bread_caps_parse_payload",
+    "bread_is_valid_i16",
+    "bread_is_valid_u8",
+]
+
+#: Fixed-layout fields carry these instead of zero when the field does not
+#: apply in the current mode or build. Check with the ``bread_is_valid_*``
+#: helpers before consuming such a field.
+BREAD_INVALID_I16 = -32768
+BREAD_INVALID_U8 = 0xFF
+
+#: Capability query opcode shared by every BREADS-compatible slice.
+BREAD_OP_GET_CAPS = 0x7F
+
+#: Capability payload schema version.
+BREAD_CAPS_SCHEMA_V1 = 0x01
+
+#: v1 payload: ``[schema:u8][level:u8][flags:u32]``.
+BREAD_CAPS_V1_PAYLOAD_LEN = 6
+
+_CAPS_V1 = struct.Struct("<BBI")
+assert _CAPS_V1.size == BREAD_CAPS_V1_PAYLOAD_LEN
+
+
+def bread_is_valid_i16(value: int) -> bool:
+    """``BREAD_IS_VALID_I16``: the field is populated, not the sentinel."""
+    return value != BREAD_INVALID_I16
+
+
+def bread_is_valid_u8(value: int) -> bool:
+    """``BREAD_IS_VALID_U8``: the field is populated, not the sentinel."""
+    return value != BREAD_INVALID_U8
+
+
+@dataclass(frozen=True, slots=True)
+class BreadCapsResult:
+    """``bread_caps_result_t``."""
+
+    schema: int
+    level: int
+    flags: int
+
+
+def bread_caps_parse_payload(payload: bytes) -> BreadCapsResult:
+    """Parse a GET_CAPS reply payload (``bread_caps_parse_payload``).
+
+    Like the C parser, this reads the 6-byte v1 prefix and ignores any
+    trailing bytes; a shorter payload is rejected.
+    """
+    require_min_len("GET_CAPS", payload, BREAD_CAPS_V1_PAYLOAD_LEN)
+    schema, level, flags = _CAPS_V1.unpack_from(payload)
+    return BreadCapsResult(schema, level, flags)

bread_crumbs_contracts/bread_version_helpers.py

@@ -0,0 +1,74 @@
+"""Version reply parsing and compatibility policy (``bread_version_helpers.h``)."""
+
+import struct
+from dataclasses import dataclass
+
+from ._wire import require_min_len
+
+__all__ = [
+    "BREAD_MIN_CRUMBS_VERSION",
+    "BREAD_OP_GET_VERSION",
+    "BREAD_VERSION_PAYLOAD_LEN",
+    "BreadVersionResult",
+    "bread_check_crumbs_compat",
+    "bread_check_module_compat",
+    "bread_parse_version",
+]
+
+#: Opcode of the version query. The headers have no macro for it;
+#: ``rlht_query_version()`` and ``dcmt_query_version()`` request the literal
+#: ``0x00``, and ``bread_parse_version()`` documents it as "opcode 0x00".
+BREAD_OP_GET_VERSION = 0x00
+
+#: Lowest peripheral CRUMBS version (major*10000 + minor*100 + patch) this
+#: contract set accepts.
+BREAD_MIN_CRUMBS_VERSION = 1200
+
+#: Version payload: ``[CRUMBS_VERSION:u16][module_major:u8][module_minor:u8][module_patch:u8]``.
+#: The headers have no macro for this length either; ``bread_parse_version()``
+#: checks ``len < 5``.
+BREAD_VERSION_PAYLOAD_LEN = 5
+
+_VERSION = struct.Struct("<HBBB")
+assert _VERSION.size == BREAD_VERSION_PAYLOAD_LEN
+
+
+@dataclass(frozen=True, slots=True)
+class BreadVersionResult:
+    """The out-parameters of ``bread_parse_version``."""
+
+    crumbs_ver: int
+    mod_major: int
+    mod_minor: int
+    mod_patch: int
+
+
+def bread_parse_version(payload: bytes) -> BreadVersionResult:
+    """Parse a version reply payload (``bread_parse_version``).
+
+    Like the C parser, this reads the 5-byte prefix and ignores any
+    trailing bytes; a shorter payload is rejected.
+    """
+    require_min_len("version", payload, BREAD_VERSION_PAYLOAD_LEN)
+    crumbs_ver, mod_major, mod_minor, mod_patch = _VERSION.unpack_from(payload)
+    return BreadVersionResult(crumbs_ver, mod_major, mod_minor, mod_patch)
+
+
+def bread_check_crumbs_compat(peripheral_ver: int) -> int:
+    """``bread_check_crumbs_compat``: 0 when at or above the minimum, else -1."""
+    return 0 if peripheral_ver >= BREAD_MIN_CRUMBS_VERSION else -1
+
+
+def bread_check_module_compat(
+    peri_major: int, peri_minor: int, expect_major: int, expect_minor: int
+) -> int:
+    """``bread_check_module_compat``.
+
+    Returns 0 when compatible, -1 when MAJOR differs, -2 when the
+    peripheral MINOR is below the expected MINOR. PATCH is ignored.
+    """
+    if peri_major != expect_major:
+        return -1
+    if peri_minor < expect_minor:
+        return -2
+    return 0

bread_crumbs_contracts/bread_watchdog.py

@@ -0,0 +1,66 @@
+"""Shared bus-liveness command watchdog (``bread_watchdog.h``).
+
+Firmware boots disarmed; a controller arms it with SET_WATCHDOG. While
+armed, any valid inbound frame refreshes it; expiry drives the slice's
+actuators to their safe state without touching estop. Support is
+advertised per type by a capability flag (``RLHT_CAP_CMD_WATCHDOG``,
+``DCMT_CAP_CMD_WATCHDOG``); do not send SET_WATCHDOG unless it is set.
+"""
+
+import struct
+from dataclasses import dataclass
+
+from ._wire import require_exact_len
+
+__all__ = [
+    "BREAD_OP_GET_WATCHDOG",
+    "BREAD_OP_SET_WATCHDOG",
+    "BREAD_WATCHDOG_FIXED_LEN",
+    "BREAD_WATCHDOG_OFF_ARMED",
+    "BREAD_WATCHDOG_OFF_TIMEOUT_MS",
+    "BREAD_WATCHDOG_OFF_TRIPPED",
+    "BREAD_WATCHDOG_OFF_TRIP_COUNT",
+    "BREAD_WATCHDOG_SET_PAYLOAD_LEN",
+    "BreadWatchdogResult",
+    "bread_watchdog_parse_payload",
+]
+
+BREAD_OP_SET_WATCHDOG = 0x7E
+BREAD_OP_GET_WATCHDOG = 0x7D
+
+#: SET_WATCHDOG payload: ``[timeout_ms:u16]``, 0 = disarm.
+BREAD_WATCHDOG_SET_PAYLOAD_LEN = 2
+
+#: GET_WATCHDOG payload: ``[armed:u8][timeout_ms:u16][tripped:u8][trip_count:u8]``.
+BREAD_WATCHDOG_OFF_ARMED = 0
+BREAD_WATCHDOG_OFF_TIMEOUT_MS = 1
+BREAD_WATCHDOG_OFF_TRIPPED = 3
+BREAD_WATCHDOG_OFF_TRIP_COUNT = 4
+BREAD_WATCHDOG_FIXED_LEN = 5
+
+_WATCHDOG = struct.Struct("<BHBB")
+assert _WATCHDOG.size == BREAD_WATCHDOG_FIXED_LEN
+
+
+@dataclass(frozen=True, slots=True)
+class BreadWatchdogResult:
+    """``bread_watchdog_result_t``."""
+
+    armed: int
+    #: Configured timeout; 0 when disarmed.
+    timeout_ms: int
+    #: Currently expired; clears on the next valid SET command.
+    tripped: int
+    #: Cumulative trips since boot, never cleared.
+    trip_count: int
+
+
+def bread_watchdog_parse_payload(payload: bytes) -> BreadWatchdogResult:
+    """Parse a GET_WATCHDOG reply payload (``bread_watchdog_parse_payload``).
+
+    Like the C parser, this rejects any length other than
+    ``BREAD_WATCHDOG_FIXED_LEN``, trailing bytes included.
+    """
+    require_exact_len("GET_WATCHDOG", payload, BREAD_WATCHDOG_FIXED_LEN)
+    armed, timeout_ms, tripped, trip_count = _WATCHDOG.unpack_from(payload)
+    return BreadWatchdogResult(armed, timeout_ms, tripped, trip_count)

bread_crumbs_contracts/crumbs.py

@@ -0,0 +1,23 @@
+"""The few CRUMBS protocol constants the contracts depend on (``crumbs.h``).
+
+Framing, CRC and I2C stay in the transport (CRUMBS itself, or a Python
+binding of it). This package stops at the message level: a type id, an
+opcode and the payload bytes between the frame header and the CRC.
+"""
+
+__all__ = [
+    "CRUMBS_CMD_SET_REPLY",
+    "CRUMBS_MAX_PAYLOAD",
+    "CRUMBS_TYPE_ID_ANY",
+]
+
+#: Wildcard type id; a peripheral never rejects a frame carrying it.
+CRUMBS_TYPE_ID_ANY = 0x00
+
+#: Opcode of the SET_REPLY frame a controller sends before reading a reply.
+#: Its one-byte payload names the opcode whose reply the peripheral should
+#: build next. The ``*_query_*`` encoders return that payload.
+CRUMBS_CMD_SET_REPLY = 0xFE
+
+#: Largest payload a CRUMBS frame carries.
+CRUMBS_MAX_PAYLOAD = 27

bread_crumbs_contracts/dcmt_ops.py

@@ -0,0 +1,214 @@
+"""DCMT (DC motor) contract (``dcmt_ops.h``).
+
+Each ``dcmt_send_*`` function returns the payload its C namesake puts on
+the wire; send it with ``DCMT_TYPE_ID`` and the matching ``DCMT_OP_*``
+opcode. Each ``dcmt_query_*`` function returns the one-byte payload of the
+SET_REPLY frame (type ``CRUMBS_TYPE_ID_ANY``, opcode ``CRUMBS_CMD_SET_REPLY``)
+that asks the slice to build that reply.
+"""
+
+import struct
+from dataclasses import dataclass
+
+from ._wire import i16, require_exact_len, u8, u16
+from .bread_caps import BREAD_OP_GET_CAPS
+from .bread_version_helpers import BREAD_OP_GET_VERSION
+from .bread_watchdog import BREAD_OP_GET_WATCHDOG
+
+__all__ = [
+    "DCMT_CAP_BASELINE_FLAGS",
+    "DCMT_CAP_BRAKE_CONTROL",
+    "DCMT_CAP_CLOSED_LOOP_POSITION",
+    "DCMT_CAP_CLOSED_LOOP_SPEED",
+    "DCMT_CAP_CMD_WATCHDOG",
+    "DCMT_CAP_LEVEL_1",
+    "DCMT_CAP_LEVEL_2",
+    "DCMT_CAP_LEVEL_3",
+    "DCMT_CAP_OPEN_LOOP_CONTROL",
+    "DCMT_CAP_PID_TUNING",
+    "DCMT_MODE_CLOSED_POSITION",
+    "DCMT_MODE_CLOSED_SPEED",
+    "DCMT_MODE_OPEN_LOOP",
+    "DCMT_MODULE_VER_MAJOR",
+    "DCMT_MODULE_VER_MINOR",
+    "DCMT_MODULE_VER_PATCH",
+    "DCMT_OP_GET_STATE",
+    "DCMT_OP_SET_BRAKE",
+    "DCMT_OP_SET_MODE",
+    "DCMT_OP_SET_OPEN_LOOP",
+    "DCMT_OP_SET_PID",
+    "DCMT_OP_SET_SETPOINT",
+    "DCMT_STATE_FIXED_LEN",
+    "DCMT_STATE_OFF_BRAKES",
+    "DCMT_STATE_OFF_ESTOP",
+    "DCMT_STATE_OFF_M1_PWM",
+    "DCMT_STATE_OFF_M2_PWM",
+    "DCMT_STATE_OFF_MODE",
+    "DCMT_STATE_OFF_POS1",
+    "DCMT_STATE_OFF_POS2",
+    "DCMT_STATE_OFF_SP1",
+    "DCMT_STATE_OFF_SP2",
+    "DCMT_STATE_OFF_SPD1",
+    "DCMT_STATE_OFF_SPD2",
+    "DCMT_TYPE_ID",
+    "DcmtStateResult",
+    "dcmt_parse_state_payload",
+    "dcmt_query_caps",
+    "dcmt_query_state",
+    "dcmt_query_version",
+    "dcmt_query_watchdog",
+    "dcmt_send_set_brake",
+    "dcmt_send_set_mode",
+    "dcmt_send_set_open_loop",
+    "dcmt_send_set_pid",
+    "dcmt_send_set_setpoint",
+    "dcmt_send_set_watchdog",
+]
+
+DCMT_TYPE_ID = 0x02
+
+DCMT_MODULE_VER_MAJOR = 1
+DCMT_MODULE_VER_MINOR = 0
+DCMT_MODULE_VER_PATCH = 0
+
+DCMT_OP_SET_OPEN_LOOP = 0x01
+DCMT_OP_SET_BRAKE = 0x02
+DCMT_OP_SET_MODE = 0x03
+DCMT_OP_SET_SETPOINT = 0x04
+DCMT_OP_SET_PID = 0x05
+
+DCMT_OP_GET_STATE = 0x80
+
+#: GET_STATE payload (19 bytes):
+#: ``[mode:u8][m1_pwm:i16][m2_pwm:i16][sp1:i16][sp2:i16]``
+#: ``[pos1:i16][pos2:i16][spd1:i16][spd2:i16][brakes:u8][estop:u8]``.
+#: ``sp1``/``sp2`` are ``BREAD_INVALID_I16`` in ``DCMT_MODE_OPEN_LOOP``;
+#: ``spd1``/``spd2`` are ``BREAD_INVALID_I16`` unless ``DCMT_MODE_CLOSED_SPEED``.
+DCMT_STATE_OFF_MODE = 0
+DCMT_STATE_OFF_M1_PWM = 1
+DCMT_STATE_OFF_M2_PWM = 3
+DCMT_STATE_OFF_SP1 = 5
+DCMT_STATE_OFF_SP2 = 7
+DCMT_STATE_OFF_POS1 = 9
+DCMT_STATE_OFF_POS2 = 11
+DCMT_STATE_OFF_SPD1 = 13
+DCMT_STATE_OFF_SPD2 = 15
+DCMT_STATE_OFF_BRAKES = 17
+DCMT_STATE_OFF_ESTOP = 18
+DCMT_STATE_FIXED_LEN = 19
+
+DCMT_MODE_OPEN_LOOP = 0x00
+DCMT_MODE_CLOSED_POSITION = 0x01
+DCMT_MODE_CLOSED_SPEED = 0x02
+
+DCMT_CAP_LEVEL_1 = 0x01
+DCMT_CAP_LEVEL_2 = 0x02
+DCMT_CAP_LEVEL_3 = 0x03
+
+DCMT_CAP_OPEN_LOOP_CONTROL = 1 << 0
+DCMT_CAP_BRAKE_CONTROL = 1 << 1
+DCMT_CAP_CLOSED_LOOP_POSITION = 1 << 2
+DCMT_CAP_CLOSED_LOOP_SPEED = 1 << 3
+DCMT_CAP_PID_TUNING = 1 << 4
+DCMT_CAP_CMD_WATCHDOG = 1 << 5
+
+DCMT_CAP_BASELINE_FLAGS = DCMT_CAP_OPEN_LOOP_CONTROL | DCMT_CAP_BRAKE_CONTROL
+
+_STATE = struct.Struct("<BhhhhhhhhBB")
+assert _STATE.size == DCMT_STATE_FIXED_LEN
+
+_U8 = struct.Struct("<B")
+_U8_U8 = struct.Struct("<BB")
+_U16 = struct.Struct("<H")
+_I16_I16 = struct.Struct("<hh")
+_PID = struct.Struct("<BBBBBB")
+
+
+@dataclass(frozen=True, slots=True)
+class DcmtStateResult:
+    """``dcmt_state_result_t``."""
+
+    mode: int
+    #: Current PWM output, always valid.
+    m1_pwm: int
+    m2_pwm: int
+    #: Active setpoint; ``BREAD_INVALID_I16`` in OPEN_LOOP.
+    sp1: int
+    sp2: int
+    #: Encoder position, always populated.
+    pos1: int
+    pos2: int
+    #: Tachometer speed; ``BREAD_INVALID_I16`` unless CLOSED_SPEED.
+    spd1: int
+    spd2: int
+    brakes: int
+    estop: int
+
+
+def dcmt_send_set_open_loop(m1_pwm: int, m2_pwm: int) -> bytes:
+    """``DCMT_OP_SET_OPEN_LOOP`` payload: ``[m1_pwm:i16][m2_pwm:i16]``."""
+    return _I16_I16.pack(i16("m1_pwm", m1_pwm), i16("m2_pwm", m2_pwm))
+
+
+def dcmt_send_set_brake(m1_brake: int, m2_brake: int) -> bytes:
+    """``DCMT_OP_SET_BRAKE`` payload: ``[m1_brake:u8][m2_brake:u8]``."""
+    return _U8_U8.pack(u8("m1_brake", m1_brake), u8("m2_brake", m2_brake))
+
+
+def dcmt_send_set_mode(mode: int) -> bytes:
+    """``DCMT_OP_SET_MODE`` payload: ``[mode:u8]`` (``DCMT_MODE_*``)."""
+    return _U8.pack(u8("mode", mode))
+
+
+def dcmt_send_set_setpoint(target1: int, target2: int) -> bytes:
+    """``DCMT_OP_SET_SETPOINT`` payload: ``[target1:i16][target2:i16]``."""
+    return _I16_I16.pack(i16("target1", target1), i16("target2", target2))
+
+
+def dcmt_send_set_pid(
+    kp1_x10: int, ki1_x10: int, kd1_x10: int, kp2_x10: int, ki2_x10: int, kd2_x10: int
+) -> bytes:
+    """``DCMT_OP_SET_PID`` payload: six ``u8`` gains, each ten times the gain."""
+    return _PID.pack(
+        u8("kp1_x10", kp1_x10),
+        u8("ki1_x10", ki1_x10),
+        u8("kd1_x10", kd1_x10),
+        u8("kp2_x10", kp2_x10),
+        u8("ki2_x10", ki2_x10),
+        u8("kd2_x10", kd2_x10),
+    )
+
+
+def dcmt_send_set_watchdog(timeout_ms: int) -> bytes:
+    """``BREAD_OP_SET_WATCHDOG`` payload: ``[timeout_ms:u16]``, 0 = disarm."""
+    return _U16.pack(u16("timeout_ms", timeout_ms))
+
+
+def dcmt_query_state() -> bytes:
+    """SET_REPLY payload requesting ``DCMT_OP_GET_STATE``."""
+    return _U8.pack(DCMT_OP_GET_STATE)
+
+
+def dcmt_query_version() -> bytes:
+    """SET_REPLY payload requesting the version reply."""
+    return _U8.pack(BREAD_OP_GET_VERSION)
+
+
+def dcmt_query_caps() -> bytes:
+    """SET_REPLY payload requesting ``BREAD_OP_GET_CAPS``."""
+    return _U8.pack(BREAD_OP_GET_CAPS)
+
+
+def dcmt_query_watchdog() -> bytes:
+    """SET_REPLY payload requesting ``BREAD_OP_GET_WATCHDOG``."""
+    return _U8.pack(BREAD_OP_GET_WATCHDOG)
+
+
+def dcmt_parse_state_payload(payload: bytes) -> DcmtStateResult:
+    """Parse a GET_STATE reply payload (``dcmt_parse_state_payload``).
+
+    Like the C parser, this rejects any length other than
+    ``DCMT_STATE_FIXED_LEN``, trailing bytes included.
+    """
+    require_exact_len("DCMT GET_STATE", payload, DCMT_STATE_FIXED_LEN)
+    return DcmtStateResult(*_STATE.unpack_from(payload))