Skip to main content

CAN BUS tools.

Project description

Github Actions workflow status Test coverage reports on Coveralls.io nala

About

CAN BUS tools in Python 3.

  • DBC, KCD, SYM, ARXML 3&4 and CDD file parsing.

  • CAN message encoding and decoding.

  • Simple and extended signal multiplexing.

  • Diagnostic DID encoding and decoding.

  • candump output decoder.

  • Node tester.

  • C source code generator.

  • CAN bus monitor.

  • Graphical plots of signals.

Project homepage: https://github.com/cantools/cantools

Documentation: https://cantools.readthedocs.io

Installation

python3 -m pip install cantools

Example usage

Scripting

The example starts by parsing a small DBC-file and printing its messages and signals.

>>> import cantools
>>> from pprint import pprint
>>> db = cantools.database.load_file('tests/files/dbc/motohawk.dbc')
>>> db.messages
[message('ExampleMessage', 0x1f0, False, 8, 'Example message used as template in MotoHawk models.')]
>>> example_message = db.get_message_by_name('ExampleMessage')
>>> pprint(example_message.signals)
[signal('Enable', 7, 1, 'big_endian', False, 1.0, 0, 0.0, 0.0, '-', False, None, {0: 'Disabled', 1: 'Enabled'}, None),
 signal('AverageRadius', 6, 6, 'big_endian', False, 0.1, 0, 0.0, 5.0, 'm', False, None, None, ''),
 signal('Temperature', 0, 12, 'big_endian', True, 0.01, 250, 229.53, 270.47, 'degK', False, None, None, None)]

The example continues encoding a message and sending it on a CAN bus using the python-can package.

>>> import can
>>> can_bus = can.interface.Bus('vcan0', bustype='socketcan')
>>> data = example_message.encode({'Temperature': 250.1, 'AverageRadius': 3.2, 'Enable': 1})
>>> message = can.Message(arbitration_id=example_message.frame_id, data=data)
>>> can_bus.send(message)

Alternatively, a message can be encoded using the encode_message() method on the database object.

The last part of the example receives and decodes a CAN message.

>>> message = can_bus.recv()
>>> db.decode_message(message.arbitration_id, message.data)
{'AverageRadius': 3.2, 'Enable': 'Enabled', 'Temperature': 250.09}

See examples for additional examples.

Command line tool

The decode subcommand

Decode CAN frames captured with the Linux program candump.

$ candump vcan0 | python3 -m cantools decode tests/files/dbc/motohawk.dbc
  vcan0  1F0   [8]  80 4A 0F 00 00 00 00 00 ::
ExampleMessage(
    Enable: 'Enabled' -,
    AverageRadius: 0.0 m,
    Temperature: 255.92 degK
)
  vcan0  1F0   [8]  80 4A 0F 00 00 00 00 00 ::
ExampleMessage(
    Enable: 'Enabled' -,
    AverageRadius: 0.0 m,
    Temperature: 255.92 degK
)
  vcan0  1F0   [8]  80 4A 0F 00 00 00 00 00 ::
ExampleMessage(
    Enable: 'Enabled' -,
    AverageRadius: 0.0 m,
    Temperature: 255.92 degK
)

Alternatively, the decoded message can be printed on a single line:

$ candump vcan0 | python3 -m cantools decode --single-line tests/files/dbc/motohawk.dbc
  vcan0  1F0   [8]  80 4A 0F 00 00 00 00 00 :: ExampleMessage(Enable: 'Enabled' -, AverageRadius: 0.0 m, Temperature: 255.92 degK)
  vcan0  1F0   [8]  80 4A 0F 00 00 00 00 00 :: ExampleMessage(Enable: 'Enabled' -, AverageRadius: 0.0 m, Temperature: 255.92 degK)
  vcan0  1F0   [8]  80 4A 0F 00 00 00 00 00 :: ExampleMessage(Enable: 'Enabled' -, AverageRadius: 0.0 m, Temperature: 255.92 degK)

The plot subcommand

The plot subcommand is similar to the decode subcommand but messages are visualized using matplotlib instead of being printed to stdout.

