pycyphal2 2.0.0.dev2__tar.gz → 2.0.0.dev3__tar.gz

{pycyphal2-2.0.0.dev2/src/pycyphal2.egg-info → pycyphal2-2.0.0.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycyphal2
-Version: 2.0.0.dev2
+Version: 2.0.0.dev3
 Summary: Pure-Python implementation of Cyphal -- a simple and robust real-time publish/subscribe stack that runs anywhere.
 Author-email: Pavel Kirienko and OpenCyphal team <pavel@opencyphal.org>
 License: MIT

{pycyphal2-2.0.0.dev2 → pycyphal2-2.0.0.dev3}/src/pycyphal2/__init__.py

@@ -155,7 +155,7 @@ from ._transport import SubjectWriter as SubjectWriter
 from ._transport import Transport as Transport
 from ._transport import TransportArrival as TransportArrival
 
-__version__ = "2.0.0.dev2"
+__version__ = "2.0.0.dev3"
 
 # pdoc needs __all__ to display re-exported members.
 __all__ = [

pycyphal2-2.0.0.dev3/src/pycyphal2/can/_media_slcan.py

@@ -0,0 +1,199 @@
+"""
+SLCAN text protocol for CAN media (frame codec + adapter handshake).
+"""
+
+from __future__ import annotations
+
+import logging
+
+from ._interface import Frame
+from ._wire import CAN_EXT_ID_MASK, DLC_TO_LENGTH, MTU_CAN_CLASSIC
+
+_logger = logging.getLogger(__name__)
+
+_CAN_STD_ID_MASK = (1 << 11) - 1
+_CR = 0x0D  # ACK / carriage return
+_LF = 0x0A
+_BEL = 0x07  # NACK / bell
+_MAX_LINE_LENGTH = 256
+_STRIP_CHARS = b" \t\r\n\x07\x03"
+
+_CMD_TERMINATOR = bytes([_CR])
+_CMD_CLOSE = b"C"
+_CMD_OPEN = b"O"
+_CMD_SET_BITRATE_PREFIX = b"S"
+_BITRATE_TO_SPEED_CODE = {
+    1_000_000: 8,
+    800_000: 7,
+    500_000: 6,
+    250_000: 5,
+    125_000: 4,
+    100_000: 3,
+    50_000: 2,
+    20_000: 1,
+    10_000: 0,
+}
+
+
+def encode_frame(identifier: int, data: bytes | bytearray | memoryview) -> bytes:
+    """
+    Encode an extended-ID Classic CAN data frame into one SLCAN ``T`` command line.
+    """
+    if not isinstance(identifier, int) or not (0 <= identifier <= CAN_EXT_ID_MASK):
+        raise ValueError(f"Invalid CAN identifier: {identifier!r}")
+    payload = bytes(data)
+    if len(payload) > MTU_CAN_CLASSIC:
+        raise ValueError(f"Invalid CAN data length: {len(payload)}")
+    return f"T{identifier:08X}{len(payload):1d}{payload.hex().upper()}\r".encode()
+
+
+def encode_deinit() -> bytes:
+    """The close command line. Sent fire-and-forget before purging input to reset the adapter."""
+    return _CMD_CLOSE + _CMD_TERMINATOR
+
+
+def encode_init_sequence(bitrate: int | None) -> list[bytes]:
+    """
+    Command lines to bring the adapter up after deinit+purge: optionally set the bitrate, then open.
+    If ``bitrate`` is None, the bitrate command is skipped, the old configured value (or adapter default) is kept.
+    A bitrate not in the standard speed-code table is sent as-is (some adapters accept raw bitrates, e.g. Zubax).
+    Each returned command line expects an ACK.
+    """
+    out: list[bytes] = []
+    if bitrate is not None:
+        code = _BITRATE_TO_SPEED_CODE.get(bitrate, bitrate)
+        out.append(_CMD_SET_BITRATE_PREFIX + str(code).encode("ascii") + _CMD_TERMINATOR)
+    out.append(_CMD_OPEN + _CMD_TERMINATOR)
+    return out
+
+
+def classify_init_response(chunk: bytes) -> bool | None:
+    """Scan a chunk for the first ACK (True) or NACK (False); return None if neither appears."""
+    for byte in chunk:
+        if byte == _CR:
+            return True
+        if byte == _BEL:
+            return False
+    return None
+
+
+class SLCANParser:
+    """
+    Incremental SLCAN parser.
+    Only data frames are returned. Unsupported or malformed input is silently dropped with debug logging.
+    Adapter-specific suffixes after the payload, such as timestamps or flags, are ignored.
+    """
+
+    def __init__(self) -> None:
+        self._buffer = bytearray()
+        self._discarding = False
+
+    def feed(self, chunk: bytes | bytearray | memoryview) -> list[Frame]:
+        out: list[Frame] = []
+        for byte in bytes(chunk):
+            if byte == _BEL:
+                if self._buffer or self._discarding:
+                    _logger.debug("SLCAN drop adapter error len=%d", len(self._buffer))
+                self._buffer.clear()
+                self._discarding = False
+                continue
+            if byte in (_CR, _LF):
+                if self._discarding:
+                    self._buffer.clear()
+                    self._discarding = False
+                    continue
+                if self._buffer:
+                    frame = _parse_line(bytes(self._buffer))
+                    if frame is not None:
+                        out.append(frame)
+                    self._buffer.clear()
+                continue
+            if self._discarding:
+                continue
+            if len(self._buffer) >= _MAX_LINE_LENGTH:
+                _logger.debug("SLCAN drop overlong line len>%d", _MAX_LINE_LENGTH)
+                self._buffer.clear()
+                self._discarding = True
+                continue
+            self._buffer.append(byte)
+        return out
+
+
+def _parse_line(line: bytes) -> Frame | None:
+    # Based on the original PyUAVCAN/PyDroneCAN implementation.
+    # Strips surrounding whitespace and control characters like BEL/ETX.
+    line = line.strip(_STRIP_CHARS)
+    if not line:
+        return None
+    command = line[:1]
+    if command in (b"T", b"x"):
+        return _parse_data_frame(line, id_length=8, max_payload_length=MTU_CAN_CLASSIC)
+    if command == b"t":
+        return _parse_data_frame(line, id_length=3, max_payload_length=MTU_CAN_CLASSIC)
+    if command == b"D":
+        return _parse_data_frame(line, id_length=8, max_payload_length=64)
+    if command in (b"r", b"R"):
+        _logger.debug("SLCAN drop unsupported frame type cmd=%r", command)
+        return None
+    _logger.debug("SLCAN drop unknown line=%r", line)
+    return None
+
+
+def _parse_data_frame(line: bytes, *, id_length: int, max_payload_length: int) -> Frame | None:
+    header_length = 2 + id_length
+    if len(line) < header_length:
+        _logger.debug("SLCAN drop short data line=%r", line)
+        return None
+    identifier = _parse_hex_int(line[1 : 1 + id_length])
+    dlc = _parse_dlc(line[1 + id_length])
+    if identifier is None or dlc is None:
+        _logger.debug("SLCAN drop malformed data header line=%r", line)
+        return None
+    payload_length = DLC_TO_LENGTH[dlc]  # _parse_dlc guarantees dlc in [0, 15]
+    if payload_length > max_payload_length:
+        _logger.debug("SLCAN drop data dlc out of range dlc=%d max=%d line=%r", dlc, max_payload_length, line)
+        return None
+    expected = header_length + payload_length * 2
+    if len(line) < expected:
+        _logger.debug("SLCAN drop data dlc mismatch len=%d expected=%d", len(line), expected)
+        return None
+    if id_length == 3 and identifier > _CAN_STD_ID_MASK:
+        _logger.debug("SLCAN drop invalid standard id=%x", identifier)
+        return None
+    data = _parse_hex_bytes(line[header_length:expected])
+    if data is None:
+        _logger.debug("SLCAN drop malformed data id=%08x", identifier)
+        return None
+    try:
+        return Frame(id=identifier, data=data)
+    except ValueError as ex:
+        _logger.debug("SLCAN drop invalid frame: %s", ex)
+        return None
+
+
+def _parse_hex_int(value: bytes) -> int | None:
+    if not value:
+        return None
+    try:
+        return int(value, 16)
+    except ValueError:
+        return None
+
+
+def _parse_hex_bytes(value: bytes) -> bytes | None:
+    if len(value) % 2 != 0:
+        return None
+    try:
+        return bytes.fromhex(value.decode("ascii"))
+    except (UnicodeDecodeError, ValueError):
+        return None
+
+
+def _parse_dlc(value: int) -> int | None:
+    if ord("0") <= value <= ord("9"):
+        return value - ord("0")
+    if ord("A") <= value <= ord("F"):
+        return 10 + value - ord("A")
+    if ord("a") <= value <= ord("f"):
+        return 10 + value - ord("a")
+    return None

pycyphal2-2.0.0.dev3/src/pycyphal2/can/webserial.py

@@ -0,0 +1,287 @@
+"""
+Browser-oriented SLCAN backend for WebSerial/Pyodide.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from abc import ABC, abstractmethod
+from collections.abc import Iterable
+
+from .._api import ClosedError, Instant
+from ._interface import Filter, Interface, TimestampedFrame
+from ._media_slcan import (
+    SLCANParser,
+    classify_init_response,
+    encode_deinit,
+    encode_frame,
+    encode_init_sequence,
+)
+
+_logger = logging.getLogger(__name__)
+
+_ACK_TIMEOUT = 3.0
+_DEINIT_SETTLE = 0.1
+_PURGE_DRAIN_TIMEOUT = 0.05
+
+
+class AsyncSerialPort(ABC):
+    """Minimal async byte stream expected from a WebSerial adapter."""
+
+    @abstractmethod
+    async def read(self) -> bytes:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def write(self, data: bytes) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def close(self) -> None:
+        raise NotImplementedError
+
+
+class WebSerialSLCANInterface(Interface):
+    """
+    SLCAN CAN interface over an application-provided async serial byte stream.
+
+    The port is expected to be already opened by browser/Pyodide glue code.
+    On startup the adapter is reset: closed, left to settle, its pending input purged (so stale frames
+    from a previous configuration are dropped), then configured for the selected bitrate and reopened.
+    If no bitrate is given, the bitrate is left unconfigured (old/default).
+    """
+
+    def __init__(self, port: AsyncSerialPort, *, name: str = "webserial", bitrate: int | None = None) -> None:
+        self._port = port
+        self._name = str(name)
+        self._bitrate = None if bitrate is None else int(bitrate)
+        self._closed = False
+        self._failure: BaseException | None = None
+        self._parser = SLCANParser()
+        self._tx_seq = 0
+        self._tx_queue: asyncio.PriorityQueue[tuple[int, int, int, bytes]] = asyncio.PriorityQueue()
+        self._rx_queue: asyncio.Queue[TimestampedFrame | BaseException] = asyncio.Queue()
+        self._init_task: asyncio.Task[None] | None = None
+        self._tx_task: asyncio.Task[None] | None = None
+        self._rx_task: asyncio.Task[None] | None = None
+        self._close_task: asyncio.Task[None] | None = None
+        self._start_init()  # Requires a running loop; this is an async interface, always built in one.
+        _logger.info("WebSerial SLCAN init iface=%s bitrate=%s", self._name, self._bitrate)
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def fd(self) -> bool:
+        return False
+
+    def filter(self, filters: Iterable[Filter]) -> None:
+        del filters
+        self._raise_if_closed()
+        # No-op: WebSerial adapters do not provide hardware acceptance filtering.
+
+    def enqueue(self, id: int, data: Iterable[memoryview], deadline: Instant) -> None:
+        self._raise_if_closed()
+        chunks = tuple(bytes(item) for item in data)
+        for chunk in chunks:
+            encode_frame(id, chunk)  # Validate before mutating the queue.
+        if self._tx_task is None:
+            self._tx_task = asyncio.get_running_loop().create_task(self._tx_loop())
+        for chunk in chunks:
+            self._tx_seq += 1
+            self._tx_queue.put_nowait((id, self._tx_seq, deadline.ns, chunk))
+
+    def purge(self) -> None:
+        if self._closed:
+            return
+        dropped = 0
+        try:
+            while True:
+                self._tx_queue.get_nowait()
+                dropped += 1
+        except asyncio.QueueEmpty:
+            pass
+        if dropped > 0:
+            _logger.debug("WebSerial SLCAN purge iface=%s dropped=%d", self._name, dropped)
+
+    async def receive(self) -> TimestampedFrame:
+        self._raise_if_closed()
+        if self._rx_task is None:
+            self._rx_task = asyncio.get_running_loop().create_task(self._rx_loop())
+        item = await self._rx_queue.get()
+        if isinstance(item, BaseException):
+            if isinstance(item, ClosedError):
+                raise item
+            raise ClosedError(f"WebSerial SLCAN interface {self._name} receive failed") from item
+        return item
+
+    def close(self) -> None:
+        self._close(ClosedError(f"WebSerial SLCAN interface {self._name} closed"))
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self._name!r}, fd={self.fd})"
+
+    async def _tx_loop(self) -> None:
+        try:
+            await self._ensure_initialized()
+        except Exception as ex:
+            self._fail(ex)
+            return
+        while not self._closed:
+            identifier, seq, deadline_ns, payload = await self._tx_queue.get()
+            if self._closed:
+                return
+            timeout = (deadline_ns - Instant.now().ns) * 1e-9
+            if timeout <= 0.0:
+                _logger.debug("WebSerial SLCAN tx drop expired iface=%s id=%08x", self._name, identifier)
+                continue
+            try:
+                await asyncio.wait_for(self._port.write(encode_frame(identifier, payload)), timeout=timeout)
+            except asyncio.TimeoutError:
+                self._tx_queue.put_nowait((identifier, seq, deadline_ns, payload))
+                await asyncio.sleep(0.001)
+            except Exception as ex:
+                self._fail(ex)
+                return
+
+    async def _rx_loop(self) -> None:
+        try:
+            await self._ensure_initialized()
+        except Exception as ex:
+            self._fail(ex)
+            return
+        while not self._closed:
+            try:
+                chunk = await self._port.read()
+            except Exception as ex:
+                self._fail(ex)
+                return
+            if not chunk:
+                self._fail(EOFError(f"WebSerial SLCAN interface {self._name} ended"))
+                return
+            for frame in self._parser.feed(chunk):
+                self._rx_queue.put_nowait(TimestampedFrame(id=frame.id, data=frame.data, timestamp=Instant.now()))
+
+    def _start_init(self) -> None:
+        if self._init_task is None:
+            self._init_task = asyncio.get_running_loop().create_task(self._init_adapter())
+            self._init_task.add_done_callback(self._on_init_done)
+
+    def _on_init_done(self, task: asyncio.Task[None]) -> None:
+        if task.cancelled():
+            return
+        try:
+            task.result()
+        except Exception as ex:
+            if not self._closed:
+                self._fail(ex)
+
+    async def _ensure_initialized(self) -> None:
+        self._raise_if_closed()
+        self._start_init()
+        assert self._init_task is not None
+        await asyncio.shield(self._init_task)
+        self._raise_if_closed()
+
+    async def _init_adapter(self) -> None:
+        _logger.info("WebSerial SLCAN setup iface=%s bitrate=%s", self._name, self._bitrate)
+        # Reset an adapter that may be in an unknown state: close, settle, discard whatever it was
+        # forwarding under the old config, then configure and open.
+        await self._port.write(encode_deinit())
+        await asyncio.sleep(_DEINIT_SETTLE)
+        await self._purge_input()
+        for command in encode_init_sequence(self._bitrate):
+            _logger.debug("WebSerial SLCAN setup cmd iface=%s cmd=%r", self._name, command)
+            await self._port.write(command)
+            await self._wait_for_init_ack()
+        _logger.info("WebSerial SLCAN setup done iface=%s", self._name)
+
+    async def _purge_input(self) -> None:
+        dropped = 0
+        while True:
+            try:
+                chunk = await asyncio.wait_for(self._port.read(), timeout=_PURGE_DRAIN_TIMEOUT)
+            except asyncio.TimeoutError:
+                break
+            if not chunk:
+                raise EOFError("SLCAN channel ended while purging input")
+            dropped += len(chunk)
+        if dropped > 0:
+            _logger.debug("WebSerial SLCAN purge stale input iface=%s dropped=%d", self._name, dropped)
+
+    async def _wait_for_init_ack(self) -> None:
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + _ACK_TIMEOUT
+        while True:
+            timeout = deadline - loop.time()
+            if timeout <= 0.0:
+                raise TimeoutError("SLCAN ACK timeout")
+            chunk = await asyncio.wait_for(self._port.read(), timeout=timeout)
+            if not chunk:
+                raise EOFError("SLCAN channel ended while waiting for ACK")
+            response = classify_init_response(chunk)
+            if response is True:
+                return
+            if response is False:
+                raise OSError("SLCAN NACK in response")
+            _logger.debug("WebSerial SLCAN setup ignored bytes iface=%s len=%d", self._name, len(chunk))
+
+    def _fail(self, ex: BaseException) -> None:
+        if self._failure is None:
+            self._failure = ex
+            _logger.error("WebSerial SLCAN interface %s failed: %s", self._name, ex)
+        self._close(ex)
+
+    def _close(self, unblock: BaseException) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        self._cancel_worker_tasks()
+        self._drain_rx_queue()
+        self._rx_queue.put_nowait(unblock)
+        self._close_port()
+
+    def _cancel_worker_tasks(self) -> None:
+        current: asyncio.Task[object] | None
+        try:
+            current = asyncio.current_task()
+        except RuntimeError:
+            current = None
+        for task in (self._init_task, self._tx_task, self._rx_task):
+            if task is not None and task is not current:
+                task.cancel()
+        self._init_task = None
+        self._tx_task = None
+        self._rx_task = None
+
+    def _close_port(self) -> None:
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            try:
+                asyncio.run(self._close_port_async())
+            except Exception as ex:
+                _logger.debug("WebSerial SLCAN port close error on %s: %s", self._name, ex)
+            return
+        self._close_task = loop.create_task(self._close_port_async())
+
+    async def _close_port_async(self) -> None:
+        try:
+            await self._port.close()
+        except Exception as ex:
+            _logger.debug("WebSerial SLCAN port close error on %s: %s", self._name, ex)
+
+    def _raise_if_closed(self) -> None:
+        if self._closed:
+            if self._failure is not None:
+                raise ClosedError(f"WebSerial SLCAN interface {self._name} failed") from self._failure
+            raise ClosedError(f"WebSerial SLCAN interface {self._name} closed")
+
+    def _drain_rx_queue(self) -> None:
+        try:
+            while True:
+                self._rx_queue.get_nowait()
+        except asyncio.QueueEmpty:
+            pass

{pycyphal2-2.0.0.dev2 → pycyphal2-2.0.0.dev3/src/pycyphal2.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycyphal2
-Version: 2.0.0.dev2
+Version: 2.0.0.dev3
 Summary: Pure-Python implementation of Cyphal -- a simple and robust real-time publish/subscribe stack that runs anywhere.
 Author-email: Pavel Kirienko and OpenCyphal team <pavel@opencyphal.org>
 License: MIT

{pycyphal2-2.0.0.dev2 → pycyphal2-2.0.0.dev3}/src/pycyphal2.egg-info/SOURCES.txt

@@ -18,11 +18,13 @@ src/pycyphal2.egg-info/requires.txt
 src/pycyphal2.egg-info/top_level.txt
 src/pycyphal2/can/__init__.py
 src/pycyphal2/can/_interface.py
+src/pycyphal2/can/_media_slcan.py
 src/pycyphal2/can/_reassembly.py
 src/pycyphal2/can/_transport.py
 src/pycyphal2/can/_wire.py
 src/pycyphal2/can/pythoncan.py
 src/pycyphal2/can/socketcan.py
+src/pycyphal2/can/webserial.py
 tests/test_gossip.py
 tests/test_hash.py
 tests/test_header.py