cantools 20.0.1

CAN BUS tools.

About

CAN BUS tools.

• DBC, KCD and SYM file mangling.

• CAN message encoding and decoding.

• Simple and extended signal multiplexing.

• candump output decoder.

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

Documentation: http://cantools.readthedocs.org/en/latest

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.db.load_file('tests/files/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.rc['interface'] = 'socketcan_ctypes'
>>> can.rc['channel'] = 'vcan0'
>>> can_bus = can.interface.Bus()
>>> 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 the test suite for additional examples: https://github.com/eerimoq/cantools/blob/master/tests/test_cantools.py

Command line tool

Decode CAN frames captured with the Linux program candump.

$ candump vcan0 | cantools decode tests/files/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/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)

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.