conduyt-py 0.1.0__tar.gz

conduyt_py-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: conduyt-py
+Version: 0.1.0
+Summary: CONDUYT protocol SDK for Python — host-side hardware control
+License: MIT
+Project-URL: Homepage, https://github.com/virgilvox/conduyt
+Project-URL: Repository, https://github.com/virgilvox/conduyt
+Project-URL: Issues, https://github.com/virgilvox/conduyt/issues
+Keywords: conduyt,iot,hardware,serial,mqtt,microcontroller,binary-protocol
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: serial
+Requires-Dist: pyserial-asyncio>=0.6; extra == "serial"
+Provides-Extra: mqtt
+Requires-Dist: aiomqtt>=2.0; extra == "mqtt"
+Provides-Extra: all
+Requires-Dist: pyserial-asyncio>=0.6; extra == "all"
+Requires-Dist: aiomqtt>=2.0; extra == "all"
+
+# conduyt-py
+
+CONDUYT protocol SDK for Python. Async and sync APIs for host-side hardware control.
+
+## Install
+
+```bash
+pip install conduyt-py
+
+# With serial transport
+pip install conduyt-py[serial]
+
+# With MQTT transport
+pip install conduyt-py[mqtt]
+
+# All transports
+pip install conduyt-py[all]
+```
+
+## Quick Start
+
+### Async
+
+```python
+from conduyt import ConduytDevice
+from conduyt.transports.serial import SerialTransport
+
+device = ConduytDevice(SerialTransport("/dev/ttyUSB0"))
+hello = await device.connect()
+
+await device.pin(13).mode("output")
+await device.pin(13).write(1)
+value = await device.pin(0).read("analog")
+
+await device.disconnect()
+```
+
+### Sync
+
+```python
+from conduyt import ConduytDeviceSync
+from conduyt.transports.serial import SerialTransport
+
+device = ConduytDeviceSync(SerialTransport("/dev/ttyUSB0"))
+device.connect()
+
+device.pin(13).mode("output")
+device.pin(13).write(1)
+value = device.pin(0).read("analog")
+
+device.disconnect()
+```
+
+### Module Usage
+
+```python
+from conduyt.modules.servo import ConduytServo
+
+servo = ConduytServo(device)
+await servo.attach(9)
+await servo.write(90)
+```
+
+## API Reference
+
+### ConduytDevice (async)
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `connect()` | `HelloResp` | Connect and run HELLO handshake |
+| `disconnect()` | `None` | Close connection |
+| `ping()` | `None` | Ping/pong roundtrip |
+| `reset()` | `None` | Reset device state |
+| `pin(num)` | `PinProxy` | Pin control object |
+
+### ConduytDeviceSync
+
+Synchronous wrapper around `ConduytDevice`. Same methods, no `await`.
+
+### PinProxy
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `mode(mode)` | `None` | Set pin mode: `"input"`, `"output"`, `"pwm"`, `"analog"`, `"input_pullup"` |
+| `write(value)` | `None` | Digital or PWM write |
+| `read(mode?)` | `int` | Read pin value |
+
+### Errors
+
+| Class | When |
+|-------|------|
+| `ConduytNAKError` | Device rejected a command |
+| `ConduytTimeoutError` | No response within timeout |
+| `ConduytDisconnectedError` | Transport disconnected |
+
+## Transports
+
+| Transport | Module | Dependency |
+|-----------|--------|------------|
+| `SerialTransport` | `conduyt.transports.serial` | `pyserial-asyncio` |
+| `MQTTTransport` | `conduyt.transports.mqtt` | `aiomqtt` |
+| `MockTransport` | `conduyt.transports.mock` | None |
+
+## Modules
+
+| Module | Import | Hardware |
+|--------|--------|----------|
+| `ConduytServo` | `conduyt.modules.servo` | Hobby servos |
+| `ConduytNeoPixel` | `conduyt.modules.neopixel` | WS2812/SK6812 LEDs |
+| `ConduytDHT` | `conduyt.modules.dht` | DHT11/DHT22 sensors |
+| `ConduytOLED` | `conduyt.modules.oled` | SSD1306 OLED displays |
+| `ConduytStepper` | `conduyt.modules.stepper` | Stepper motors |
+| `ConduytEncoder` | `conduyt.modules.encoder` | Rotary encoders |
+| `ConduytPID` | `conduyt.modules.pid` | PID controller |
+
+## Requirements
+
+- Python >= 3.10
+- `pyserial-asyncio >= 0.6` (for serial transport)
+- `aiomqtt >= 2.0` (for MQTT transport)
+
+## License
+
+MIT. Copyright (c) 2026 LumenCanvas.

