Concordia FSAE Firmware Repo

This repository contains the embedded firmware, host-side drive software, CAN network definitions, and simulation tooling for the Concordia FSAE vehicle.

The repository's reusable simulation framework and CAN code generator are documented separately:

• Rig is the firmware-independent Python/Rust simulation and scheduling library.
• Yamcan validates the YAML CAN network definition and generates the C, Rust, DBC, statistics, and manifest artifacts consumed by firmware and host applications.
• Simulation bindings adapt Rig to this firmware's peripherals and generated ABIs.
• Simulation models implement the component, controller, and vehicle behavior exercised by the simulation tests.

Documenting the Code

README.md should be stored in each component folder. See below for programming guidelines for this repository.

Component Folder and File Hierarchy

Embedded Components

Name	Designator	Path	Comments
Steering Wheel	stw	components/steering_wheel/	Steering Wheel Controller
BMS Boss	bmsb	components/bms_boss/	Battery Management System Boss Controller
BMS Worker	bmsw	components/bms_worker/	Battery Management System Boss Controller
Bootloader	bl	components/bootloader/	Embedded Bootloaders for all Controllers
Heartbeat	heartbeat	components/heartbeat/	Generic Heartbeat Application for all Controllers
Front Vehicle Controller	vcfront	components/vc/front	Vehicle Controller code specific to the Front Controller
Power Distribution Unit	vcpdu	components/vc/pdu	Vehicle Controller code specific to the Power Distribution Unit
Rear Vehicle Controller	vcrear	components/vc/rear	Vehicle Controller code specific to the Rear Controller

Drive Software - Linux

Name	Designator	Path	Comments
Can Bridge	can-bridge	drive-stack/can-bridge	Handles bridging and decoding CAN messages over IPC
Concordia UDS Tool	conUDS	drive-stack/conUDS	Tool to drive UDS sessions with controllers.

Platforms

Platform	Designator	Comments
CFR24	cfr24	Competition car for 2024
CFR25	cfr25	Competition car for 2025

Sections

• Each component is broken into 3 main code sources

1. Source Code
   • The source code is typically located in ./components/$COMPONENT_DESIGNATOR/ for each component
   • Hardware sources to be included ./components/$DESIGNATOR/HW/mcuConfig.yaml unless multiple platforms are supported
   • The source code, while it varies between component, has these typical areas:
     1. ./components/$COMPONENT_DESIGNATOR/build/
        • Contains all object files, binary files, etc...
     2. ./components/$COMPONENT_DESIGNATOR/generated/
        • Contains code generated by scripts and/or programs which is used by the embedded system
     3. ./components/$COMPONENT_DESIGNATOR/HW/
        • Contains all firmware source code and header files which interfaces between System Calls and the Hardware
     4. ./components/$COMPONENT_DESIGNATOR/include/
        • Contains all System and Application header files
     5. ./components/$COMPONENT_DESIGNATOR/lib/
        • Contains any library source code and header files which the System uses
     6. ./components/$COMPONENT_DESIGNATOR/RTOS -Contains all source code and header files relating to the implementation of the System's RTOS
     7. ./components/$COMPONENT_DESIGNATOR/src
        • Contains all System and Application level source code
     8. ./components/$COMPONENT_DESIGNATOR/BUCK
        • Defines the build targets for that component
     9. ./components/shared/: Team libraries, configurations, drivers, firmware, and other...
2. Embedded System
   • Contains libraries, openocd configurations, and platform code accessible to all devices located in ./embedded/
   • Select important sections:
     1. ./embedded/libs/CMSIS/: Controller independant system level library
        • Used for RTOS and other controller independant systems
     2. ./embedded/platforms/: Supported Hardware and MCU platforms
        • Contains the HAL/LL, startup code, and link script for the STM32 family of devices in ./embedded/platforms/stm32/
3. Chip Configuration
   • The chip configuration is stored in YAML files in ./embedded/platforms/$CHIP.yaml

Setting Up and Using the Development Environment

