Rationale
DBC files are an extremely powerful way of describing CAN data. However, DBC syntax can be quite confusing to decode, making DBC files not the friendliest to read or edit. To prevent unnecessary frustration over editing DBC files, the team is instead using a custom YAML format to define all mars rover CAN data in a human-readable way. YAML is extremely simple to pick up, reads just like English, and is great for storing serializable data, making it the perfect candidate to store descriptions of CAN data. There also exists many tools and libraries for manipulating YAML files in popular scripting languages such as Python, making it very flexible to work with YAML and tailor it to our CAN needs.
How it Works
All the essential DBC information is stored in the YAML CAN file. A python script takes care of generating the DBC file based on the information specified in the YAML file. The script also generates the C header and source files for encoding, decoding, packing, and unpacking CAN data based on the information supplied from the DBC file.
UWRT YAML CAN Format
All descriptions of mars rover CAN messages and signals are stored in a single YAML file located in the UWRT Hardware Bridge GitHub repository. The HW bridge repo is shared between the Firmware and Software teams so CAN descriptions are standardized between teams.
Bus
The first entry at the top-most level of the YAML CAN file is the rover CAN bus. The CAN bus entry has the following fields:
nodes
- List of all nodes in the bus
messages
- List of all CAN messages in the bus
Message
Each CAN message entry has the following fields:
comment
- Brief description of the CAN message
id
- The message CAN ID (in decimal)
size
- The message size in bytes (max = 8)
senders
- List of nodes that send this message
receivers
- List of ndoes that receive this message
frequency
- Frequency in Hz at which the message is transmitted. If the message is one-shot, it has a frequency of 0.
signals
- List of all signals in the message
Signal
Each CAN signal entry has the following fields:
comment
- Brief description of the CAN signal
startbit
- The index of the starting bit of the signal within the message
length
- The length of the signal in bits
is_signed
- True if the raw signal value is signed, false if it's unsigned
scale
- The scale applied when converting between the raw signal value and the decoded signal value
offset
- The offset applied when converting between the raw signal value and the actual signal value
unit
- The units of the signal
values
- If the signal has choices, this field lists the key-value pairs of raw signal value to choice mappings
min
- The minimum value of the decoded signal
max
- The maximum value of the decoded signal
NOTE:
For each signal, you can provide either the scale/offset fields or the min/max fields, or both. If only one of these pairs is provided, the other pair will be automatically generated based on the signal length and the values of what was provided.