pyxcp 0.25.4__cp313-cp313-win_amd64.whl

pyxcp/utils/__init__.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python
+import datetime
+import functools
+import operator
+import sys
+from binascii import hexlify
+from enum import IntEnum
+from time import perf_counter, sleep
+from typing import Union
+
+import chardet
+import pytz
+
+from pyxcp.cpp_ext.cpp_ext import TimestampInfo
+
+
+def hexDump(arr: Union[bytes | bytearray]):
+    if isinstance(arr, (bytes, bytearray)):
+        size = len(arr)
+        try:
+            arr = arr.hex()
+        except BaseException:  # noqa: B036
+            arr = hexlify(arr).decode("ascii")
+        return "[{}]".format(" ".join([arr[i * 2 : (i + 1) * 2] for i in range(size)]))
+    elif isinstance(arr, (list, tuple)):
+        arr = bytes(arr)
+        size = len(arr)
+        try:
+            arr = arr.hex()
+        except BaseException:  # noqa: B036
+            arr = hexlify(arr).decode("ascii")
+        return "[{}]".format(" ".join([arr[i * 2 : (i + 1) * 2] for i in range(size)]))
+    else:
+        return "[{}]".format(" ".join([f"{x:02x}" for x in arr]))
+
+
+def seconds_to_nanoseconds(value: float) -> int:
+    return int(value * 1_000_000_000)
+
+
+def slicer(iterable, sliceLength, converter=None):
+    if converter is None:
+        converter = type(iterable)
+    length = len(iterable)
+    return [converter(iterable[item : item + sliceLength]) for item in range(0, length, sliceLength)]
+
+
+def functools_reduce_iconcat(a):
+    return functools.reduce(operator.iconcat, a, [])
+
+
+def flatten(*args):
+    """Flatten a list of lists into a single list.
+
+    s. https://stackoverflow.com/questions/952914/how-do-i-make-a-flat-list-out-of-a-list-of-lists
+    """
+    return functools.reduce(operator.iconcat, args, [])
+
+
+def getPythonVersion():
+    return sys.version_info
+
+
+def decode_bytes(byte_str: bytes) -> str:
+    """Decode bytes with the help of chardet"""
+    encoding = chardet.detect(byte_str).get("encoding")
+    if not encoding:
+        return byte_str.decode("ascii", "ignore")
+    else:
+        return byte_str.decode(encoding)
+
+
+PYTHON_VERSION = getPythonVersion()
+
+
+def short_sleep():
+    sleep(0.0005)
+
+
+def delay(amount: float):
+    """Performe a busy-wait delay, which is much more precise than `time.sleep`"""
+
+    start = perf_counter()
+    while perf_counter() < start + amount:
+        pass
+
+
+class CurrentDatetime(TimestampInfo):
+    def __init__(self, timestamp_ns: int):
+        TimestampInfo.__init__(self, timestamp_ns)
+        timezone = pytz.timezone(self.timezone)
+        dt = datetime.datetime.fromtimestamp(timestamp_ns / 1_000_000_000.0)
+        self.utc_offset = int(timezone.utcoffset(dt).total_seconds() / 60)
+        self.dst_offset = int(timezone.dst(dt).total_seconds() / 60)
+
+    def __str__(self):
+        return f"""CurrentDatetime(
+    datetime="{datetime.datetime.fromtimestamp(self.timestamp_ns / 1_000_000_000.0)!s}",
+    timezone="{self.timezone}",
+    timestamp_ns={self.timestamp_ns},
+    utc_offset={self.utc_offset},
+    dst_offset={self.dst_offset}
+)"""
+
+
+def enum_from_str(enum_class: IntEnum, enumerator: str) -> IntEnum:
+    """Create an `IntEnum` instance from an enumerator `str`.
+
+    Parameters
+    ----------
+    enum_class: IntEnum
+
+    enumerator: str
+
+    Examples
+    --------
+
+    class Color(enum.IntEnum):
+        RED = 0
+        GREEN = 1
+        BLUE = 2
+
+    color: Color = enum_from_str(Color, "GREEN")
+
+
+    """
+    return enum_class(enum_class.__members__.get(enumerator))

