pyxcp

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: ruff| |Ask DeepWiki| Ask Zread |PDF Manual|

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.11, < 3.16
- 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
-----------

**New to pyXCP?** Start with the 15-minute `Quickstart Guide <quickstart.rst>`_ for a hands-on introduction.

The comprehensive `tutorial <tutorial.rst>`_ walks you through typical tasks end-to-end.

**Using A2L files?** See the `A2L Integration Guide <a2l_integration.rst>`_ for symbolic access to ECU parameters.

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()

Async facade for awaitable command handling plus DAQ/event streaming:

.. code:: python

   import asyncio

   from pyxcp.cmdline import ArgumentParser
   from pyxcp.transport import AsyncPolicyAdapter


   async def main():
       ap = ArgumentParser(description="pyXCP async example")
       policy = AsyncPolicyAdapter()

       async with ap.async_run(policy=policy) as x:
           await x.connect()
           status = await x.getStatus()
           print(status)

           daq_frames = x.subscribe_daq()
           frame = await daq_frames.get()
           print(frame.category, frame.counter, frame.payload.hex())


   asyncio.run(main())

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
- xcp-discovery — multicast discovery for XCP on Ethernet (with optional SET_SLAVE_IP_ADDRESS)
- 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)
- High-precision IEEE 1588/PTP hardware timestamping (Ethernet/UDP on Windows and Linux)
- Data Acquisition (DAQ) and Stimulation (STIM)
- Calibration (read/write parameters)
- Flashing/programming workflows
- **A2L (ASAM MCD‑2 MC) support** — symbolic access via `pya2ldb <https://github.com/christoph2/pya2l>`_
- Recorder utilities and converters (see `recorder <recorder.rst>`__)
- Extensible architecture for custom transports

Related Projects
~~~~~~~~~~~~~~~~

**asamint** — High-level MCS (Measurement & Calibration System)

For production-grade workflows with command-line batch operations, see the `asamint project <https://github.com/christoph2/asamint>`_.

``asamint`` integrates ``pyxcp``, ``pya2ldb``, ``asammdf``, and ``objutils`` to provide:

- Command-line MCS functionality
- ASAM CDF (calibration data file) creation
- MDF (ASAM MCD-3 MC) export
- Orchestrated multi-tool workflows
- Production measurement campaigns

**When to use:**

- ``pyxcp``: Custom applications, test automation, learning XCP
- ``asamint``: Production calibration, batch operations, command-line MCS

Documentation
-------------

- Getting started tutorial: `tutorial <tutorial.rst>`__
- **A2L Integration Guide**: `a2l_integration <a2l_integration.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.11 - 3.15, 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

.. |GitHub Actions| 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: ruff| image:: https://img.shields.io/badge/code%20style-ruff-000000.svg
   :target: https://docs.astral.sh/ruff/
   :alt: Ruff
.. |Ask DeepWiki| image:: https://deepwiki.com/badge.svg
   :target: https://deepwiki.com/christoph2/pyxcp
.. |Ask Zread| image:: https://img.shields.io/badge/Ask-Zread-blue.svg
   :target: https://zread.ai/christoph2/pyxcp
.. |PDF Manual| image:: https://img.shields.io/badge/docs-PDF%20manual-blue.svg
   :target: https://pyxcp.readthedocs.io/_/downloads/en/latest/pdf/