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 YAML 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. The code generation suite makes use of the cantools API.
Making Changes to Rover CAN
Because the entirety of the rover's CAN messages are described in a single YAML file, you should follow the procedure outlined below when implementing or updating features that rely on CAN.
- Create a new git branch in the HW Bridge repository
- In your new branch, make the necessary edits to the YAML CAN file (can/uwrt_mars_rover_can.yaml)
- In the root directory of the HW Bridge repository, run:
python3 scripts/generate_can.py - You can now make use of any of the generated CAN enums, structs, and functions under can/generated
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 YAML file is the rover CAN bus. The CAN bus entry has the following fields:
bus_frequency
- The frequency (Hz) or bitrate (bps) of the CAN bus
canid_filter_mask
- Mask used for filtering the address portion of rover CAN ID
canid_filters
- Rover CAN ID filter values
nodes
- List of all nodes in the bus
roboteq_canids
- CAN IDs of Roboteq messages
messages
- List of all CAN messages in the bus
Message
...
Each CAN message entry has the following fields:
...
- Brief description of the CAN message
id
- The message CAN ID (in decimal)
size
- The message size in bytes (max = 8)
...
- List of nodes that send this message
receivers
- List of ndoes nodes that receive this message
...
- List of all signals in the message
Signal
...
Each CAN signal entry has the following fields:
...
- 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
...
- True if the raw signal value is signed, false if it's unsigned
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
scale
- The scale applied when converting between the raw signal value and the decoded signal value
...
- 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 signal value to choice mappings
min
- The minimum value of the decoded signal
...
- The maximum value of the decoded signal
...
NOTES
- 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.
- The signal min/max bounds do not include the signal SNA value (SNA = signal not available). The value of SNA is generally set to the maximum value representable by the signal.