conduyt_py-0.1.0/README.md

@@ -0,0 +1,124 @@
+# conduyt-py
+
+CONDUYT protocol SDK for Python. Async and sync APIs for host-side hardware control.
+
+## Install
+
+```bash
+pip install conduyt-py
+
+# With serial transport
+pip install conduyt-py[serial]
+
+# With MQTT transport
+pip install conduyt-py[mqtt]
+
+# All transports
+pip install conduyt-py[all]
+```
+
+## Quick Start
+
+### Async
+
+```python
+from conduyt import ConduytDevice
+from conduyt.transports.serial import SerialTransport
+
+device = ConduytDevice(SerialTransport("/dev/ttyUSB0"))
+hello = await device.connect()
+
+await device.pin(13).mode("output")
+await device.pin(13).write(1)
+value = await device.pin(0).read("analog")
+
+await device.disconnect()
+```
+
+### Sync
+
+```python
+from conduyt import ConduytDeviceSync
+from conduyt.transports.serial import SerialTransport
+
+device = ConduytDeviceSync(SerialTransport("/dev/ttyUSB0"))
+device.connect()
+
+device.pin(13).mode("output")
+device.pin(13).write(1)
+value = device.pin(0).read("analog")
+
+device.disconnect()
+```
+
+### Module Usage
+
+```python
+from conduyt.modules.servo import ConduytServo
+
+servo = ConduytServo(device)
+await servo.attach(9)
+await servo.write(90)
+```
+
+## API Reference
+
+### ConduytDevice (async)
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `connect()` | `HelloResp` | Connect and run HELLO handshake |
+| `disconnect()` | `None` | Close connection |
+| `ping()` | `None` | Ping/pong roundtrip |
+| `reset()` | `None` | Reset device state |
+| `pin(num)` | `PinProxy` | Pin control object |
+
+### ConduytDeviceSync
+
+Synchronous wrapper around `ConduytDevice`. Same methods, no `await`.
+
+### PinProxy
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `mode(mode)` | `None` | Set pin mode: `"input"`, `"output"`, `"pwm"`, `"analog"`, `"input_pullup"` |
+| `write(value)` | `None` | Digital or PWM write |
+| `read(mode?)` | `int` | Read pin value |
+
+### Errors
+
+| Class | When |
+|-------|------|
+| `ConduytNAKError` | Device rejected a command |
+| `ConduytTimeoutError` | No response within timeout |
+| `ConduytDisconnectedError` | Transport disconnected |
+
+## Transports
+
+| Transport | Module | Dependency |
+|-----------|--------|------------|
+| `SerialTransport` | `conduyt.transports.serial` | `pyserial-asyncio` |
+| `MQTTTransport` | `conduyt.transports.mqtt` | `aiomqtt` |
+| `MockTransport` | `conduyt.transports.mock` | None |
+
+## Modules
+
+| Module | Import | Hardware |
+|--------|--------|----------|
+| `ConduytServo` | `conduyt.modules.servo` | Hobby servos |
+| `ConduytNeoPixel` | `conduyt.modules.neopixel` | WS2812/SK6812 LEDs |
+| `ConduytDHT` | `conduyt.modules.dht` | DHT11/DHT22 sensors |
+| `ConduytOLED` | `conduyt.modules.oled` | SSD1306 OLED displays |
+| `ConduytStepper` | `conduyt.modules.stepper` | Stepper motors |
+| `ConduytEncoder` | `conduyt.modules.encoder` | Rotary encoders |
+| `ConduytPID` | `conduyt.modules.pid` | PID controller |
+
+## Requirements
+
+- Python >= 3.10
+- `pyserial-asyncio >= 0.6` (for serial transport)
+- `aiomqtt >= 2.0` (for MQTT transport)
+
+## License
+
+MIT. Copyright (c) 2026 LumenCanvas.

