python-can-canpal 0.1.0rc1__py3-none-any.whl

canpal/__init__.py

@@ -0,0 +1,10 @@
+"""CANPAL backend for python-can; importing does not load the native SDK."""
+
+__version__ = "0.1.0rc1"
+
+
+def __getattr__(name):
+    if name == "CanpalBus":
+        from .bus import CanpalBus
+        return CanpalBus
+    raise AttributeError(name)

canpal/bus.py

@@ -0,0 +1,312 @@
+"""One physical CANPAL device and selected channel per python-can Bus."""
+from __future__ import annotations
+
+from contextlib import contextmanager
+import ctypes as C
+import ipaddress
+import logging
+import math
+import threading
+import time
+
+from can import BusABC, CanInitializationError, CanOperationError, CanTimeoutError
+from can.bus import CanProtocol
+
+from . import codec, discovery, native
+
+LOG = logging.getLogger(__name__)
+_connect_lock = threading.Lock()
+_registry_lock = threading.Lock()
+# Values are opaque ownership tokens: the registry must not keep Bus objects alive.
+_uids = {}
+_endpoints = {}
+
+
+def _timeout(value):
+    if value is not None and (not isinstance(value, (int, float))
+                              or not math.isfinite(value) or value < 0):
+        raise ValueError("timeout must be None or a finite nonnegative number")
+    return value
+
+
+class CanpalBus(BusABC):
+    def __init__(
+        self, channel=0, *, transport, bitrate, device_id=None, usb_port=None,
+        host=None, port=None, fd=False, data_bitrate=None, listen_only=False,
+        termination=None, can_filters=None, receive_own_messages=False,
+        library_path=None, **kwargs,
+    ):
+        self._is_shutdown = True
+        self._handle = None
+        self._token = object()
+        self._registered_uid = None
+        self._endpoint = None
+        self._closing = False
+        self._fault = None
+        self._initialized = False
+        self._condition = threading.Condition()
+        self._inflight = 0
+        self._send_lock = threading.Lock()
+        self._recv_lock = threading.Lock()
+        self._shutdown_lock = threading.Lock()
+        self._next_tag = 1
+        if kwargs:
+            raise ValueError(f"Unsupported CANPAL options: {', '.join(sorted(kwargs))}")
+        if transport not in ("usb", "wlan"):
+            raise ValueError("transport must be 'usb' or 'wlan'")
+        if type(channel) is not int or not 0 <= channel <= 255:
+            raise ValueError("channel must be a nonnegative integer")
+        for name, value in (("fd", fd), ("listen_only", listen_only),
+                            ("receive_own_messages", receive_own_messages)):
+            if type(value) is not bool:
+                raise ValueError(f"{name} must be a bool")
+        if termination is not None and type(termination) is not bool:
+            raise ValueError("termination must be None or bool")
+        if receive_own_messages:
+            raise ValueError("receive_own_messages=True is not supported")
+        if type(bitrate) is not int or bitrate <= 0:
+            raise ValueError("bitrate must be a positive integer")
+        if fd and (type(data_bitrate) is not int or data_bitrate <= 0):
+            raise ValueError("fd=True requires data_bitrate")
+        if not fd and data_bitrate is not None:
+            raise ValueError("data_bitrate requires fd=True")
+        expected_uid = discovery.normalize_uid(device_id)
+        if transport == "usb":
+            if host is not None or port is not None:
+                raise ValueError("USB cannot use host/port")
+            if expected_uid is None and usb_port is None:
+                raise ValueError("USB requires device_id or usb_port")
+            if usb_port is not None:
+                discovery.normalize_port(usb_port)
+        else:
+            if usb_port is not None:
+                raise ValueError("WLAN cannot use usb_port")
+            if not isinstance(host, str):
+                raise ValueError("WLAN requires an IPv4 host")
+            host = str(ipaddress.IPv4Address(host))
+            if type(port) is not int or not 1 <= port <= 65535:
+                raise ValueError("WLAN requires a TCP port between 1 and 65535")
+        self.channel, self.fd, self.listen_only = channel, fd, listen_only
+        self._api = native.load_library(library_path)
+        try:
+            with _connect_lock:
+                with _registry_lock:
+                    if expected_uid in _uids:
+                        raise CanInitializationError(f"CANPAL {expected_uid} is already occupied")
+                    occupied = {ep[1] for ep in _endpoints if ep[0] == "usb"}
+                if transport == "usb":
+                    candidates = [
+                        (("usb", name), native.Connection(CommType=0, LocalPort=number))
+                        for name, number in discovery.usb_candidates(
+                            usb_port, occupied, expected_uid is not None
+                        )
+                    ]
+                else:
+                    candidates = [(("wlan", host, port), native.Connection(
+                        CommType=2, DestHost=host.encode("ascii"), DestPort=port
+                    ))]
+                errors = []
+                for endpoint, connection in candidates:
+                    with _registry_lock:
+                        if endpoint in _endpoints:
+                            raise CanInitializationError(f"CANPAL endpoint {endpoint} is occupied")
+                    handle = self._api.YX_Open(C.byref(connection))
+                    if not handle:
+                        errors.append(f"{endpoint}: open failed")
+                        continue
+                    retained = False
+                    try:
+                        info = native.DeviceInfo()
+                        if not self._api.YX_GetDeviceInfo(handle, C.byref(info)):
+                            errors.append(f"{endpoint}: identity read failed")
+                            continue
+                        if expected_uid and info.uid != expected_uid:
+                            errors.append(f"{endpoint}: UID mismatch ({info.uid})")
+                            continue
+                        with _registry_lock:
+                            if info.uid in _uids:
+                                raise CanInitializationError(f"CANPAL {info.uid} is already occupied")
+                            _uids[info.uid] = self._token
+                            _endpoints[endpoint] = self._token
+                        self._registered_uid = self.device_id = info.uid
+                        self._endpoint, self._handle, self.device_info = endpoint, handle, info
+                        retained = True
+                        break
+                    finally:
+                        if not retained:
+                            self._api.YX_Close(handle)
+                if self._handle is None:
+                    raise CanInitializationError(
+                        "CANPAL not found or inaccessible: " + ("; ".join(errors) or "no free USB candidates")
+                    )
+                self._configure(bitrate, data_bitrate, termination)
+                self.channel_info = f"CANPAL {self.device_id} {self._endpoint} CAN{channel}"
+                self._can_protocol = CanProtocol.CAN_FD if fd else CanProtocol.CAN_20
+                super().__init__(channel=channel, can_filters=can_filters)
+        except BaseException:
+            self._dispose()
+            raise
+
+    def _command(self, name, *args):
+        result = getattr(self._api, name)(self._handle, *args)
+        if result:
+            self._fault = f"{name} returned SDK error {result}"
+            raise CanInitializationError(
+                f"{getattr(self, 'device_id', '?')}: {self._fault}", error_code=result
+            )
+
+    def _configure(self, bitrate, data_bitrate, termination):
+        capacity = native.Capacity()
+        info = self.device_info
+        if not self._api.YX_GetCapacity(info.DeviceModel, C.byref(capacity)):
+            raise CanInitializationError(f"Unsupported device model {info.DeviceModel}")
+        if self.channel >= capacity.CAN_channel_num:
+            raise CanInitializationError("Selected CAN channel is unavailable")
+        if self.fd and not capacity.CAN_FD_supported:
+            raise CanInitializationError("This CANPAL does not support CAN FD")
+        if not capacity.CAN_Classic_supported:
+            raise CanInitializationError("This CANPAL does not support CAN")
+        if self._endpoint[0] == "wlan" and not (capacity.Wifi_supported or capacity.Ethernet_supported):
+            raise CanInitializationError("Device does not support network transport")
+        self._use_fd_api = info.DeviceModel in (2, 3, 5)
+        suffix = "FD" if self._use_fd_api else ""
+        ctrl_type = native.FDController if self._use_fd_api else native.Controller
+        previous, ctrl = ctrl_type(), ctrl_type()
+        self._command("YXCAN_GetController" + suffix, self.channel, C.byref(previous))
+        ctrl.CANMode = 2 if self.listen_only else 0
+        try:
+            if self._use_fd_api:
+                modern = info.SWVer >= 0x0120
+                nominal = codec.FD_NOMINAL_80 if modern else codec.FD_NOMINAL_100
+                data = codec.FD_DATA_80 if modern else codec.FD_DATA_100
+                ctrl.NomBaudrate = bitrate
+                ctrl.NomSJW, ctrl.NomBS1, ctrl.NomBS2 = nominal[bitrate]
+                ctrl.DataBaudrate = data_bitrate if self.fd else 2_000_000
+                ctrl.DataSJW, ctrl.DataBS1, ctrl.DataBS2 = data[ctrl.DataBaudrate]
+                ctrl.FrameMode, ctrl.ISOModeEnable = (2 if self.fd else 0), 1
+                ctrl.ResistorEnable = previous.ResistorEnable if termination is None else int(termination)
+            else:
+                ctrl.Baudrate = bitrate
+                ctrl.SJW, ctrl.BS1, ctrl.BS2 = codec.CLASSIC_TIMING[bitrate]
+                ctrl.Option = (previous.Option & 0x0C) if termination is None else (4 if termination else 0)
+        except KeyError as exc:
+            raise CanInitializationError(f"No SDK timing preset for bitrate {exc.args[0]}") from exc
+        # Device-wide options are volatile. One Bus exclusively owns this device.
+        # Same sequence as the SDK's J2534 setup; no YX_SaveSetting call.
+        for parameter_id in (0, 1, 19, 21):  # filter, automation, bridge, spy
+            value = native.Parameter(ID=parameter_id, Len=1)
+            self._command("YX_SetParameter", C.byref(value))
+            check = native.Parameter(ID=parameter_id)
+            self._command("YX_GetParameter", C.byref(check))
+            if check.Len != 1 or check.Data[0] != 0:
+                raise CanInitializationError(f"Parameter {parameter_id} readback mismatch")
+        self._command("YXCAN_SetController" + suffix, self.channel, C.byref(ctrl))
+        check = ctrl_type()
+        self._command("YXCAN_GetController" + suffix, self.channel, C.byref(check))
+        if bytes(check) != bytes(ctrl):
+            raise CanInitializationError("Controller readback mismatch")
+        init = native.InitHW()
+        before = time.time()
+        self._command("YXCAN_Initialize", self.channel, C.byref(init))
+        after = time.time()
+        if not init.Inited:
+            raise CanInitializationError("SDK returned Inited=0")
+        self._initialized = True
+        self._clock = codec.TimestampClock(int.from_bytes(init.Timestamp, "little"), (before + after) / 2)
+        self._send_native = getattr(self._api, "YXCAN_Send" + suffix)
+        self._receive_native = getattr(self._api, "YXCAN_Receive" + suffix)
+        self._message_type = native.FDMessage if self._use_fd_api else native.ClassicMessage
+
+    @contextmanager
+    def _call(self):
+        with self._condition:
+            if self._closing or not self._handle or self._fault:
+                raise CanOperationError(self._fault or "CANPAL is closing or closed")
+            self._inflight += 1
+            handle = self._handle
+        try:
+            yield handle
+        finally:
+            with self._condition:
+                self._inflight -= 1
+                self._condition.notify_all()
+
+    def send(self, msg, timeout=None):
+        _timeout(timeout)
+        if self.listen_only:
+            raise CanOperationError("Cannot transmit in listen-only mode")
+        # Validate before waiting; tag assignment is serialized below.
+        packet = codec.encode(msg, self.channel, self._use_fd_api, self.fd, 1)
+        acquired = self._send_lock.acquire() if timeout is None else self._send_lock.acquire(timeout=timeout)
+        if not acquired:
+            raise CanTimeoutError("Timed out before CANPAL submission; frame was not submitted")
+        try:
+            with self._call() as handle:
+                packet.TXCtrl.TxHandle = self._next_tag
+                self._next_tag = self._next_tag % 65535 + 1
+                if not self._send_native(handle, C.byref(packet)):
+                    raise CanOperationError("CANPAL rejected frame submission; no Python retry")
+        finally:
+            self._send_lock.release()
+
+    def _recv_internal(self, timeout):
+        _timeout(timeout)
+        if not self._recv_lock.acquire(blocking=False):
+            raise CanOperationError("Only one receiver/Notifier may read a CANPAL Bus")
+        try:
+            deadline = None if timeout is None else time.monotonic() + timeout
+            while True:
+                remaining = None if deadline is None else max(0, deadline - time.monotonic())
+                wait_ms = 50 if remaining is None else min(50, int(remaining * 1000))
+                packet = self._message_type()
+                with self._call() as handle:
+                    got = self._receive_native(handle, C.byref(packet), wait_ms)
+                    if not got and not self._api.YX_Online(handle):
+                        self._fault = f"CANPAL {self.device_id} disconnected"
+                        raise CanOperationError(self._fault)
+                if got and packet.Bus == self.channel:
+                    if packet.MsgType == 0:
+                        try:
+                            stamp = self._clock.convert(packet.Timestamp)
+                            message = codec.decode(packet, stamp)
+                            if message.is_fd and not self.fd:
+                                raise ValueError("FD frame received on classic-only Bus")
+                            return message, False
+                        except ValueError as exc:
+                            LOG.warning("Discarding invalid frame from %s: %s", self.device_id, exc)
+                    else:
+                        LOG.debug("CANPAL %s record type=%d result=%d",
+                                  self.device_id, packet.MsgType, packet.TXCtrl.Result)
+                if deadline is not None and time.monotonic() >= deadline:
+                    return None, False
+                if wait_ms == 0 and not got:
+                    time.sleep(min(0.001, max(0, deadline - time.monotonic())))
+        finally:
+            self._recv_lock.release()
+
+    def _dispose(self):
+        if self._handle:
+            self._api.YX_Close(self._handle)
+            self._handle = None
+        with _registry_lock:
+            if self._registered_uid and _uids.get(self._registered_uid) is self._token:
+                del _uids[self._registered_uid]
+            if self._endpoint and _endpoints.get(self._endpoint) is self._token:
+                del _endpoints[self._endpoint]
+
+    def shutdown(self):
+        with self._shutdown_lock:
+            if self._is_shutdown and self._handle is None:
+                return
+            with self._condition:
+                self._closing = True
+            super().shutdown()
+            with self._condition:
+                self._condition.wait_for(lambda: self._inflight == 0)
+            try:
+                if self._handle and self._initialized and not self._fault and self._api.YX_Online(self._handle):
+                    result = self._api.YXCAN_Uninitialize(self._handle, self.channel)
+                    if result:
+                        LOG.warning("CANPAL %s uninitialize failed (%d); closing", self.device_id, result)
+            finally:
+                self._dispose()

