pyxcp 0.23.0__cp313-cp313-win_arm64.whl

pyxcp/tests/test_transport.py

@@ -0,0 +1,81 @@
+from unittest import mock
+
+import pytest
+
+import pyxcp.transport.base as tr
+
+
+def create_config():
+    # Exception: XCPonEth - Failed to resolve address <MagicMock name='mock.transport.eth.host' id='2414047113872'>:<MagicMock name='mock.transport.eth.port' id='2414047478992'>
+    config = mock.MagicMock()
+    config.general.return_value = mock.MagicMock()
+    config.transport.return_value = mock.MagicMock()
+    config.transport.eth.return_value = mock.MagicMock()
+    config.transport.eth.host = "localhost"
+    config.transport.eth.port = 5555
+    config.transport.eth.bind_to_address = ""
+    config.transport.eth.bind_to_port = 0
+    config.transport.create_daq_timestamps = False
+    return config
+
+
+def test_factory_works():
+    config = create_config()
+    assert isinstance(tr.create_transport("eth", config=config), tr.BaseTransport)
+    assert isinstance(tr.create_transport("sxi", config=config), tr.BaseTransport)
+    assert isinstance(
+        tr.create_transport(
+            "can",
+            config={
+                "CAN_ID_MASTER": 1,
+                "CAN_ID_SLAVE": 2,
+                "CAN_DRIVER": "MockCanInterface",
+            },
+        ),
+        tr.BaseTransport,
+    )
+
+
+def test_factory_works_case_insensitive():
+    assert isinstance(tr.create_transport("ETH"), tr.BaseTransport)
+    assert isinstance(tr.create_transport("SXI"), tr.BaseTransport)
+    assert isinstance(
+        tr.create_transport(
+            "CAN",
+            config={
+                "CAN_ID_MASTER": 1,
+                "CAN_ID_SLAVE": 2,
+                "CAN_DRIVER": "MockCanInterface",
+            },
+        ),
+        tr.BaseTransport,
+    )
+
+
+def test_factory_invalid_transport_name_raises():
+    with pytest.raises(ValueError):
+        tr.create_transport("xCp")
+
+
+def test_transport_names():
+    transports = tr.available_transports()
+
+    assert "can" in transports
+    assert "eth" in transports
+    assert "sxi" in transports
+
+
+def test_transport_names_are_lower_case_only():
+    transports = tr.available_transports()
+
+    assert "CAN" not in transports
+    assert "ETH" not in transports
+    assert "SXI" not in transports
+
+
+def test_transport_classes():
+    transports = tr.available_transports()
+
+    assert issubclass(transports.get("can"), tr.BaseTransport)
+    assert issubclass(transports.get("eth"), tr.BaseTransport)
+    assert issubclass(transports.get("sxi"), tr.BaseTransport)

pyxcp/tests/test_utils.py

@@ -0,0 +1,30 @@
+from sys import version_info
+
+from pyxcp.utils import PYTHON_VERSION, flatten, getPythonVersion, hexDump, slicer
+
+
+def test_hexdump(capsys):
+    print(hexDump(range(16)), end="")
+    captured = capsys.readouterr()
+    assert captured.out == "[00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f]"
+
+
+def test_slicer1():
+    res = slicer([1, 2, 3, 4, 5, 6, 7, 8], 4)
+    assert res == [[1, 2, 3, 4], [5, 6, 7, 8]]
+
+
+def test_slicer2():
+    res = slicer(["10", "20", "30", "40", "50", "60", "70", "80"], 4, tuple)
+    assert res == [("10", "20", "30", "40"), ("50", "60", "70", "80")]
+
+
+def test_flatten1():
+    res = flatten([[1, 2, 3, 4], [5, 6, 7, 8]])
+    assert res == [1, 2, 3, 4, 5, 6, 7, 8]
+
+
+def test_version():
+    assert getPythonVersion() == version_info
+    assert PYTHON_VERSION == version_info
+    assert getPythonVersion() == PYTHON_VERSION