conduyt_py-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "conduyt-py"
+version = "0.1.0"
+description = "CONDUYT protocol SDK for Python — host-side hardware control"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+dependencies = []
+keywords = ["conduyt", "iot", "hardware", "serial", "mqtt", "microcontroller", "binary-protocol"]
+
+[project.urls]
+Homepage = "https://github.com/virgilvox/conduyt"
+Repository = "https://github.com/virgilvox/conduyt"
+Issues = "https://github.com/virgilvox/conduyt/issues"
+
+[project.optional-dependencies]
+serial = ["pyserial-asyncio>=0.6"]
+mqtt = ["aiomqtt>=2.0"]
+all = ["pyserial-asyncio>=0.6", "aiomqtt>=2.0"]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

conduyt_py-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

conduyt_py-0.1.0/src/conduyt/__init__.py

@@ -0,0 +1,18 @@
+"""
+conduyt-py — CONDUYT Protocol SDK for Python
+
+Reference host-side SDK for the CONDUYT protocol.
+Transport-agnostic, capability-first hardware control.
+"""
+
+from conduyt.device import ConduytDevice
+from conduyt.sync import ConduytDeviceSync
+from conduyt.core.errors import ConduytNAKError, ConduytTimeoutError, ConduytDisconnectedError
+
+__all__ = [
+    "ConduytDevice",
+    "ConduytDeviceSync",
+    "ConduytNAKError",
+    "ConduytTimeoutError",
+    "ConduytDisconnectedError",
+]

conduyt_py-0.1.0/src/conduyt/core/cobs.py

@@ -0,0 +1,60 @@
+"""COBS — Consistent Overhead Byte Stuffing"""
+
+
+def cobs_encode(src: bytes | bytearray) -> bytes:
+    """Encode data using COBS. Output never contains 0x00."""
+    if len(src) == 0:
+        return bytes([0x01])
+
+    dst = bytearray()
+    code_idx = len(dst)
+    dst.append(0)  # placeholder for first code byte
+    code = 1
+
+    for b in src:
+        if b == 0x00:
+            dst[code_idx] = code
+            code_idx = len(dst)
+            dst.append(0)  # placeholder
+            code = 1
+        else:
+            dst.append(b)
+            code += 1
+            if code == 0xFF:
+                dst[code_idx] = code
+                code_idx = len(dst)
+                dst.append(0)
+                code = 1
+
+    dst[code_idx] = code
+    return bytes(dst)
+
+
+def cobs_decode(src: bytes | bytearray) -> bytes | None:
+    """Decode COBS-encoded data. Returns None on decode error."""
+    if len(src) == 0:
+        return None
+
+    dst = bytearray()
+    idx = 0
+
+    while idx < len(src):
+        code = src[idx]
+        idx += 1
+
+        if code == 0x00:
+            return None  # unexpected zero
+
+        count = code - 1
+
+        if idx + count > len(src):
+            return None
+
+        for _ in range(count):
+            dst.append(src[idx])
+            idx += 1
+
+        if code < 0xFF and idx < len(src):
+            dst.append(0x00)
+
+    return bytes(dst)

conduyt_py-0.1.0/src/conduyt/core/constants.py