canpal/codec.py

@@ -0,0 +1,110 @@
+"""CAN message conversion without mutating caller-owned messages."""
+from __future__ import annotations
+
+from can import Message
+
+from .native import ClassicMessage, FDMessage
+
+FD_LENGTHS = (0, 1, 2, 3, 4, 5, 6, 7, 8, 12, 16, 20, 24, 32, 48, 64)
+TIMESTAMP_MASK = (1 << 48) - 1
+
+
+def encode(message: Message, channel: int, use_fd_api: bool, fd_enabled: bool, tag: int):
+    if not isinstance(message, Message):
+        raise ValueError("send expects a can.Message")
+    if message.is_error_frame:
+        raise ValueError("Transmitting error frames is not supported")
+    if not isinstance(message.arbitration_id, int) or not (
+        0 <= message.arbitration_id <= (0x1FFFFFFF if message.is_extended_id else 0x7FF)
+    ):
+        raise ValueError("CAN arbitration ID is out of range")
+    if message.is_fd and (not fd_enabled or not use_fd_api):
+        raise ValueError("FD transmission requires an FD-enabled Bus")
+    if message.is_fd and message.is_remote_frame:
+        raise ValueError("CAN FD cannot contain RTR frames")
+    if not message.is_fd and (message.bitrate_switch or message.error_state_indicator):
+        raise ValueError("BRS/ESI require a CAN FD frame")
+    if not isinstance(message.dlc, int) or not 0 <= message.dlc <= (64 if message.is_fd else 8):
+        raise ValueError("CAN data length is out of range")
+    if message.is_remote_frame:
+        if len(message.data):
+            raise ValueError("RTR frames must not contain data")
+    elif message.dlc != len(message.data):
+        raise ValueError("Message.dlc must equal the data length")
+    if not 1 <= tag <= 65535:
+        raise ValueError("TX tag must be between 1 and 65535")
+    native = FDMessage() if use_fd_api else ClassicMessage()
+    native.MsgFlag = (
+        int(message.is_extended_id) | (int(message.is_remote_frame) << 1)
+        | (int(message.is_fd) << 2) | (int(message.bitrate_switch) << 3)
+        | (int(message.error_state_indicator) << 4)
+    )
+    native.Bus, native.ID = channel, message.arbitration_id
+    native.DLC = (next(i for i, size in enumerate(FD_LENGTHS) if size >= message.dlc)
+                  if message.is_fd else message.dlc)
+    native.Data[:len(message.data)] = message.data
+    native.TXCtrl.TxHandle = tag
+    native.TXCtrl.MaxTry = 255
+    return native
+
+
+def decode(native, timestamp: float) -> Message:
+    flags = int(native.MsgFlag)
+    is_fd, is_rtr = bool(flags & 4), bool(flags & 2)
+    if flags & ~0x1F or (is_fd and is_rtr) or (not is_fd and flags & 0x18):
+        raise ValueError(f"Invalid native CAN flags: 0x{flags:02x}")
+    if native.DLC > (15 if is_fd else 8):
+        raise ValueError("Invalid native DLC")
+    if is_fd and not isinstance(native, FDMessage):
+        raise ValueError("FD frame in a classic API record")
+    length = FD_LENGTHS[native.DLC] if is_fd else native.DLC
+    return Message(
+        timestamp=timestamp, arbitration_id=native.ID,
+        is_extended_id=bool(flags & 1), is_remote_frame=is_rtr,
+        is_fd=is_fd, bitrate_switch=bool(flags & 8),
+        error_state_indicator=bool(flags & 16), channel=int(native.Bus),
+        dlc=length, data=b"" if is_rtr else bytes(native.Data[:length]),
+        is_rx=True, check=True,
+    )
+
+
+class TimestampClock:
+    def __init__(self, raw_anchor: int, wall_anchor: float):
+        self.raw_anchor, self.wall_anchor = raw_anchor, wall_anchor
+
+    def convert(self, raw) -> float:
+        value = int.from_bytes(raw, "little")
+        delta = (value - self.raw_anchor) & TIMESTAMP_MASK
+        # A record from before initialization must not be dated years into the future.
+        if delta > (1 << 47):
+            raise ValueError("Timestamp precedes this controller initialization")
+        return self.wall_anchor + delta / 1_000_000
+
+
+# Presets originate in CANPALAPI canpal_driver_tp.cpp at c78e2d3.
+# Classic SJW/BS values use SDK register encodings (time quanta minus one).
+CLASSIC_TIMING = {
+    1_000_000: (0, 15, 3), 800_000: (0, 8, 2), 500_000: (0, 9, 2),
+    250_000: (0, 15, 3), 125_000: (0, 15, 3), 100_000: (0, 15, 3),
+    83_333: (0, 15, 3), 50_000: (0, 15, 3), 33_333: (0, 11, 2),
+    20_000: (0, 15, 2), 10_000: (0, 15, 2), 5_000: (0, 15, 2),
+}
+FD_NOMINAL_100 = {
+    1_000_000: (3, 18, 6), 500_000: (3, 19, 5), 250_000: (3, 19, 5),
+    125_000: (3, 19, 5), 100_000: (4, 31, 8), 83_333: (4, 31, 8),
+    50_000: (4, 31, 8), 33_333: (4, 31, 8), 25_000: (4, 31, 8),
+    20_000: (4, 31, 8), 15_000: (4, 32, 8), 10_000: (4, 31, 8),
+    5_000: (4, 31, 8),
+}
+FD_NOMINAL_80 = {
+    1_000_000: (2, 11, 4), 500_000: (3, 15, 4), 250_000: (3, 15, 4),
+    125_000: (3, 15, 4), 100_000: (4, 19, 5), 83_333: (3, 19, 4),
+    50_000: (5, 25, 6), 33_333: (5, 23, 6), 25_000: (4, 34, 5),
+    20_000: (4, 34, 5), 15_000: (6, 40, 7), 10_000: (5, 43, 6),
+    5_000: (6, 56, 7),
+}
+FD_DATA_100 = {5_000_000: (1, 13, 6), 4_000_000: (1, 18, 6), 2_000_000: (1, 18, 6)}
+FD_DATA_80 = {
+    8_000_000: (1, 6, 3), 5_000_000: (1, 11, 4),
+    4_000_000: (1, 13, 6), 2_000_000: (1, 29, 10),
+}

