urst-mpy 1.0.2__tar.gz

urst_mpy-1.0.2/LICENSE.md

@@ -0,0 +1,73 @@
+# Sustainable Use License
+
+Version 1.0
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license
+to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject
+to the limitations below.
+
+## Limitations
+
+You may use or modify the software only for your own internal business purposes or for non-commercial or
+personal use. You may distribute the software or provide it to others only if you do so free of charge for
+non-commercial purposes. You may not alter, remove, or obscure any licensing, copyright, or other notices of
+the licensor in the software. Any use of the licensor’s trademarks is subject to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can license, or becomes able to
+license, to make, have made, use, sell, offer for sale, import and have imported the software, in each case
+subject to the limitations and conditions in this license. This license does not cover any patent claims that
+you cause to be infringed by modifications or additions to the software. If you or your company make any
+written claim that the software infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company makes such a claim, your patent
+license ends immediately for work on behalf of your company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these
+terms. If you modify the software, you must include in any modified copies of the software a prominent notice
+stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed, and your license will
+automatically terminate. If the licensor provides you with a notice of your violation, and you cease all
+violation of this license no later than 30 days after you receive that notice, your license will be reinstated
+retroactively. However, if you violate these terms after such reinstatement, any additional violation of these
+terms will cause your license to terminate automatically and permanently.
+
+## No Liability
+
+As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will
+not be liable to you for any damages arising out of these terms or the use or nature of the software, under
+any kind of legal claim.
+
+## Definitions
+
+The “licensor” is the entity offering these terms.
+
+The “software” is the software the licensor makes available under these terms, including any portion of it.
+
+“You” refers to the individual or entity agreeing to these terms.
+
+“Your company” is any legal entity, sole proprietorship, or other kind of organization that you work for, plus
+all organizations that have control over, are under the control of, or are under common control with that
+organization. Control means ownership of substantially all the assets of an entity, or the power to direct its
+management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+“Your license” is the license granted to you for the software under these terms.
+
+“Use” means anything you do with the software requiring your license.
+
+“Trademark” means trademarks, service marks, and similar rights.

