python-can-flexible-serial 0.1.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

flexible_serial/bus.py

@@ -12,9 +12,15 @@ https://python-can.readthedocs.io/en/stable/plugin-interface.html for the
 python-can plugin interface this implements.
 """
 
+from __future__ import annotations
+
+import copy
 import io
 import logging
+import os
 import struct
+import threading
+from collections import deque
 from collections.abc import Sequence
 from typing import TypedDict, Callable, Any, Optional, cast
 import binascii
@@ -113,7 +119,8 @@ class FlexibleSerial(BusABC):
 
     ERROR_TEXT = {
         SerialError.DESYNC: "Start-of-Frame desync",
-        SerialError.BAD_DLC: f"DataLength Invalid (>{MAX_DATA_LEN_FD} bytes)",
+        # decode_serial_can_error adds the limit that applied: 8 bytes, or 64 for an FD frame
+        SerialError.BAD_DLC: "DataLength Invalid",
         SerialError.BAD_EOF: "End-of-Frame mismatch",
         SerialError.BAD_CRC: "CRC Error",
     }
@@ -130,9 +137,15 @@ class FlexibleSerial(BusABC):
         :ivar crc_type: One of :attr:`CRC_TYPES` (``"none"``, ``"crc16-ccitt"``).
         :ivar flags_byte: Carry extended/error/remote/FD metadata in a dedicated header byte.
         :ivar no_timestamp: Omit the 4-byte (uint32 milliseconds) timestamp header field.
-        :ivar rx_bytes_callback: ``callback(raw_bytes, is_rx)`` invoked for every
+        :ivar data_processed_callback: ``callback(raw_bytes, is_rx)`` invoked for every
             frame written or chunk of buffer consumed while reading; useful for
             logging/debugging raw wire traffic.
+        :ivar receive_own_messages: Hand every successfully sent message back through
+            :meth:`~_recv_internal`, so transmitted frames reach listeners as ordinary
+            receives and callers do not have to synthesize their own echo. Off by default.
+            The echo is the message as given, so set ``is_rx=False`` when sending if the
+            direction matters downstream. ``timestamp`` is passed through when set and
+            stamped at write time when not, matching how rx timestamps are handled.
         """
         big_endian: bool
         sof: bytes
@@ -141,7 +154,8 @@ class FlexibleSerial(BusABC):
         crc_type: str
         flags_byte: bool
         no_timestamp: bool
-        rx_bytes_callback: Callable | None
+        data_processed_callback: Callable | None
+        receive_own_messages: bool
 
 
     DEFAULT_FRAME_KWARGS: FrameKwargs = {
@@ -152,18 +166,36 @@ class FlexibleSerial(BusABC):
         "crc_type": "none",
         "flags_byte": False,
         "no_timestamp": False,
-        "rx_bytes_callback": None
+        "data_processed_callback": None,
+        "receive_own_messages": False
     }
 
+    RX_QUEUE_MAX_FRAMES = 10_000
+    '''Cap on messages waiting to be handed out by _recv_internal.
+
+    High enough that it only ever catches a caller who opted into receive_own_messages and then
+    never drains - which is their bug, not ours, but should not be an unbounded leak. Received
+    frames cannot realistically reach it: what one read can queue is bounded by the driver's own
+    buffer, a few hundred frames at most, and _recv_internal hands them straight back out.
+    '''
+
     DataProcessedCallback = Callable[[bytes, bool], None]
     ''' Provides arguments [data bytes, is_rx] '''
 
+    # Advantech PCIE-16xx serial cards (adv17v35x driver, Exar XR17V35x UART). The driver sets the RX FIFO
+    # trigger to 32 bytes whenever the port is first opened, so a frame shorter than that waits for the
+    # UART's ~4 character idle timeout. ADV_WRITE_REG (_IO('x', 2) in adv17v35x.c) writes one UART register.
+    ADVANTECH_PCI_DRIVER = "ADVserial"
+    ADVANTECH_WRITE_REG = 0x7802
+    ADVANTECH_RXTRG_REG = 0x0B
+
     def __init__(
         self,
         channel: str,
         baudrate: int = 115200,
         timeout: float = 0.1,
         rtscts: bool = False,
+        low_latency: bool = True,
         **kwargs: Any,
     ) -> None:
         """
@@ -183,13 +215,19 @@ class FlexibleSerial(BusABC):
         :param rtscts:
             Turn hardware handshake (RTS/CTS) on and off (default false)
 
+        :param low_latency:
+            Ask the port to hand over received bytes as they arrive rather than in batches
+            (default true). Linux only, and best effort: a port that doesn't support it is
+            logged and opened anyway. See :meth:`_set_low_latency` for what it does per hardware.
+            Pass false to leave the port's own settings alone.
+
         :param kwargs:
             Frame-layout options (see :class:`FrameKwargs` and
             :attr:`DEFAULT_FRAME_KWARGS` for defaults), plus any remaining
             kwargs passed to the base class constructor, see
-            :meth:`can.BusABC.__init__`. All frame-layout kwargs accept
-            hex strings (e.g. ``"0xAA"``) in addition to their native type,
-            since python-can CLI tools pass ``--bus-kwargs`` as strings.
+            :meth:`can.BusABC.__init__`. ``sof`` and ``eof`` also accept
+            hex strings (e.g. ``"0xAA"``), since python-can CLI tools pass
+            ``--bus-kwargs`` as strings.
 
         :raises ~can.exceptions.CanInitializationError:
             If the given parameters are invalid.
@@ -210,6 +248,28 @@ class FlexibleSerial(BusABC):
 
         self._rx_buffer = bytearray()
 
+        self._receive_own_messages = self._pop_bool_kwarg(kwargs, "receive_own_messages")
+
+        # send() warns about the first out-of-range timestamp it clamps, not every one
+        self._timestamp_clamp_warned = False
+
+        # Everything waiting to be handed out by _recv_internal(), from both sources in the order
+        # it was queued: frames parsed off the wire, and - with receive_own_messages - echoes that
+        # send() queued as it was given them, so nothing is re-encoded going out or re-parsed
+        # coming back in.
+        #
+        # One queue rather than two because _recv_internal() returns one message per call, as
+        # python-can requires, while parsing every complete frame the buffer holds per trip to
+        # the hardware: a burst is timestamped in one pass instead of one frame per round trip
+        # through the caller's listeners, however slow those are. Both sources then just pop from
+        # here. deque.append and popleft are atomic, which matters because send() may be queueing
+        # an echo from another thread while _recv_internal() pops.
+        self._rx_queue: deque[Message] = deque(maxlen=self.RX_QUEUE_MAX_FRAMES)
+
+        # Serializes the write path. Backends over a socket or a vendor C library get this from underneath.
+        # Re-entrant so a data_processed_callback that sends cannot deadlock.
+        self._tx_lock = threading.RLock()
+
         self._sof = self._coerce_bytes_kwarg(
             "sof",
             kwargs.pop("sof", self.DEFAULT_FRAME_KWARGS["sof"]),
@@ -234,7 +294,7 @@ class FlexibleSerial(BusABC):
         self._configure_frame_offsets(no_timestamp=no_timestamp)
 
         # Register user callback for when serial bytes are received/transmitted
-        self._pop_rx_bytes_callback(kwargs)
+        self._pop_data_processed_callback(kwargs)
 
         try:
             self._ser = serial.serial_for_url(
@@ -244,9 +304,12 @@ class FlexibleSerial(BusABC):
             raise CanInitializationError(
                 "Could not create the serial device"
             ) from error
-         
+
+        if low_latency:
+            self._set_low_latency()
+
         logger.info(f"Opened Serial Port {channel} with frame settings:\r\n"
-              f"\tEndianness: {"big" if big_endian else "little"}\r\n"
+              f"\tEndianness: {'big' if big_endian else 'little'}\r\n"
               f"\tSOF: {self._sof}\r\n"
               f"\tEOF: {self._eof}\r\n"
               f"\tTimestamp: {not no_timestamp}\r\n"
@@ -261,8 +324,10 @@ class FlexibleSerial(BusABC):
         """
         Close the serial interface.
         """
+        # Tasks first (stop() only sets flags), then the lock, so an in-flight write finishes before the port closes under it.
         super().shutdown()
-        self._ser.close()
+        with self._tx_lock:
+            self._ser.close()
 
     def send(self, msg: Message, timeout: Optional[float] = None) -> None:
         """