canpal/discovery.py

@@ -0,0 +1,66 @@
+"""USB enumeration only: no CAN traffic and no network discovery."""
+from __future__ import annotations
+
+from pathlib import Path
+import re
+import sys
+
+from serial.tools import list_ports
+
+VID_PID = (0x0483, 0x5740)
+
+
+def normalize_uid(value: str | None) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str) or re.fullmatch(r"[0-9a-fA-F]{24}", value) is None:
+        raise ValueError("device_id must contain exactly 24 hexadecimal digits")
+    return value.lower()
+
+
+def normalize_port(value: str, platform: str | None = None) -> tuple[str, int]:
+    platform = platform or sys.platform
+    if not isinstance(value, str):
+        raise ValueError("usb_port must be a COM name or /dev/ttyACM path")
+    if platform == "win32":
+        match = re.fullmatch(r"COM([0-9]+)", value, re.IGNORECASE)
+        number = int(match[1]) if match else -1
+        if not 1 <= number <= 65535:
+            raise ValueError(f"Invalid CANPAL USB port: {value!r}")
+        return f"COM{number}", number
+    if value.startswith("/dev/serial/by-id/"):
+        value = str(Path(value).resolve(strict=True))
+    match = re.fullmatch(r"/dev/ttyACM([0-9]+)", value)
+    number = int(match[1]) if match else -1
+    if not 0 <= number <= 65535:
+        raise ValueError(f"Invalid CANPAL USB port: {value!r}")
+    return f"/dev/ttyACM{number}", number
+
+
+def usb_candidates(preferred: str | None, occupied: set[str], discover: bool):
+    records = list(list_ports.comports())
+    candidates = []
+    if preferred is not None:
+        name, number = normalize_port(preferred)
+        known = next((item for item in records if item.device.lower() == name.lower()), None)
+        incompatible = (known is not None and known.vid is not None and known.pid is not None
+                        and (known.vid, known.pid) != VID_PID)
+        if incompatible and not discover:
+            raise ValueError(f"{name} belongs to a different USB product")
+        if not incompatible:
+            candidates.append((name, number))
+    if discover:
+        discovered = []
+        for item in records:
+            if (item.vid, item.pid) != VID_PID:
+                continue
+            try:
+                discovered.append(normalize_port(item.device))
+            except ValueError:
+                continue
+        candidates.extend(sorted(discovered, key=lambda candidate: candidate[1]))
+    seen = set()
+    for name, number in candidates:
+        if name not in seen and name not in occupied:
+            seen.add(name)
+            yield name, number