pyxcp/utils/cli.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python
+"""
+Reusable command-line parser utilities.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+
+class StrippingParser:
+    """Base class for parsers that can strip recognized arguments from sys.argv.
+
+    This is useful when multiple argument parsers are used in a single process (chained),
+    and downstream parsers should not see arguments already handled by an
+    upstream parser.
+    """
+
+    def __init__(self, parser: argparse.ArgumentParser) -> None:
+        """Initialize with an existing ArgumentParser instance."""
+        self._parser = parser
+
+    @property
+    def parser(self) -> argparse.ArgumentParser:
+        """Return the underlying ArgumentParser instance."""
+        return self._parser
+
+    def parse_known(self, argv: Sequence[str] | None = None) -> tuple[argparse.Namespace, list[str]]:
+        """Parse known args from ``argv`` and return (namespace, remaining).
+
+        Does not mutate ``sys.argv``.
+        """
+        if argv is None:
+            argv = sys.argv[1:]
+        namespace, remaining = self._parser.parse_known_args(argv)
+
+        # Emulate standard -h/--help behavior if "help" is in the namespace
+        if getattr(namespace, "help", False):
+            # Print help and exit similarly to ArgumentParser
+            # We need a temporary full parser to render standard help including program name
+            full = argparse.ArgumentParser(description=self._parser.description)
+            for action in self._parser._actions:
+                if action.option_strings and action.dest == "help":
+                    continue
+                full._add_action(action)
+            full.print_help()
+            sys.exit(0)
+
+        return namespace, list(remaining)
+
+    def strip_from_argv(self, argv: list[str] | None = None) -> None:
+        """Remove this parser's recognized options from ``sys.argv`` in-place.
+
+        If ``argv`` is provided, it is treated as a mutable list whose content
+        will be replaced with the stripped version (first element preserved as
+        program name). If omitted, ``sys.argv`` is modified.
+        """
+        arg_list = argv if argv is not None else sys.argv
+        if not arg_list:
+            return
+        _, remaining = self.parse_known(arg_list[1:])
+        # Rebuild argv with program name + remaining
+        prog = arg_list[0]
+        arg_list[:] = [prog] + remaining
+
+    def parse_and_strip(self, argv: list[str] | None = None) -> argparse.Namespace:
+        """Parse options and strip them from argv; returns the parsed namespace."""
+        arg_list = argv if argv is not None else sys.argv
+        if not arg_list:
+            # Fallback for empty list
+            return self.parse_known([])[0]
+        namespace, remaining = self.parse_known(arg_list[1:])
+        # mutate
+        prog = arg_list[0]
+        arg_list[:] = [prog] + remaining
+        return namespace

pyxcp/vector/map.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python
+
+MAP_NAMES = {
+    1: "BorlandC 16 Bit",
+    2: "M166",
+    3: "Watcom",
+    4: "HiTech HC05",
+    6: "IEEE",
+    7: "Cosmic",
+    8: "SDS",
+    9: "Fujitsu Softune 1(.mp1)",
+    10: "GNU",
+    11: "Keil 16x",
+    12: "BorlandC 32 Bit",
+    13: "Keil 16x (static)",
+    14: "Keil 8051",
+    15: "ISI",
+    16: "Hiware HC12",
+    17: "TI TMS470",
+    18: "Archimedes",
+    19: "COFF",
+    20: "IAR",
+    21: "VisualDSP",
+    22: "GNU 16x",
+    23: "GNU VxWorks",
+    24: "GNU 68k",
+    25: "DiabData",
+    26: "VisualDSP DOS",
+    27: "HEW SH7055",
+    28: "Metrowerks",
+    29: "Microsoft standard",
+    30: "ELF/DWARF 16 Bit",
+    31: "ELF/DWARF 32 Bit",
+    32: "Fujitsu Softune 3..8(.mps)",
+    33: "Microware Hawk",
+    34: "TI C6711",
+    35: "Hitachi H8S",
+    36: "IAR HC12",
+    37: "Greenhill Multi 2000",
+    38: "LN308(MITSUBISHI) for M16C/80",
+    39: "COFF settings auto detected",
+    40: "NEC CC78K/0 v35",
+    41: "Microsoft extended",
+    42: "ICCAVR",
+    43: "Omf96 (.m96)",
+    44: "COFF/DWARF",
+    45: "OMF96 Binary (Tasking C196)",
+    46: "OMF166 Binary (Keil C166)",
+    47: "Microware Hawk Plug&Play ASCII",
+    48: "UBROF Binary (IAR)",
+    49: "Renesas M32R/M32192 ASCII",
+    50: "OMF251 Binary (Keil C251)",
+    51: "Microsoft standard VC8",
+    52: "Microsoft VC8 Release Build (MATLAB DLL)",
+    53: "Microsoft VC8 Debug Build (MATLAB DLL)",
+    54: "Microsoft VC8 Debug file (pdb)",
+}
+
+"""
+3.0  Automatic detection sequence
+
+-  The master (CANape) sends the command GET_ID with the idType = 219 (0xDB hex) to the ECU
+-  The ECU sets the MTA (memory transfer address) pointer to the first byte of the data block containing the
+MAP file identification and returns the number of bytes which need to be uploaded to the master as well as
+the counter which defines the appropriate memory segment
+-  The master requests the specified number of bytes from the ECU by sending UPLOAD commands
+-  The master looks for the appropriate MAP file in the MAP file directory and updates the addresses in the
+a2l file accordingly
+
+Command sequence GET_ID
+
+Id of the MAP format
+
+Counter
+
+MAP name
+
+"""
+
+
+def mapfile_name(name, counter, fmt):
+    return f"{fmt:2d}{counter:d}{name:s}.map"

pyxcp-0.25.4.dist-info/METADATA

@@ -0,0 +1,341 @@
+Metadata-Version: 2.4
+Name: pyxcp
+Version: 0.25.4
+Summary: Universal Calibration Protocol for Python
+License: LGPLv3
+License-File: LICENSE
+Keywords: automotive,ecu,xcp,asam,autosar
+Author: Christoph Schueler
+Author-email: cpu.gems@googlemail.com
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development
+Requires-Dist: bandit (>=1.7.8,<2.0.0)
+Requires-Dist: chardet (>=5.2.0,<6.0.0)
+Requires-Dist: construct (>=2.10.68,<3.0.0)
+Requires-Dist: line-profiler-pycharm (>=1.1.0,<2.0.0)
+Requires-Dist: mako (>=1.2.4,<2.0.0)
+Requires-Dist: pydantic (>=2.5,<3)
+Requires-Dist: pyserial (>=3.5,<4.0)
+Requires-Dist: python-can (>=4.2.2,<5.0.0)
+Requires-Dist: pytz (>=2025.2,<2026.0)
+Requires-Dist: pyusb (>=1.2.1,<2.0.0)
+Requires-Dist: rich (>=14.0.0,<15.0.0)
+Requires-Dist: toml (>=0.10.2,<0.11.0)
+Requires-Dist: tomlkit (>=0.13.3,<0.14.0)
+Requires-Dist: traitlets (<=5.11.2)
+Requires-Dist: uptime (>=3.0.1,<4.0.0)
+Project-URL: Homepage, https://github.com/christoph2/pyxcp
+Description-Content-Type: text/x-rst
+
+Readme
+======
+
+.. image:: pyxcp_social.svg
+    :align: center
+
+Reliable Python tooling for the ASAM MCD-1 XCP protocol (measurement,
+calibration, flashing) with multiple transports (CAN, Ethernet, USB,
+Serial) and handy CLI utilities.
+
+|PyPI| |Python Versions| |License: LGPL v3+| |Code style: black|
+
+``pyXCP`` is a production-ready Python library for communicating with
+XCP-enabled devices, most commonly automotive ECUs. Use it to take
+measurements, adjust parameters (calibration), stream DAQ/STIM, and
+program devices during development.
+
+Highlights:
+
+- Transports: Ethernet (TCP/IP), CAN, USB, Serial (SxI)
+- Cross-platform: Windows, Linux, macOS
+- Rich CLI tools for common XCP tasks
+- Extensible architecture and layered design
+
+--------------
+
+Installation
+------------
+
+The easiest way is from PyPI:
+
+.. code:: shell
+
+   pip install pyxcp
+
+To install from the main branch:
+
+.. code:: shell
+
+   pip install git+https://github.com/christoph2/pyxcp.git
+
+Requirements
+~~~~~~~~~~~~
+
+- Python >= 3.10
+- Building from source requires a working C/C++ toolchain (native
+  extensions are used for performance). Wheels are provided for common
+  platforms and Python versions; if a wheel is not available, pip will
+  build from source.
+- An XCP slave device (or simulator)
+
+Quick start
+-----------
+
+The tutorial walks you through typical tasks end-to-end: see `tutorial <tutorial.rst>`_.
+
+Minimal example using the built-in argument parser and context manager:
+
+.. code:: python
+
+   from pyxcp.cmdline import ArgumentParser
+
+   ap = ArgumentParser(description="pyXCP hello world")
+
+   with ap.run() as x:
+       x.connect()
+       identifier = x.identifier(0x01)
+       print(f"ID: {identifier!r}")
+       print(x.slaveProperties)
+       x.disconnect()
+
+Configuration
+~~~~~~~~~~~~~
+
+``pyXCP`` supports a
+`traitlets <https://github.com/ipython/traitlets>`__\-based configuration system.
+
+- Recommended Python config example and generator: `tutorial <tutorial.rst>`__ and `configuration <configuration.rst>`__
+- Legacy TOML examples remain available for compatibility.
+
+Command‑line tools
+~~~~~~~~~~~~~~~~~~
+
+Installed entry points (see pyproject.toml):
+
+- xcp-info — print capabilities and properties
+- xcp-id-scanner — scan for slave identifiers
+- xcp-fetch-a2l — retrieve A2L from target (if supported)
+- xcp-profile — generate/convert config files
+- xcp-examples — launch assorted demos/examples
+- xmraw-converter — convert recorder .xmraw data
+- pyxcp-probe-can-drivers — list available CAN interfaces
+
+Run any tool with -h for options.
+
+Features
+--------
+
+- Multiple transport layers: Ethernet (TCP), CAN, USB, SxI (serial/UART)
+- Data Acquisition (DAQ) and Stimulation (STIM)
+- Calibration (read/write parameters)
+- Flashing/programming workflows
+- A2L (ASAM MCD‑2 MC) support
+- Recorder utilities and converters (see `recorder <recorder.rst>`__)
+- Extensible architecture for custom transports
+
+Documentation
+-------------
+
+- Getting started tutorial: `tutorial <tutorial.rst>`__
+- Configuration: `configuration <configuration.rst>`__
+- CAN driver setup and troubleshooting: `howto_can_driver <howto_can_driver.rst>`__
+- Recorder: `recorder <recorder.rst>`__
+- Troubleshooting: `troubleshooting <troubleshooting.rst>`__
+- Troubleshooting matrix (common errors, root causes, fixes):
+  `troubleshooting_matrix <troubleshooting_matrix.rst>`__
+
+To build the Sphinx documentation locally:
+
+1. Install doc requirements:
+	``pip install -r docs/requirements.txt``
+2. Build:
+	``sphinx-build -b html docs docs/_build/html``
+3. Open
+	``docs/_build/html/index.html``
+
+Compatibility
+-------------
+
+- Operating systems: Windows, Linux, macOS
+- Python: 3.10 - 3.14, CPython wheels where available
+- CAN backends: python-can compatible drivers (see `howto_can_driver <howto_can_driver.rst>`__)
+
+Contributing
+------------
+
+Contributions are welcome! Please: - Read `CODE_OF_CONDUCT <../CODE_OF_CONDUCT.md>`__ - Open an
+issue or discussion before large changes - Use
+`pre-commit <https://github.com/pre-commit/pre-commit>`__ to run linters
+and tests locally
+
+License
+-------
+
+GNU Lesser General Public License v3 or later (LGPLv3+). See LICENSE for
+details.
+
+References
+----------
+
+- ASAM MCD‑1 XCP standard:
+  https://www.asam.net/standards/detail/mcd-1-xcp/
+
+About ASAM MCD‑1 XCP
+--------------------
+
+XCP (Universal Measurement and Calibration Protocol) is an ASAM standard
+defining a vendor‑neutral protocol to access internal data of electronic
+control units (ECUs) for measurement, calibration (parameter tuning),
+and programming. XCP decouples the protocol from the physical transport,
+so the same command set can be carried over different buses such as CAN,
+FlexRay, Ethernet, USB, or Serial.
+
+- Roles: An XCP Master (this library) communicates with an XCP Slave
+  (your device/ECU or simulator).
+- Layered concept: XCP defines an application layer and transport
+  layers. ``pyXCP`` implements the application layer and multiple transport
+  bindings.
+- Use cases:
+
+  - Measurement: Read variables from the ECU in real‑time, including
+    high‑rate DAQ streaming.
+  - Calibration: Read/write parameters (calibration data) in RAM/flash.
+  - Programming: Download new program/data to flash (where the slave
+    supports it).
+
+For the authoritative description, see the ASAM page:
+https://www.asam.net/standards/detail/mcd-1-xcp/
+
+XCP in a nutshell
+-----------------
+
+- Connect/Session: The master establishes a connection, negotiates
+  capabilities/features, and optionally unlocks protected functions via
+  seed & key.
+- Addressing: Memory is accessed via absolute or segment‑relative
+  addresses. Addressing modes are described in the associated A2L file
+  (ASAM MCD‑2 MC), which maps symbolic names to addresses, data types,
+  and conversion rules.
+- Events: The slave exposes events (e.g., “1 ms task”, “Combustion
+  cycle”), which trigger DAQ sampling. The master assigns signals (ODTs)
+  to these events for time‑aligned acquisition.
+- DAQ/STIM: DAQ = Data Acquisition (slave → master), STIM = Stimulation
+  (master → slave). Both use event‑driven lists for deterministic
+  timing.
+- Timestamps: DAQ may carry timestamps from the slave for precise time
+  correlation.
+- Security: Access to sensitive commands (e.g., programming,
+  calibration) can be protected by a seed & key algorithm negotiated at
+  runtime.
+- Checksums: XCP defines checksum services useful for verifying memory
+  regions (e.g., after flashing).
+
+Relation to A2L (ASAM MCD‑2 MC)
+-------------------------------
+
+While XCP defines the protocol, the A2L file describes the measurement
+and calibration objects (characteristics, measurements), data types,
+conversion rules, and memory layout. In practice, you use ``pyXCP`` together
+with an A2L to: - Resolve symbolic names to addresses and data types. -
+Configure DAQ lists from human‑readable signal names. - Interpret raw
+values using the appropriate conversion methods.
+
+``pyXCP`` provides utilities to fetch A2L data when supported by the slave
+and to work with A2L‑described objects. See also
+`pya2ldb <https://github.com/christoph2/pya2l>`__!
+
+Transports and addressing
+-------------------------
+
+XCP is transport‑agnostic. ``pyXCP`` supports multiple transports and
+addressing schemes: - CAN (XCP on CAN): Robust and ubiquitous in
+vehicles; limited payload and bandwidth; suited for many calibration
+tasks and moderate DAQ rates. - Ethernet (XCP on TCP/UDP): High
+bandwidth with low latency; well suited for rich DAQ and programming
+workflows. - USB: High throughput for lab setups; requires device
+support. - Serial/SxI: Simple point‑to‑point links for embedded targets
+and simulators.
+
+The exact capabilities (e.g., max CTO/DTO, checksum types, timestamping)
+are negotiated at connect time and depend on the slave and transport.
+
+Supported features (overview)
+-----------------------------
+
+The scope of features depends on the connected slave. At the library
+level, ``pyXCP`` provides: - Session management: CONNECT/DISCONNECT,
+GET_STATUS/SLAVE_PROPERTIES, communication mode setup, error handling. -
+Memory access: Upload/short upload, Download/Download Next,
+verifications, optional paged memory where supported. - DAQ/STIM:
+Configuration of DAQ lists/ODTs, event assignment, data streaming,
+timestamp handling when available. - Programming helpers: Building
+blocks for program/erase/write flows (exact sequence per slave’s flash
+algorithm and A2L description). - Security/Seed & Key: Pluggable
+seed‑to‑key resolution including 32↔64‑bit bridge on Windows. -
+Utilities: Identifier scanning, A2L helpers, recorder and converters.
+
+Refer to `tutorial <tutorial.rst>`__ and `configuration <configuration.rst>`__ for feature usage,
+and xcp-info for a capability dump of your target.
+
+Compliance and versions
+-----------------------
+
+``pyXCP`` aims to be compatible with commonly used parts of ASAM MCD‑1 XCP.
+Specific optional features are enabled when a slave advertises them
+during CONNECT. Because implementations vary across vendors and ECU
+projects, always consult your A2L and use xcp-info to confirm negotiated
+options (e.g., checksum type, timestamp unit, max DTO size, address
+granularity).
+
+If you rely on a particular XCP feature/profile not mentioned here,
+please open an issue with details about your slave and A2L so we can
+clarify support and—if feasible—add coverage.
+
+Safety, performance, and limitations
+------------------------------------
+
+- Safety‑critical systems: XCP is a development and testing protocol. Do
+  not enable measurement/calibration on safety‑critical systems in the
+  field unless your system‑level safety case covers it.
+- Performance: Achievable DAQ rates depend on transport bandwidth, ECU
+  event rates, DTO sizes, and host processing. Ethernet typically yields
+  the highest throughput.
+- Latency/jitter: Event scheduling in the slave and OS scheduling on the
+  host can affect determinism. Use timestamps to correlate data
+  precisely.
+- Access control: Seed & key protects sensitive functions; your
+  organization’s policy should govern algorithm distribution and access.
+
+Further resources
+-----------------
+
+- ASAM MCD‑1 XCP standard (overview and membership):
+  https://www.asam.net/standards/detail/mcd-1-xcp/
+- ASAM MCD‑2 MC (A2L) for object descriptions:
+  https://www.asam.net/standards/detail/mcd-2-mc/
+- Introduction to DAQ/STIM concepts (ASAM publications and vendor docs)
+- Related: CCP (legacy predecessor to XCP), ASAM MDF for measurement
+  data storage
+
+.. |CI| image:: https://github.com/christoph2/pyxcp/workflows/Python%20application/badge.svg
+   :target: https://github.com/christoph2/pyxcp/actions
+.. |PyPI| image:: https://img.shields.io/pypi/v/pyxcp.svg
+   :target: https://pypi.org/project/pyxcp/
+.. |Python Versions| image:: https://img.shields.io/pypi/pyversions/pyxcp.svg
+   :target: https://pypi.org/project/pyxcp/
+.. |License: LGPL v3+| image:: https://img.shields.io/badge/License-LGPL%20v3%2B-blue.svg
+   :target: https://www.gnu.org/licenses/lgpl-3.0
+.. |Code style: black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
+   :target: https://github.com/psf/black
+