@@ -0,0 +1,119 @@
+"""
+CONDUYT Protocol Constants
+Generated from protocol/constants.json — DO NOT EDIT
+"""
+
+PROTOCOL_VERSION = 0x01
+MAGIC = bytes([0x43, 0x44])  # "CD"
+HEADER_SIZE = 8  # MAGIC(2) + VER(1) + TYPE(1) + SEQ(1) + LEN(2) + CRC(1)
+
+# Host -> Device Commands
+class CMD:
+    PING            = 0x01
+    HELLO           = 0x02
+    PIN_MODE        = 0x10
+    PIN_WRITE       = 0x11
+    PIN_READ        = 0x12
+    PIN_SUBSCRIBE   = 0x13
+    PIN_UNSUBSCRIBE = 0x14
+    I2C_WRITE       = 0x20
+    I2C_READ        = 0x21
+    I2C_READ_REG    = 0x22
+    SPI_XFER        = 0x30
+    MOD_CMD         = 0x40
+    STREAM_START    = 0x50
+    STREAM_STOP     = 0x51
+    DS_WRITE        = 0x60
+    DS_READ         = 0x61
+    DS_SUBSCRIBE    = 0x62
+    OTA_BEGIN       = 0x70
+    OTA_CHUNK       = 0x71
+    OTA_FINALIZE    = 0x72
+    RESET           = 0xF0
+
+# Device -> Host Events
+class EVT:
+    PONG            = 0x80
+    HELLO_RESP      = 0x81
+    ACK             = 0x82
+    NAK             = 0x83
+    PIN_EVENT       = 0x90
+    PIN_READ_RESP   = 0x91
+    I2C_READ_RESP   = 0xA0
+    SPI_XFER_RESP   = 0xB0
+    MOD_EVENT       = 0xC0
+    MOD_RESP        = 0xC1
+    STREAM_DATA     = 0xD0
+    DS_EVENT        = 0xD1
+    DS_READ_RESP    = 0xD2
+    LOG             = 0xE0
+    FATAL           = 0xFF
+
+# NAK Error Codes
+class ERR:
+    UNKNOWN_TYPE         = 0x01
+    CRC_MISMATCH         = 0x02
+    PAYLOAD_TOO_LARGE    = 0x03
+    INVALID_PIN          = 0x04
+    PIN_MODE_UNSUPPORTED = 0x05
+    I2C_NOT_AVAILABLE    = 0x06
+    I2C_NACK             = 0x07
+    MODULE_NOT_LOADED    = 0x08
+    UNKNOWN_MODULE_CMD   = 0x09
+    MODULE_BUSY          = 0x0A
+    SUB_LIMIT_REACHED    = 0x0B
+    OUT_OF_MEMORY        = 0x0C
+    UNKNOWN_DATASTREAM   = 0x0D
+    DATASTREAM_READONLY  = 0x0E
+    OTA_INVALID          = 0x0F
+    VERSION_MISMATCH     = 0x10
+
+ERR_NAMES: dict[int, str] = {
+    ERR.UNKNOWN_TYPE: "UNKNOWN_TYPE",
+    ERR.CRC_MISMATCH: "CRC_MISMATCH",
+    ERR.PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE",
+    ERR.INVALID_PIN: "INVALID_PIN",
+    ERR.PIN_MODE_UNSUPPORTED: "PIN_MODE_UNSUPPORTED",
+    ERR.I2C_NOT_AVAILABLE: "I2C_NOT_AVAILABLE",
+    ERR.I2C_NACK: "I2C_NACK",
+    ERR.MODULE_NOT_LOADED: "MODULE_NOT_LOADED",
+    ERR.UNKNOWN_MODULE_CMD: "UNKNOWN_MODULE_CMD",
+    ERR.MODULE_BUSY: "MODULE_BUSY",
+    ERR.SUB_LIMIT_REACHED: "SUB_LIMIT_REACHED",
+    ERR.OUT_OF_MEMORY: "OUT_OF_MEMORY",
+    ERR.UNKNOWN_DATASTREAM: "UNKNOWN_DATASTREAM",
+    ERR.DATASTREAM_READONLY: "DATASTREAM_READONLY",
+    ERR.OTA_INVALID: "OTA_INVALID",
+    ERR.VERSION_MISMATCH: "VERSION_MISMATCH",
+}
+
+# Datastream Type Codes
+class DS_TYPE:
+    BOOL    = 0x01
+    INT8    = 0x02
+    UINT8   = 0x03
+    INT16   = 0x04
+    UINT16  = 0x05
+    INT32   = 0x06
+    FLOAT32 = 0x07
+    STRING  = 0x08
+    BYTES   = 0x09
+
+# Pin Capability Bitmask
+class PIN_CAP:
+    DIGITAL_IN  = 1 << 0
+    DIGITAL_OUT = 1 << 1
+    PWM_OUT     = 1 << 2
+    ANALOG_IN   = 1 << 3
+    I2C_SDA     = 1 << 4
+    I2C_SCL     = 1 << 5
+    SPI         = 1 << 6
+    INTERRUPT   = 1 << 7
+
+# Pin Modes
+class PIN_MODE:
+    INPUT        = 0x00
+    OUTPUT       = 0x01
+    PWM          = 0x02
+    ANALOG       = 0x03
+    INPUT_PULLUP = 0x04

conduyt_py-0.1.0/src/conduyt/core/crc8.py