canpal/native.py

@@ -0,0 +1,187 @@
+"""ctypes bindings to the packed CANPAL v1.3.7.6 C interface."""
+from __future__ import annotations
+
+import ctypes as C
+import ctypes.util
+import os
+import platform
+from pathlib import Path
+import struct
+import sys
+import threading
+
+from can import CanInterfaceNotImplementedError
+
+U8, U16, U32 = C.c_uint8, C.c_uint16, C.c_uint32
+P = C.POINTER
+HANDLE = C.c_void_p
+
+
+class Packed(C.Structure):
+    _pack_ = 1
+
+
+class Connection(Packed):
+    _fields_ = [
+        ("CommType", U32), ("DestHost", C.c_char * 256), ("DestPort", U16),
+        ("LocalHost", C.c_char * 256), ("LocalPort", U16),
+    ]
+
+
+class DeviceInfo(Packed):
+    _fields_ = [
+        ("DeviceName", C.c_char * 20), ("DeviceModel", U32),
+        ("HWVer", U16), ("SWVer", U16), ("UniqueID", U8 * 12),
+    ]
+
+    @property
+    def uid(self):
+        return bytes(self.UniqueID).hex()
+
+
+class Capacity(Packed):
+    _fields_ = [(name, U8) for name in (
+        "CAN_Classic_supported", "CAN_FD_supported", "LIN_supported",
+        "KLine_supported", "ISO_TP_supported", "Wifi_supported",
+        "Ethernet_supported", "USB_supported", "CAN_channel_num",
+        "LIN_channel_num", "KLine_channel_num",
+    )]
+
+
+class Parameter(Packed):
+    _fields_ = [("ID", U8), ("Data", U8 * 32), ("Len", U8)]
+
+
+class TxControl(Packed):
+    _fields_ = [("TxHandle", U16), ("MaxTry", U8), ("MinGap", U8), ("Result", U16)]
+
+
+class ClassicMessage(Packed):
+    _fields_ = [
+        ("MsgType", U8), ("MsgFlag", U8), ("Bus", U8), ("ID", U32),
+        ("DLC", U8), ("Data", U8 * 8), ("Timestamp", U8 * 6),
+        ("TXCtrl", TxControl),
+    ]
+
+
+class FDMessage(Packed):
+    _fields_ = [
+        ("MsgType", U8), ("MsgFlag", U8), ("Bus", U8), ("ID", U32),
+        ("DLC", U8), ("Timestamp", U8 * 6), ("TXCtrl", TxControl),
+        ("Data", U8 * 64),
+    ]
+
+
+class Controller(Packed):
+    _fields_ = [
+        ("CANMode", U8), ("Baudrate", U32), ("SJW", U8), ("BS1", U8),
+        ("BS2", U8), ("Option", U8),
+    ]
+
+
+class FDController(Packed):
+    _fields_ = [
+        ("CANMode", U8), ("NomBaudrate", U32), ("NomSJW", U8),
+        ("NomBS1", U16), ("NomBS2", U8), ("DataBaudrate", U32),
+        ("DataSJW", U8), ("DataBS1", U8), ("DataBS2", U8),
+        ("FrameMode", U8), ("ResistorEnable", U8), ("ISOModeEnable", U8),
+        ("CANTPEnable", U8),
+    ]
+
+
+class InitHW(Packed):
+    _fields_ = [("Inited", U8), ("Timestamp", U8 * 6)]
+
+
+class Filter(Packed):
+    _fields_ = [
+        ("Index", U8), ("Active", U8), ("FilterType", U8),
+        ("ID", U32), ("Mask", U32),
+    ]
+
+
+ABI_TYPES = {
+    "YXConnection": Connection, "YXDeviceInfo": DeviceInfo, "YXCapacity": Capacity,
+    "YXParameter": Parameter, "YXCANMsgTxControl": TxControl,
+    "YXCANMsg": ClassicMessage, "YXCANFDMsg": FDMessage,
+    "YXCANController": Controller, "YXCANFDController": FDController,
+    "YXCANInitHW": InitHW, "YXCANFilter": Filter,
+}
+
+
+class Native:
+    def __init__(self, path: str):
+        self.path = path
+        self._dll_dirs = []
+        try:
+            if sys.platform == "win32":
+                if Path(path).is_file():
+                    self._dll_dirs.append(os.add_dll_directory(str(Path(path).resolve().parent)))
+                for directory in os.environ.get("CANPAL_DEPENDENCY_DIRS", "").split(os.pathsep):
+                    if directory:
+                        self._dll_dirs.append(os.add_dll_directory(str(Path(directory).resolve())))
+                self.lib = C.WinDLL(path)
+            else:
+                self.lib = C.CDLL(path)
+            self._bind("YX_Open", HANDLE, P(Connection))
+            self._bind("YX_Close", None, HANDLE)
+            self._bind("YX_Online", C.c_bool, HANDLE)
+            self._bind("YX_GetDeviceInfo", C.c_bool, HANDLE, P(DeviceInfo))
+            self._bind("YX_GetCapacity", C.c_bool, U32, P(Capacity))
+            self._bind("YX_SetParameter", U32, HANDLE, P(Parameter))
+            self._bind("YX_GetParameter", U32, HANDLE, P(Parameter))
+            self._bind("YXCAN_Initialize", U32, HANDLE, U8, P(InitHW))
+            self._bind("YXCAN_Uninitialize", U32, HANDLE, U8)
+            for suffix, message, controller in (
+                ("", ClassicMessage, Controller), ("FD", FDMessage, FDController),
+            ):
+                self._bind("YXCAN_Send" + suffix, C.c_bool, HANDLE, P(message))
+                self._bind("YXCAN_Receive" + suffix, C.c_bool, HANDLE, P(message), U32)
+                self._bind("YXCAN_SetController" + suffix, U32, HANDLE, U8, P(controller))
+                self._bind("YXCAN_GetController" + suffix, U32, HANDLE, U8, P(controller))
+            self._bind("YXCAN_SetFilter", U32, HANDLE, U8, P(Filter))
+            self._bind("YXCAN_GetFilter", U32, HANDLE, U8, P(Filter))
+        except (OSError, AttributeError) as exc:
+            for directory in self._dll_dirs:
+                directory.close()
+            raise CanInterfaceNotImplementedError(
+                f"Cannot load CANPAL library {path!r}: {exc}"
+            ) from exc
+
+    def _bind(self, name, restype, *argtypes):
+        function = getattr(self.lib, name)
+        function.restype = restype
+        function.argtypes = list(argtypes)
+        setattr(self, name, function)
+
+
+_load_lock = threading.Lock()
+_loaded: Native | None = None
+
+
+def load_library(path=None) -> Native:
+    global _loaded
+    if (struct.calcsize("P") != 8 or sys.platform not in ("win32", "linux")
+            or platform.machine().lower() not in ("amd64", "x86_64")):
+        raise CanInterfaceNotImplementedError("CANPAL requires x86-64 Windows or Linux")
+    candidate = path or os.environ.get("CANPAL_LIBRARY")
+    if candidate:
+        try:
+            candidate = str(Path(candidate).expanduser().resolve(strict=True))
+        except OSError as exc:
+            raise CanInterfaceNotImplementedError(f"CANPAL library does not exist: {candidate}") from exc
+    else:
+        candidate = ctypes.util.find_library("CANPAL")
+        if not candidate:
+            raise CanInterfaceNotImplementedError(
+                "Set library_path or CANPAL_LIBRARY to the installed CANPAL DLL/SO"
+            )
+    with _load_lock:
+        if _loaded is not None:
+            if os.path.normcase(_loaded.path) != os.path.normcase(candidate):
+                raise CanInterfaceNotImplementedError(
+                    "A different CANPAL SDK is already loaded in this process"
+                )
+            return _loaded
+        _loaded = Native(candidate)
+        return _loaded

