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

flexible_serial/__init__.py

@@ -0,0 +1,5 @@
+"""Template python-can plugin for a flexible serial interface."""
+
+from .bus import FlexibleSerial
+
+__all__ = ["FlexibleSerial"]

flexible_serial/bus.py

@@ -0,0 +1,780 @@
+"""
+A python-can interface plugin for a configurable, framed binary protocol
+over a serial port. For example use over serial ports like "/dev/ttyS1" or
+"/dev/ttyUSB0" on Linux machines or "COM1" on Windows.
+
+Unlike python-can's fixed-layout ``serial``/``slcan`` interfaces, the frame
+layout (SOF/EOF delimiters, ID width, optional CRC, optional flags byte,
+optional timestamp) is configurable via constructor kwargs so it can be
+matched to firmware on the other end of the link. See the README for the
+full frame layout and kwarg reference, and
+https://python-can.readthedocs.io/en/stable/plugin-interface.html for the
+python-can plugin interface this implements.
+"""
+
+import io
+import logging
+import struct
+from collections.abc import Sequence
+from typing import TypedDict, Callable, Any, Optional, cast
+import binascii
+import time
+from enum import IntEnum
+
+from can import (
+    BusABC,
+    CanInitializationError,
+    CanInterfaceNotImplementedError,
+    CanOperationError,
+    CanProtocol,
+    CanTimeoutError,
+    Message,
+)
+from can.typechecking import AutoDetectedConfig
+
+logger = logging.getLogger("can.flexible_serial")
+
+try:
+    import serial.tools.list_ports
+except ImportError:
+    logger.warning(
+        "You won't be able to use the serial can backend without "
+        "the `pyserial` package installed!"
+    )
+    serial = None
+
+# move these into the class
+CAN_ERR_FLAG = 0x20000000
+CAN_RTR_FLAG = 0x40000000
+CAN_EFF_FLAG = 0x80000000
+CAN_ID_MASK_EXT = 0x1FFFFFFF
+CAN_ID_MASK_STD = 0x7FF
+
+FLAG_BYTE_ERROR     = 0x01
+FLAG_BYTE_RTR       = 0x02
+FLAG_BYTE_EXTENDED  = 0x04
+FLAG_BYTE_FD        = 0x08
+FLAG_BYTE_FD_BRS    = 0x10
+FLAG_BYTE_IS_RX     = 0x20
+
+MAX_DATA_LEN_CLASSIC = 8
+MAX_DATA_LEN_FD = 64
+
+'''
+Frame Layout (see README.md for the full reference):
+- SOF           -> 1 or more bytes
+HEADER
+- timestamp     -> options: 0 or 4 bytes, uint32 milliseconds
+- dlc           -> 1 byte
+- flags byte    -> options 0 or 1 byte
+- id            -> options 2 or 4 bytes
+DATA PAYLOAD    -> 0 - 64 bytes
+- CRC           -> optional (0 or some num of bytes)
+- EOF           -> 1 or more bytes
+'''
+
+class TimeoutTimer():
+    def __init__(self, timeout: Optional[float]):
+        if timeout is None:
+            self._is_infinite = True
+            self._timeout = 0.0
+        else:
+            self._is_infinite = False
+            self._timeout = max(0.0, timeout)
+        self._start_time = time.monotonic()
+
+    def expired(self) -> bool:
+        if self._is_infinite:
+            return False
+
+        return (time.monotonic() - self._start_time) >= self._timeout
+    
+    def remaining_time(self) -> float | None:
+        if self._is_infinite:
+            return None
+
+        elapsed = time.monotonic() - self._start_time
+        return max(0.0, self._timeout - elapsed)
+
+
+class FlexibleSerial(BusABC):
+    """
+    Enable basic can communication over a serial device using a flexible binary protocol
+
+    .. note:: See :meth:`~_recv_internal` for some special semantics.
+    """
+
+    class SerialError(IntEnum):
+        NONE = 0
+        DESYNC = 1
+        BAD_DLC = 2
+        BAD_EOF = 3
+        BAD_CRC = 4
+
+    ERROR_TEXT = {
+        SerialError.DESYNC: "Start-of-Frame desync",
+        SerialError.BAD_DLC: f"DataLength Invalid (>{MAX_DATA_LEN_FD} bytes)",
+        SerialError.BAD_EOF: "End-of-Frame mismatch",
+        SerialError.BAD_CRC: "CRC Error",
+    }
+
+    CRC_TYPES = frozenset({"none","crc16-ccitt"})
+
+    class FrameKwargs(TypedDict):
+        """Constructor kwargs controlling the wire frame layout.
+
+        :ivar big_endian: Byte order for header/CRC fields.
+        :ivar sof: Start-of-frame delimiter (bytes, or hex string from CLI kwargs).
+        :ivar eof: End-of-frame delimiter (bytes, or hex string from CLI kwargs).
+        :ivar uint16_id: Use a 2-byte arbitration ID instead of 4-byte; rejects extended IDs.
+        :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
+            frame written or chunk of buffer consumed while reading; useful for
+            logging/debugging raw wire traffic.
+        """
+        big_endian: bool
+        sof: bytes
+        eof: bytes
+        uint16_id: bool
+        crc_type: str
+        flags_byte: bool
+        no_timestamp: bool
+        rx_bytes_callback: Callable | None
+
+
+    DEFAULT_FRAME_KWARGS: FrameKwargs = {
+        "big_endian": False,
+        "sof": b"\xAA",
+        "eof": b"\xBB",
+        "uint16_id": False,
+        "crc_type": "none",
+        "flags_byte": False,
+        "no_timestamp": False,
+        "rx_bytes_callback": None
+    }
+
+    DataProcessedCallback = Callable[[bytes, bool], None]
+    ''' Provides arguments [data bytes, is_rx] '''
+
+    def __init__(
+        self,
+        channel: str,
+        baudrate: int = 115200,
+        timeout: float = 0.1,
+        rtscts: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        """
+        :param channel:
+            The serial device to open. For example "/dev/ttyS1" or
+            "/dev/ttyUSB0" on Linux or "COM1" on Windows systems.
+
+        :param baudrate:
+            Baud rate of the serial device in bit/s (default 115200).
+
+            .. warning::
+                Some serial port implementations don't care about the baudrate.
+
+        :param timeout:
+            Timeout for the serial device read calls in seconds (default 0.1).
+
+        :param rtscts:
+            Turn hardware handshake (RTS/CTS) on and off (default false)
+
+        :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.
+
+        :raises ~can.exceptions.CanInitializationError:
+            If the given parameters are invalid.
+        :raises TypeError: If channel is empty/None
+        :raises ~can.exceptions.CanInterfaceNotImplementedError:
+            If the serial module is not installed.
+        """
+
+        if not serial:
+            raise CanInterfaceNotImplementedError("the serial module is not installed")
+
+        if not channel:
+            raise TypeError("Must specify a serial port.")
+
+        self.channel = channel
+        self.channel_info = f"Flexible serial interface: {channel}"
+        self._can_protocol = CanProtocol.CAN_20
+
+        self._rx_buffer = bytearray()
+
+        self._sof = self._coerce_bytes_kwarg(
+            "sof",
+            kwargs.pop("sof", self.DEFAULT_FRAME_KWARGS["sof"]),
+        )
+        self._eof = self._coerce_bytes_kwarg(
+            "eof",
+            kwargs.pop("eof", self.DEFAULT_FRAME_KWARGS["eof"]),
+        )
+
+        big_endian = self._pop_bool_kwarg(kwargs, "big_endian")
+        no_timestamp = self._pop_bool_kwarg(kwargs, "no_timestamp")
+        uint16_id = self._pop_bool_kwarg(kwargs, "uint16_id")
+        flags_byte = self._pop_bool_kwarg(kwargs, "flags_byte")
+
+        self._configure_header(
+            big_endian=big_endian,
+            no_timestamp=no_timestamp,
+            uint16_id=uint16_id,
+            flags_byte=flags_byte,
+        )
+        self._configure_crc(big_endian=big_endian, kwargs=kwargs)
+        self._configure_frame_offsets(no_timestamp=no_timestamp)
+
+        # Register user callback for when serial bytes are received/transmitted
+        self._pop_rx_bytes_callback(kwargs)
+
+        try:
+            self._ser = serial.serial_for_url(
+                channel, baudrate=baudrate, timeout=timeout, rtscts=rtscts
+            )
+        except ValueError as error:
+            raise CanInitializationError(
+                "Could not create the serial device"
+            ) from error
+         
+        logger.info(f"Opened Serial Port {channel} with frame settings:\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"
+              f"\tFlags Byte: {flags_byte}\r\n"
+              f"\tID Length: {2 if uint16_id else 4} bytes\r\n"
+              f"\tCRC: {self._crc_type}",
+        )
+
+        super().__init__(channel, **kwargs)
+
+    def shutdown(self) -> None:
+        """
+        Close the serial interface.
+        """
+        super().shutdown()
+        self._ser.close()
+
+    def send(self, msg: Message, timeout: Optional[float] = None) -> None:
+        """
+        Send a message over the serial device.
+
+        :param msg:
+            Message to send.
+
+            .. note:: If the timestamp is a float value it will be converted
+                      to an integer.
+
+        :param timeout:
+            This parameter will be ignored. The timeout value of the channel is
+            used instead.
+
+        """
+
+        # Reject extended frames if uint16 ID is selected
+        if self._id_is_uint16_t and msg.is_extended_id:
+            raise ValueError("uint16_id=True does not support extended CAN IDs")
+
+        # Mask ID, optionally placing error flags into ID field if its extended AND there is flags byte
+        arbitration_id = msg.arbitration_id & (CAN_ID_MASK_EXT if msg.is_extended_id else CAN_ID_MASK_STD)
+        if not self._has_flags_byte and not self._id_is_uint16_t:
+            if msg.is_extended_id:
+                arbitration_id |= CAN_EFF_FLAG
+            if msg.is_error_frame:
+                arbitration_id |= CAN_ERR_FLAG
+            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))
+
+        # Construct frame
+        frame = bytearray(self._sof)
+        frame += self._header_pack(timestamp_int, msg, arbitration_id)
+        frame += msg.data
+        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
+        
+    @staticmethod
+    def decode_serial_can_error(msg: Message) -> str:
+        '''
+        Data Byte 0 | Data Byte 1
+          DESYNC    | num bytes dropped
+          BAD_DLC   | Received DLC
+          BAD_EOF   |   n/a
+          BAD_CRC   |   n/a
+        '''
+        if not msg.is_error_frame:
+            return ""
+        if len(msg.data) == 0:
+            return "Unknown, no data bytes to decode error type"
+        if msg.data[0] == FlexibleSerial.SerialError.DESYNC:
+            text = FlexibleSerial.ERROR_TEXT[FlexibleSerial.SerialError.DESYNC]
+            if len(msg.data) >= 2:
+                return text + f" -> {msg.data[1]} bytes dropped"
+            else:
+                return text
+        elif msg.data[0] == FlexibleSerial.SerialError.BAD_DLC:
+            text = FlexibleSerial.ERROR_TEXT[FlexibleSerial.SerialError.BAD_DLC]
+            if len(msg.data) >= 2:
+                return text + f" -> Rx data length = {msg.data[1]}"
+            else:
+                return text
+        elif msg.data[0] == FlexibleSerial.SerialError.BAD_EOF:
+            return FlexibleSerial.ERROR_TEXT[FlexibleSerial.SerialError.BAD_EOF]
+        elif msg.data[0] == FlexibleSerial.SerialError.BAD_CRC:
+            return FlexibleSerial.ERROR_TEXT[FlexibleSerial.SerialError.BAD_CRC]
+        else:
+            return f"Unknown data bytes error encoding: {msg.data.hex(' ')}"
+        
+    def _recv_internal(
+        self, timeout: Optional[float]
+    ) -> tuple[Optional[Message], bool]:
+        """
+        Read a message from the serial device.
+
+        :param timeout: length to block until a message is received
+
+        :returns:
+            Received message and :obj:`False` (because no filtering as taken place).
+        """
+
+        timer = TimeoutTimer(timeout)
+        try:
+            while (True):
+                msg = self._try_decode_message_from_buffer()
+                if msg is not None:
+                    return (msg, False)
+
+                # The parser needs more bytes; allow one serial read before
+                # checking the deadline again so recv(0) still polls hardware.
+                # update timeout with remaining time
+                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)
+                self._rx_buffer.extend(new_rx_bytes)
+
+                msg = self._try_decode_message_from_buffer()
+                if msg is not None:
+                    return (msg, False)
+
+                if timer.expired():
+                    return (None, False)
+            
+        except serial.SerialException as error:
+            raise CanOperationError("could not read from serial") from error
+
+    def fileno(self) -> int:
+        try:
+            return cast("int", self._ser.fileno())
+        except io.UnsupportedOperation:
+            raise NotImplementedError(
+                "fileno is not implemented using current CAN bus on this platform"
+            ) from None
+        except Exception as exception:
+            raise CanOperationError("Cannot fetch fileno") from exception
+
+    @staticmethod
+    def _detect_available_configs() -> 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})
+        return configs
+
+    @classmethod
+    def _pop_bool_kwarg(cls, kwargs: dict[str, Any], name: str) -> bool:
+        value = kwargs.pop(name, cls.DEFAULT_FRAME_KWARGS[name])
+        if not isinstance(value, bool):
+            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)
+        if value is None:
+            self._on_data_processed_callback = None
+            return
+        if not callable(value):
+            raise TypeError("'rx_bytes_callback' must be callable")
+        self._on_data_processed_callback = value
+
+    def _configure_header(
+        self,
+        *,
+        big_endian: bool,
+        no_timestamp: bool,
+        uint16_id: bool,
+        flags_byte: bool,
+    ) -> None:
+        self._has_timestamp = not no_timestamp
+        self._id_is_uint16_t = uint16_id
+        self._has_flags_byte = flags_byte
+
+        header_format = self._build_header_format(
+            big_endian=big_endian,
+            no_timestamp=no_timestamp,
+            uint16_id=uint16_id,
+            flags_byte=flags_byte,
+        )
+        self._header = struct.Struct(header_format)
+        self._header_pack = self._select_header_pack()
+
+    @staticmethod
+    def _build_header_format(
+        *,
+        big_endian: bool,
+        no_timestamp: bool,
+        uint16_id: bool,
+        flags_byte: bool,
+    ) -> str:
+        header_format = ">" if big_endian else "<"      # Little/Big Endian
+        header_format += "" if no_timestamp else "I"    # Timestamp -> 0 or 4 bytes
+        header_format += "B"                            # DLC       -> 1 byte
+        header_format += "B" if flags_byte else ""      # Flags     -> 0 or 1 byte
+        header_format += "H" if uint16_id else "I"      # ID        -> 2 or 4 bytes
+        return header_format
+
+    def _select_header_pack(self) -> Callable[[int, Message, int], bytes]:
+        if (not self._has_timestamp and not self._has_flags_byte):
+            return self._pack_header_no_timestamp_no_flags
+        elif (not self._has_timestamp and self._has_flags_byte):
+            return self._pack_header_no_timestamp_yes_flags
+        elif (self._has_timestamp and not self._has_flags_byte):
+            return self._pack_header_yes_timestamp_no_flags
+        elif (self._has_timestamp and self._has_flags_byte):
+            return self._pack_header_yes_timestamp_yes_flags
+
+        raise RuntimeError("Unable to select header pack function")
+
+    def _configure_crc(self, *, big_endian: bool, kwargs: dict[str, Any]) -> None:
+        crc_type = kwargs.pop("crc_type", self.DEFAULT_FRAME_KWARGS["crc_type"])
+        if not isinstance(crc_type, str):
+            raise TypeError(f"'crc_type' must be str, not {type(crc_type).__name__}")
+
+        crc_type = crc_type.lower()
+        crc_type = "none" if crc_type == "" else crc_type
+        if crc_type not in self.CRC_TYPES:
+            raise ValueError(
+                f"'crc_type' {crc_type} not supported, must be one of {self.CRC_TYPES}"
+            )
+        
+        self._crc_type = crc_type
+        if crc_type == "crc16-ccitt":
+            self._has_crc = True
+            self._crc_calculate = self._crc16_calculate_ccitt
+            self._crc_struct = struct.Struct((">" if big_endian else "<") + "H")
+            self._crc_size = self._crc_struct.size
+        else:
+            self._has_crc = False
+            self._crc_calculate = self._crc_calculate_none
+            self._crc_size = 0
+
+    def _configure_frame_offsets(self, *, no_timestamp: bool) -> None:
+        self._sof_len = len(self._sof)
+        self._eof_len = len(self._eof)
+        self._header_offset = self._sof_len
+        self._payload_offset = self._header_offset + self._header.size
+
+        self._crc_calc_start_offset = self._sof_len
+        self._crc_calc_start_offset += 0 if no_timestamp else 4
+        self._crc_calc_start_offset += 1
+
+        self._min_frame_length = self._payload_offset + self._crc_size + self._eof_len
+
+    @staticmethod
+    def _coerce_bytes_kwarg(name: str, value: Any) -> bytes:
+        if isinstance(value, (bytes, bytearray)):
+            byte_value = bytes(value)
+        elif isinstance(value, str):
+            byte_value = FlexibleSerial._parse_hex_bytes(name, value)
+        else:
+            raise TypeError(
+                f"'{name}' must be bytes or a hex string, "
+                f"not {type(value).__name__}"
+            )
+
+        if not byte_value:
+            raise ValueError(f"'{name}' must not be empty")
+        return byte_value
+
+    @staticmethod
+    def _parse_hex_bytes(name: str, value: str) -> bytes:
+        hex_value = value.strip()
+        hex_value = hex_value.replace("\\x", "").replace("\\X", "")
+        hex_value = hex_value.replace("0x", "").replace("0X", "")
+
+        for separator in (" ", "\t", "\r", "\n", "_", "-", ":", ","):
+            hex_value = hex_value.replace(separator, "")
+
+        if len(hex_value) % 2:
+            raise ValueError(
+                f"'{name}' hex string must contain an even number of digits"
+            )
+
+        try:
+            return bytes.fromhex(hex_value)
+        except ValueError as error:
+            raise ValueError(f"'{name}' must be bytes or a hex string") from error
+
+    # A different pack_header method for each possible header structure
+    # They all use the same arguments so the call to self._pack_header(...) in send() doesn't fail
+    def _pack_header_no_timestamp_no_flags(self, timestamp: int, msg: Message, arbitration_id: int) -> bytes:
+        return self._header.pack(msg.dlc, arbitration_id)
+    def _pack_header_no_timestamp_yes_flags(self, timestamp: int, msg: Message, arbitration_id: int) -> bytes:
+        return self._header.pack(msg.dlc, self._build_flags_byte(msg), arbitration_id)
+    def _pack_header_yes_timestamp_no_flags(self, timestamp: int, msg: Message, arbitration_id: int) -> bytes:
+        return self._header.pack(timestamp, msg.dlc, arbitration_id)
+    def _pack_header_yes_timestamp_yes_flags(self, timestamp: int, msg: Message, arbitration_id: int) -> bytes:
+        return self._header.pack(timestamp, msg.dlc, self._build_flags_byte(msg), arbitration_id)
+
+    def _crc_calculate_none(self, data: memoryview) -> bytes:
+        """ Return an empty bytes if CRC is not implemented """
+        return b""
+    
+    def _crc16_calculate_ccitt(self, data: memoryview) -> bytes:
+        """
+        CRC16-CCITT with 0xFFFF start seed using polynomial 0x1021
+        """
+        crc = binascii.crc_hqx(data, 0xFFFF)
+        return self._crc_struct.pack(crc)
+    
+    @staticmethod
+    def _build_flags_byte(msg: Message) -> int:
+        """ Build and return a packed byte filed with CAN message metadata"""
+        flags = 0
+        if msg.is_extended_id:
+            flags = FLAG_BYTE_EXTENDED
+        if msg.is_error_frame:
+            flags |= FLAG_BYTE_ERROR
+        if msg.is_remote_frame:
+            flags |= FLAG_BYTE_RTR
+        if msg.bitrate_switch:
+            flags |= FLAG_BYTE_FD_BRS
+        if msg.is_fd:
+            flags |= FLAG_BYTE_FD
+        if msg.is_rx:
+            flags |= FLAG_BYTE_IS_RX
+        return flags
+
+    def _build_rx_error_message(
+        self,
+        error: "FlexibleSerial.SerialError",
+        *,
+        timestamp: Optional[float] = None,
+        arbitration_id: int = 0,
+        is_extended_id: bool = False,
+        is_fd: bool = False,
+        is_rx: bool = True,
+        bitrate_switch: bool = False,
+        detail: Optional[int] = None,
+    ) -> Message:
+        if detail is None:
+            data = bytes([int(error)])
+        else:
+            data = bytes([int(error), max(0, min(detail, 0xFF))])
+
+        return Message(
+            timestamp=time.time() if timestamp is None else timestamp,
+            arbitration_id=arbitration_id,
+            is_extended_id=is_extended_id,
+            is_remote_frame=False,
+            is_error_frame=True,
+            dlc=len(data),
+            data=data,
+            is_fd=is_fd,
+            is_rx=is_rx,
+            bitrate_switch=bitrate_switch,
+            channel=self._ser.port
+        )
+
+    def _try_decode_message_from_buffer(self) -> Optional[Message]:
+        """Parse one complete message from the buffered serial bytes, if available."""
+
+        if not self._rx_buffer:
+            return None
+
+        # Search for SOF and preserve any partial SOF at the end of the buffer.
+        sof_index = self._rx_buffer.find(self._sof)
+        if sof_index < 0:
+            keep_len = 0
+            max_keep_len = min(len(self._rx_buffer), self._sof_len - 1)
+            for candidate_len in range(max_keep_len, 0, -1):
+                if self._sof.startswith(bytes(self._rx_buffer[-candidate_len:])):
+                    keep_len = candidate_len
+                    break
+
+            dropped_count = len(self._rx_buffer) - keep_len
+            if dropped_count <= 0:
+                return None
+
+            if self._on_data_processed_callback:
+                self._on_data_processed_callback(self._rx_buffer[:dropped_count], True)
+            del self._rx_buffer[:dropped_count]
+            return self._build_rx_error_message(
+                self.SerialError.DESYNC,
+                detail=dropped_count,
+            )
+
+        # Drop any junk before the next complete SOF.
+        if sof_index > 0:
+            if self._on_data_processed_callback:
+                self._on_data_processed_callback(self._rx_buffer[:sof_index], True)
+            del self._rx_buffer[:sof_index]
+            return self._build_rx_error_message(
+                self.SerialError.DESYNC,
+                detail=sof_index,
+            )
+
+        # Wait until the smallest valid frame can fit in the buffer.
+        if len(self._rx_buffer) < self._min_frame_length:
+            return None
+
+        # Unpack fixed header fields.
+        header = self._header.unpack_from(self._rx_buffer, self._header_offset)
+        header_idx = 0
+        if self._has_timestamp:
+            timestamp = header[header_idx] / 1000.0
+            header_idx += 1
+        else:
+            timestamp = time.time()
+
+        dlc = header[header_idx]
+        header_idx += 1
+
+        if self._has_flags_byte:
+            flags_byte = header[header_idx]
+            header_idx += 1
+        else:
+            flags_byte = None
+
+        arbitration_id = header[header_idx]
+
+        # Parse message metadata from flags byte, ID flags, or format defaults.
+        if self._has_flags_byte:
+            is_extended_id  = bool(flags_byte & FLAG_BYTE_EXTENDED)
+            is_error_frame  = bool(flags_byte & FLAG_BYTE_ERROR)
+            is_remote_frame = bool(flags_byte & FLAG_BYTE_RTR)
+            is_can_fd       = bool(flags_byte & FLAG_BYTE_FD)
+            is_can_fd_brs   = bool(flags_byte & FLAG_BYTE_FD_BRS)
+            is_rx           = bool(flags_byte & FLAG_BYTE_IS_RX)
+        elif self._id_is_uint16_t:
+            is_extended_id  = False
+            is_error_frame  = False
+            is_remote_frame = False
+            is_can_fd       = dlc > 8
+            is_can_fd_brs   = False
+            is_rx           = True
+        else:
+            is_extended_id  = bool(arbitration_id & CAN_EFF_FLAG)
+            is_error_frame  = bool(arbitration_id & CAN_ERR_FLAG)
+            is_remote_frame = bool(arbitration_id & CAN_RTR_FLAG)
+            is_can_fd       = False
+            is_can_fd_brs   = False
+            is_rx           = True
+
+        # Mask protocol flag bits out of the CAN ID.
+        if is_extended_id:
+            arbitration_id = arbitration_id & CAN_ID_MASK_EXT
+        else:
+            arbitration_id = arbitration_id & CAN_ID_MASK_STD
+
+        # 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)
+            del self._rx_buffer[0]
+            return self._build_rx_error_message(
+                self.SerialError.BAD_DLC,
+                timestamp=timestamp,
+                arbitration_id=arbitration_id,
+                is_extended_id=is_extended_id,
+                is_fd=is_can_fd,
+                is_rx=is_rx,
+                bitrate_switch=is_can_fd_brs,
+                detail=dlc,
+            )
+
+        # Compute variable-length frame boundaries.
+        crc_offset = self._payload_offset + dlc
+        eof_offset = crc_offset + self._crc_size
+        frame_end = eof_offset + self._eof_len
+
+        # Wait until the complete frame is buffered.
+        if len(self._rx_buffer) < frame_end:
+            return None
+
+        # 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)
+            del self._rx_buffer[0]
+            return self._build_rx_error_message(
+                self.SerialError.BAD_EOF,
+                timestamp=timestamp,
+                arbitration_id=arbitration_id,
+                is_extended_id=is_extended_id,
+                is_fd=is_can_fd,
+                is_rx=is_rx,
+                bitrate_switch=is_can_fd_brs,
+            )
+
+        # Validate CRC when enabled.
+        if self._has_crc:
+            expected_crc = self._crc_calculate(
+                memoryview(self._rx_buffer)[self._crc_calc_start_offset:crc_offset]
+            )
+            received_crc = self._rx_buffer[crc_offset:eof_offset]
+            if expected_crc != received_crc:
+                if self._on_data_processed_callback:
+                    self._on_data_processed_callback(self._rx_buffer[:frame_end], True)
+                del self._rx_buffer[:frame_end]
+                return self._build_rx_error_message(
+                    self.SerialError.BAD_CRC,
+                    timestamp=timestamp,
+                    arbitration_id=arbitration_id,
+                    is_extended_id=is_extended_id,
+                    is_fd=is_can_fd,
+                    is_rx=is_rx,
+                    bitrate_switch=is_can_fd_brs,
+                )
+
+        # Build decoded CAN message and consume the frame bytes.
+        payload = bytearray(self._rx_buffer[self._payload_offset:crc_offset])
+        if self._on_data_processed_callback:
+            self._on_data_processed_callback(self._rx_buffer[:frame_end], True)
+        del self._rx_buffer[:frame_end]
+        return Message(
+            timestamp=timestamp,
+            arbitration_id=arbitration_id,
+            is_extended_id=is_extended_id,
+            is_remote_frame=is_remote_frame,
+            is_error_frame=is_error_frame,
+            dlc=dlc,
+            data=payload,
+            is_fd=is_can_fd,
+            is_rx=is_rx,
+            bitrate_switch=is_can_fd_brs,
+            channel=self._ser.port
+        )

python_can_flexible_serial-0.1.0.dist-info/METADATA

@@ -0,0 +1,261 @@
+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

@@ -0,0 +1,8 @@
+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,,

python_can_flexible_serial-0.1.0.dist-info/WHEEL

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

python_can_flexible_serial-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[can.interface]
+flexible_serial = flexible_serial.bus:FlexibleSerial

python_can_flexible_serial-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Bulow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

python_can_flexible_serial-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+flexible_serial