Workflows

1. Installation and Set-Up

Buck2

Note: We use buckle to get a deterministic buck2 version and prelude to ensure a homogenous development environment. See: https://github.com/benbrittain/buckle

1. Install buckle, reindeer, and uv on your host system.

2. Buck2 Usage

1. Build a target with buckle build //$TARGET_PATH:$TARGET_NAME
   • You can specify a specific local output directory with buckle build ... --out $SOME_LOCAL_PATH
   • buck2/buckle (when not specified) outputs the files to some deep folder in buck-out/
2. Run software locally with buckle run //$TARGET_PATH:$TARGET_NAME
   • Software must be compatible with your host system

3. Simulation and CAN Tooling

The main simulation and network checks are available through Buck:

# Run the standalone Rig tests and every simulation test target.
buckle test //tools/rig/... //sim/...

# Build the validated CAN network cache and common network artifacts.
buckle build //network:network
buckle build //network:dbc --out dbc/
buckle build //network:stats --out stats/
buckle build //network:manifest-uds --out manifest-uds.yaml

Firmware and drive-stack targets use the macros in tools/yamcan/defs.bzl to generate node-specific CAN code. The generated files are build outputs; edit the YAML definitions under network/definition/ instead of generated artifacts.

4. Formatting

This repository uses pre-commit for formatting checks. The configured formatters are:

• uncrustify for C/C++ sources using uncrustify.cfg
• yamlfmt for YAML files using yamlfmt.yaml

Install the tools locally:

Install pixi:

curl -fsSL https://pixi.sh/install.sh | sh

Install pre-commit and prek:

pip3 install pre-commit prek

Install the pinned uncrustify binary:

pixi install

Install the Git hook:

pre-commit install

Run formatting on all files:

pre-commit run --all-files

Useful commands:

• Run all formatting checks with CI-style output: pre-commit run --all-files --show-diff-on-failure
• Run only C/C++ formatting: pre-commit run uncrustify --all-files
• Run only YAML formatting: pre-commit run yamlfmt --all-files
• Check active uncrustify version: pixi run uncrustify --version

CI runs the same pre-commit formatting checks in .github/workflows/formatting.yml. If branch protection requires that workflow, pull requests will be blocked until formatting passes.

Notes

• To clean your current directory, run buckle clean
• If doing loading/debugging of physical hardware, the ST-LINK or other interface must be plugged in by USB before starting the container. Docker containers do not support dynamic loading of USB peripherals
  • Note: This only works if no bootloader is installed. If a bootloader is installed and you are debugging through JTAG, you should still flash over CAN

Compilation Database

Tools like clangd use a compilation database (typically compile_commands.json)to provide lots of useful functionality like jump-to-def, show-refs, etc.

We support building compilation databases for our components! For example, to build the compilation database for the steering wheel, you would run: buckle bxl buck2/tools/comp_db.bxl:gen -- --targets //components/steering_wheel:elf

This will produce a compile_commands.json file in directory such as buck-out/v2/gen-bxl/root/7439b47151304f30/buck2/tools/comp_db.bxl/__gen__/fe0a63d85e25de4b/compile_commands.json

You probably want to symlink this into the root of the repo so that tools like clangd can find it. You can do this with a single command pretty easily like this:

ln -sf $(buckle bxl buck2/tools/comp_db.bxl:gen -- --targets //components/steering_wheel:elf) $(git rev-parse --show-toplevel)

If you like, you can take this a step further by defining an alias for this in your shell (~/.bashrc, ~/.zshrc, etc.), for example:

compdb() {
    local targets
    targets=$1

    local root
    root=$(git rev-parse --show-toplevel)`

    ln -sf $(buckle bxl buck2/tools/comp_db.bxl:gen -- --targets "$1") "$root"
}

Which you can them simply run directly as: compdb //components/steering_wheel:elf!

Relevant links: Implementation in buck2: facebook/buck2#810 Discussion around improving user experience around running BXLs: facebook/buck2#86