Skip to content
CAN bus tools.
Python Makefile
Branch: master
Clone or download
Latest commit d227e89 Jan 25, 2020
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
cantools Version 33.1.1. Jan 25, 2020
docs Copyright year 2019. Jan 14, 2019
examples Fix deprecated SocketCAN interfaces in examples Mar 25, 2019
tests Cleanup after merge. Jan 25, 2020
.appveyor.yml Try Python 3.8 on AppVeyor. Jan 5, 2020
.gitattributes Added gitattributes for correct language detection on GitHub. Nov 22, 2018
.gitignore
.travis.yml Test with Python 3.8 on Travis. Jan 2, 2020
LICENSE Copyright year 2019. Jan 14, 2019
MANIFEST.in Update MANIFEST.in Nov 3, 2019
Makefile Generate integer values in range check if not floating point signal. Feb 1, 2019
README.rst README. Jan 20, 2020
requirements.txt Use textparser in sym format as well. Dec 8, 2018
setup.py

README.rst

buildstatus appveyor coverage

About

CAN BUS tools in Python 3.

  • DBC, KCD, SYM, ARXML 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.

Python 2 support is deprecated as Python 3 has better unicode support.

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

Documentation: https://cantools.readthedocs.io

Installation

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 | 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 | 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 dump subcommand

Dump given database in a human readable format:

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

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

$ 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 last example we use --no-floating-point-numbers to generate code without floating point types, i.e. float and double.

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

Other C code generators:

The monitor subcommand

Monitor CAN bus traffic in a text based user interface.

$ cantools monitor tests/files/dbc/motohawk.dbc

https://github.com/eerimoq/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.

    pip install -r requirements.txt
    
  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 tests.

    make test
    
  6. Create a pull request.

You can’t perform that action at this time.