python_can_canpal-0.1.0rc1.dist-info/METADATA

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: python-can-canpal
+Version: 0.1.0rc1
+Summary: CANPAL USB and TCP backend for python-can
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: System :: Hardware :: Hardware Drivers
+Requires-Python: <3.13,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-can==4.6.1
+Requires-Dist: pyserial==3.5
+Provides-Extra: test
+Requires-Dist: pytest<10,>=8; extra == "test"
+Requires-Dist: build<2,>=1; extra == "test"
+Requires-Dist: twine<8,>=6; extra == "test"
+Dynamic: license-file
+
+# python-can-canpal
+
+CANPAL USB and TCP client backend for [python-can](https://python-can.readthedocs.io/).
+
+**0.1.0rc1 is an experimental preview. Full hardware release acceptance is incomplete.**
+Use it for evaluation on an isolated test bench. It is not the qualified 0.1.0 release.
+
+## Install
+
+Requires Python 3.12, python-can 4.6.1, pySerial 3.5, and a separately supplied
+64-bit CANPAL native SDK with the fixes described below.
+
+```text
+python -m pip install python-can-canpal==0.1.0rc1
+```
+
+The Python package does **not** include the CANPAL SDK, firmware, device drivers,
+Qt/MinGW runtime, or fake binaries. Obtain compatible native components from your
+CANPAL supplier before attempting hardware access. The MIT license applies to
+the new Python plugin, tests and documentation; native components have separate licenses.
+
+## What has been verified
+
+| Environment | Preview evidence |
+| --- | --- |
+| Windows 11 x64 | X5 classic CAN/RTR and X6 classic CAN/RTR/ISO FD over USB and explicit-IP WLAN TCP |
+| Windows, multiple devices | Short concurrent checks: two USB devices, X5 USB + X6 WLAN, X5 WLAN + X6 USB |
+| Ubuntu 24.04 x86_64 in Hyper-V | Software, ABI and real SDK regressions; X5/X6 hardware checks through temporary SSH TCP forwarding via a Windows WLAN connection |
+
+Both devices had CAN1 wired to their own CAN2 on separate physical buses.
+These checks do not use an independent reference CAN interface. Classic checks
+covered standard/extended frames and RTR DLC 0–8 in both directions. X6 FD checks
+covered lengths 0–64 and BRS off/on. The post-fix checks verified 5,280 frames in total.
+
+**Not yet qualified:** independent-reference CAN/CAN FD interoperability, native
+Linux USB or direct Linux WLAN, two simultaneous WLAN devices, controlled physical
+port renumbering/disconnection, rated-load/endurance runs, and native resource
+stability. Fake tests cover additional error paths but do not establish those hardware claims.
+Formal 0.1.0 retains the complete release acceptance requirements.
+
+## Native SDK and firmware requirements
+
+The tested SDK source revision is `e222ccf48f29c530fd09617df6e3a83a8095d25f`.
+It includes command ACK matching, cooperative worker shutdown and a Qt serial
+buffered-read fix. Matching exported function names alone does not establish compatibility.
+
+Classic RTR also requires firmware that preserves the received DLC. The original
+X5 firmware reporting `0x0332` and X6 firmware reporting `0x0127` cleared RTR DLC
+to zero. Supplier-signed diagnostic builds fixed this on the two test devices.
+Those builds still report the same version numbers: ask your supplier to identify
+the actual fixed build. The plugin cannot recover DLC that firmware has discarded.
+
+Set `CANPAL_LIBRARY` to the absolute DLL/SO path, or pass `library_path`.
+On Windows, `CANPAL_DEPENDENCY_DIRS` may list Qt/MinGW runtime directories,
+separated by semicolons. On Linux, install the matching Qt 5 runtime and grant
+serial-port access through udev or the dialout group.
+
+## Connect by UID or IP
+
+```python
+import can
+
+with can.Bus(interface="canpal", ignore_config=True,
+             transport="usb", device_id="YOUR_24_HEX_DIGIT_UID",
+             channel=0, bitrate=500_000) as bus:
+    message = bus.recv(timeout=1)
+```
+
+The device UID remains the selector when a COM/ttyACM number changes. After a
+reconnection, close and recreate the Bus using the same UID; automatic reconnect
+is not implemented. Physical port renumbering acceptance is still pending.
+
+Use `transport="wlan", host="192.0.2.10", port=8000` for TCP direct connection.
+The IP and port must match the actual device; no network discovery is attempted.
+Keep `device_id` to verify identity at that endpoint. X6 CAN FD additionally uses
+`fd=True, data_bitrate=2_000_000`.
+
+Different physical devices use independent Bus objects. A device can have one
+Bus and one selected CAN channel at a time. Use one Notifier per device for
+independent fault handling. UDP, server mode, transmit echo and concurrent
+channels on one device are not implemented.
+
+A successful `send()` means the native queue accepted the frame, not that the
+CAN bus acknowledged it. Use a single receiver per Bus, stop its Notifier before
+shutdown, and handle python-can exceptions. Timestamp alignment is approximate
+per device and does not provide precise synchronization between devices.
+
+The source distribution includes Chinese installation, testing and release notes.

python_can_canpal-0.1.0rc1.dist-info/RECORD

@@ -0,0 +1,11 @@
+canpal/__init__.py,sha256=ma9PXNvzG0PuVnfsA_VgWV0fEqEnjENeKocNVhpjGQ0,247
+canpal/bus.py,sha256=qvbEPcj6JHpb9CSuWfOmXwSyc-7qfgaAJ6GL_CLkSUM,15772
+canpal/codec.py,sha256=6Ca234uYrnLZnvHHss4zmTg9IGMsdlsJlNGPe6mjDFw,4991
+canpal/discovery.py,sha256=UNx9Eaem9p-33Na_YwKUDOF-k2bIkpLlX2Ob6UiMWgU,2620
+canpal/native.py,sha256=C5FyVPf5x3TjTFduRuaYYD1TFFDj84eqfzX0j0T0Ftk,6626
+python_can_canpal-0.1.0rc1.dist-info/licenses/LICENSE,sha256=kEiYDR3fINcxYdg12ab44v0EmiP5ktgYtNML_-LllSE,1309
+python_can_canpal-0.1.0rc1.dist-info/METADATA,sha256=XZ2l8PEDgaK6awzUTj3zP9FlSpQzUL8M-l_PfTVjUk4,5276
+python_can_canpal-0.1.0rc1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+python_can_canpal-0.1.0rc1.dist-info/entry_points.txt,sha256=U9E74XVtECBGl6VUWoQpI_2tBmb2lkOBRJ048FCQCeM,46
+python_can_canpal-0.1.0rc1.dist-info/top_level.txt,sha256=WsJHmkaVmRho9-7_TQ3I8BwrHsYL4HT9C0H2d1bsFXQ,7
+python_can_canpal-0.1.0rc1.dist-info/RECORD,,

python_can_canpal-0.1.0rc1.dist-info/WHEEL

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

python_can_canpal-0.1.0rc1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[can.interface]
+canpal = canpal.bus:CanpalBus

python_can_canpal-0.1.0rc1.dist-info/licenses/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 Python CANPAL contributors
+
+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.
+
+This license applies to the newly developed PythonCAN plugin, test harness,
+and documentation. The separately supplied CANPAL SDK, its headers, firmware,
+Qt, and other third-party components retain their respective licenses.

python_can_canpal-0.1.0rc1.dist-info/top_level.txt

@@ -0,0 +1 @@
+canpal