# wsantos/santospilot architecture

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

- Interactive diagram: https://gitdiagram.com/wsantos/santospilot
- Repository: https://github.com/wsantos/santospilot

## Overview

##### Project type and purpose
- This is a full-stack, embedded driver-assistance system (openpilot/FrogPilot).
- Runs on a Linux-based “comma” device plus a microcontroller-based CAN interface board (“Panda”).
- Provides camera-based perception, model inference, planning, control, UI, logging, and CAN bus actuation.

##### Top-level modules (from the file tree)
- cereal – message schema (Cap’n Proto) and codegen for IPC
- common – shared helper libraries (file I/O, params, logging, math)
- msgq/msgq_repo – Python C-extension wrappers around ZeroMQ + Capnp IPC
- opendbc – CAN DBC databases and packer/parser for vehicle messages
- panda – firmware (STM32) + Python API for CAN, USB, DFU
- selfdrive – core services: camerad, modeld, controlsd, locationd, navd, plannerd, etc.
- system – low-level daemons (hardware abstraction, procs, loggerd, sensord, manager)
- ui – Qt/QML offroad/onroad interface + translation assets
- tools – web tools (fleet manager, teleop), CLI utilities
- third_party – 3rd-party libs (acados MPC solver, JSON11, Kaitai, map renderer)

##### Architectural pattern
- Microservices (one process per function) supervised by a central manager (system/manager).
- Publish/subscribe / RPC via Cap’n Proto over ZeroMQ (msgq).
- Build and deploy using SCons for native binaries and Python packaging.

##### Main components & interactions
A. Hardware layer
- Cameras & Sensors → camerad (system/camerad)
- Panda MCU (CAN, USB) ←→ panda Python API
- GPS modem → qcomgpsd / ubloxd
- IMU, accelerometer via sensord
B. IPC backbone
- msgq (ZeroMQ + Capnp) – message bus shared by all daemons
C. Core services (selfdrive)
1. camerad – captures raw frames, publishes image messages
2. modeld / classic_modeld / tinygrad_modeld – runs neural nets on frames, outputs detection & path
3. locationd – dead-reckons & GPS, publishes vehicle pose
4. navd – map rendering & route guidance
5. controlsd – consumes model & localization, publishes actuator setpoints
6. plannerd / frogpilot_planner – higher-level path, turn anticipation, map speed controller
D. Actuation
- controlsd → msgq → panda API → CAN bus messages to car ECUs
E. UI
- ui/qt – subscribes to onroad/offroad state, displays camera view, path overlay, gauges
- web-based fleetmanager – Python Flask app accesses logs, telemetry via filesystem or uploader
F. Logging & telemetry
- loggerd – subscribes to all topics, writes to disk, rotates logs, invokes uploader
- uploader (system/loggerd/uploader.py) – optionally pushes logs to cloud
G. Process management
- system/manager – reads process_config, starts/stops/restarts daemons
- updated – handles software updates via casync

