YAML CAN Description

Owned by Former user (Deleted)
Last updated: May 09, 2021
3 min read

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. 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.

  1. Create a new git branch in the HW Bridge repository
  2. In your new branch, make the necessary edits to the YAML CAN file (can/uwrt_mars_rover_can.yaml)
  3. In the root directory of the HW Bridge repository, run: python3 scripts/generate_can.py
  4. 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 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

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

size

  • The message size in bytes (max = 8)

senders

  • List of nodes that send this message

receivers

  • List of nodes 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

length

  • The length of the signal in bits

is_signed

  • 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

offset

  • The offset applied when converting between the raw signal value and the actual signal value

min

  • The minimum value of the decoded signal

max

  • 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.