Canmatrix

1.2 · active · verified Mon Apr 13

Canmatrix implements a "Python Can Matrix Object" which describes CAN communication and related objects such as Boardunits, Frames, Signals, and Values. It serves as a versatile tool for reading, writing, and manipulating various CAN database formats including .dbc, .dbf, .kcd, .arxml, .yaml, and .xls(x). The library also provides command-line utilities, `canconvert` for format conversion and `cancompare` for comparing CAN databases.

Warnings

breaking Major internal refactoring and module reorganization in versions leading up to 1.0 (specifically around 0.8 and 0.9) introduced breaking changes. Direct imports of modules like `canmatrix.convert` or `canmatrix.formats.<format>` from earlier versions (pre-0.8) are likely to fail, as many components were moved to `canmatrix.cli` and `canmatrix.formats` submodules. Python 2 support was officially dropped with the 1.0 release.
Fix: Update import paths (e.g., `from canmatrix.cli import convert`, `from canmatrix.formats import dbc`). Ensure your environment uses Python 3.8+ for current versions.
gotcha To work with specific CAN database formats (e.g., ARXML, KCD, XLSX, YAML), you often need to install `canmatrix` with additional optional dependencies. A basic `pip install canmatrix` will not include these, leading to `ModuleNotFoundError` when trying to load or save those formats.
Fix: Install `canmatrix` with the necessary extras, e.g., `pip install 'canmatrix[arxml]'` for ARXML support or `pip install 'canmatrix[xls,xlsx]'` for Excel support. Refer to the documentation for a complete list of optional dependencies.
gotcha Older versions of `canmatrix` might have compatibility issues with Python 3.12 and newer due to an incompatible `future` dependency. An issue regarding this (`#742`) was resolved in May 2024.
Fix: Upgrade to `canmatrix` version 1.0 or later (ideally 1.2 or the latest available) to ensure full compatibility with Python 3.12+ environments. If stuck on an older version, consider downgrading Python or manually patching.

Install

pip install canmatrix Core library
pip install 'canmatrix[arxml,kcd,fibex,odx]' # For XML-based formats With optional XML dependencies
pip install 'canmatrix[xls,xlsx]' # For Excel formats With optional Excel dependencies

Imports

CanMatrix
```
from canmatrix import CanMatrix
```
The main object representing a CAN database.
dbc_load
```
from canmatrix.formats import dbc
```
For loading DBC files; other formats are similarly available under `canmatrix.formats` (e.g., `arxml`, `kcd`).
dbc_dump
```
from canmatrix.formats import dbc
```
For dumping (saving) DBC files; other formats are similarly available under `canmatrix.formats`.
cli_convert
```
from canmatrix.cli import convert
```
CLI tools like `convert` and `compare` were moved to the `canmatrix.cli` submodule in version 0.8.

Quickstart

This quickstart demonstrates how to load a CAN database (DBC file) into a `CanMatrix` object, then iterate through its frames and signals to access their properties. A dummy DBC file is created for a runnable example.

import os
from canmatrix.formats import dbc

# Create a dummy DBC file for demonstration
dummy_dbc_content = '''
BO_ 100 MSG_1: 8 Vector__XXX
 SG_ Sig1 : 0|8@1+ (1,0) [0|255] "" Vector__XXX
 SG_ Sig2 : 8|16@1+ (0.1,0) [0|6553.5] "" Vector__XXX
'''

dbc_file_path = 'dummy.dbc'
with open(dbc_file_path, 'w') as f:
    f.write(dummy_dbc_content)

# Load the CAN matrix from the DBC file
db = dbc.load(dbc_file_path)

# Access frames and signals
for frame_name in db:
    frame = db.frames[frame_name]
    print(f"Frame: {frame.name} (ID: {frame.arbitration_id.id}, DLC: {frame.size} bytes)")
    for signal_name in frame.signals:
        signal = frame.signals[signal_name]
        print(f"  Signal: {signal.name} (StartBit: {signal.start_bit}, Length: {signal.size} bits)")

# Clean up the dummy file
os.remove(dbc_file_path)

view raw JSON →