$ candump -l vcan0
$ cat candump-2021-01-04_180521.log
(1609779922.655421) vcan0 00000343#B204B9049C049C04
(1609779922.655735) vcan0 0000024A#120527052E051905
(1609779923.657524) vcan0 00000343#C404C404CB04C404
(1609779923.658086) vcan0 0000024A#8B058B058B059205
(1609779924.659912) vcan0 00000343#5C04790479045504
(1609779924.660471) vcan0 0000024A#44064B0659064406
(1609779925.662277) vcan0 00000343#15040704F203F203
(1609779925.662837) vcan0 0000024A#8B069906A706A706
(1609779926.664191) vcan0 00000343#BC03B503A703BC03
(1609779926.664751) vcan0 0000024A#A006A706C406C406

$ cat candump-2021-01-04_180521.log | python3 -m cantools plot tests/files/dbc/abs.dbc
https://github.com/cantools/cantools/raw/master/docs/plot-1.png

If you don’t want to show all signals you can select the desired signals with command line arguments. A * can stand for any number of any character, a ? for exactly one arbitrary character. Signals separated by a - are displayed in separate subplots. Optionally a format can be specified after a signal, separated by a colon.

$ cat candump-2021-01-04_180521.log | python3 -m cantools plot tests/files/dbc/abs.dbc '*33.*fl:-<' '*33.*fr:->' - '*33.*rl:-<' '*33.*rr:->'
https://github.com/cantools/cantools/raw/master/docs/plot-2-subplots.png

Signals with a different range of values can be displayed in the same subplot on different vertical axes by separating them with a comma.

$ cat candump-2021-01-04_180521.log | cantools plot --auto-color tests/files/dbc/abs.dbc -- \
   --ylabel 'Bremse 33' '*_33.*fl*:-<' '*_33.*fr*:>' '*_33.*rl*:3' '*_33.*rr*:4' , \
   --ylabel 'Bremse 2' '*_2.*fl*:-<' '*_2.*fr*:>' '*_2.*rl*:3' '*_2.*rr*:4'
https://github.com/cantools/cantools/raw/master/docs/plot-2-axes.png

Matplotlib comes with different preinstalled styles that you can use:

$ cat candump-2021-01-04_180521.log | cantools plot tests/files/dbc/abs.dbc --style seaborn
https://github.com/cantools/cantools/raw/master/docs/plot-seaborn.png

You can try all available styles with

$ cantools plot --list-styles . | sed -n '/^- /s/^- //p' | while IFS= read -r style; do
      cat candump-2021-01-04_180521.log | cantools plot tests/files/dbc/abs.dbc --style "$style" --title "--style '$style'"
  done

For more information see

$ python3 -m cantools plot --help

Note that by default matplotlib is not installed with cantools. But it can be by specifying an extra at installation:

$ python3 -m pip install cantools[plot]

The dump subcommand

Dump given database in a human readable format:

$ python3 -m cantools dump tests/files/dbc/motohawk.dbc
================================= Messages =================================

  ------------------------------------------------------------------------

  Name:       ExampleMessage
  Id:         0x1f0
  Length:     8 bytes
  Cycle time: - ms
  Senders:    PCM1
  Layout:

                          Bit

             7   6   5   4   3   2   1   0
           +---+---+---+---+---+---+---+---+
         0 |<-x|<---------------------x|<--|
           +---+---+---+---+---+---+---+---+
             |                       +-- AverageRadius
             +-- Enable
           +---+---+---+---+---+---+---+---+
         1 |-------------------------------|
           +---+---+---+---+---+---+---+---+
         2 |----------x|   |   |   |   |   |
     B     +---+---+---+---+---+---+---+---+
     y               +-- Temperature
     t     +---+---+---+---+---+---+---+---+
     e   3 |   |   |   |   |   |   |   |   |
           +---+---+---+---+---+---+---+---+
         4 |   |   |   |   |   |   |   |   |
           +---+---+---+---+---+---+---+---+
         5 |   |   |   |   |   |   |   |   |
           +---+---+---+---+---+---+---+---+
         6 |   |   |   |   |   |   |   |   |
           +---+---+---+---+---+---+---+---+
         7 |   |   |   |   |   |   |   |   |
           +---+---+---+---+---+---+---+---+

  Signal tree:

    -- {root}
       +-- Enable
       +-- AverageRadius
       +-- Temperature

  Signal choices:

    Enable
        0 Disabled
        1 Enabled

  ------------------------------------------------------------------------

The list subcommand

Print all information of a given database in a human readable format. This is very similar to the “dump” subcommand, but the output is less pretty, slightly more comprehensive and easier to parse by shell scripts:

