How commaai/panda works
Project type and purpose
• This is an embedded firmware + host-side library project for automotive CAN/CAN-FD communication.
• Firmware runs on STM32F4/F7 MCUs (“board” folder).
• A Python userspace library (“python” folder) and assorted scripts/examples provide the host interface.
• A rich CI/test harness validates firmware, MISRA compliance, HIL tests, and Python code.
File structure
• Top-level folders:
– board: microcontroller firmware (bootloader, drivers, application, safety model)
– drivers: host OS drivers build scripts (SPI kernel module)
– python: host API library (USB, serial, SPI abstraction)
– scripts/examples: CLI tools, example code for CAN operations
– tests: unit tests, hardware-in-the-loop (HIL), MISRA checks
– CI configs: GitHub Actions (.github/workflows), Jenkinsfile, Dockerfile, SConstruct/SConscript build
• Build flow: SCons → firmware binaries; Python packaging via pyproject.toml; host driver build via Makefiles.
• Deployment: Dockerfile for reproducible environment; Jenkins/GitHub workflows for CI.
README for extra insights
• Safety model integration with opendbc.
• Heavy emphasis on code rigor: MISRA, cppcheck, Wall/extra flags, mutation tests.
• HIL tests that exercise CAN send/recv, loopback, USB/SPI latency.
• Host-side usage: USB bulk, CAN API, safety mode setting.
Main components
A. Hardware Layer (MCU board)
1. Bootstub (bootloader code)
2. Application firmware
– Core modules: main.c, bootstub.c
– Drivers: gpio, spi, bxcan/fdcan, timers, usb, interrupts, watchdog
– Safety model (opendbc integration)
– HAL + low-level register access (stm32f4/, stm32h7/)
3. Peripherals
– CAN buses, USB port, SPI bus, UART, I²C (if present)
– FPGA/power interfaces (fan, sound, etc.)
B. Host Layer
1. Python library (python/): Panda class, can_recv/send, dfu, serial, usb, spi abstractions
2. C++ bindings (referenced externally in openpilot)
3. Scripts/examples (scripts/, examples/) for diagnostics, health tests, flash, firmware queries
4. Linux driver build (drivers/spi/) for spidev support
C. CI & Test Infrastructure
1. Build pipelines: SCons build (SConstruct), Docker container, Jenkinsfile, GitHub Actions
2. Static analysis: cppcheck + MISRA checker
3. Unit tests: firmware (opendbc safety tests), Python (pytest, ruff, mypy)
4. HIL tests: tests/hitl scripts driving a real or simulated board
5. Release scripts: make_release.sh, test.sh, setup.sh
Relationships and data flows
• Host → USB/SPI → MCU bootstub/app (firmware download, DFU)
• Host ↔ CAN bus messages via firmware (forward, receive, send)
• Firmware → Safety module → CAN send authorization
• CI server → Build container → compile/flash → HIL rig → test harness
• Python API → USB interface → board firmware → physical CAN network
Architectural patterns & design principles
• Layered abstraction:
– Hardware Abstraction Layer (register headers under stm32f4/, stm32h7/)
– Driver layer (board/drivers/)
– Application layer (board/main.c + safety logic)
• Separation of concerns: safety code strictly in opendbc module, application code above HAL.
• Modular host library exposing a clean API (Panda class) decoupled from firmware internals.
• CI as code: all build and test steps defined in version-controlled workflow files.