##### Architectural patterns & principles
- Single Responsibility: each daemon does one job.
- Loose coupling via message bus.
- Clear separation: perception → planning → control → actuation → UI.
- Hardware abstraction layer isolates Panda firmware from Python API.
- Build-time codegen (Capnp, DBC packer/parser, acados C code) for serialization & MPC.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Layer
    subgraph "Hardware Layer"
        style HardwareLayer fill:none,stroke:none
        cameras["Cameras"]:::hardware
        imu_gps["IMU / GPS"]:::hardware
        panda_fw["Panda Firmware"]:::hardware
        panda_api["Panda Python API"]:::hardware
        cameras -->|video feed| camerad
        imu_gps -->|IMU data| sensord
        imu_gps -->|GPS data| qcomgpsd
        imu_gps -->|GPS data| ubloxd
        panda_api -->|flashing| panda_fw
    end

    %% IPC Backbone
    subgraph "IPC Backbone"
        style IPCBackbone fill:none,stroke:none
        msgq["msgq (ZeroMQ + Capnp)"]:::infra
    end

    %% Core Services
    subgraph "Perception Services"
        style Perception fill:none,stroke:none
        camerad["camerad"]:::perception
        modeld["modeld"]:::perception
        classic_modeld["classic_modeld"]:::perception
        tinygrad_modeld["tinygrad_modeld"]:::perception
        camerad -->|images| modeld
        camerad -->|images| classic_modeld
        camerad -->|images| tinygrad_modeld
    end

    subgraph "Data Services"
        style DataServices fill:none,stroke:none
        locationd["locationd"]:::dataservices
        navd["navd"]:::dataservices
        sensord["sensord"]:::infra
        qcomgpsd["qcomgpsd"]:::infra
        ubloxd["ubloxd"]:::infra
        sensord -->|IMU topics| locationd
        qcomgpsd -->|GPS topics| locationd
        ubloxd -->|GPS topics| locationd
    end

    subgraph "Planning & Control"
        style PlanningControl fill:none,stroke:none
        plannerd["plannerd"]:::planning
        controlsd["controlsd"]:::planning
        locationd -->|pose| plannerd
        navd -->|route| plannerd
        modeld -->|detections| controlsd
        classic_modeld -->|detections| controlsd
        tinygrad_modeld -->|detections| controlsd
        plannerd -->|trajectory| controlsd
        controlsd -->|actuators| panda_api
    end

    %% Logging & Updates
    subgraph "Logging & Updates"
        style LoggingUpdates fill:none,stroke:none
        loggerd["loggerd"]:::infra
        uploader["uploader"]:::infra
        updated["updated"]:::infra
        camerad -->|logs| loggerd
        modeld -->|logs| loggerd
        classic_modeld -->|logs| loggerd
        tinygrad_modeld -->|logs| loggerd
        locationd -->|logs| loggerd
        navd -->|logs| loggerd
        plannerd -->|logs| loggerd
        controlsd -->|logs| loggerd
        loggerd -->|upload| uploader
        uploader -->|cloud storage| external_cloud
        updated -->|restart| manager
    end

    %% Process Management
    subgraph "Process Management"
        style ProcessManagement fill:none,stroke:none
        manager["manager"]:::infra
        hardwared["hardwared"]:::infra
        manager -->|supervises| camerad
        manager -->|supervises| modeld
        manager -->|supervises| classic_modeld
        manager -->|supervises| tinygrad_modeld
        manager -->|supervises| locationd
        manager -->|supervises| navd
        manager -->|supervises| plannerd
        manager -->|supervises| controlsd
        manager -->|supervises| loggerd
        manager -->|supervises| updated
        manager -->|supervises| sensord
        manager -->|supervises| qcomgpsd
        manager -->|supervises| ubloxd
        manager -->|supervises| hardwared
    end

    %% UI Layer
    subgraph "UI & Tools"
        style UI fill:none,stroke:none
        qtui["Qt/QML UI"]:::ui
        translations["UI Translations"]:::ui
        fleetmanager["FrogPilot FleetManager"]:::ui
        msgq -->|UI topics| qtui
        msgq -->|fleet topics| fleetmanager
        loggerd -->|logs| fleetmanager
    end

    %% External Systems
    subgraph "External Systems"
        style ExternalSystems fill:none,stroke:none
        external_map["Map Tile Server"]:::external
        external_cloud["Remote Log Storage"]:::external
        navd -->|tile requests| external_map
    end

    %% Build & Codegen
    subgraph "Build & Codegen"
        style Codegen fill:none,stroke:none
        cereal["cereal"]:::infra
        common["common"]:::infra
        opendbc["opendbc"]:::infra
        msgq_repo["msgq_repo/msgq"]:::infra
        acados["third_party/acados"]:::infra
    end

    %% Connections to IPC
    camerad -->|pub/sub| msgq
    modeld -->|pub/sub| msgq
    classic_modeld -->|pub/sub| msgq
    tinygrad_modeld -->|pub/sub| msgq
    locationd -->|pub/sub| msgq
    navd -->|pub/sub| msgq
    plannerd -->|pub/sub| msgq
    controlsd -->|pub/sub| msgq
    loggerd -->|pub/sub| msgq
    updated -->|pub/sub| msgq
    sensord -->|pub/sub| msgq
    qcomgpsd -->|pub/sub| msgq
    ubloxd -->|pub/sub| msgq
    hardwared -->|pub/sub| msgq

    %% Legend
    subgraph "Legend"
        A["Perception"]:::perception
        B["Planning & Control"]:::planning
        C["Data Services"]:::dataservices
        D["Infrastructure"]:::infra
        E["UI & Tools"]:::ui
        F["Hardware"]:::hardware
    end

    %% Click Events
    click cereal "https://github.com/wsantos/santospilot/tree/FrogPilot/cereal/"
    click common "https://github.com/wsantos/santospilot/tree/FrogPilot/common/"
    click msgq_repo "https://github.com/wsantos/santospilot/tree/FrogPilot/msgq_repo/msgq/"
    click opendbc "https://github.com/wsantos/santospilot/tree/FrogPilot/opendbc/"
    click panda_fw "https://github.com/wsantos/santospilot/tree/FrogPilot/panda/board/"
    click panda_api "https://github.com/wsantos/santospilot/tree/FrogPilot/panda/python/"
    click camerad "https://github.com/wsantos/santospilot/tree/FrogPilot/system/camerad/"
    click modeld "https://github.com/wsantos/santospilot/tree/FrogPilot/selfdrive/modeld/"
    click classic_modeld "https://github.com/wsantos/santospilot/tree/FrogPilot/selfdrive/classic_modeld/"
    click tinygrad_modeld "https://github.com/wsantos/santospilot/tree/FrogPilot/selfdrive/tinygrad_modeld/"
    click locationd "https://github.com/wsantos/santospilot/tree/FrogPilot/selfdrive/locationd/"
    click navd "https://github.com/wsantos/santospilot/tree/FrogPilot/selfdrive/navd/"
    click plannerd "https://github.com/wsantos/santospilot/blob/FrogPilot/selfdrive/controls/plannerd.py"
    click controlsd "https://github.com/wsantos/santospilot/blob/FrogPilot/selfdrive/controls/controlsd.py"
    click loggerd "https://github.com/wsantos/santospilot/tree/FrogPilot/system/loggerd/"
    click uploader "https://github.com/wsantos/santospilot/blob/FrogPilot/system/loggerd/uploader.py"
    click manager "https://github.com/wsantos/santospilot/tree/FrogPilot/system/manager/"
    click updated "https://github.com/wsantos/santospilot/tree/FrogPilot/system/updated/"
    click sensord "https://github.com/wsantos/santospilot/tree/FrogPilot/system/sensord/"
    click qcomgpsd "https://github.com/wsantos/santospilot/tree/FrogPilot/system/qcomgpsd/"
    click ubloxd "https://github.com/wsantos/santospilot/tree/FrogPilot/system/ubloxd/"
    click hardwared "https://github.com/wsantos/santospilot/blob/FrogPilot/system/hardware/hardwared.py"
    click qtui "https://github.com/wsantos/santospilot/tree/FrogPilot/selfdrive/ui/qt/"
    click translations "https://github.com/wsantos/santospilot/tree/FrogPilot/selfdrive/ui/translations/"
    click fleetmanager "https://github.com/wsantos/santospilot/tree/FrogPilot/selfdrive/frogpilot/fleetmanager/"

    %% Styles
    classDef perception fill:#a2f5a2,stroke:#333,stroke-width:1px
    classDef planning fill:#a2c4f5,stroke:#333,stroke-width:1px
    classDef dataservices fill:#f5c18a,stroke:#333,stroke-width:1px
    classDef infra fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef ui fill:#dfa2f5,stroke:#333,stroke-width:1px
    classDef hardware fill:#f5f1a2,stroke:#333,stroke-width:1px
    classDef external fill:#e0e0e0,stroke:#333,stroke-width:1px
```
