canmatrix

Canmatrix is a Python package designed to read and write various CAN (Controller Area Network) database formats. It implements a 'Python Can Matrix Object' that models CAN communication components such as Boardunits, Frames, Signals, and Values.

Beyond the Python API, it provides two command-line tools:

• canconvert: For converting CAN databases between different formats.
• cancompare: For comparing two CAN databases.

Key capabilities include parsing multiple automotive communication matrix file formats and performing CAN message encoding and decoding.

canmatrix is a Python package designed to manage CAN (Controller Area Network) communication data. It provides two primary ways to interact with CAN databases:

1. Python API: Implements a Python Can Matrix Object that describes CAN communication components, including Boardunits, Frames, Signals, and Values.
2. Command Line Tools: Provides two standalone utilities for database manipulation:
   • canconvert: Used for converting CAN databases between different formats.
   • cancompare: Used for comparing two CAN databases.

Detailed information on installation, CLI usage, supported formats, and the Python API can be found in their respective documentation sections.

The canmatrix.canmatrix module provides the fundamental building blocks for representing CAN database structures. Use these classes to programmatically construct or inspect CAN network definitions:

• Ecu: Represents an Electronic Control Unit.
• Frame: Represents a CAN message/frame.
• Signal: Represents an individual signal within a frame.
• SignalGroup: A collection of related signals.
• ArbitrationId: Represents the CAN identifier.
• DecodedSignal: Represents the value of a signal after it has been unpacked from raw data.
• Define: Used for defining specific signal properties or constraints.

The canmatrix package installs two scripts. Their availability depends on your operating system:

• **
• Windows: The scripts are typically located in your Python installation's Scripts directory (e.g., C:\python3.4\Scripts or C:\python2.7\Scripts).

By default, canmatrix supports a core set of formats. To enable support for additional formats such as arxml, kcd, fibex, xls, or xlsx, install the package using the specific extra syntax from the GitHub repository. For example, to install with kcd support, use the following command:

$ pip install git+https://github.com/ebroecker/canmatrix#egg=canmatrix[kcd]

After installing canmatrix via pip, two executables are typically available in your Python environment's path: canconvert and cancompare.

If the executables are not found in your path, you can run them as Python modules:

• To convert: python -m canmatrix.cli.convert [args]
• To compare: python -m canmatrix.cli.compare [args]

The canconvert command is used to convert CAN database formats between all supported formats (e.g., .dbc, .arxml, .xlsx, .dbf, .sym).

Basic Usage

• Convert DBC to XLSX: canconvert source.dbc target.xlsx
• Convert DBC to DBF: canconvert source.dbc target.dbf
• Convert ARXML to DBC: canconvert source.arxml target.dbc
  • Note: Since .arxml can contain multiple databases, the output files will be named using the pattern BUS-NAME-IN-ARXML_target.dbc for each database found.
• Convert to same format: canconvert source.dbc target.dbc

The canconvert tool allows for various modifications during the conversion process, such as deleting elements, renaming them, or recalculating DLC.

Deletion and Renaming

• Delete Signals: --deleteSignal=sig1,sig2
• Rename Signals: --renameSignal=old:new
• Delete Frames: --deleteFrame=frame1,frame2
• Rename Frames: --renameFrame=old:new
• Delete ECUs: --deleteECU=ecu1,ecu2
• Rename ECUs: --renameECU=old:new
• Delete Signal Attributes: --deleteSignalAttributes attr1,attr2
• Delete Frame Attributes: --deleteFrameAttributes attr1,attr2
• Delete Zero Sized Signals: --deleteZeroSignals
• Delete Obsolete Defines: --deleteObsoleteDefines

canconvert --deleteSignal=mySignal,mySignal2 source.dbc target.dbc

Use canconvert to switch frame types between standard CAN and CANFD.

• Set to CANFD: --setFrameFd=frame1,frame2
• Set to standard CAN: --unsetFrameFd=frame1,frame2

canconvert --setFrameFd=myFrame,myFrame2 source.dbc target.dbc

You can convert a CAN database (like a .dbc file) into a Python script that acts as a Scapy decoder.

1. Use the canconvert CLI tool to generate the target Python file:

   canconvert source.dbc target.py

2. Use the generated module in your Scapy code:

   load_contrib("target")
   sock = CANSocket("can0", basecls=DBC)
   pkt = sock.recv()

You can use canconvert to adjust the Data Length Code (DLC) or compress frames to fill gaps between signals.

DLC Recalculation

• max: --recalcDLC=max — Recalculates DLC; the target will store the calculated DLC if it is larger than the source DLC.
• force: --recalcDLC=force — Recalculates DLC; the target will store the calculated DLC independently of the source.

Frame Compression

• compressFrame: --compressFrame=frame1,frame2 — Fills gaps between signals. This only works for frames containing exclusively big-endian or exclusively little-endian signals. Use * to target all frames.

canconvert --recalcDLC=max source.dbc target.dbc
canconvert --compressFrame=myFrame,myFrame2 source.dbc target.dbc