# commaai/panda architecture

> Architecture diagram of the GitHub repository commaai/panda, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/commaai/panda
- Repository: https://github.com/commaai/panda

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Board Firmware Layer
    subgraph "Board Firmware"
        direction TB
        Bootloader["Bootloader"]:::firmware
        Application["Application Firmware"]:::firmware
        Drivers["Firmware Drivers"]:::firmware
        HAL1["STM32F4 HAL"]:::firmware
        HAL2["STM32H7 HAL"]:::firmware
        Safety["Safety Model"]:::firmware
        Jungle["Jungle Variant Firmware"]:::firmware
    end

    %% Hardware Peripherals
    subgraph "Hardware Peripherals"
        direction TB
        PER_CAN["CAN Buses"]:::hardware
        PER_USB["USB Port"]:::hardware
        PER_SPI["SPI Bus"]:::hardware
        PER_UART["UART"]:::hardware
        PER_I2C["I²C"]:::hardware
        PER_FPGA["FPGA/Power IF"]:::hardware
    end

    %% Host Ecosystem Layer
    subgraph "Host Ecosystem"
        direction TB
        PyLib["Python Host Library"]:::host
        Scripts["Scripts & Examples"]:::host
        CXX["C++ Bindings"]:::host
        DriverHost["Linux Kernel Driver (SPI)"]:::host
    end

    %% CI & Test Infrastructure
    subgraph "CI & Test Infrastructure"
        direction TB
        Build["Build System"]:::ci
        Static["Static Analysis"]:::ci
        Unit["Unit Tests"]:::ci
        HIL["HIL Tests"]:::ci
        Release["Release Scripts"]:::ci
    end

    %% Data Flows and Dependencies
    PyLib -->|USB/SPI| Bootloader
    PyLib -->|USB/SPI| Application
    DriverHost -->|SPI| Application
    Application -->|CAN| PER_CAN
    Application -->|USB| PER_USB
    Application -->|SPI| PER_SPI
    Application -->|UART| PER_UART
    Application -->|I²C| PER_I2C
    Application -->|FPGA/Power| PER_FPGA
    Safety -->|integrated into| Application
    HAL1 -->|provides registers| Application
    HAL2 -->|provides registers| Application
    HAL1 -->|provides registers| Drivers
    HAL2 -->|provides registers| Drivers
    Bootloader -->|DFU| Application

    Build -->|compiles| Bootloader
    Build -->|compiles| Application
    Build -->|packages| PyLib
    Build -->|builds| DriverHost
    Static -->|analyzes| Application
    Static -->|analyzes| Drivers
    Unit -->|tests| PyLib
    Unit -->|tests| Drivers
    HIL -->|executes on| Application
    HIL -->|executes on| Bootloader
    Release -->|publishes| PyLib
    Release -->|publishes| Application

    %% Click Events
    click Bootloader "https://github.com/commaai/panda/blob/master/board/bootstub.c"
    click Application "https://github.com/commaai/panda/blob/master/board/main.c"
    click Drivers "https://github.com/commaai/panda/blob/master/board/drivers/gpio.h"
    click HAL1 "https://github.com/commaai/panda/tree/master/board/stm32f4/"
    click HAL2 "https://github.com/commaai/panda/tree/master/board/stm32h7/"
    click Safety "https://github.com/commaai/panda/blob/master/board/health.h"
    click Jungle "https://github.com/commaai/panda/blob/master/board/jungle/main.c"
    click PyLib "https://github.com/commaai/panda/blob/master/python/__init__.py"
    click Scripts "https://github.com/commaai/panda/tree/master/scripts/"
    click DriverHost "https://github.com/commaai/panda/blob/master/drivers/spi/spidev_panda.c"
    click Build "https://github.com/commaai/panda/tree/master/SConstruct"
    click Static "https://github.com/commaai/panda/blob/master/tests/misra/checkers.txt"
    click Unit "https://github.com/commaai/panda/blob/master/tests/usbprotocol/test_comms.py"
    click HIL "https://github.com/commaai/panda/blob/master/tests/hitl/1_program.py"
    click Release "https://github.com/commaai/panda/blob/master/scripts/make_release.sh"

    %% Styles
    classDef firmware fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef host fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef ci fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef hardware fill:#D3D3D3,stroke:#000,stroke-width:1px;
```