urst_mpy-1.0.2/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: urst-mpy
+Version: 1.0.2
+Summary: MicroPython implementation of the Universal Reliable Serial Transport protocol [URST](https://github.com/simonl65/URST-Specification/blob/main/URST-Specification.md)
+Author: Simon R. Lincoln
+Author-email: Simon R. Lincoln <oss@codeability.co.uk>
+License-Expression: SUL-1.0
+License-File: LICENSE.md
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: Implementation :: MicroPython
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: Communications
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Requires-Dist: pyserial>=3.5
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/simonl65/URST-mpy
+Project-URL: Bug Tracker, https://github.com/simonl65/URST-mpy/issues
+Description-Content-Type: text/markdown
+
+# URST (Universal Reliable Serial Transport) for MicroPython
+
+[![License](https://img.shields.io/badge/license-SUL--1.0-green.svg)](LICENSE.md)
+
+**URST for MicroPython** is a professional-grade implementation of the [Universal Reliable Serial Transport (URST) protocol](URST-Specification.md). It provides reliable, error-checked, and fragmented data transmission over unreliable serial (UART/XBee) connections, specifically optimized for MicroPython devices like the Raspberry Pi Pico and ESP32.
+
+## Key Features
+
+- **Reliable Delivery**: Strict stop-and-wait ARQ (Automatic Repeat Request) with configurable timeouts and retries.
+- **MicroPython Optimized**: Native support for `machine.UART` and `utime.ticks_ms()` for precise timing on hardware.
+- **Hardware Agnostic**: Works on Desktop Python (via `pyserial`) and MicroPython seamlessly.
+- **Error Detection**: Robust CRC-16/CCITT_FALSE validation for every frame.
+- **Robust Framing**: Uses COBS (Consistent Overhead Byte Stuffing) for zero-byte-free encoding, ensuring unambiguous frame delimiting via `0x00`.
+- **Message Fragmentation**: Automatically handles messages larger than the physical MTU (up to 8KB+ reassembly).
+- **Connection Handshake**: Built-in capability negotiation and sequence synchronization.
+- **Simple API**: Clean `send()` and `read()` interface that abstracts away the complexity of serial framing and retransmission.
+
+## Installation
+
+### For MicroPython Devices
+
+**Option A — Source install via mip (simplest):**
+
+```bash
+mpremote mip install github:simonl65/URST-mpy
+```
+
+**Option B — Pre-compiled .mpy (smallest flash footprint, fastest startup):**
+
+Pre-compiling with `mpy-cross` reduces the package from ~19.7 KB to ~6.4 KB on flash
+and eliminates the parse-and-compile step at boot time.
+
+```bash
+# 1. Install mpy-cross (once)
+pip install mpy-cross
+
+# 2. Clone the repo and build
+git clone https://github.com/simonl65/urst-mpy.git
+cd urst-mpy
+make mpy          # produces dist/urst/*.mpy
+
+# 3. Deploy the compiled files to your device
+mpremote cp -r dist/urst :
+```
+
+**Option C — Copy source directly:**
+
+Copy the `urst/` directory from this repository to the root of your MicroPython device's filesystem.
+
+### For Desktop Development
+
+If you want to use it on your PC (e.g., for testing or gateway applications), install `pyserial` first:
+
+```bash
+pip install pyserial
+```
+
+## Quick Start (MicroPython)
+
+```python
+import urst
+import machine
+import time
+
+# 1. Initialize UART on your device (e.g., Raspberry Pi Pico)
+uart = machine.UART(0, baudrate=57600, tx=machine.Pin(0), rx=machine.Pin(1))
+
+# 2. Initialize URST with the UART object
+transport = urst.Urst(uart)
+
+# 3. Send a message (automatically handles framing, CRC, and ACK waiting)
+# It will fragment large data into ~194 byte chunks automatically.
+transport.send(b"Hello from Pico!")
+
+# 4. Read a complete message (handles reassembly of fragments)
+while True:
+    message = transport.read()
+    if message:
+        print(f"Received: {message.decode()}")
+    time.sleep(0.1)
+```
+
+## Quick Start (Desktop Python)
+
+```python
+from urst import Urst
+
+# Initialize URST on your serial port (requires pyserial)
+transport = Urst(port="/dev/ttyUSB0", baud=57600)
+
+transport.send(b"Hello from Desktop!")
+message = transport.read()
+```
+
+## Protocol Architecture
+
+URST follows a strictly layered architecture to ensure separation of concerns:
+
+```text
+┌───────────────────────────────────┐
+│    Handler Layer (Application)    │  User API: send(), read()
+├───────────────────────────────────┤
+│     Protocol Layer (Reliable)     │  CONNECT/ACK/NAK, Retransmission
+├───────────────────────────────────┤
+│     Transport Layer (Framing)     │  Frame Type, Sequence Numbers
+├───────────────────────────────────┤
+│    Codec Layer (Encoding/IO)      │  COBS, CRC, UART (machine/pyserial)
+└───────────────────────────────────┘
+```
+
+For full technical details, please refer to the [URST Specification](URST-Specification.md).
+
+## Development
+
+### Setup
+
+This project uses [uv](https://docs.astral.sh/uv/) for local development and testing.
+
+```bash
+git clone https://github.com/simonl65/urst-mpy.git
+cd urst-mpy
+uv sync
+```
+
+### Running Tests
+
+If using UV:
+
+```bash
+uv run pytest
+```
+
+If you aren't using UV you should set `PYTHONPATH` to ensure the tests find the package correctly:
+
+```bash
+PYTHONPATH=. pytest
+```
+
+### Linting & Formatting
+
+```bash
+uv run ruff check .
+uv run ruff format .
+```
+
+## License
+
+This project is licensed under the **Sustainable Use License (SUL-1.0)**. See the [LICENSE.md](LICENSE.md) file for details.
+
+---
+
+**Author:** Simon R. Lincoln ([oss@codeability.co.uk](mailto:oss@codeability.co.uk))

urst_mpy-1.0.2/README.md

@@ -0,0 +1,152 @@
+# URST (Universal Reliable Serial Transport) for MicroPython
+
+[![License](https://img.shields.io/badge/license-SUL--1.0-green.svg)](LICENSE.md)
+
+**URST for MicroPython** is a professional-grade implementation of the [Universal Reliable Serial Transport (URST) protocol](URST-Specification.md). It provides reliable, error-checked, and fragmented data transmission over unreliable serial (UART/XBee) connections, specifically optimized for MicroPython devices like the Raspberry Pi Pico and ESP32.
+
+## Key Features
+
+- **Reliable Delivery**: Strict stop-and-wait ARQ (Automatic Repeat Request) with configurable timeouts and retries.
+- **MicroPython Optimized**: Native support for `machine.UART` and `utime.ticks_ms()` for precise timing on hardware.
+- **Hardware Agnostic**: Works on Desktop Python (via `pyserial`) and MicroPython seamlessly.
+- **Error Detection**: Robust CRC-16/CCITT_FALSE validation for every frame.
+- **Robust Framing**: Uses COBS (Consistent Overhead Byte Stuffing) for zero-byte-free encoding, ensuring unambiguous frame delimiting via `0x00`.
+- **Message Fragmentation**: Automatically handles messages larger than the physical MTU (up to 8KB+ reassembly).
+- **Connection Handshake**: Built-in capability negotiation and sequence synchronization.
+- **Simple API**: Clean `send()` and `read()` interface that abstracts away the complexity of serial framing and retransmission.
+
+## Installation
+
+### For MicroPython Devices
+
+**Option A — Source install via mip (simplest):**
+
+```bash
+mpremote mip install github:simonl65/URST-mpy
+```
+
+**Option B — Pre-compiled .mpy (smallest flash footprint, fastest startup):**
+
+Pre-compiling with `mpy-cross` reduces the package from ~19.7 KB to ~6.4 KB on flash
+and eliminates the parse-and-compile step at boot time.
+
+```bash
+# 1. Install mpy-cross (once)
+pip install mpy-cross
+
+# 2. Clone the repo and build
+git clone https://github.com/simonl65/urst-mpy.git
+cd urst-mpy
+make mpy          # produces dist/urst/*.mpy
+
+# 3. Deploy the compiled files to your device
+mpremote cp -r dist/urst :
+```
+
+**Option C — Copy source directly:**
+
+Copy the `urst/` directory from this repository to the root of your MicroPython device's filesystem.
+
+### For Desktop Development
+
+If you want to use it on your PC (e.g., for testing or gateway applications), install `pyserial` first:
+
+```bash
+pip install pyserial
+```
+
+## Quick Start (MicroPython)
+
+```python
+import urst
+import machine
+import time
+
+# 1. Initialize UART on your device (e.g., Raspberry Pi Pico)
+uart = machine.UART(0, baudrate=57600, tx=machine.Pin(0), rx=machine.Pin(1))
+
+# 2. Initialize URST with the UART object
+transport = urst.Urst(uart)
+
+# 3. Send a message (automatically handles framing, CRC, and ACK waiting)
+# It will fragment large data into ~194 byte chunks automatically.
+transport.send(b"Hello from Pico!")
+
+# 4. Read a complete message (handles reassembly of fragments)
+while True:
+    message = transport.read()
+    if message:
+        print(f"Received: {message.decode()}")
+    time.sleep(0.1)
+```
+
+## Quick Start (Desktop Python)
+
+```python
+from urst import Urst
+
+# Initialize URST on your serial port (requires pyserial)
+transport = Urst(port="/dev/ttyUSB0", baud=57600)
+
+transport.send(b"Hello from Desktop!")
+message = transport.read()
+```
+
+## Protocol Architecture
+
+URST follows a strictly layered architecture to ensure separation of concerns:
+
+```text
+┌───────────────────────────────────┐
+│    Handler Layer (Application)    │  User API: send(), read()
+├───────────────────────────────────┤
+│     Protocol Layer (Reliable)     │  CONNECT/ACK/NAK, Retransmission
+├───────────────────────────────────┤
+│     Transport Layer (Framing)     │  Frame Type, Sequence Numbers
+├───────────────────────────────────┤
+│    Codec Layer (Encoding/IO)      │  COBS, CRC, UART (machine/pyserial)
+└───────────────────────────────────┘
+```
+
+For full technical details, please refer to the [URST Specification](URST-Specification.md).
+
+## Development
+
+### Setup
+
+This project uses [uv](https://docs.astral.sh/uv/) for local development and testing.
+
+```bash
+git clone https://github.com/simonl65/urst-mpy.git
+cd urst-mpy
+uv sync
+```
+
+### Running Tests
+
+If using UV:
+
+```bash
+uv run pytest
+```
+
+If you aren't using UV you should set `PYTHONPATH` to ensure the tests find the package correctly:
+
+```bash
+PYTHONPATH=. pytest
+```
+
+### Linting & Formatting
+
+```bash
+uv run ruff check .
+uv run ruff format .
+```
+
+## License
+
+This project is licensed under the **Sustainable Use License (SUL-1.0)**. See the [LICENSE.md](LICENSE.md) file for details.
+
+---
+
+**Author:** Simon R. Lincoln ([oss@codeability.co.uk](mailto:oss@codeability.co.uk))

urst_mpy-1.0.2/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "urst-mpy"
+version = "1.0.2"
+description = "MicroPython implementation of the Universal Reliable Serial Transport protocol [URST](https://github.com/simonl65/URST-Specification/blob/main/URST-Specification.md)"
+readme = "README.md"
+license = "SUL-1.0"
+license-files = ["LICENSE.md"]
+authors = [{ name = "Simon R. Lincoln", email = "oss@codeability.co.uk" }]
+requires-python = ">=3.12"
+dependencies = ["pyserial>=3.5"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: Implementation :: MicroPython",
+    "Topic :: System :: Networking",
+    "Topic :: Communications",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+"Repository" = "https://github.com/simonl65/URST-mpy"
+"Bug Tracker" = "https://github.com/simonl65/URST-mpy/issues"
+
+[build-system]
+requires = ["uv_build>=0.11.19"]
+build-backend = "uv_build"
+
+[tool.uv_build]
+package-dir = ""
+[tool.uv.build-backend]
+module-root = ""
+module-name = "urst"
+
+[dependency-groups]
+dev = ["pytest>=8.0", "pytest-cov>=5.0", "ruff>=0.4", "uv-build>=0.11.19"]
+
+
+# --- Ruff ---
+[tool.ruff]
+src = ["urst"]
+line-length = 80
+target-version = "py312"
+exclude = ["build", "dist", ".venv", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes errors
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear bug-hunting (e.g., bare except)
+    "SIM", # flake8-simplify
+    "S",   # security
+    "I",   # isort imports
+]
+ignore = ["E501", "SIM105"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+
+# --- Pytest ---
+[tool.pytest.ini_options]
+minversion = "6.0"
+pythonpath = ["."]
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py", "*_tests.py"]

urst_mpy-1.0.2/urst/__init__.py

@@ -0,0 +1,18 @@
+try:
+    import logging
+except ImportError:
+    # Minimal MicroPython fallback: swallow all log calls via __getattr__.
+    class _NoLog:
+        def __getattr__(self, _):
+            return lambda *a, **k: None
+
+    class _NoLogging:
+        def getLogger(self, _):
+            return _NoLog()
+
+    logging = _NoLogging()
+
+from .core_handler import Urst
+
+__version__ = "1.0.2"
+__all__ = ["Urst"]

urst_mpy-1.0.2/urst/codec_layer.py

@@ -0,0 +1,175 @@
+try:
+    import logging
+except ImportError:
+    from . import logging
+
+# MicroPython compatibility for typing
+try:
+    from typing import Any
+except ImportError:
+    # Minimal fallback for MicroPython
+    pass
+
+# MicroPython compatibility for time
+import time
+
+try:
+    _ = time.ticks_ms
+except AttributeError:
+    # Desktop Python shim
+    def ticks_ms():
+        return int(time.time() * 1000)
+
+    def ticks_diff(later, earlier):
+        return later - earlier
+
+    time.ticks_ms = ticks_ms
+    time.ticks_diff = ticks_diff
+
+logger = logging.getLogger(__name__)
+
+
+def calculate_crc16(data: bytes | bytearray) -> int:
+    """
+    Calculate the CRC16/CCITT-FALSE for the given data.
+
+    Poly: 0x1021, Init: 0xFFFF, No final XOR, MSB-first.
+    """
+    crc = 0xFFFF
+    for byte in data:
+        crc ^= byte << 8
+        for _ in range(8):
+            crc = (crc << 1 ^ 4129) & 65535 if crc & 32768 else crc << 1 & 65535
+    return crc
+
+
+def serialize_crc(crc):
+    """Serialize CRC into 2 bytes, little-endian (no struct dependency)."""
+    return bytes([crc & 0xFF, (crc >> 8) & 0xFF])
+
+
+def cobs_encode(data: bytes | bytearray) -> bytes:
+    """
+    Encode data using Consistent Overhead Byte Stuffing (COBS).
+    """
+    output = bytearray()
+    code_index = 0
+    code = 1
+    output.append(0)
+
+    for byte in data:
+        if byte == 0:
+            output[code_index] = code
+            code_index = len(output)
+            output.append(0)
+            code = 1
+            continue
+
+        output.append(byte)
+        code += 1
+
+        if code == 0xFF:
+            output[code_index] = code
+            code_index = len(output)
+            output.append(0)
+            code = 1
+
+    output[code_index] = code
+    return bytes(output)
+
+
+def cobs_decode(data: bytes | bytearray) -> bytes | None:
+    """
+    Decode COBS-encoded data.
+    """
+    if len(data) == 0:
+        return None
+    if 0x00 in data:
+        return None
+
+    output = bytearray()
+    index = 0
+    size = len(data)
+
+    while index < size:
+        code = data[index]
+        if code == 0:
+            return None
+
+        index += 1
+        end = index + code - 1
+        if end > size:
+            return None
+
+        output.extend(data[index:end])
+        index = end
+
+        if code < 0xFF and index < size:
+            output.append(0x00)
+
+    return bytes(output)
+
+
+class CodecLayer:
+    """
+    Handles encoding and decoding of URST packets at the byte level.
+    """
+
+    def __init__(self, ser: Any):
+        self.ser = ser
+        self._rx_buffer = bytearray()
+        logger.debug("Initializing Codec Layer")
+
+    def write_frame(self, frame: bytes) -> int:
+        """
+        Write a complete physical frame to the serial port.
+        """
+        sent = self.ser.write(frame)
+        if hasattr(self.ser, "flush"):
+            self.ser.flush()
+        return sent
+
+    def read_frame(self, timeout_ms: int = 1000) -> bytes | None:
+        """
+        Read from serial until a complete frame is found (between two 0x00 delimiters).
+        """
+        start_time = time.ticks_ms()
+
+        while time.ticks_diff(time.ticks_ms(), start_time) < timeout_ms:
+            # Check if we already have a frame in the buffer
+            if b"\x00" in self._rx_buffer:
+                # Find the first 0x00
+                first_zero = self._rx_buffer.find(b"\x00")
+
+                # If there's another 0x00 after it, we might have a frame
+                second_zero = self._rx_buffer.find(b"\x00", first_zero + 1)
+                if second_zero != -1:
+                    # Extract the frame
+                    frame = bytes(self._rx_buffer[first_zero : second_zero + 1])
+                    # Remove from buffer by reassigning to remaining slice
+                    self._rx_buffer = self._rx_buffer[second_zero + 1 :]
+
+                    # If it's just two 0x00s with nothing between, it's not a valid frame
+                    if len(frame) <= 2:
+                        continue
+                    return frame
+
+                # If no second zero, but we have a lot of junk before first zero, clear it
+                if first_zero > 0:
+                    self._rx_buffer = self._rx_buffer[first_zero:]
+
+            # Read more data
+            if hasattr(self.ser, "in_waiting"):
+                bytes_to_read = max(1, self.ser.in_waiting)
+            elif hasattr(self.ser, "any"):
+                bytes_to_read = max(1, self.ser.any())
+            else:
+                bytes_to_read = 1
+
+            data = self.ser.read(bytes_to_read)
+            if data:
+                self._rx_buffer.extend(data)
+            else:
+                time.sleep(0.01)  # Avoid busy waiting
+
+        return None

urst_mpy-1.0.2/urst/constants.py

@@ -0,0 +1,28 @@
+# fmt: off
+try:
+    from micropython import const
+except ImportError:
+    def const(x): return x  # noqa: E731
+
+# Protocol Constants
+MAX_RETRIES             = const(3)      # Maximum transmission attempts
+ACK_TIMEOUT_MS          = const(1000)   # ACK timeout in milliseconds
+MAX_PAYLOAD_SIZE        = const(200)    # Maximum payload bytes
+RX_BUFFER_SIZE          = const(512)    # Receive buffer size in bytes
+MAX_MSG_BYTES           = const(8192)   # Maximum message bytes advertised
+MAX_FRAGMENTS           = const(32)     # Maximum fragments per message
+CONSECUTIVE_COBS_FAILS  = const(5)      # Consecutive COBS fails threshold
+
+# Frame Types
+FRAME_DATA          = const(0x01)  # Application data frame
+FRAME_ACK           = const(0x02)  # Acknowledgment (success)
+FRAME_NAK           = const(0x03)  # Negative acknowledgment
+FRAME_FRAG          = const(0x04)  # Fragmented message chunk
+FRAME_CONNECT       = const(0x05)  # Connection establishment + caps
+FRAME_CONNECT_ACK   = const(0x06)  # Connection acknowledgment + caps
+FRAME_ERROR         = const(0x07)  # Receiver error / capability info
+FRAME_ABORT         = const(0x08)  # Abort transmission of message
+FRAME_BUSY          = const(0x09)  # Receiver busy (pause sending)
+FRAME_READY         = const(0x0A)  # Receiver ready (resume sending)
+
+FRAME_DELIMITER     = const(0x00)

urst_mpy-1.0.2/urst/core_handler.py

@@ -0,0 +1,136 @@
+try:
+    import logging
+except ImportError:
+    from . import logging
+import sys
+
+# MicroPython compatibility for typing
+try:
+    from typing import TYPE_CHECKING, Any
+except ImportError:
+    TYPE_CHECKING = False
+    # Minimal fallback
+    pass
+
+from . import constants
+from .codec_layer import CodecLayer
+from .protocol_layer import ProtocolLayer
+
+if TYPE_CHECKING:
+    pass  # type: ignore
+
+logger = logging.getLogger(__name__)
+
+
+class Urst:
+    """
+    Main interface for the Universal Reliable Serial Transport (URST) protocol.
+    """
+
+    def __init__(self, port: Any, baud: int = 57600, *, timeout: float = 1.0):
+        logger.debug("Initializing Urst")
+        self.port = port
+        self.baud = baud
+        self.timeout = timeout
+
+        if sys.implementation.name == "micropython":
+            import machine
+
+            if isinstance(port, machine.UART):
+                self.ser = port
+            else:
+                # port could be id (int)
+                self.ser = machine.UART(port, baudrate=baud)  # type: ignore
+        else:
+            # Desktop implementation
+            if hasattr(port, "write") and hasattr(port, "read"):
+                # Already a serial-like object (e.g. mock or already opened serial)
+                self.ser = port
+            else:
+                try:
+                    from serial import Serial as SerialImpl  # type: ignore
+
+                    self.ser = SerialImpl(
+                        port=port, baudrate=baud, timeout=timeout
+                    )
+                except ImportError as exc:
+                    raise RuntimeError(
+                        "pyserial is required to use Urst on desktop Python"
+                    ) from exc
+
+        self.codec = CodecLayer(self.ser)
+        self.protocol = ProtocolLayer(self.codec)
+        self._msg_id = 0
+        self._reassembly: dict[int, Any] = {}
+
+    def send(self, data: bytes) -> int:
+        """
+        Send data over the URST transport with automatic fragmentation and reliability.
+        """
+        max_frag_data = constants.MAX_PAYLOAD_SIZE - 6  # 194 bytes
+
+        if len(data) <= max_frag_data:
+            if self.protocol.send_reliable(constants.FRAME_DATA, data):
+                return len(data)
+            return 0
+
+        total_frags = (len(data) + max_frag_data - 1) // max_frag_data
+        msg_id = self._msg_id
+        self._msg_id = (self._msg_id + 1) & 0xFF
+
+        for i in range(total_frags):
+            chunk = data[i * max_frag_data : (i + 1) * max_frag_data]
+            # Fragment payload structure (§6.2)
+            header = bytes([msg_id, i, total_frags, len(chunk)])
+            if not self.protocol.send_reliable(
+                constants.FRAME_FRAG, header + chunk
+            ):
+                return i * max_frag_data
+
+        return len(data)
+
+    def read(self, bytes_to_read: int = -1) -> bytes:
+        """
+        Read a complete URST message (reassembled if necessary).
+        """
+        while True:
+            frame = self.protocol.receive_frame()
+            if not frame:
+                return b""  # Timeout or duplicate frame (already ACKed)
+
+            frame_type = frame["type"]
+            payload = frame["payload"]
+
+            if frame_type == constants.FRAME_DATA:
+                return payload
+
+            if frame_type == constants.FRAME_FRAG:
+                if len(payload) < 4:
+                    continue
+
+                msg_id = payload[0]
+                frag_num = payload[1]
+                total = payload[2]
+                data_len = payload[3]
+                data = payload[4 : 4 + data_len]
+
+                if msg_id not in self._reassembly:
+                    self._reassembly[msg_id] = {"total": total, "fragments": {}}
+
+                self._reassembly[msg_id]["fragments"][frag_num] = data
+
+                if len(self._reassembly[msg_id]["fragments"]) == total:
+                    # Reassemble message
+                    msg = b"".join(
+                        self._reassembly[msg_id]["fragments"][j]
+                        for j in range(total)
+                    )
+                    del self._reassembly[msg_id]
+                    return msg
+
+            # Handle other frame types or continue waiting
+            if (
+                frame_type == constants.FRAME_CONNECT
+                or frame_type == constants.FRAME_CONNECT_ACK
+            ):
+                continue

urst_mpy-1.0.2/urst/protocol_layer.py

@@ -0,0 +1,296 @@
+try:
+    import logging
+except ImportError:
+    from . import logging
+
+import struct
+
+# Pre-computed CONNECT capability payload (fixed protocol constants).
+# Hoisted to avoid re-running struct.pack on every handshake call.
+_CONNECT_PAYLOAD = struct.pack("<BHBBHBB", 4, 8192, 32, 1, 1000, 3, 0)
+
+# MicroPython compatibility for typing
+try:  # noqa: SIM105
+    from typing import Any
+except ImportError:
+    # Minimal fallback for MicroPython
+    pass
+
+# MicroPython compatibility for time
+import time  # noqa: E402
+
+try:
+    _ = time.ticks_ms  # type: ignore
+except AttributeError:
+    # Desktop Python shim
+    def ticks_ms():
+        return int(time.time() * 1000)
+
+    def ticks_diff(later, earlier):
+        return later - earlier
+
+    time.ticks_ms = ticks_ms  # type: ignore
+    time.ticks_diff = ticks_diff  # type: ignore
+
+from collections import deque  # noqa: E402
+
+from . import constants  # noqa: E402
+from .codec_layer import (  # noqa: E402
+    calculate_crc16,
+    cobs_decode,
+    cobs_encode,
+    serialize_crc,
+)
+
+logger = logging.getLogger(__name__)
+
+# Module-level tuples avoid re-allocating set objects on each membership test.
+# Using tuple for MicroPython portability (frozenset availability varies by port).
+_VALID_FRAME_TYPES = (
+    constants.FRAME_DATA,
+    constants.FRAME_ACK,
+    constants.FRAME_NAK,
+    constants.FRAME_FRAG,
+    constants.FRAME_CONNECT,
+    constants.FRAME_CONNECT_ACK,
+    constants.FRAME_ERROR,
+    constants.FRAME_ABORT,
+    constants.FRAME_BUSY,
+    constants.FRAME_READY,
+)
+_EMPTY_PAYLOAD_TYPES = (
+    constants.FRAME_ACK,
+    constants.FRAME_NAK,
+    constants.FRAME_BUSY,
+    constants.FRAME_READY,
+)
+_DATA_FRAG_TYPES = (constants.FRAME_DATA, constants.FRAME_FRAG)
+_PAYLOAD_FRAME_TYPES = (
+    constants.FRAME_DATA,
+    constants.FRAME_FRAG,
+    constants.FRAME_CONNECT,
+)
+
+
+def _is_empty_payload_only_type(frame_type):
+    return frame_type in _EMPTY_PAYLOAD_TYPES
+
+
+def build_frame(frame_type: int, seq: int, payload: bytes = b"") -> bytes:
+    """
+    Build a complete physical frame (delimiter + COBS + delimiter).
+
+    Order: Header (type, seq) -> Payload -> CRC -> COBS -> Delimiters.
+    """
+    if frame_type not in _VALID_FRAME_TYPES:
+        raise ValueError(f"Unknown frame type: {frame_type}")
+    if not 0 <= seq <= 0xFF:
+        raise ValueError("Sequence number must be in range 0..255")
+
+    logical = bytes([frame_type, seq]) + payload
+    crc = calculate_crc16(logical)
+    with_crc = logical + serialize_crc(crc)
+    encoded = cobs_encode(with_crc)
+    delimiter = bytes([constants.FRAME_DELIMITER])
+    return delimiter + encoded + delimiter
+
+
+def parse_frame(raw: bytes) -> dict | None:
+    """
+    Strips delimiters, COBS-decodes, validates CRC, and parses the header.
+
+    Returns:
+        {'type': int, 'seq': int, 'payload': bytes} or None on failure.
+    """
+    if len(raw) < 3:
+        return None
+
+    delimiter = constants.FRAME_DELIMITER
+    if raw[0] != delimiter or raw[-1] != delimiter:
+        return None
+
+    encoded = raw[1:-1]
+    decoded = cobs_decode(encoded)
+    if decoded is None or len(decoded) < 4:
+        return None
+
+    payload_with_header = decoded[:-2]
+    received_crc = int.from_bytes(decoded[-2:], "little")
+    expected_crc = calculate_crc16(payload_with_header)
+    if received_crc != expected_crc:
+        return None
+
+    frame_type = payload_with_header[0]
+    seq = payload_with_header[1]
+    payload = payload_with_header[2:]
+
+    if frame_type not in _VALID_FRAME_TYPES:
+        return None
+    if (
+        len(payload) > constants.MAX_PAYLOAD_SIZE
+        and len(payload) != 252
+        and frame_type == constants.FRAME_DATA
+    ):
+        return None
+    if _is_empty_payload_only_type(frame_type) and payload:
+        return None
+
+    return {"type": frame_type, "seq": seq, "payload": payload}
+
+
+class ProtocolLayer:
+    """
+    Handles the URST protocol logic, including sequence management and reliable delivery.
+    """
+
+    def __init__(self, codec: Any):
+        self.codec = codec
+        self.next_send_seq = 0
+        self.expected_recv_seq = 0
+        self.last_received_seq = -1
+        self.is_connected = False
+        self._recv_queue = deque(
+            (), constants.MAX_FRAGMENTS
+        )  # O(1) popleft on MicroPython
+        logger.debug("Initializing Protocol Layer")
+
+    def connect(self) -> bool:
+        """Perform the CONNECT handshake with retries (§5.6)."""
+        payload = _CONNECT_PAYLOAD
+        for attempt in range(constants.MAX_RETRIES + 1):
+            logger.debug(f"Handshake attempt {attempt + 1}")
+            self.codec.write_frame(
+                build_frame(constants.FRAME_CONNECT, 0, payload)
+            )
+            # Handshake must not use the queue as it needs fresh response
+            resp = self.codec.read_frame(constants.ACK_TIMEOUT_MS)
+            if resp:
+                p = parse_frame(resp)
+                if p and p["type"] == constants.FRAME_CONNECT_ACK:
+                    (
+                        self.next_send_seq,
+                        self.expected_recv_seq,
+                        self.last_received_seq,
+                    ) = 0, 0, -1
+                    self.is_connected = True
+                    logger.debug("URST Connected (received CONNECT_ACK)")
+                    return True
+                if p and p["type"] == constants.FRAME_CONNECT:
+                    self.codec.write_frame(
+                        build_frame(
+                            constants.FRAME_CONNECT_ACK, p["seq"], payload
+                        )
+                    )
+                    (
+                        self.next_send_seq,
+                        self.expected_recv_seq,
+                        self.last_received_seq,
+                    ) = 0, 0, -1
+                    self.is_connected = True
+                    logger.debug(
+                        "URST Connected (simultaneous CONNECT resolved)"
+                    )
+                    return True
+                if p:
+                    logger.warning(
+                        f"Unexpected frame during handshake: {p['type']}"
+                    )
+            else:
+                logger.warning("Handshake timeout")
+        return False
+
+    def send_reliable(self, frame_type: int, payload: bytes) -> bool:
+        """Send a frame reliably using stop-and-wait (§5.1.1)."""
+        if (
+            not self.is_connected
+            and frame_type != constants.FRAME_CONNECT
+            and not self.connect()
+        ):
+            logger.error("Failed to establish connection before sending")
+            return False
+
+        seq = self.next_send_seq
+        frame = build_frame(frame_type, seq, payload)
+
+        for attempt in range(constants.MAX_RETRIES + 1):
+            logger.debug(
+                f"Sending frame type {frame_type:#x}, seq {seq}, attempt {attempt + 1}"
+            )
+            self.codec.write_frame(frame)
+
+            start_wait = time.ticks_ms()  # type: ignore
+            while (
+                time.ticks_diff(time.ticks_ms(), start_wait)
+                < constants.ACK_TIMEOUT_MS
+            ):  # type: ignore
+                # Read fresh frames only, bypassing the queue
+                p = self.receive_frame(timeout_ms=100, use_queue=False)
+                if p:
+                    if p["type"] == constants.FRAME_ACK and p["seq"] == seq:
+                        self.next_send_seq = (self.next_send_seq + 1) & 0xFF
+                        logger.debug(f"Received ACK for seq {seq}")
+                        return True
+                    if p["type"] == constants.FRAME_NAK and p["seq"] == seq:
+                        logger.warning(
+                            f"Received NAK for seq {seq}, retrying..."
+                        )
+                        break
+
+                    # If it's a payload frame, it's already been ACKed by receive_frame.
+                    # We must queue it so Urst.read() can find it later.
+                    if p["type"] in _DATA_FRAG_TYPES:
+                        logger.debug(
+                            f"Queuing payload frame type {p['type']} received during wait"
+                        )
+                        self._recv_queue.append(p)
+            else:
+                logger.warning(f"Timeout waiting for ACK for seq {seq}")
+
+        return False
+
+    def receive_frame(
+        self, timeout_ms: int | None = None, use_queue: bool = True
+    ) -> dict | None:
+        """Receive a frame and handle ACKs/seq checks (§5.1.2, §5.6.2)."""
+        if use_queue and self._recv_queue:
+            return self._recv_queue.popleft()
+
+        if timeout_ms is None:
+            timeout_ms = constants.ACK_TIMEOUT_MS
+
+        raw = self.codec.read_frame(timeout_ms)
+        if not raw:
+            return None
+        p = parse_frame(raw)
+        if not p:
+            return None
+        ft, seq = p["type"], p["seq"]
+
+        if ft == constants.FRAME_ACK or ft == constants.FRAME_NAK:
+            return p
+
+        if ft in _PAYLOAD_FRAME_TYPES:
+            if ft == constants.FRAME_CONNECT or seq == self.expected_recv_seq:
+                if ft == constants.FRAME_CONNECT:
+                    payload = _CONNECT_PAYLOAD
+                    self.codec.write_frame(
+                        build_frame(constants.FRAME_CONNECT_ACK, seq, payload)
+                    )
+                    (
+                        self.next_send_seq,
+                        self.expected_recv_seq,
+                        self.last_received_seq,
+                    ) = 0, 0, -1
+                    self.is_connected = True
+                    return p
+                self.codec.write_frame(build_frame(constants.FRAME_ACK, seq))
+                self.last_received_seq, self.expected_recv_seq = (
+                    seq,
+                    (self.expected_recv_seq + 1) & 0xFF,
+                )
+                return p
+            if seq == self.last_received_seq:
+                self.codec.write_frame(build_frame(constants.FRAME_ACK, seq))
+                return None
+            self.codec.write_frame(build_frame(constants.FRAME_NAK, seq))
+        return p