@@ -271,13 +336,17 @@ class FlexibleSerial(BusABC):
         :param msg:
             Message to send.
 
-            .. note:: If the timestamp is a float value it will be converted
-                      to an integer.
+            .. note:: When the layout has a timestamp field, ``msg.timestamp``
+                      (seconds) is sent as integer milliseconds, clamped to
+                      0..0xFFFFFFFF rather than raising like python-can's
+                      ``serial`` interface. The first clamp logs a warning.
 
         :param timeout:
-            This parameter will be ignored. The timeout value of the channel is
-            used instead.
+            Serial write timeout for this write, in seconds (None blocks until
+            written).
 
+        :raises ~can.exceptions.CanTimeoutError:
+            If the write doesn't finish within ``timeout``.
         """
 
         # Reject extended frames if uint16 ID is selected
@@ -294,8 +363,17 @@ class FlexibleSerial(BusABC):
             if msg.is_remote_frame:
                 arbitration_id |= CAN_RTR_FLAG
 
-        # Generate timestamp even when frame format options omits it
-        timestamp_int = max(0, min(int(msg.timestamp * 1000), 0xFFFFFFFF))
+        # Generate timestamp even when frame format options omits it. msg.timestamp is seconds and
+        # the wire field uint32 milliseconds, as in python-can's serial interface. Out of range is
+        # clamped rather than raised, so one odd clock doesn't stop a live trace - but said once, so
+        # it isn't silent either.
+        timestamp_ms = int(msg.timestamp * 1000)
+        timestamp_int = max(0, min(timestamp_ms, 0xFFFFFFFF))
+        if self._has_timestamp and not self._timestamp_clamp_warned and timestamp_int != timestamp_ms:
+            self._timestamp_clamp_warned = True
+            logger.warning(f"{self.channel}: timestamp {msg.timestamp} s doesn't fit the frame's uint32 "
+                           f"millisecond field, sent as {timestamp_int} ms. Later out-of-range timestamps "
+                           f"are clamped the same way without another warning.")
 
         # Construct frame
         frame = bytearray(self._sof)
@@ -304,16 +382,30 @@ class FlexibleSerial(BusABC):
         frame += self._crc_calculate(memoryview(frame)[self._crc_calc_start_offset:])
         frame += self._eof
 
-        try:
-            if timeout != self._ser.write_timeout:
-                self._ser.write_timeout = timeout
-            self._ser.write(frame)
-            if self._on_data_processed_callback:
-                self._on_data_processed_callback(frame, False)
-        except serial.PortNotOpenError as error:
-            raise CanOperationError("writing to closed port") from error
-        except serial.SerialTimeoutException as error:
-            raise CanTimeoutError() from error
+        # Building the frame above touches nothing shared. Everything below does: write_timeout
+        # is port-wide, and the echo and callback both report frame order.
+        with self._tx_lock:
+            try:
+                if timeout != self._ser.write_timeout:
+                    self._ser.write_timeout = timeout
+                self._ser.write(frame)
+
+                if self._receive_own_messages:
+                    echo = copy.copy(msg)
+                    echo.data = bytearray(msg.data)
+                    # Same rule _recv_internal uses when the wire carries no timestamp: pass
+                    # through what we were given, otherwise stamp it. can.Message defaults
+                    # timestamp to 0.0, so an unset one lands here 
+                    if not msg.timestamp:
+                        echo.timestamp = time.time()
+                    self._rx_queue.append(echo)
+
+                if self._on_data_processed_callback:
+                    self._on_data_processed_callback(frame, False)
+            except serial.PortNotOpenError as error:
+                raise CanOperationError("writing to closed port") from error
+            except serial.SerialTimeoutException as error:
+                raise CanTimeoutError() from error
         
     @staticmethod
     def decode_serial_can_error(msg: Message) -> str:
@@ -335,7 +427,9 @@ class FlexibleSerial(BusABC):
             else:
                 return text
         elif msg.data[0] == FlexibleSerial.SerialError.BAD_DLC:
-            text = FlexibleSerial.ERROR_TEXT[FlexibleSerial.SerialError.BAD_DLC]
+            # The error frame keeps the bad frame's FD flag, which decided the limit it broke
+            limit = MAX_DATA_LEN_FD if msg.is_fd else MAX_DATA_LEN_CLASSIC
+            text = FlexibleSerial.ERROR_TEXT[FlexibleSerial.SerialError.BAD_DLC] + f" (>{limit} bytes)"
             if len(msg.data) >= 2:
                 return text + f" -> Rx data length = {msg.data[1]}"
             else:
@@ -359,12 +453,26 @@ class FlexibleSerial(BusABC):
             Received message and :obj:`False` (because no filtering as taken place).
         """
 
+        # Queued on an earlier call - hand the next one over without touching the port at all.
+        if self._rx_queue:
+            return (self._rx_queue.popleft(), False)
+
         timer = TimeoutTimer(timeout)
         try:
             while (True):
+                # Drain every complete frame the buffer holds rather than just the first. Each is
+                # timestamped as it is found, inside this loop, so their timestamps reflect when
+                # the bytes were read and not what happened between calls.
                 msg = self._try_decode_message_from_buffer()
                 if msg is not None:
