{"id":5143,"library":"canmatrix","title":"Canmatrix","description":"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.","status":"active","version":"1.2","language":"en","source_language":"en","source_url":"http://github.com/ebroecker/canmatrix","tags":["CAN","canbus","automotive","dbc","arxml","kcd","dbf","sym","fibex","eds"],"install":[{"cmd":"pip install canmatrix","lang":"bash","label":"Core library"},{"cmd":"pip install 'canmatrix[arxml,kcd,fibex,odx]' # For XML-based formats","lang":"bash","label":"With optional XML dependencies"},{"cmd":"pip install 'canmatrix[xls,xlsx]' # For Excel formats","lang":"bash","label":"With optional Excel dependencies"}],"dependencies":[{"reason":"Core dependency for object serialization.","package":"attrs","optional":false},{"reason":"Core dependency for command-line interface tools.","package":"click","optional":false},{"reason":"Required for processing XML-based formats such as ARXML, KCD, Fibex, and ODX.","package":"lxml","optional":true},{"reason":"Required for reading legacy .xls Excel files.","package":"xlrd","optional":true},{"reason":"Required for writing legacy .xls Excel files.","package":"xlwt-future","optional":true},{"reason":"Required for writing .xlsx Excel files.","package":"XlsxWriter","optional":true},{"reason":"Required for processing YAML format.","package":"PyYAML","optional":true}],"imports":[{"note":"The main object representing a CAN database.","symbol":"CanMatrix","correct":"from canmatrix import CanMatrix"},{"note":"For loading DBC files; other formats are similarly available under `canmatrix.formats` (e.g., `arxml`, `kcd`).","symbol":"dbc_load","correct":"from canmatrix.formats import dbc"},{"note":"For dumping (saving) DBC files; other formats are similarly available under `canmatrix.formats`.","symbol":"dbc_dump","correct":"from canmatrix.formats import dbc"},{"note":"CLI tools like `convert` and `compare` were moved to the `canmatrix.cli` submodule in version 0.8.","wrong":"import canmatrix.convert","symbol":"cli_convert","correct":"from canmatrix.cli import convert"}],"quickstart":{"code":"import os\nfrom canmatrix.formats import dbc\n\n# Create a dummy DBC file for demonstration\ndummy_dbc_content = '''\nBO_ 100 MSG_1: 8 Vector__XXX\n SG_ Sig1 : 0|8@1+ (1,0) [0|255] \"\" Vector__XXX\n SG_ Sig2 : 8|16@1+ (0.1,0) [0|6553.5] \"\" Vector__XXX\n'''\n\ndbc_file_path = 'dummy.dbc'\nwith open(dbc_file_path, 'w') as f:\n    f.write(dummy_dbc_content)\n\n# Load the CAN matrix from the DBC file\ndb = dbc.load(dbc_file_path)\n\n# Access frames and signals\nfor frame_name in db:\n    frame = db.frames[frame_name]\n    print(f\"Frame: {frame.name} (ID: {frame.arbitration_id.id}, DLC: {frame.size} bytes)\")\n    for signal_name in frame.signals:\n        signal = frame.signals[signal_name]\n        print(f\"  Signal: {signal.name} (StartBit: {signal.start_bit}, Length: {signal.size} bits)\")\n\n# Clean up the dummy file\nos.remove(dbc_file_path)\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.0 (prior to fix in May 2024)"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}