CAN BUS tools

Warnings

• breaking 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.
  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.
• gotcha 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.
  Fix: For comprehensive J1939 protocol handling, consider using the `python-can-j1939` library which provides more complete SAE J1939 support.
• gotcha 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).
  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.
• deprecated Python 2 support was deprecated in older versions. The library now explicitly requires Python 3.10 and above.
  Fix: Ensure your environment is running Python 3.10 or a newer compatible version. Upgrade your Python interpreter if necessary.
• gotcha 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.
  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`.

Install

• pip install cantools Install stable version

Imports

• cantools

  import cantools

• load_file

  import cantools.database
  db = cantools.database.load_file('path/to/your.dbc')

• Database

  from cantools.database import Database, Message, Signal

  For manually constructing a CAN database in Python.

Quickstart

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`.

import cantools
import os

# A minimal DBC file content for demonstration
dbc_content = """
VERSION """

NS_ :
BS_:

BU_: Vector__XXX

BO_ 256 EXAMPLE_MESSAGE: 8 Vector__XXX
 SG_ Signal1 : 0|8@1+ (1,0) [0|255] "Unit" Vector__XXX
 SG_ Signal2 : 8|8@1+ (0.1,0) [0|25.5] "V" Vector__XXX
"""

# Load the database from a string (or use cantools.database.load_file('path/to/your.dbc'))
try:
    db = cantools.database.load_string(dbc_content, database_format='dbc')
    print("Database loaded successfully.")

    # Get a message from the database
    example_message = db.get_message_by_name('EXAMPLE_MESSAGE')

    # Encode a message
    data = example_message.encode({'Signal1': 100, 'Signal2': 12.5})
    print(f"Encoded data for EXAMPLE_MESSAGE: {data.hex()}")

    # Decode a message
    decoded_data = db.decode_message(example_message.frame_id, data)
    print(f"Decoded data: {decoded_data}")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Note: For real-world usage, provide a valid .dbc file path.")