-                    return (msg, False)
+                    self._rx_queue.append(msg)
+                    continue
+
+                # Buffer holds no more complete frames. Anything queued - a frame from the pass
+                # above, or an echo send() left here - goes out now rather than waiting behind
+                # the blocking read below.
+                if self._rx_queue:
+                    return (self._rx_queue.popleft(), False)
 
                 # The parser needs more bytes; allow one serial read before
                 # checking the deadline again so recv(0) still polls hardware.
@@ -372,11 +480,22 @@ class FlexibleSerial(BusABC):
                 self._ser.timeout = timer.remaining_time()
                 # get bytes in hw serial rx buffer, up to an eof delimiter match
                 new_rx_bytes = self._ser.read_until(self._eof)
+                # ...then take the rest of what the driver already had. read_until stops at the
+                # first EOF, so on its own it leaves a backlog behind and each frame in it would
+                # not be parsed - or timestamped - until its own recv() came round, after the
+                # previous frame had been through the caller's listeners. read_all does not
+                # block, so this costs nothing when there is no backlog.
+                new_rx_bytes += self._ser.read_all()
                 self._rx_buffer.extend(new_rx_bytes)
 
+                # Queue the first frame and go back round rather than returning it here, so the
+                # drain at the top of the loop parses and timestamps the rest of what the read
+                # above brought in, in the same pass. Returning straight from here would leave
+                # the backlog unparsed until the next call, which is the thing being fixed.
                 msg = self._try_decode_message_from_buffer()
                 if msg is not None:
-                    return (msg, False)
+                    self._rx_queue.append(msg)
+                    continue
 
                 if timer.expired():
                     return (None, False)
@@ -394,14 +513,77 @@ class FlexibleSerial(BusABC):
         except Exception as exception:
             raise CanOperationError("Cannot fetch fileno") from exception
 
+    def _set_low_latency(self) -> None:
+        """Make the open port deliver received bytes as they arrive, for the hardware that needs telling.
+
+        - Any Linux tty: pyserial's ``set_low_latency_mode`` (the ``ASYNC_LOW_LATENCY`` flag, no root
+          needed). FTDI's driver turns it into a 1 ms latency timer instead of the default 16 ms, and keeps
+          it until the adapter is replugged, so later opens by other programs get it too.
+        - Advantech PCIE-16xx: RX FIFO trigger set to 1 byte (see :attr:`ADVANTECH_PCI_DRIVER`). The driver
+          puts it back to 32 the next time the port is opened with nothing else holding it open.
+
+        Neither failing stops the bus opening; it only logs a warning.
+        """
+        set_low_latency_mode = getattr(self._ser, "set_low_latency_mode", None)
+        if set_low_latency_mode is not None:
+            try:
+                set_low_latency_mode(True)
+                logger.info(f"{self.channel}: low latency mode on")
+            except (NotImplementedError, ValueError, OSError) as error:
+                logger.warning(f"{self.channel}: could not set low latency mode: {error}")
+
+        if self._is_advantech_port(self.channel):
+            import fcntl   # POSIX only; _is_advantech_port is only ever True on Linux
+            try:
+                fcntl.ioctl(self._ser.fileno(), self.ADVANTECH_WRITE_REG, struct.pack("BB", self.ADVANTECH_RXTRG_REG, 1))
+                logger.info(f"{self.channel}: Advantech RX FIFO trigger set to 1 byte")
+            except OSError as error:
+                logger.warning(f"{self.channel}: could not set the Advantech RX FIFO trigger: {error}")
+
+    @classmethod
+    def _is_advantech_port(cls, channel: str) -> bool:
+        """Whether a Linux tty belongs to an Advantech PCIE-16xx card, from the driver bound to its PCI device.
+
+        Follows symlinks such as ``/dev/hil-1622b-ch4`` or ``/dev/serial/by-id/...`` to the tty, then walks
+        up its sysfs device path: the tty itself sits on serial-core's own devices, below the PCI device the
+        Advantech driver binds to. False for anything else, including non-Linux ports and URLs.
+        """
+        tty = os.path.basename(os.path.realpath(channel))
+        device = os.path.realpath(f"/sys/class/tty/{tty}/device")
+        while device.startswith("/sys/devices/"):
+            driver = os.path.join(device, "driver")
+            if os.path.islink(driver) and os.path.basename(os.path.realpath(driver)) == cls.ADVANTECH_PCI_DRIVER:
+                return True
+            device = os.path.dirname(device)
+        return False
+
     @staticmethod
-    def _detect_available_configs() -> Sequence[AutoDetectedConfig]:
+    def _is_unpopulated_uart(channel: str) -> bool:
+        """Whether a Linux tty is a serial-core placeholder with no UART behind it, eg. the 8250
+        driver's spare ttyS4-31.
+
+        pyserial hides those by their sysfs subsystem being "platform", which stopped working once
+        the kernel moved serial-core ttys onto its own serial-base bus (6.5): every ttyS0-31 is
+        listed. serial-core's ``type`` attribute is the UART type it probed, 0 (PORT_UNKNOWN) when
+        none answered, the same thing setserial reports as "unknown". False for anything without
+        that attribute, so non-serial-core ttys, non-Linux ports and URLs are always kept.
+        """
+        tty = os.path.basename(os.path.realpath(channel))
+        try:
+            with open(f"/sys/class/tty/{tty}/type") as f:
+                return f.read().strip() == "0"
+        except OSError:
+            return False
+
+    @classmethod
+    def _detect_available_configs(cls) -> Sequence[AutoDetectedConfig]:
         configs: list[AutoDetectedConfig] = []
         if serial is None:
             return configs
 
         for port in serial.tools.list_ports.comports():
-            configs.append({"interface": "flexible_serial", "channel": port.device})
+            if not cls._is_unpopulated_uart(port.device):
+                configs.append({"interface": "flexible_serial", "channel": port.device})
         return configs
 
     @classmethod
@@ -411,13 +593,13 @@ class FlexibleSerial(BusABC):
             raise TypeError(f"'{name}' must be bool, not {type(value).__name__}")
         return value
     
-    def _pop_rx_bytes_callback(self, kwargs: dict[str, Any]):
-        value = kwargs.pop("rx_bytes_callback", None)
+    def _pop_data_processed_callback(self, kwargs: dict[str, Any]):
+        value = kwargs.pop("data_processed_callback", None)
         if value is None:
             self._on_data_processed_callback = None
             return
         if not callable(value):
