Concordia FSAE Firmware Repo

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

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

2. Buck2 Usage

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

Notes

• To clean your current directory, run buck2 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: buck2 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 $(buck2 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 $(buck2 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