pyxcp/timing.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python
+import time
+
+
+class Timing:
+    T_US = 1000 * 1000
+    T_MS = 1000
+    T_S = 1
+
+    UNIT_MAP = {
+        T_US: "uS",
+        T_MS: "mS",
+        T_S: "S",
+    }
+    FMT = "min:  {0:2.3f} {4}\nmax:  {1:2.3f} {4}\n" "avg:  {2:2.3f} {4}\nlast: {3:2.3f} {4}"
+
+    def __init__(self, unit=T_MS, record=False):
+        self.min = None
+        self.max = None
+        self.avg = None
+        self._previous = None
+        self.unit = unit
+        self._record = record
+        self._values = []
+
+    def start(self):
+        self._start = time.perf_counter()
+
+    def stop(self):
+        self._stop = time.perf_counter()
+        elapsed = self._stop - self._start
+        if self._record:
+            self._values.append(elapsed)
+        if self._previous:
+            self.min = min(self._previous, elapsed)
+            self.max = max(self._previous, elapsed)
+            self.avg = (self._previous + elapsed) / 2
+        else:
+            self.min = self.max = self.avg = elapsed
+        self._previous = elapsed
+
+    def __str__(self):
+        unitName = Timing.UNIT_MAP.get(self.unit, "??")
+        self.min = 0 if self.min is None else self.min
+        self.max = 0 if self.max is None else self.max
+        self.avg = 0 if self.avg is None else self.avg
+        self._previous = 0 if self._previous is None else self._previous
+        return Timing.FMT.format(
+            self.min * self.unit,
+            self.max * self.unit,
+            self.avg * self.unit,
+            self._previous * self.unit,
+            unitName,
+        )
+
+    __repr__ = __str__
+
+    @property
+    def values(self):
+        return self._values

pyxcp/transport/__init__.py

@@ -0,0 +1,10 @@
+#!/usr/bin/env python
+from .base import FrameAcquisitionPolicy  # noqa: F401
+from .base import FrameRecorderPolicy  # noqa: F401
+from .base import LegacyFrameAcquisitionPolicy  # noqa: F401
+from .base import NoOpPolicy  # noqa: F401
+from .base import StdoutPolicy  # noqa: F401
+from .can import Can  # noqa: F401
+from .eth import Eth  # noqa: F401
+from .sxi import SxI  # noqa: F401
+from .usb_transport import Usb  # noqa: F401

pyxcp/transport/base.py

