9 destinations
← CAN bus guides

August 27, 2026

Decode a CAN DBC File Locally with cantools

Inspect a DBC, decode live or recorded candump data locally, and validate byte order, scaling, units and multiplexed signals.

Turn a timestamped CAN capture into named engineering signals with a DBC file and the open-source cantools command line—without uploading a trace to a cloud service.

What a DBC file adds to a raw CAN frame

A raw Classical CAN record gives you an identifier, payload length, payload bytes and usually a timestamp. A DBC database can associate an identifier with a message name and describe signals inside the payload: start bit, bit length, byte order, signedness, scale, offset, unit, value choices and multiplexing.

For a numeric signal, tools commonly apply a linear conversion of the form:

physical value = raw value × scale + offset

The hard part is not running the equation. It is using the correct message definition for the exact network and software revision, and confirming byte order and multiplexor state.

1. Install cantools in an isolated Python environment

python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install --upgrade pip cantools
python3 -m cantools --help

Pin the package version in a project requirements file when the result must be reproducible. Keep the DBC revision, capture and tool version together.

2. Inspect the DBC before decoding traffic

List the database contents in a human-readable form:

python3 -m cantools list -a network.dbc

Check at least:

  • expected message identifiers and whether they use 11-bit or 29-bit frames;
  • payload length;
  • signal byte order, signedness, scale, offset and unit;
  • named values and multiplexors;
  • database source, revision and intended controller/software version.

Stop if the database and capture disagree on frame format or length. Do not “fix” the capture until the source of the mismatch is understood.

3. Decode a live SocketCAN stream

With a correctly configured can0 interface, pipe candump output into the decoder:

candump can0 | python3 -m cantools decode network.dbc

For a compact one-line view:

candump can0 | python3 -m cantools decode --single-line network.dbc

Decode a saved capture

Create a log with the can-utils log format:

candump -L can0 | tee can0-capture.log

Then decode the file locally:

cat can0-capture.log | python3 -m cantools decode --single-line network.dbc

Keep the untouched raw log. A decoded export is derived evidence; it should never replace the original bytes and timestamps.

4. Validate before trusting a named signal

  1. Start with a controlled stimulus. Change one known bench input through a safe, bounded range.
  2. Compare raw and decoded views. Confirm that the expected bits change and that unrelated signals remain stable.
  3. Check units and limits. A number can look reasonable while using the wrong unit, scale or signedness.
  4. Check timing. Compare the observed update period with the documented message cycle.
  5. Record exceptions. Missing messages, invalid values and multiplexor branches are part of the result.

Common reasons for convincing but wrong output

  • DBC for a different model year, firmware or option package;
  • 11-bit versus 29-bit identifier mismatch;
  • little-endian versus big-endian signal interpretation;
  • signed value decoded as unsigned;
  • multiplexed signal decoded under the wrong selector;
  • offset or unit ignored in a downstream spreadsheet.

Keep the workflow local

The MallMars pilot is intended to validate this capture → import → decode → record path in a local browser interface. Review the CAN Isolated target and exclusions; no cloud account or universal vehicle database is promised.

Primary references