{"id":4903,"library":"cantools","title":"CAN BUS tools","description":"cantools is a Python 3 library for working with CAN (Controller Area Network) bus data. It provides extensive functionalities for parsing and interacting with various CAN database file formats, including DBC, KCD, SYM, ARXML (versions 3&4), and CDD. Key features include encoding and decoding CAN messages, handling simple and extended signal multiplexing, diagnostic DID encoding and decoding, and command-line tools for monitoring CAN bus traffic, generating C source code from databases, and visualizing signals. The library is actively maintained with regular updates.","status":"active","version":"41.3.0","language":"en","source_language":"en","source_url":"https://github.com/cantools/cantools","tags":["CAN bus","DBC","ARXML","KCD","automotive","signal processing","encoding","decoding","CAN-FD"],"install":[{"cmd":"pip install cantools","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for interacting with live CAN buses (sending and receiving messages), used in many examples.","package":"python-can","optional":true},{"reason":"Required for the 'plot' subcommand to visualize signals.","package":"matplotlib","optional":true}],"imports":[{"symbol":"cantools","correct":"import cantools"},{"symbol":"load_file","correct":"import cantools.database\ndb = cantools.database.load_file('path/to/your.dbc')"},{"note":"For manually constructing a CAN database in Python.","symbol":"Database","correct":"from cantools.database import Database, Message, Signal"}],"quickstart":{"code":"import cantools\nimport os\n\n# A minimal DBC file content for demonstration\ndbc_content = \"\"\"\nVERSION \"\"\"\n\nNS_ :\nBS_:\n\nBU_: Vector__XXX\n\nBO_ 256 EXAMPLE_MESSAGE: 8 Vector__XXX\n SG_ Signal1 : 0|8@1+ (1,0) [0|255] \"Unit\" Vector__XXX\n SG_ Signal2 : 8|8@1+ (0.1,0) [0|25.5] \"V\" Vector__XXX\n\"\"\"\n\n# Load the database from a string (or use cantools.database.load_file('path/to/your.dbc'))\ntry:\n    db = cantools.database.load_string(dbc_content, database_format='dbc')\n    print(\"Database loaded successfully.\")\n\n    # Get a message from the database\n    example_message = db.get_message_by_name('EXAMPLE_MESSAGE')\n\n    # Encode a message\n    data = example_message.encode({'Signal1': 100, 'Signal2': 12.5})\n    print(f\"Encoded data for EXAMPLE_MESSAGE: {data.hex()}\")\n\n    # Decode a message\n    decoded_data = db.decode_message(example_message.frame_id, data)\n    print(f\"Decoded data: {decoded_data}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Note: For real-world usage, provide a valid .dbc file path.\")\n","lang":"python","description":"This quickstart demonstrates how to load a CAN database (either from a string or file), encode Python dictionary data into a CAN message payload, and then decode a CAN message payload back into human-readable signal values. For actual CAN bus communication, the `python-can` library is commonly used in conjunction with `cantools`."},"warnings":[{"fix":"Review code accessing `Signal.initial` or `*.decimal` attributes. Ensure you are working with scaled values for `initial`. For precise comparisons, use `Database.is_similar()` instead of direct equality checks after load-store-load cycles.","message":"In version 39.0.0, the `initial` attribute of `Signal` objects was changed to always hold the scaled signal value. Previously, it used raw values for DBC files and scaled values for ARXML. Additionally, the machinery for storing decimal numbers without rounding errors (`*.decimal` attributes) was removed.","severity":"breaking","affected_versions":">=39.0.0"},{"fix":"For comprehensive J1939 protocol handling, consider using the `python-can-j1939` library which provides more complete SAE J1939 support.","message":"cantools has weak or limited direct support for J1939 PGNs (Parameter Group Numbers). While basic decoding might work by splitting databases, for robust J1939 support, it's recommended to use the dedicated `python-can-j1939` package.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure you are using a recent version of `cantools` (>=40.0.0) which may have improved CAN-FD handling. If issues persist, consider manually parsing extended data payloads or consulting specific `cantools` examples for CAN-FD if available.","message":"Decoding CAN-FD messages or any CAN message with a payload length greater than 8 bytes using `database.decode_message()` might fail in some earlier versions or specific contexts, as the method was primarily designed for standard CAN messages (up to 8 bytes).","severity":"gotcha","affected_versions":"<40.0.0 (potentially some earlier minor versions)"},{"fix":"Ensure your environment is running Python 3.10 or a newer compatible version. Upgrade your Python interpreter if necessary.","message":"Python 2 support was deprecated in older versions. The library now explicitly requires Python 3.10 and above.","severity":"deprecated","affected_versions":"<35.0.0 (Python 2 supported), >=3.10.0 (Python 3.10+ required)"},{"fix":"Ensure `diskcache` is updated to a compatible version (>=5.0.2 if manually managing) or simply use a clean Python 3.10+ environment with `pip install cantools`.","message":"An older `diskcache` dependency (version < 5.0.2) used by `cantools` could cause installation issues on Python 2 environments. While `cantools` now requires Python 3.10+, if you encounter `diskcache`-related installation failures in a mixed or legacy setup, it might be due to this.","severity":"gotcha","affected_versions":"Older versions of cantools, especially when used with Python 2.x environments. Less relevant for current Python 3.10+ requirement."}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}