pyxcp
Advanced tools
.. 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|
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:
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
-----------
**New to pyXCP?** Start with the 15-minute `Quickstart Guide <quickstart.md>`_ 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()
Configuration
pyXCP supports a
traitlets <https://github.com/ipython/traitlets>__-based configuration system.
tutorial <tutorial.rst>__ and configuration <configuration.rst>__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)
- 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.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
.. |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
FAQs
Universal Calibration Protocol for Python
We found that pyxcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
An emerging npm supply chain attack that infects repos, steals CI secrets, and targets developer AI toolchains for further compromise.
Company News
Socket is proud to join the OpenJS Foundation as a Silver Member, deepening our commitment to the long-term health and security of the JavaScript ecosystem.
Security News
npm now links to Socket's security analysis on every package page. Here's what you'll find when you click through.