@@ -0,0 +1,440 @@
+#!/usr/bin/env python
+import abc
+import logging
+import threading
+from collections import deque
+from typing import Any, Dict, Optional, Set, Type
+
+import pyxcp.types as types
+from pyxcp.cpp_ext.cpp_ext import Timestamp, TimestampType
+from pyxcp.recorder import XcpLogFileWriter
+from pyxcp.timing import Timing
+from pyxcp.utils import (
+    CurrentDatetime,
+    flatten,
+    hexDump,
+    seconds_to_nanoseconds,
+    short_sleep,
+)
+
+
+class FrameAcquisitionPolicy:
+    """
+    Base class for all frame acquisition policies.
+
+    Parameters
+    ---------
+    filter_out: set or None
+        A set of frame types to filter out.
+        If None, all frame types are accepted for further processing.
+
+        Example: (FrameType.REQUEST, FrameType.RESPONSE, FrameType.EVENT, FrameType.SERV)
+                  ==> care only about DAQ frames.
+    """
+
+    def __init__(self, filter_out: Optional[Set[types.FrameCategory]] = None):
+        self._frame_types_to_filter_out = filter_out or set()
+
+    @property
+    def filtered_out(self) -> Set[types.FrameCategory]:
+        return self._frame_types_to_filter_out
+
+    def feed(self, frame_type: types.FrameCategory, counter: int, timestamp: int, payload: bytes) -> None: ...  # noqa: E704
+
+    def finalize(self) -> None:
+        """
+        Finalize the frame acquisition policy (if required).
+        """
+        ...
+
+
+class NoOpPolicy(FrameAcquisitionPolicy):
+    """
+    No operation / do nothing policy.
+    """
+
+
+class LegacyFrameAcquisitionPolicy(FrameAcquisitionPolicy):
+    """Dequeue based frame acquisition policy.
+
+    Deprecated: Use only for compatibility reasons.
+    """
+
+    def __init__(self, filter_out: Optional[Set[types.FrameCategory]] = None) -> None:
+        super().__init__(filter_out)
+        self.reqQueue = deque()
+        self.resQueue = deque()
+        self.daqQueue = deque()
+        self.evQueue = deque()
+        self.servQueue = deque()
+        self.metaQueue = deque()
+        self.errorQueue = deque()
+        self.stimQueue = deque()
+        self.QUEUE_MAP = {
+            types.FrameCategory.CMD: self.reqQueue,
+            types.FrameCategory.RESPONSE: self.resQueue,
+            types.FrameCategory.EVENT: self.evQueue,
+            types.FrameCategory.SERV: self.servQueue,
+            types.FrameCategory.DAQ: self.daqQueue,
+            types.FrameCategory.METADATA: self.metaQueue,
+            types.FrameCategory.ERROR: self.errorQueue,
+            types.FrameCategory.STIM: self.stimQueue,
+        }
+
+    def feed(self, frame_type: types.FrameCategory, counter: int, timestamp: int, payload: bytes) -> None:
+        if frame_type not in self.filtered_out:
+            queue = self.QUEUE_MAP.get(frame_type)
+            if queue is not None:
+                queue.append((counter, timestamp, payload))
+
+
+class FrameRecorderPolicy(FrameAcquisitionPolicy):
+    """Frame acquisition policy that records frames."""
+
+    def __init__(
+        self,
+        file_name: str,
+        filter_out: Optional[Set[types.FrameCategory]] = None,
+        prealloc: int = 10,
+        chunk_size: int = 1,
+    ) -> None:
+        super().__init__(filter_out)
+        self.recorder = XcpLogFileWriter(file_name, prealloc=prealloc, chunk_size=chunk_size)
+
+    def feed(self, frame_type: types.FrameCategory, counter: int, timestamp: int, payload: bytes) -> None:
+        if frame_type not in self.filtered_out:
+            self.recorder.add_frame(frame_type, counter, timestamp, payload)
+
+    def finalize(self) -> None:
+        self.recorder.finalize()
+
+
+class StdoutPolicy(FrameAcquisitionPolicy):
+    """Frame acquisition policy that prints frames to stdout."""
+
+    def __init__(self, filter_out: Optional[Set[types.FrameCategory]] = None) -> None:
+        super().__init__(filter_out)
+
+    def feed(self, frame_type: types.FrameCategory, counter: int, timestamp: int, payload: bytes) -> None:
+        if frame_type not in self.filtered_out:
+            print(f"{frame_type.name:8} {counter:6}  {timestamp:8d} {hexDump(payload)}")
+
+
+class EmptyFrameError(Exception):
+    """Raised when an empty frame is received."""
+
+
+class BaseTransport(metaclass=abc.ABCMeta):
+    """Base class for transport-layers (Can, Eth, Sxi).
+
+    Parameters
+    ----------
+    config: dict-like
+        Parameters like bitrate.
+    loglevel: ["INFO", "WARN", "DEBUG", "ERROR", "CRITICAL"]
+        Controls the verbosity of log messages.
+
+    """
+
+    def __init__(self, config, policy: Optional[FrameAcquisitionPolicy] = None, transport_layer_interface: Optional[Any] = None):
+        self.has_user_supplied_interface: bool = transport_layer_interface is not None
+        self.transport_layer_interface: Optional[Any] = transport_layer_interface
+        self.parent = None
+        self.policy: FrameAcquisitionPolicy = policy or LegacyFrameAcquisitionPolicy()
+        self.closeEvent: threading.Event = threading.Event()
+
+        self.command_lock: threading.Lock = threading.Lock()
+        self.policy_lock: threading.Lock = threading.Lock()
+
+        self.logger = logging.getLogger("PyXCP")
+        self._debug: bool = self.logger.level == 10
+        if transport_layer_interface:
+            self.logger.info(f"Transport - User Supplied Transport-Layer Interface: '{transport_layer_interface!s}'")
+        self.counter_send: int = 0
+        self.counter_received: int = -1
+        self.create_daq_timestamps: bool = config.create_daq_timestamps
+        self.timestamp = Timestamp(TimestampType.ABSOLUTE_TS)
+        self._start_datetime: CurrentDatetime = CurrentDatetime(self.timestamp.initial_value)
+        self.alignment: int = config.alignment
+        self.timeout: int = seconds_to_nanoseconds(config.timeout)
+        self.timer_restart_event: threading.Event = threading.Event()
+        self.timing: Timing = Timing()
+        self.resQueue: deque = deque()
+        self.listener: threading.Thread = threading.Thread(
+            target=self.listen,
+            args=(),
+            kwargs={},
+        )
+
+        self.first_daq_timestamp: Optional[int] = None
+        # self.timestamp_origin = self.timestamp.value
+        # self.datetime_origin = datetime.fromtimestamp(self.timestamp_origin)
+        self.pre_send_timestamp: int = self.timestamp.value
+        self.post_send_timestamp: int = self.timestamp.value
+        self.recv_timestamp: int = self.timestamp.value
+
+    def __del__(self) -> None:
+        self.finish_listener()
+        self.close_connection()
+
+    def load_config(self, config) -> None:
+        """Load configuration data."""
+        class_name: str = self.__class__.__name__.lower()
+        self.config: Any = getattr(config, class_name)
+
+    def close(self) -> None:
+        """Close the transport-layer connection and event-loop."""
+        self.finish_listener()
+        if self.listener.is_alive():
+            self.listener.join()
+        self.close_connection()
+
+    @abc.abstractmethod
+    def connect(self) -> None:
+        pass
+
+    def get(self):
+        """Get an item from a deque considering a timeout condition."""
+        start: int = self.timestamp.value
+        while not self.resQueue:
+            if self.timer_restart_event.is_set():
+                start: int = self.timestamp.value
+                self.timer_restart_event.clear()
+            if self.timestamp.value - start > self.timeout:
+                raise EmptyFrameError
+            short_sleep()
+        item = self.resQueue.popleft()
+        # print("Q", item)
+        return item
+
+    @property
+    def start_datetime(self) -> int:
+        """datetime of program start.
+
+        Returns
+        -------
+        int
+        """
+        return self._start_datetime
+
+    def start_listener(self):
+        if self.listener.is_alive():
+            self.finish_listener()
+            self.listener.join()
+
+        self.listener = threading.Thread(target=self.listen)
+        self.listener.start()
+
+    def finish_listener(self):
+        if hasattr(self, "closeEvent"):
+            self.closeEvent.set()
+
+    def _request_internal(self, cmd, ignore_timeout=False, *data):
+        with self.command_lock:
+            frame = self._prepare_request(cmd, *data)
+            self.timing.start()
+            with self.policy_lock:
+                self.policy.feed(types.FrameCategory.CMD, self.counter_send, self.timestamp.value, frame)
+            self.send(frame)
+            try:
+                xcpPDU = self.get()
+            except EmptyFrameError:
+                if not ignore_timeout:
+                    MSG = f"Response timed out (timeout={self.timeout / 1_000_000_000}s)"
+                    with self.policy_lock:
+                        self.policy.feed(types.FrameCategory.METADATA, self.counter_send, self.timestamp.value, bytes(MSG, "ascii"))
+                    raise types.XcpTimeoutError(MSG) from None
+                else:
+                    self.timing.stop()
+                    return
+            self.timing.stop()
+            pid = types.Response.parse(xcpPDU).type
+            if pid == "ERR" and cmd.name != "SYNCH":
+                with self.policy_lock:
+                    self.policy.feed(types.FrameCategory.ERROR, self.counter_received, self.timestamp.value, xcpPDU[1:])
+                err = types.XcpError.parse(xcpPDU[1:])
+                raise types.XcpResponseError(err)
+            return xcpPDU[1:]
+
+    def request(self, cmd, *data):
+        return self._request_internal(cmd, False, *data)
+
+    def request_optional_response(self, cmd, *data):
+        return self._request_internal(cmd, True, *data)
+
+    def block_request(self, cmd, *data):
+        """
+        Implements packet transmission for block communication model (e.g. DOWNLOAD block mode)
+        All parameters are the same as in request(), but it does not receive response.
+        """
+
+        # check response queue before each block request, so that if the slave device
+        # has responded with a negative response (e.g. ACCESS_DENIED or SEQUENCE_ERROR), we can
+        # process it.
+        if self.resQueue:
+            xcpPDU = self.resQueue.popleft()
+            pid = types.Response.parse(xcpPDU).type
+            if pid == "ERR" and cmd.name != "SYNCH":
+                err = types.XcpError.parse(xcpPDU[1:])
+                raise types.XcpResponseError(err)
+        with self.command_lock:
+            if isinstance(data, list):
+                data = data[0]  # C++ interfacing.
+            frame = self._prepare_request(cmd, *data)
+            with self.policy_lock:
+                self.policy.feed(
+                    types.FrameCategory.CMD if int(cmd) >= 0xC0 else types.FrameCategory.STIM,
+                    self.counter_send,
+                    self.timestamp.value,
+                    frame,
+                )
+            self.send(frame)
+
+    def _prepare_request(self, cmd, *data):
+        """
+        Prepares a request to be sent
+        """
+        if self._debug:
+            self.logger.debug(cmd.name)
+        self.parent._setService(cmd)
+
+        cmd_len = cmd.bit_length() // 8  # calculate bytes needed for cmd
+        packet = bytes(flatten(cmd.to_bytes(cmd_len, "big"), data))
+
+        header = self.HEADER.pack(len(packet), self.counter_send)
+        self.counter_send = (self.counter_send + 1) & 0xFFFF
+
+        frame = header + packet
+
+        remainder = len(frame) % self.alignment
+        if remainder:
+            frame += b"\0" * (self.alignment - remainder)
+
+        if self._debug:
+            self.logger.debug(f"-> {hexDump(frame)}")
+        return frame
+
+    def block_receive(self, length_required: int) -> bytes:
+        """
+        Implements packet reception for block communication model
+        (e.g. for XCP on CAN)
+
+        Parameters
+        ----------
+        length_required: int
+            number of bytes to be expected in block response packets
+
+        Returns
+        -------
+        bytes
+            all payload bytes received in block response packets
+
+        Raises
+        ------
+        :class:`pyxcp.types.XcpTimeoutError`
+        """
+        block_response = b""
+        start = self.timestamp.value
+        while len(block_response) < length_required:
+            if len(self.resQueue):
+                partial_response = self.resQueue.popleft()
+                block_response += partial_response[1:]
+            else:
+                if self.timestamp.value - start > self.timeout:
+                    raise types.XcpTimeoutError("Response timed out [block_receive].") from None
+                short_sleep()
+        return block_response
+
+    @abc.abstractmethod
+    def send(self, frame):
+        pass
+
+    @abc.abstractmethod
+    def close_connection(self):
+        """Does the actual connection shutdown.
+        Needs to be implemented by any sub-class.
+        """
+        pass
+
+    @abc.abstractmethod
+    def listen(self):
+        pass
+
+    def process_event_packet(self, packet):
+        packet = packet[1:]
+        ev_type = packet[0]
+        self.logger.debug(f"EVENT-PACKET: {hexDump(packet)}")
+        if ev_type == types.Event.EV_CMD_PENDING:
+            self.timer_restart_event.set()
+
+    def process_response(self, response: bytes, length: int, counter: int, recv_timestamp: int) -> None:
+        if counter == self.counter_received:
+            self.logger.warning(f"Duplicate message counter {counter} received from the XCP slave")
+            if self._debug:
+                self.logger.debug(f"<- L{length} C{counter} {hexDump(response[:512])}")
+            return
+        self.counter_received = counter
+        pid = response[0]
+        if pid >= 0xFC:
+            if self._debug:
+                self.logger.debug(f"<- L{length} C{counter} {hexDump(response)}")
+            if pid >= 0xFE:
+                self.resQueue.append(response)
+                with self.policy_lock:
+                    self.policy.feed(types.FrameCategory.RESPONSE, self.counter_received, self.timestamp.value, response)
+                self.recv_timestamp = recv_timestamp
+            elif pid == 0xFD:
+                self.process_event_packet(response)
+                with self.policy_lock:
+                    self.policy.feed(types.FrameCategory.EVENT, self.counter_received, self.timestamp.value, response)
+            elif pid == 0xFC:
+                with self.policy_lock:
+                    self.policy.feed(types.FrameCategory.SERV, self.counter_received, self.timestamp.value, response)
+        else:
+            if self._debug:
+                self.logger.debug(f"<- L{length} C{counter} ODT_Data[0:8] {hexDump(response[:8])}")
+            if self.first_daq_timestamp is None:
+                self.first_daq_timestamp = recv_timestamp
+            if self.create_daq_timestamps:
+                timestamp = recv_timestamp
+            else:
+                timestamp = 0
+            with self.policy_lock:
+                self.policy.feed(types.FrameCategory.DAQ, self.counter_received, timestamp, response)
+
+    # @abc.abstractproperty
+    # @property
+    # def transport_layer_interface(self) -> Any:
+    #    pass
+
+    # @transport_layer_interface.setter
+    # def transport_layer_interface(self, value: Any) -> None:
+    #    self._transport_layer_interface = value
+
+
+def create_transport(name: str, *args, **kws) -> BaseTransport:
+    """Factory function for transports.
+
+    Returns
+    -------
+    :class:`BaseTransport` derived instance.
+    """
+    name = name.lower()
+    transports = available_transports()
+    if name in transports:
+        transport_class: Type[BaseTransport] = transports[name]
+    else:
+        raise ValueError(f"{name!r} is an invalid transport -- please choose one of [{' | '.join(transports.keys())}].")
+    return transport_class(*args, **kws)
+
+
+def available_transports() -> Dict[str, Type[BaseTransport]]:
+    """List all subclasses of :class:`BaseTransport`.
+
+    Returns
+    -------
+    dict
+        name: class
+    """
+    transports = BaseTransport.__subclasses__()
+    return {t.__name__.lower(): t for t in transports}