DBC Files

Owned by c552li@uwaterloo.ca (Deactivated)
Last updated: Apr 08, 2021
3 min read

What is a DBC File?

A lot of different types of data get sent over CAN, ranging from sensor readings to actuator control commands to fault indicators, but at the end of the day a CAN message is just a sequence of raw data bytes. How can we interpret these sequences of bytes as meaningful pieces of information? That's where DBC files come in. A DBC (Database CAN) file is a way of describing how CAN data is encoded or decoded. Each CAN message and signal in a bus is described in DBC syntax, telling you exactly what is represented by the message or signal and how it is structured.

DBC Syntax

DBC files can be difficult to read since the syntax is quite cryptic. Here's a breakdown of how it works (there are more DBC topics that aren't covered here but these are the main ones seen in the rover DBC file):

DBC Message Syntax

BO_ <CAN ID> <message name>: <length in bytes> <sender>

  • BO_: each CAN message in a DBC file starts with "BO_"
  • CAN ID: the decimal value of the 11-bit CAN ID (or 29-bit for extended CAN)
  • Message name: name given to the CAN message (1-32 characters, may contain A-z, digits, and underscores)
  • Length in bytes: the length of the CAN payload in bytes
  • Sender: the node that transmits the CAN message

Example:

BO_ 1569 ARM_setControlMode: 3 JETSON

  • This describes a CAN message called "ARM_setControlMode" with CAN ID 1569 (0x621). It has a size of 3 bytes and is sent by the Jetson node.

DBC Signal Syntax

SG_ <signal Name> : <start bit>|<length><endianness><sign> (<scale>,<offset>) [<min>|<max>] "<unit>" <receiver>

  • SG_: each CAN signal in a DBC file starts with "SG_"
  • Signal name: name given to the CAN signal (1-32 characters, may contain A-z, digits, and underscores)
  • Start bit: the index of the first bit of the signal within the CAN message
  • Length: length of the signal in bits
  • Endianness: @1 for little-endian, @0 for big-endian
  • Sign: + for unsigned signal, - for signed
  • Scale: used to convert the raw signal value to the physical value (see conversion formula below)
  • Offset: used to convert the raw signal value to the physical value (see conversion formula below)
  • Min: (optional) the minimum physical value of the signal
  • Max: (optional) the maximum physical value of the signal
  • Unit: the units of the signal
  • Receiver: the node that receives the signal

Raw to Physical Value Conversion:

physical_value = offset + scale * raw_value

Example:

SG_ ARM_turntableControlMode : 0|3@1+ (1.0,0.0) [0.0|6.0] "" ARM

  • This describes a CAN signal called "ARM_turntableControlMode" that starts on bit 0 of the CAN message, has a length of 3 bits, is unsigned, and has a little endian byte order. The scale is 1.0 and offset is 0.0, giving a min of 0.0 and max of 6.0 (not including SNA value). This particular signal doesn't have units, and is received by the arm node.

Value Tables

Some CAN signals have enum-type states representable by integer signal values. Value tables provide a way of mapping state descriptions to signal values. The syntax is as follows:

VAL_ <CAN ID> <signal name> <value1> "<state1>" <value2> "<state2>" ... ;

  • VAL_: each value table in the DBC file starts with "VAL_"
  • CAN ID: the CAN ID of the message containing the signal
  • Signal name: name given to the CAN signal
  • Value-state pairs: list of values to states

Example:

VAL_ 1569 ARM_turntableControlMode 0 "OPEN_LOOP" 1 "POSITION" 2 "VELOCITY" 3 "CURRENT" 7 "SNA" ;

  • This value table corresponds to the ARM_turntableControlMode signal from CAN message ID 1569. A signal value of 0 represents open loop control, 1 represents position control, 2 represents velocity control, 3 represents current control, and 7 is the SNA (signal not available) value.

Comments

Comments are text descriptions of a CAN message or signal that give more information about the CAN data.

The syntax for message comments is:

CM_ BO_ <CAN ID> "<comment>";

Example:

CM_ BO_ 1569 "Set control mode for arm joints";

The syntax for signal comments is:

CM_ SG_ <CAN ID> <signal name> "<comment>";

Example:

CM_ SG_ 1569 ARM_clawControlMode "Arm claw control mode";

Further Reading