@@ -0,0 +1,44 @@
+"""CRC8 Dallas/Maxim (polynomial 0x31, init 0x00)"""
+
+_TABLE = bytes([
+    0x00, 0x31, 0x62, 0x53, 0xC4, 0xF5, 0xA6, 0x97,
+    0xB9, 0x88, 0xDB, 0xEA, 0x7D, 0x4C, 0x1F, 0x2E,
+    0x43, 0x72, 0x21, 0x10, 0x87, 0xB6, 0xE5, 0xD4,
+    0xFA, 0xCB, 0x98, 0xA9, 0x3E, 0x0F, 0x5C, 0x6D,
+    0x86, 0xB7, 0xE4, 0xD5, 0x42, 0x73, 0x20, 0x11,
+    0x3F, 0x0E, 0x5D, 0x6C, 0xFB, 0xCA, 0x99, 0xA8,
+    0xC5, 0xF4, 0xA7, 0x96, 0x01, 0x30, 0x63, 0x52,
+    0x7C, 0x4D, 0x1E, 0x2F, 0xB8, 0x89, 0xDA, 0xEB,
+    0x3D, 0x0C, 0x5F, 0x6E, 0xF9, 0xC8, 0x9B, 0xAA,
+    0x84, 0xB5, 0xE6, 0xD7, 0x40, 0x71, 0x22, 0x13,
+    0x7E, 0x4F, 0x1C, 0x2D, 0xBA, 0x8B, 0xD8, 0xE9,
+    0xC7, 0xF6, 0xA5, 0x94, 0x03, 0x32, 0x61, 0x50,
+    0xBB, 0x8A, 0xD9, 0xE8, 0x7F, 0x4E, 0x1D, 0x2C,
+    0x02, 0x33, 0x60, 0x51, 0xC6, 0xF7, 0xA4, 0x95,
+    0xF8, 0xC9, 0x9A, 0xAB, 0x3C, 0x0D, 0x5E, 0x6F,
+    0x41, 0x70, 0x23, 0x12, 0x85, 0xB4, 0xE7, 0xD6,
+    0x7A, 0x4B, 0x18, 0x29, 0xBE, 0x8F, 0xDC, 0xED,
+    0xC3, 0xF2, 0xA1, 0x90, 0x07, 0x36, 0x65, 0x54,
+    0x39, 0x08, 0x5B, 0x6A, 0xFD, 0xCC, 0x9F, 0xAE,
+    0x80, 0xB1, 0xE2, 0xD3, 0x44, 0x75, 0x26, 0x17,
+    0xFC, 0xCD, 0x9E, 0xAF, 0x38, 0x09, 0x5A, 0x6B,
+    0x45, 0x74, 0x27, 0x16, 0x81, 0xB0, 0xE3, 0xD2,
+    0xBF, 0x8E, 0xDD, 0xEC, 0x7B, 0x4A, 0x19, 0x28,
+    0x06, 0x37, 0x64, 0x55, 0xC2, 0xF3, 0xA0, 0x91,
+    0x47, 0x76, 0x25, 0x14, 0x83, 0xB2, 0xE1, 0xD0,
+    0xFE, 0xCF, 0x9C, 0xAD, 0x3A, 0x0B, 0x58, 0x69,
+    0x04, 0x35, 0x66, 0x57, 0xC0, 0xF1, 0xA2, 0x93,
+    0xBD, 0x8C, 0xDF, 0xEE, 0x79, 0x48, 0x1B, 0x2A,
+    0xE1, 0xD0, 0x83, 0xB2, 0x25, 0x14, 0x47, 0x76,
+    0x58, 0x69, 0x3A, 0x0B, 0x9C, 0xAD, 0xFE, 0xCF,
+    0xA2, 0x93, 0xC0, 0xF1, 0x66, 0x57, 0x04, 0x35,
+    0x1B, 0x2A, 0x79, 0x48, 0xDF, 0xEE, 0xBD, 0x8C,
+])
+
+
+def crc8(data: bytes | bytearray) -> int:
+    """Compute CRC8 Dallas/Maxim over a byte sequence."""
+    crc = 0x00
+    for b in data:
+        crc = _TABLE[crc ^ b]
+    return crc

