Package: cantools
AboutCAN 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.candumpoutput decoder.Nodetester.Csource code generator.CAN bus monitor.Graphical plots of signals.Project homepage:https://github.com/cantools/cantoolsDocumentation:https://cantools.readthedocs.ioInstallationpython3-mpipinstallcantoolsExample usageScriptingThe example starts by parsing asmall DBC-fileand printing its
messages and signals.>>>importcantools>>>frompprintimportpprint>>>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 continuesencodinga message and sending it on a CAN
bus using thepython-canpackage.>>>importcan>>>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 theencode_message()method on the database object.The last part of the example receives anddecodesa CAN message.>>>message=can_bus.recv()>>>db.decode_message(message.arbitration_id,message.data){'AverageRadius':3.2,'Enable':'Enabled','Temperature':250.09}Seeexamplesfor additional examples.Command line toolThe decode subcommandDecode CAN frames captured with the Linux programcandump.$ 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 subcommandThe plot subcommand is similar to the decode subcommand but messages are visualized usingmatplotlibinstead of being printed to stdout.$candump-lvcan0$catcandump-2021-01-04_180521.log(1609779922.655421)vcan000000343#B204B9049C049C04(1609779922.655735)vcan00000024A#120527052E051905(1609779923.657524)vcan000000343#C404C404CB04C404(1609779923.658086)vcan00000024A#8B058B058B059205(1609779924.659912)vcan000000343#5C04790479045504(1609779924.660471)vcan00000024A#44064B0659064406(1609779925.662277)vcan000000343#15040704F203F203(1609779925.662837)vcan00000024A#8B069906A706A706(1609779926.664191)vcan000000343#BC03B503A703BC03(1609779926.664751)vcan00000024A#A006A706C406C406$catcandump-2021-01-04_180521.log|python3-mcantoolsplottests/files/dbc/abs.dbcIf 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.$catcandump-2021-01-04_180521.log|python3-mcantoolsplottests/files/dbc/abs.dbc'*33.*fl:-<''*33.*fr:->'-'*33.*rl:-<''*33.*rr:->'Signals with a different range of values can be displayed in the same subplot on different vertical axes by separating them with a comma.$catcandump-2021-01-04_180521.log|cantoolsplot--auto-colortests/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'Matplotlib comes with different preinstalled styles that you can use:$catcandump-2021-01-04_180521.log|cantoolsplottests/files/dbc/abs.dbc--styleseabornYou can try all available styles with$cantoolsplot--list-styles.|sed-n'/^- /s/^- //p'|whileIFS=read-rstyle;docatcandump-2021-01-04_180521.log|cantoolsplottests/files/dbc/abs.dbc--style"$style"--title"--style '$style'"doneFor more information see$python3-mcantoolsplot--helpNote that by default matplotlib is not installed with cantools. But it can be by specifying an extra
at installation:$python3-mpipinstallcantools[plot]The dump subcommandDump 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 subcommandPrint 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-mcantoolslist-atests/files/dbc/motohawk.dbcExampleMessage:Comment[None]:ExamplemessageusedastemplateinMotoHawkmodels.FrameID:0x1f0(496)Size:8bytesIsextendedframe:FalseSignals:Enable:Type:IntegerStartbit:7Length:1bitsUnit:-Issigned:FalseNamedvalues:0:DisabledThe generate C source subcommandGenerateCsource code from given database.The generated code contains:Messagestructs.Messagepackandunpackfunctions.Signalencodeanddecodefunctions.Frame id, length, type, cycle time and signal choicesdefines.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 istests/files/dbc/motohawk.dbc.$ python3 -m cantools generate_c_source tests/files/dbc/motohawk.dbc
Successfully generated motohawk.h and motohawk.c.Seemotohawk.handmotohawk.cfor the contents of the generated
files.In this example we use--use-floatso 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-nameto 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.Seemy_database_name.handmy_database_name.cfor the contents
of the generated files.In the next example we use--no-floating-point-numbersto generate
code without floating point types, i.e.floatanddouble.$ python3 -m cantools generate_c_source --no-floating-point-numbers tests/files/dbc/motohawk.dbc
Successfully generated motohawk.h and motohawk.c.Seemotohawk_no_floating_point_numbers.handmotohawk_no_floating_point_numbers.cfor the contents of the
generated files.In the last example--nodeis 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.Seemotohawk_sender_node.handmotohawk_sender_node.cfor the contents of the
generated files.Other C code generators:http://www.coderdbc.comhttps://github.com/howerj/dbcchttps://github.com/lonkamikaze/hsk-libs/blob/master/scripts/dbc2c.awkhttps://sourceforge.net/projects/comframe/The monitor subcommandMonitor CAN bus traffic in a text based user interface.$ python3 -m cantools monitor tests/files/dbc/motohawk.dbcThe 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.ContributingFork the repository.Install prerequisites.python3 -m pip install -e .[dev]Implement the new feature or bug fix.Implement test case(s) to ensure that future changes do not break
legacy.Run the lintersruff check src
mypy srcRun the tests.tox -e pyCreate a pull request.