-            raise TypeError("'rx_bytes_callback' must be callable")
+            raise TypeError("'data_processed_callback' must be callable")
         self._on_data_processed_callback = value
 
     def _configure_header(
@@ -703,7 +885,7 @@ class FlexibleSerial(BusABC):
         # Validate DLC before trusting it as the payload length.
         if dlc > (MAX_DATA_LEN_FD if is_can_fd else MAX_DATA_LEN_CLASSIC):
             if self._on_data_processed_callback:
-                self._on_data_processed_callback(self._rx_buffer[0], True)
+                self._on_data_processed_callback(self._rx_buffer[0:1], True)
             del self._rx_buffer[0]
             return self._build_rx_error_message(
                 self.SerialError.BAD_DLC,
@@ -728,7 +910,7 @@ class FlexibleSerial(BusABC):
         # Validate EOF delimiter.
         if self._rx_buffer[eof_offset:frame_end] != self._eof:
             if self._on_data_processed_callback:
-                self._on_data_processed_callback(self._rx_buffer[0], True)
+                self._on_data_processed_callback(self._rx_buffer[0:1], True)
             del self._rx_buffer[0]
             return self._build_rx_error_message(
                 self.SerialError.BAD_EOF,

python_can_flexible_serial-0.2.2.dist-info/METADATA

@@ -0,0 +1,304 @@
+Metadata-Version: 2.4
+Name: python-can-flexible-serial
+Version: 0.2.2
+Summary: python-can interface plugin for configurable, framed binary serial protocols
+Author: Matt Bulow
+Maintainer: Matt Bulow
+License-Expression: MIT
+Project-URL: python-can plugin interface, https://python-can.readthedocs.io/en/stable/plugin-interface.html
+Keywords: python-can,CAN,CANbus,CAN FD,serial,UART,plugin
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: Software Development :: Embedded Systems :: Controller Area Network (CAN)
+Classifier: Topic :: System :: Hardware :: Hardware Drivers
+Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
+Classifier: Topic :: Terminals :: Serial
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-can<5,>=4.4
+Requires-Dist: pyserial>=3.5
+Dynamic: license-file
+
+# python-can-flexible-serial
+
+A [python-can](https://python-can.readthedocs.io/) interface plugin that speaks a
+configurable, framed binary protocol over a serial port. It follows the
+[python-can plugin interface](https://python-can.readthedocs.io/en/stable/plugin-interface.html),
+so once installed it is usable anywhere python-can accepts an `interface=`
+name — `can.Bus`, `python -m can.viewer`, `python -m can.logger`,
+`python -m can.bridge`, etc. — alongside the other community interface
+plugins listed on that page (`python-can-canine`, `python-can-cvector`,
+`python-can-remote`, `python-can-sontheim`, `python-can-cando`,
+`python-can-candle`, ...).
+
+Unlike the fixed-layout `slcan` and `serial` interfaces bundled with
+python-can, the frame layout here is configurable via constructor kwargs
+(SOF/EOF delimiters, ID width, optional CRC, optional flags byte, optional
+timestamp) so it can be adapted to match firmware on the other end of the
+serial link without changing code.
+
+It's just as useful with no CAN anywhere. Frame a plain serial link's messages this way and python-can's tooling works on them without writing a parser: `can.logger` traces (`.blf`, `.asc`, `.mf4`, ...), `can.viewer`, `can.bridge`, message filters, periodic sends, and DBC decoding of the payloads with [cantools](https://cantools.readthedocs.io/).
+
+## Frame layout
+
+| Section | Field | Size | Optional / Configurable |
+|---|---|---|---|
+| — | SOF | 1+ bytes | Configurable delimiter (default `0xAA`) |
+| Header | timestamp | 0 or 4 bytes | Optional — omitted when `no_timestamp=True` |
+| Header | dlc | 1 byte | Always present |
+| Header | flags | 0 or 1 byte | Optional — only present when `flags_byte=True` |
+| Header | id | 2 or 4 bytes | Sizeable — 2 bytes when `uint16_id=True`, else 4 |
+| Payload | data | 0-64 bytes | Sizeable — length equals `dlc` |
+| — | crc | 0 or N bytes | Optional — size/presence set by `crc_type` |
+| — | EOF | 1+ bytes | Configurable delimiter (default `0xBB`) |
+
+Details on each section:
+
+- **SOF / EOF** — arbitrary-length byte sequences used purely as framing delimiters. They are never covered by the CRC.
+- **timestamp** *(optional, fixed 4 bytes when present)* — `uint32` milliseconds. It works the same way as in python-can's built-in `serial` interface: on send, `msg.timestamp` (seconds) is multiplied by 1000 and truncated; on receive, the field is divided by 1000 into `msg.timestamp`. It's whatever clock the sender uses (device uptime, say), not wall-clock time, and it wraps after about 49.7 days. If you use it, set `msg.timestamp` yourself: a message stamped with wall-clock time, like `time.time()`, doesn't fit. Out-of-range values are clamped to `0`–`0xFFFFFFFF` rather than raising as `serial` does, so one frame with an odd clock doesn't stop a live trace; the first one on each bus logs a warning on the `can.flexible_serial` logger. Omit the field entirely with `no_timestamp=True` to save 4 bytes per frame; python-can then stamps each frame when it's read.
+- **dlc** *(always present, fixed 1 byte)* — the payload length in bytes (not a CAN DLC code), which also sizes the `data` section on receive.
+- **flags** *(optional, fixed 1 byte when present)* — see "Flags byte" below for the bit layout. When absent, the same metadata is instead packed into spare bits of the `id` field (see below).
+- **id** *(always present, sizeable: 2 or 4 bytes)* — arbitration ID. `uint16_id=True` shrinks it to 2 bytes but rejects extended (29-bit) IDs; the default 4-byte field supports both standard and extended IDs.
+- **data** *(sizeable, 0-64 bytes)* — the CAN payload, `dlc` bytes long. How many bytes are allowed depends on how the layout says a frame is CAN FD:
+
+  | Layout | CAN FD frames | Max payload |
+  |---|---|---|
+  | `flags_byte=True` | the FD bit (and BRS bit) in the flags byte | 64 for FD frames, 8 otherwise |
+  | `uint16_id=True`, no flags byte | any frame longer than 8 bytes is taken as FD | 64 |
+  | 4-byte ID, no flags byte | not representable | 8 |
+
+  A longer payload than the layout allows is received as a `BAD_DLC` error frame (see "Error frames").
+- **crc** *(optional, 0 or 2 bytes)* — set by `crc_type`: `"none"`, or `"crc16-ccitt"` (CRC-16/CCITT-FALSE: polynomial `0x1021`, initial value `0xFFFF`, no reflection, no final XOR — Python's `binascii.crc_hqx(data, 0xFFFF)`). It covers the **flags byte (if present), the ID and the data** — not the SOF, timestamp, length byte or EOF. That's by design: the length byte decides where the receiver reads the CRC and EOF from, so a corrupted length still fails the CRC or EOF check.
+
+Byte order for the timestamp, ID and CRC fields is little-endian by default, or big-endian when `big_endian=True`.
+
+### Flags byte
+
+When `flags_byte=True`, extended/error/remote/FD metadata is carried in a dedicated byte instead of being packed into spare bits of the arbitration ID:
+
+| Bit  | Mask | Meaning | From / to `can.Message` |
+|------|------|---------|---|
+| 0    | `0x01` | Error frame | `is_error_frame` |
+| 1    | `0x02` | Remote frame (RTR) | `is_remote_frame` |
+| 2    | `0x04` | Extended (29-bit) ID | `is_extended_id` |
+| 3    | `0x08` | CAN FD frame | `is_fd` |
+| 4    | `0x10` | CAN FD bit-rate switch | `bitrate_switch` |
+| 5    | `0x20` | Frame originated as RX (vs. TX) | `is_rx` |
+
+Every bit is passed through as-is in both directions; the interface never rewrites them. That includes bit 5: `can.Message` defaults to `is_rx=True`, so a sent frame carries the RX bit unless you send it with `is_rx=False`. Forwarding a recorded trace keeps each frame's direction.
+
+When `flags_byte=False`, extended/error/remote status is instead OR'd into spare high bits of the 32-bit arbitration ID field (standard `python-can` convention: `CAN_EFF_FLAG`, `CAN_ERR_FLAG`, `CAN_RTR_FLAG`). This only applies when `uint16_id=False`: a 16-bit ID field has no spare bits, so with `uint16_id=True` and no flags byte, error and remote frames can't be represented and every received frame is a data frame with `is_rx=True`.
+
+### Error frames
+
+Protocol-level errors are surfaced as `Message` objects with `is_error_frame=True` rather than raising exceptions, matching how other python-can interfaces report bus errors. Byte 0 of their data is the error code (`FlexibleSerial.SerialError`), and byte 1, when present, a detail:
+
+| Code | Name | Byte 1 | What the receiver does next |
+|---|---|---|---|
+| 1 | `DESYNC` | number of bytes dropped | Skips the bytes before the next SOF |
+| 2 | `BAD_DLC` | the length received | Drops one byte and resynchronizes; the rest of the bad frame then usually shows up as a `DESYNC` |
+| 3 | `BAD_EOF` | — | Drops one byte and resynchronizes; the rest of the bad frame then usually shows up as a `DESYNC` |
+| 4 | `BAD_CRC` | — | Drops the whole frame |
+
+Use `FlexibleSerial.decode_serial_can_error(msg)` to get a human-readable description, e.g. `"Start-of-Frame desync -> 3 bytes dropped"`. `BAD_DLC`, `BAD_EOF` and `BAD_CRC` error frames carry the ID, timestamp and flags read from the bad frame's header; `DESYNC` ones have ID 0 and the time the junk was found.
+
+## Installation
+
+From PyPI:
+
+```
+pip install python-can-flexible-serial
+```
+
+or, in a project managed with [uv](https://docs.astral.sh/uv/), `uv add python-can-flexible-serial`.
+
+### Using a local clone from another project
+
+If that project is managed with [uv](https://docs.astral.sh/uv/), add this
+repo as an editable path dependency, pointing at wherever you've cloned it:
+
+```powershell
+uv add --editable plugins/python-can-flexible-serial
+```
+
+Run this from *that* project's directory, not from within this repo — `uv
+add` adds a dependency to the project in your current directory, so running
+it from inside `python-can-flexible-serial` itself is a self-dependency and
+uv will refuse it.
+
+With plain pip, from that project's environment:
+
+```powershell
+python -m pip install -e /path/to/python-can-flexible-serial
+```
+
+### Working on this repo itself
+
+Use `uv sync` (a uv-managed project installs itself editable by default):
+
+```powershell
+uv sync
+```
+
+Or with plain pip, from this repo's root:
+
+```powershell
+python -m pip install -e .
+```
+
+Either way, this registers the plugin with python-can via the `can.interface`
+entry point (`flexible_serial = "flexible_serial.bus:FlexibleSerial"`), so it
+becomes available as `interface="flexible_serial"` anywhere python-can
+resolves interfaces, without any further imports.
+
+## Usage
+
+```python
+import can
+
+bus = can.interface.Bus(
+    interface="flexible_serial",
+    channel="COM3",
+    baudrate=115200,
+)
+
+bus.send(can.Message(arbitration_id=0x123, data=[0x01, 0x02, 0x03], is_extended_id=False))
+msg = bus.recv(timeout=1.0)   # None if nothing arrived in time
+
+bus.shutdown()
+```
+
+Only opening the bus is specific to this plugin: the constructor arguments below pick the port and the frame layout. Everything after that is the standard [python-can bus API](https://python-can.readthedocs.io/en/stable/bus.html), the same as with any other interface: `send()` and `recv()`, iterating over the bus, `can.Notifier` with listeners and loggers, `send_periodic()`, `set_filters()`, and `with can.Bus(...) as bus:` or `shutdown()`. The few behaviors specific to this interface are under "Sending and receiving" below.
+
+### Constructor arguments
+
+| Argument | Type | Default | Description |
+|---|---|---|---|
+| `channel` | `str` | *(required)* | Serial device, e.g. `"COM3"` or `"/dev/ttyUSB0"`, or any [pyserial URL](https://pyserial.readthedocs.io/en/latest/url_handlers.html): `loop://` for testing, `socket://host:port`, `rfc2217://host:port`, ... |
+| `baudrate` | `int` | `115200` | Serial baud rate |
+| `timeout` | `float` | `0.1` | Serial read timeout, in seconds |
+| `rtscts` | `bool` | `False` | Enable RTS/CTS hardware handshake |
+| `low_latency` | `bool` | `True` | Linux: have the port hand over received bytes as they arrive (see "Low latency" below) |
+| `sof` | `bytes` \| hex `str` | `0xAA` | Start-of-frame delimiter |
+| `eof` | `bytes` \| hex `str` | `0xBB` | End-of-frame delimiter |
+| `big_endian` | `bool` | `False` | Byte order for the timestamp, ID and CRC fields |
+| `uint16_id` | `bool` | `False` | Use a 2-byte arbitration ID instead of 4-byte; rejects extended IDs |
+| `flags_byte` | `bool` | `False` | Carry frame metadata in a dedicated byte (see "Flags byte" above) |
+| `no_timestamp` | `bool` | `False` | Omit the 4-byte timestamp header field |
+| `crc_type` | `str` | `"none"` | One of `"none"`, `"crc16-ccitt"` |
+| `receive_own_messages` | `bool` | `False` | python-can's standard option: every message you send is also returned by `recv()` (see "Sending and receiving" below) |
+| `data_processed_callback` | `Callable[[bytes, bool], None] \| None` | `None` | Called with `(raw_bytes, is_rx)` whenever a frame is sent or a chunk of buffer is consumed on receive, including bytes dropped while resynchronizing; useful for logging/debugging the raw wire traffic. It runs on the thread calling `send()` or `recv()`, so keep it quick. |
+
+The `bool` arguments must be real booleans in Python code. Any other keyword arguments are passed on to python-can's `BusABC`, such as `can_filters`.
+
+`sof` and `eof` accept either raw `bytes` (when constructing a `Bus` from Python) or a hex string (when passed as a CLI `--bus-kwargs` value, since python-can CLI tools pass kwargs as strings). A hex string can be written as `0x4040`, `4040`, `40 40` or `\x40\x40`, and may use `_`, `-`, `:` or `,` between bytes:
+
+```powershell
+python -m can.logger -i flexible_serial -c COM3 --bus-kwargs sof=0xAA eof=0x0D0A
+```
+
+Prefer the `0x` prefix for CLI hex values, especially if the delimiter contains only digits, since python-can auto-converts bare numeric kwargs.
+
+### Low latency
+
+By default a serial port may hold received bytes back and deliver them in
+batches, which delays received frames and their timestamps (with
+`no_timestamp=True`, a frame is stamped when it is read). The bus turns that
+off when it opens the port, for the hardware that needs telling. It is Linux
+only and best effort: anything that can't be set may be logged as a warning and the
+port opens anyway. Pass `low_latency=False` to leave the port's own settings
+alone.
+
+| Hardware | Port's own setting | With `low_latency=True` (the default) |
+|---|---|---|
+| FTDI USB serial (`ftdi_sio`) | 16 ms latency timer | 1 ms, via pyserial's `set_low_latency_mode`. The adapter keeps it until it's replugged, so later opens by other programs get it too. |
+| Advantech PCIE-16xx cards (`adv17v35x` driver) | RX FIFO interrupt after 32 bytes, or after ~4 idle characters | Interrupt on every byte. The driver puts it back to 32 the next time the port is opened with nothing else holding it open. |
+| Other Linux ttys | — | pyserial's `set_low_latency_mode`; what that does depends on the driver |
+
+No root is needed for either. On Windows, set the FTDI latency timer in the
+port's Device Manager properties instead.
+
+### Sending and receiving
+
+- **Threads:** `send()` is safe to call from several threads at once, including python-can's periodic send tasks (`bus.send_periodic()`); frames are never interleaved on the wire.
+- **Send timeout:** `send(msg, timeout=...)` sets the serial write timeout for that write; a write that doesn't finish in time raises `can.CanTimeoutError`.
+- **Bursts:** each read takes every complete frame the port has buffered and stamps them in the same pass, so with `no_timestamp=True` a burst gets timestamps from when its bytes were read, not from when your code got round to each `recv()`.
+- **Own messages:** with `receive_own_messages=True`, each message you send is returned by `recv()` exactly as you passed it, after it's written: nothing is re-encoded or rewritten, including `is_rx`, so set `is_rx=False` when sending if the direction matters downstream. A message with no timestamp (`0.0`, the `can.Message` default) is stamped with the time it was written. Echoes are queued in order with received frames.
+- **`fileno()`** returns the port's file descriptor where the platform has one, so the bus works with `select`-based tools and python-can's asyncio `Notifier`.
+
+### CLI examples
+
+```powershell
+python -m can.viewer -i flexible_serial -c COM6 --bus-kwargs sof=0x4040 eof=0x0A uint16_id=True crc_type=crc16-ccitt flags_byte=False no_timestamp=True
+```
+
+Bridging to another interface:
+
+```powershell
+python -m can.bridge --bus1-interface flexible_serial --bus1-channel COM7 --bus1-bus-kwargs sof=0x4040 eof=0x0A uint16_id=True crc_type=crc16-ccitt flags_byte=False no_timestamp=True --bus2-interface kvaser --bus2-channel 0 --bus2-bitrate 125000
+```
+
+### Autodetection
+
+Like the built-in `serial` interface, available serial ports are surfaced
+through python-can's autodetection API:
+
+```python
+import can
+print(can.detect_available_configs(interfaces=["flexible_serial"]))
+```
+
+It lists every port pyserial finds, except, on Linux, serial-core placeholder ttys with no UART behind them (such as the spare `ttyS4`–`ttyS31` the 8250 driver always creates). Newer kernels (6.5+) stopped pyserial from hiding those itself.
+
+## Development
+
+Test dependencies (`pytest`) are in the `dev` dependency group, which `uv sync` installs by default:
+
+```powershell
+uv sync
+```
+or, with pip 25.1 or newer:
+```powershell
+python -m pip install -e . --group dev
+```
+
+Run the test suite with:
+
+```
+uv run pytest
+```
+or
+```powershell
+python -m pytest
+```
+
+To run it against a specific Python version, the way CI does: `uv run --python 3.9 pytest`.
+
+`tests/test_bus.py` runs round-trip tests against two backends — a fully in-memory mocked serial port and pyserial's `loop://` — mirroring the structure of python-can's own `serial` interface test suite. A few tests exercise `fcntl` and are skipped on Windows; they run in CI.
+
+CI and the release process, including publishing to PyPI, are described in `RELEASING.md` in the repository.
+
+## Future improvement ideas
+
+- **`can_filters` support** — already works today for free: `BusABC.recv()`
+  always calls `_matches_filters()` in software unless `_recv_internal`
+  reports the message as pre-filtered, and this interface never does. What's
+  still missing is a hardware-style optimization: implement the optional
+  `_apply_filters()` hook so frames can be dropped *before* the CRC check
+  runs, instead of always paying the full decode+CRC cost and filtering
+  afterward.
+- Support the CAN FD protocol for the `BusABC` parent (`can_protocol`
+  currently reports `CAN_20` unconditionally).
+- Add an option for arbitrary (non-CAN) data length up to 255 bytes, since
+  `dlc` is only 1 byte — useful for passing arbitrary serial payloads through
+  python-can tooling without being constrained to CAN/CAN FD payload sizes.

python_can_flexible_serial-0.2.2.dist-info/RECORD

@@ -0,0 +1,8 @@
+flexible_serial/__init__.py,sha256=0XQ0axiWmTV75TIN2M0pM71QNvG_VbDm2wirLRALeRk,129
+flexible_serial/bus.py,sha256=0ALHPKomevVitfn22fxroOJH9F4PIO1ckwPERKK1Lus,40282
+python_can_flexible_serial-0.2.2.dist-info/licenses/LICENSE,sha256=gldqXfJjP9VXoXHVOw464BYthZBw6u3ZMNtPjDTZKe8,1076
+python_can_flexible_serial-0.2.2.dist-info/METADATA,sha256=rwedELYmzTT92_xQZDv6aybHo7V8CuVQdAcHfYVbEnU,18155
+python_can_flexible_serial-0.2.2.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+python_can_flexible_serial-0.2.2.dist-info/entry_points.txt,sha256=FvRVfuDmEVWkQEeHq4CEczaXichOYQpbSLzelMhE8V0,69
+python_can_flexible_serial-0.2.2.dist-info/top_level.txt,sha256=CBMqcoYnde__UVfBfwco7r1FFNAkA4MPV5evBl4Bsws,16
+python_can_flexible_serial-0.2.2.dist-info/RECORD,,

{python_can_flexible_serial-0.1.0.dist-info → python_can_flexible_serial-0.2.2.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (83.0.0)
+Generator: setuptools (84.2.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

{python_can_flexible_serial-0.1.0.dist-info → python_can_flexible_serial-0.2.2.dist-info}/licenses/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Matt Bulow
+Copyright (c) 2026 CisLunar Industries
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

python_can_flexible_serial-0.1.0.dist-info/METADATA

@@ -1,261 +0,0 @@
-Metadata-Version: 2.4
-Name: python-can-flexible-serial
-Version: 0.1.0
-Summary: python-can interface plugin for a configurable binary serial CAN protocol
-Project-URL: python-can plugin interface, https://python-can.readthedocs.io/en/stable/plugin-interface.html
-Keywords: can,python-can,serial,plugin
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: python-can<5,>=4.4
-Requires-Dist: pyserial>=3.5
-Provides-Extra: dev
-Requires-Dist: pytest>=8; extra == "dev"
-Dynamic: license-file
-
-# python-can-flexible-serial
-
-A [python-can](https://python-can.readthedocs.io/) interface plugin that speaks a
-configurable, framed binary protocol over a serial port. It follows the
-[python-can plugin interface](https://python-can.readthedocs.io/en/stable/plugin-interface.html),
-so once installed it is usable anywhere python-can accepts an `interface=`
-name — `can.Bus`, `python -m can.viewer`, `python -m can.logger`,
-`python -m can.bridge`, etc. — alongside the other community interface
-plugins listed on that page (`python-can-canine`, `python-can-cvector`,
-`python-can-remote`, `python-can-sontheim`, `python-can-cando`,
-`python-can-candle`, ...).
-
-Unlike the fixed-layout `slcan` and `serial` interfaces bundled with
-python-can, the frame layout here is configurable via constructor kwargs
-(SOF/EOF delimiters, ID width, optional CRC, optional flags byte, optional
-timestamp) so it can be adapted to match firmware on the other end of the
-serial link without changing code.
-
-## Frame layout
-
-| Section | Field | Size | Optional / Configurable |
-|---|---|---|---|
-| — | SOF | 1+ bytes | Configurable delimiter (default `0xAA`) |
-| Header | timestamp | 0 or 4 bytes | Optional — omitted when `no_timestamp=True` |
-| Header | dlc | 1 byte | Always present |
-| Header | flags | 0 or 1 byte | Optional — only present when `flags_byte=True` |
-| Header | id | 2 or 4 bytes | Sizeable — 2 bytes when `uint16_id=True`, else 4 |
-| Payload | data | 0-64 bytes | Sizeable — length equals `dlc` |
-| — | crc | 0 or N bytes | Optional — size/presence set by `crc_type` |
-| — | EOF | 1+ bytes | Configurable delimiter (default `0xBB`) |
-
-Details on each section:
-
-- **SOF / EOF** — arbitrary-length byte sequences used purely as framing
-  delimiters. They are never covered by the CRC.
-- **timestamp** *(optional, fixed 4 bytes when present)* — `uint32`
-  milliseconds. Omit entirely with `no_timestamp=True` to save 4 bytes per
-  frame if the far end doesn't supply/need one; python-can still assigns a
-  local receive timestamp in that case.
-- **dlc** *(always present, fixed 1 byte)* — raw payload length in bytes;
-  also used to size the `data` section on receive.
-- **flags** *(optional, fixed 1 byte when present)* — see "Flags byte" below
-  for the bit layout. When absent, the same metadata is instead packed into
-  spare bits of the `id` field (see below).
-- **id** *(always present, sizeable: 2 or 4 bytes)* — arbitration ID.
-  `uint16_id=True` shrinks it to 2 bytes but rejects extended (29-bit) IDs;
-  the default 4-byte field supports both standard and extended IDs.
-- **data** *(sizeable, 0-64 bytes)* — the CAN payload; length is whatever
-  `dlc` says, up to 64 bytes for CAN FD-sized frames or 8 bytes otherwise.
-- **crc** *(optional, sizeable: 0 or N bytes)* — set by `crc_type`
-  (`"none"` or `"crc16-ccitt"`); covers the header and payload, but not
-  SOF/EOF.
-
-Byte order for the header and CRC fields is little-endian by default, or
-big-endian when `big_endian=True`.
-
-### Flags byte
-
-When `flags_byte=True`, extended/error/remote/FD metadata is carried in a
-dedicated byte instead of being packed into spare bits of the arbitration ID:
-
-| Bit  | Mask | Meaning |
-|------|------|---------|
-| 0    | `0x01` | Error frame |
-| 1    | `0x02` | Remote frame (RTR) |
-| 2    | `0x04` | Extended (29-bit) ID |
-| 3    | `0x08` | CAN FD frame |
-| 4    | `0x10` | CAN FD bit-rate switch |
-| 5    | `0x20` | Frame originated as RX (vs. TX) |
-
-When `flags_byte=False`, extended/error/remote status is instead OR'd into
-spare high bits of the 32-bit arbitration ID field (standard `python-can`
-convention: `CAN_EFF_FLAG`, `CAN_ERR_FLAG`, `CAN_RTR_FLAG`). This only applies
-when `uint16_id=False`, since a 16-bit ID field has no spare bits for flags.
-
-### Error frames
-
-Protocol-level errors (frame desync, bad DLC, EOF mismatch, bad CRC) are
-surfaced as `Message` objects with `is_error_frame=True` rather than raising
-exceptions, matching how other python-can interfaces report bus errors. Use
-`FlexibleSerial.decode_serial_can_error(msg)` to get a human-readable
-description of an error message's contents.
-
-## Installation
-
-How you install this depends on whether you're *using* it as a dependency
-of some other project, or working on this repo itself.
-
-### Using this plugin from another project
-
-If that project is managed with [uv](https://docs.astral.sh/uv/), add this
-repo as an editable path dependency, pointing at wherever you've cloned it:
-
-```powershell
-uv add --editable plugins/python-can-flexible-serial
-```
-
-Run this from *that* project's directory, not from within this repo — `uv
-add` adds a dependency to the project in your current directory, so running
-it from inside `python-can-flexible-serial` itself is a self-dependency and
-uv will refuse it.
-
-With plain pip, from that project's environment:
-
-```powershell
-python -m pip install -e /path/to/python-can-flexible-serial
-```
-
-### Working on this repo itself
-
-Use `uv sync` (a uv-managed project installs itself editable by default):
-
-```powershell
-uv sync
-```
-
-Or with plain pip, from this repo's root:
-
-```powershell
-python -m pip install -e .
-```
-
-Either way, this registers the plugin with python-can via the `can.interface`
-entry point (`flexible_serial = "flexible_serial.bus:FlexibleSerial"`), so it
-becomes available as `interface="flexible_serial"` anywhere python-can
-resolves interfaces, without any further imports.
-
-## Usage
-
-```python
-import can
-
-bus = can.interface.Bus(
-    interface="flexible_serial",
-    channel="COM3",
-    baudrate=115200,
-)
-```
-
-### Constructor arguments
-
-| Argument | Type | Default | Description |
-|---|---|---|---|
-| `channel` | `str` | *(required)* | Serial device, e.g. `"COM3"` or `"/dev/ttyUSB0"` |
-| `baudrate` | `int` | `115200` | Serial baud rate |
-| `timeout` | `float` | `0.1` | Serial read timeout, in seconds |
-| `rtscts` | `bool` | `False` | Enable RTS/CTS hardware handshake |
-| `sof` | `bytes` \| hex `str` | `0xAA` | Start-of-frame delimiter |
-| `eof` | `bytes` \| hex `str` | `0xBB` | End-of-frame delimiter |
-| `big_endian` | `bool` | `False` | Byte order for header/CRC fields |
-| `uint16_id` | `bool` | `False` | Use a 2-byte arbitration ID instead of 4-byte; rejects extended IDs |
-| `flags_byte` | `bool` | `False` | Carry frame metadata in a dedicated byte (see "Flags byte" above) |
-| `no_timestamp` | `bool` | `False` | Omit the 4-byte timestamp header field |
-| `crc_type` | `str` | `"none"` | One of `"none"`, `"crc16-ccitt"` |
-| `rx_bytes_callback` | `Callable[[bytes, bool], None] \| None` | `None` | Called with `(raw_bytes, is_rx)` whenever a frame is sent or a chunk of buffer is consumed on receive; useful for logging/debugging the raw wire traffic |
-
-`sof` and `eof` accept either raw `bytes` (when constructing a `Bus` from
-Python) or a hex string (when passed as a CLI `--bus-kwargs` value, since
-python-can CLI tools pass kwargs as strings):
-
-```powershell
-python -m can.logger -i flexible_serial -c COM3 --bus-kwargs sof=0xAA eof=0x0D0A
-```
-
-Prefer the `0x` prefix for CLI hex values, especially if the delimiter
-contains only digits, since python-can auto-converts bare numeric kwargs.
-
-### CLI examples
-
-```powershell
-python -m can.viewer -i flexible_serial -c COM6 --bus-kwargs sof=0x4040 eof=0x0A uint16_id=True crc_type=crc16-ccitt flags_byte=False no_timestamp=True
-```
-
-Bridging to another interface:
-
-```powershell
-python -m can.bridge --bus1-interface flexible_serial --bus1-channel COM7 --bus1-bus-kwargs sof=0x4040 eof=0x0A uint16_id=True crc_type=crc16-ccitt flags_byte=False no_timestamp=True --bus2-interface kvaser --bus2-channel 0 --bus2-bitrate 125000
-```
-
-### Autodetection
-
-Like the built-in `serial` interface, available serial ports are surfaced
-through python-can's autodetection API:
-
-```python
-import can
-print(can.detect_available_configs(interfaces=["flexible_serial"]))
-```
-
-## Layout
-
-```text
-python-can-flexible-serial/
-  pyproject.toml
-  README.md
-  src/
-    flexible_serial/
-      __init__.py
-      bus.py
-  tests/
-    test_hex_bytes.py
-    test_bus.py
-    message_helper.py
-```
-
-## Development
-
-Install with the `dev` extra to pull in test dependencies (`pytest`):
-
-```powershell
-uv sync --extra dev
-```
-or
-```powershell
-python -m pip install -e .[dev]
-```
-
-Run the test suite with:
-
-```
-uv run -m pytest
-```
-or
-```powershell
-python -m pytest
-```
-
-`tests/test_bus.py` scaffolds round-trip tests against two backends — a fully
-in-memory mocked serial port and pyserial's `loop://` — mirroring the
-structure of python-can's own `serial` interface test suite. The test
-bodies are currently stubs (`skipTest`); fill them in as coverage is added.
-
-## Future improvement ideas
-
-- **`can_filters` support** — already works today for free: `BusABC.recv()`
-  always calls `_matches_filters()` in software unless `_recv_internal`
-  reports the message as pre-filtered, and this interface never does. What's
-  still missing is a hardware-style optimization: implement the optional
-  `_apply_filters()` hook so frames can be dropped *before* the CRC check
-  runs, instead of always paying the full decode+CRC cost and filtering
-  afterward.
-- Support the CAN FD protocol for the `BusABC` parent (`can_protocol`
-  currently reports `CAN_20` unconditionally).
-- Add an option for arbitrary (non-CAN) data length up to 255 bytes, since
-  `dlc` is only 1 byte — useful for passing arbitrary serial payloads through
-  python-can tooling without being constrained to CAN/CAN FD payload sizes.

python_can_flexible_serial-0.1.0.dist-info/RECORD

@@ -1,8 +0,0 @@
-flexible_serial/__init__.py,sha256=0XQ0axiWmTV75TIN2M0pM71QNvG_VbDm2wirLRALeRk,129
-flexible_serial/bus.py,sha256=QXFIIey4GF-jp2sXYVjNElWBQeEvz12dbvZSqA2Ocho,29230
-python_can_flexible_serial-0.1.0.dist-info/licenses/LICENSE,sha256=T9834WtL-nnhksAVXTn15FNr5fYyS1KzyLodhEVbKm4,1067
-python_can_flexible_serial-0.1.0.dist-info/METADATA,sha256=7TlEeJcNW4_UCjzT-0y3JKzHHngHHk7TQ8dy4UOoX7s,10036
-python_can_flexible_serial-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-python_can_flexible_serial-0.1.0.dist-info/entry_points.txt,sha256=FvRVfuDmEVWkQEeHq4CEczaXichOYQpbSLzelMhE8V0,69
-python_can_flexible_serial-0.1.0.dist-info/top_level.txt,sha256=CBMqcoYnde__UVfBfwco7r1FFNAkA4MPV5evBl4Bsws,16
-python_can_flexible_serial-0.1.0.dist-info/RECORD,,