conduyt_py-0.1.0/src/conduyt/core/errors.py

@@ -0,0 +1,30 @@
+"""CONDUYT Error Types"""
+
+from .constants import ERR_NAMES
+
+
+class ConduytNAKError(Exception):
+    """Raised when the device replies with a NAK packet."""
+
+    def __init__(self, code: int, seq: int) -> None:
+        name = ERR_NAMES.get(code, f"UNKNOWN_0x{code:02x}")
+        super().__init__(f"NAK: {name} (code=0x{code:02x}, seq={seq})")
+        self.code = code
+        self.error_name = name
+        self.seq = seq
+
+
+class ConduytTimeoutError(Exception):
+    """Raised when a command does not receive a response in time."""
+
+    def __init__(self, seq: int, timeout_ms: int) -> None:
+        super().__init__(f"Timeout: no response for seq={seq} after {timeout_ms}ms")
+        self.seq = seq
+        self.timeout_ms = timeout_ms
+
+
+class ConduytDisconnectedError(Exception):
+    """Raised when an operation is attempted on a disconnected device."""
+
+    def __init__(self, message: str = "Device is not connected") -> None:
+        super().__init__(message)

conduyt_py-0.1.0/src/conduyt/core/wire.py

@@ -0,0 +1,78 @@
+"""CONDUYT Wire Format — Packet encode/decode"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+
+from .constants import PROTOCOL_VERSION, MAGIC, HEADER_SIZE
+from .crc8 import crc8
+
+
+@dataclass
+class ConduytPacket:
+    version: int
+    type: int
+    seq: int
+    payload: bytes
+
+
+def wire_encode(packet: ConduytPacket) -> bytes:
+    """Encode a ConduytPacket into raw wire bytes."""
+    payload_len = len(packet.payload)
+    buf = bytearray(HEADER_SIZE + payload_len)
+
+    # MAGIC
+    buf[0] = MAGIC[0]
+    buf[1] = MAGIC[1]
+    # VER
+    buf[2] = packet.version
+    # TYPE
+    buf[3] = packet.type
+    # SEQ
+    buf[4] = packet.seq
+    # LEN (little-endian uint16)
+    struct.pack_into("<H", buf, 5, payload_len)
+    # PAYLOAD
+    buf[7 : 7 + payload_len] = packet.payload
+    # CRC8 over [VER..end of PAYLOAD]
+    crc_region = buf[2 : 7 + payload_len]
+    buf[7 + payload_len] = crc8(crc_region)
+
+    return bytes(buf)
+
+
+def wire_decode(data: bytes | bytearray) -> ConduytPacket:
+    """Decode raw wire bytes into a ConduytPacket. Raises ValueError on error."""
+    if len(data) < HEADER_SIZE:
+        raise ValueError(f"Incomplete packet: need {HEADER_SIZE} bytes, got {len(data)}")
+
+    if data[0] != MAGIC[0] or data[1] != MAGIC[1]:
+        raise ValueError(f"Invalid magic: 0x{data[0]:02x}{data[1]:02x}")
+
+    version = data[2]
+    if version != PROTOCOL_VERSION:
+        raise ValueError(f"Version mismatch: expected {PROTOCOL_VERSION}, got {version}")
+
+    pkt_type = data[3]
+    seq = data[4]
+    payload_len = struct.unpack_from("<H", data, 5)[0]
+
+    total = HEADER_SIZE + payload_len
+    if len(data) < total:
+        raise ValueError(f"Incomplete packet: need {total} bytes, got {len(data)}")
+
+    crc_region = data[2 : 7 + payload_len]
+    expected_crc = crc8(crc_region)
+    actual_crc = data[7 + payload_len]
+
+    if expected_crc != actual_crc:
+        raise ValueError(f"CRC mismatch: expected 0x{expected_crc:02x}, got 0x{actual_crc:02x}")
+
+    payload = bytes(data[7 : 7 + payload_len])
+    return ConduytPacket(version=version, type=pkt_type, seq=seq, payload=payload)
+
+
+def make_packet(pkt_type: int, seq: int, payload: bytes = b"") -> ConduytPacket:
+    """Create a ConduytPacket ready for encoding."""
+    return ConduytPacket(version=PROTOCOL_VERSION, type=pkt_type, seq=seq, payload=payload)