$ python3 -m cantools list -a tests/files/dbc/motohawk.dbc
ExampleMessage:
  Comment[None]: Example message used as template in MotoHawk models.
  Frame ID: 0x1f0 (496)
  Size: 8 bytes
  Is extended frame: False
  Signals:
    Enable:
      Type: Integer
      Start bit: 7
      Length: 1 bits
      Unit: -
      Is signed: False
      Named values:
        0: Disabled

The generate C source subcommand

Generate C source code from given database.

The generated code contains:

Known limitations:

  • The maximum signal size is 64 bits, which in practice is never exceeded.

Below is an example of how to generate C source code from a database. The database is tests/files/dbc/motohawk.dbc.

$ python3 -m cantools generate_c_source tests/files/dbc/motohawk.dbc
Successfully generated motohawk.h and motohawk.c.

See motohawk.h and motohawk.c for the contents of the generated files.

In this example we use --use-float so floating point numbers in the generated code are single precision (float) instead of double precision (double).

$ python3 -m cantools generate_c_source --use-float tests/files/dbc/motohawk.dbc
Successfully generated motohawk.h and motohawk.c.

In the next example we use --database-name to set a custom namespace for all generated types, defines and functions. The output file names are also changed by this option.

$ python3 -m cantools generate_c_source --database-name my_database_name tests/files/dbc/motohawk.dbc
Successfully generated my_database_name.h and my_database_name.c.

See my_database_name.h and my_database_name.c for the contents of the generated files.

In the next example we use --no-floating-point-numbers to generate code without floating point types, i.e. float and double.

$ python3 -m cantools generate_c_source --no-floating-point-numbers tests/files/dbc/motohawk.dbc
Successfully generated motohawk.h and motohawk.c.

See motohawk_no_floating_point_numbers.h and motohawk_no_floating_point_numbers.c for the contents of the generated files.

In the last example --node is used to generate message pack functions only for messages sent by the specified node and unpack functions only for messages with its signal receivers belonging to that node.

$ cantools generate_c_source tests/files/dbc/motohawk.dbc --node PCM1
Successfully generated motohawk.h and motohawk.c.

See motohawk_sender_node.h and motohawk_sender_node.c for the contents of the generated files.

Other C code generators:

The monitor subcommand

Monitor CAN bus traffic in a text based user interface.

$ python3 -m cantools monitor tests/files/dbc/motohawk.dbc
https://github.com/cantools/cantools/raw/master/docs/monitor.png

The menu at the bottom of the monitor shows the available commands.

  • Quit: Quit the monitor. Ctrl-C can be used as well.

  • Filter: Only display messages matching given regular expression. Press <Enter> to return to the menu from the filter input line.

  • Play/Pause: Toggle between playing and paused (or running and freezed).

  • Reset: Reset the monitor to its initial state.

Contributing

  1. Fork the repository.

  2. Install prerequisites.

    python3 -m pip install -e .[dev]
  3. Implement the new feature or bug fix.

  4. Implement test case(s) to ensure that future changes do not break legacy.

  5. Run the linters

    ruff check src
    mypy src
  6. Run the tests.

    tox -e py
  7. Create a pull request.

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cantools-39.4.11.tar.gz (978.1 kB view details)

Uploaded Source

Built Distribution

cantools-39.4.11-py3-none-any.whl (153.5 kB view details)

Uploaded Python 3

File details

Details for the file cantools-39.4.11.tar.gz.

File metadata

  • Download URL: cantools-39.4.11.tar.gz
  • Upload date:
  • Size: 978.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for cantools-39.4.11.tar.gz
Algorithm Hash digest
SHA256 0b7bd88a236bb2ddfd7da5dd713058e97b749185e9d1257413b27bd4cfe7d82a
MD5 70bf62962ea8b66d6cdb82923acbc129
BLAKE2b-256 4c7ecae9bbdb3e1e591376ec40321585e8e6ed8527723b9f8c08eaea9de3e53e

See more details on using hashes here.

File details

Details for the file cantools-39.4.11-py3-none-any.whl.

File metadata

  • Download URL: cantools-39.4.11-py3-none-any.whl
  • Upload date:
  • Size: 153.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for cantools-39.4.11-py3-none-any.whl
Algorithm Hash digest
SHA256 9207b1150b49de31040b00e95276c2951727e21f00ebfc922802dabb8cd10d02
MD5 841720f78166888904b98ea41c214601
BLAKE2b-256 f618a228010954f00ca7e02a6034c0f4bd3626f3c3e626f4b52a6f51054faf0b

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page