# j-vanetten/openpilot architecture

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

- Interactive diagram: https://gitdiagram.com/j-vanetten/openpilot
- Repository: https://github.com/j-vanetten/openpilot

## Overview

##### Project type and purpose
- This is an embedded robotics operating system (“openpilot”) for advanced driver-assistance and semi-autonomous control in production vehicles.
- It runs as a collection of cooperating daemons on a comma AI device (comma 3X, etc.) inside a car, interfacing with sensors, vehicle CAN bus, and providing real-time control, vision, and UI.

##### File structure
- Top-level modules:
- system/ – low-level device daemons (hardwared, sensord, camerad, loggerd, locationd, modeld, controlsd, etc.)
- panda/ – the safety-certified board firmware and host driver (“Panda”) that sits on the CAN bus
- openpilot/ – high-level application code (selfdrive, UI, tools)
- cereal/ and msgq/ – Cap’n Proto definitions and messaging bridge libraries
- opendbc/ – automotive CAN database definitions and code generators
- common/ – shared utility libraries (logging, parameters, math, I/O)
- Build and deployment:
- SConstruct, Dockerfiles, Jenkinsfile, pyproject.toml

a. Hardware layer
– Vehicle sensors (camera, IMU, radar via DCAN/FD-CAN)
– Panda board – safety MCU + CAN interface
– Host SoC running Linux
b. System daemons (processes)
– sensord (IMU/GPS), camerad (camera capture), locationd (pose & calibration), modeld (neural network inference), controlsd/plannerd (trajectory planning & control), loggerd (data logging), manager (process supervision), ui (Qt-based user interface), pandad (host-side comms with Panda)
c. Middleware/message bus
– Cap’n Proto pub-sub via cereal/messaging bridging to ZeroMQ or local sockets
d. Data stores & config
– On-disk logs, parameter store (common/params), DBC definitions (opendbc)
e. External interfaces
– Wi-Fi/ethernet OTA updates, cloud telemetry (Athena), developer tools (tools/)

##### Relationships and data flow
- Sensors → sensord / camerad → publish CAN and video frames → modeld
- modeld → outputs detection, lane, lead car → plannerd (trajectory)
- plannerd → controlsd (lateral/longitudinal) → actuator commands → pandad → Panda → vehicle CAN
- manager → starts/stops all daemons, health checks
- loggerd subscribes to all topics to persist logs
- ui subscribes to key topics (live video, controls state, alerts) to render HMI
- locationd provides localization services to modeld and controlsd
- external Athena updater and registration modules run alongside for cloud sync

##### Architectural patterns and principles
- Microservices-style: many single-responsibility daemons communicating over a message bus
- Pub-sub messaging: decoupled producers/consumers via Cap’n Proto + ZeroMQ
- Safety domains: Panda enforces ISO 26262 safety rules in C, independent of host code
- Configuration & extensibility: DBC code generation (opendbc), Cap’n Proto schema (cereal), plugin-style “car ports” under selfdrive/car
- Build automation: SCons and Docker ensure reproducible cross-compilation

##### Key technologies, frameworks, and libraries
- Cap’n Proto schemas (cereal/*.capnp) and C++/Python codegen
- Python and C++ daemons, QML/Qt for UI
- SCons build system, Docker for containerized builds
- OpenCV, Eigen and custom CUDA/OpenCL runners for model inference
- ZeroMQ bridging layer (msgq)
- Flask or internal HTTP for developer tools (tools/)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hardware Layer
    subgraph "Hardware Layer"
        direction TB
        Sensors["Vehicle Sensors\n(camera, IMU, radar)"]:::hardware
        PandaFW["Panda Board Firmware"]:::hardware
        HostSoC["Host SoC (Linux)"]:::hardware
    end

    %% System Daemons Layer
    subgraph "System Daemons" 
        direction TB
        SensorD["sensord"]:::daemon
        CameraD["camerad"]:::daemon
        LocationD["locationd"]:::daemon
        ModelD["modeld"]:::daemon
        PlannerD["plannerd"]:::daemon
        ControlD["controlsd"]:::daemon
        LoggerD["loggerd"]:::daemon
        Manager["manager"]:::daemon
        PandaD["pandad"]:::daemon
    end

    %% Middleware Layer
    subgraph "Middleware / Message Bus"
        direction TB
        MsgBus["Messaging Bus\n(Cap'n Proto & ZeroMQ)"]:::middleware
        Schemas["Cap'n Proto Schemas"]:::middleware
    end

    %% Application / UI Layer
    subgraph "Application / UI"
        direction TB
        UI["UI (Qt-based)"]:::ui
    end

    %% Data Stores & Config
    subgraph "Data Stores & Config"
        direction TB
        Logs["On-disk Logs"]:::datastore
        Params["Parameter Store"]:::datastore
        DBC["DBC Definitions & Codegen"]:::datastore
    end

    %% External / Cloud
    subgraph "External / Cloud"
        direction TB
        Athena["Athena Updater & Telemetry"]:::external
        Tools["Developer Tools"]:::external
    end

    %% Connections: Hardware -> Daemons
    Sensors -->|publishes IMU/GPS| SensorD
    Sensors -->|captures video| CameraD
    PandaFW -->|CAN bus interface| PandaD
    HostSoC -->|runs daemons| Manager

    %% Daemons -> Middleware
    SensorD -->|pub CAN msgs| MsgBus
    CameraD -->|pub video frames| MsgBus
    LocationD -->|pub localization| MsgBus
    ModelD -->|sub video, CAN\npub detections| MsgBus
    PlannerD -->|sub detections\npub trajectory| MsgBus
    ControlD -->|sub trajectory\npub actuator cmd| MsgBus
    PandaD -->|sub actuator cmd\npub CAN| MsgBus
    LoggerD -->|sub all topics| Logs
    UI -->|sub key topics| MsgBus

    %% Middleware -> Daemons
    MsgBus -->|serves topics| ModelD
    MsgBus -->|serves topics| PlannerD
    MsgBus -->|serves topics| ControlD
    MsgBus -->|serves topics| LocationD
    MsgBus -->|serves topics| UI

    %% Config & Data Stores
    Params -->|used by| Manager
    Params -->|used by| DaemonDUMMY["*"] 
    DBC -->|codegen for| PlannerD
    DBC -->|codegen for| ControlD

    %% External interfaces
    Manager -->|runs updater| Athena
    Athena -->|OTA updates| HostSoC
    Tools -->|dev access| MsgBus

    %% Safety boundary highlight
    PandaFW -.->|ISO 26262 safety\nMCU boundary| HostSoC

    %% Click Events
    click PandaFW "https://github.com/j-vanetten/openpilot/tree/jvePilot-release/panda/board"
    click SensorD "https://github.com/j-vanetten/openpilot/blob/jvePilot-release/system/sensord/__init__.py"
    click SensorD "https://github.com/j-vanetten/openpilot/tree/jvePilot-release/system/sensord/sensors"
    click CameraD "https://github.com/j-vanetten/openpilot/blob/jvePilot-release/system/camerad/main.cc"
    click CameraD "https://github.com/j-vanetten/openpilot/tree/jvePilot-release/system/camerad/cameras/"
    click LocationD "https://github.com/j-vanetten/openpilot/blob/jvePilot-release/selfdrive/locationd/locationd.py"
    click ModelD "https://github.com/j-vanetten/openpilot/blob/jvePilot-release/selfdrive/modeld/modeld.py"
    click PlannerD "https://github.com/j-vanetten/openpilot/blob/jvePilot-release/selfdrive/controls/plannerd.py"
    click ControlD "https://github.com/j-vanetten/openpilot/blob/jvePilot-release/selfdrive/controls/controlsd.py"
    click LoggerD "https://github.com/j-vanetten/openpilot/blob/jvePilot-release/system/loggerd/loggerd.cc"
    click Manager "https://github.com/j-vanetten/openpilot/blob/jvePilot-release/system/manager/manager.py"
    click UI "https://github.com/j-vanetten/openpilot/tree/jvePilot-release/selfdrive/ui/qt/"
    click PandaD "https://github.com/j-vanetten/openpilot/blob/jvePilot-release/selfdrive/pandad/main.cc"
    click MsgBus "https://github.com/j-vanetten/openpilot/blob/jvePilot-release/cereal/messaging/bridge.cc"
    click MsgBus "https://github.com/j-vanetten/openpilot/tree/jvePilot-release/msgq_repo/msgq/"
    click Schemas "https://github.com/j-vanetten/openpilot/blob/jvePilot-release/cereal/*.capnp"
    click Params "https://github.com/j-vanetten/openpilot/blob/jvePilot-release/common/params.py"
    click Params "https://github.com/j-vanetten/openpilot/blob/jvePilot-release/common/params.cc"
    click DBC "https://github.com/j-vanetten/openpilot/tree/jvePilot-release/opendbc_repo/opendbc/"
    click Athena "https://github.com/j-vanetten/openpilot/blob/jvePilot-release/system/athena/athenad.py"
    click Athena "https://github.com/j-vanetten/openpilot/blob/jvePilot-release/system/athena/registration.py"
    click Tools "https://github.com/j-vanetten/openpilot/tree/jvePilot-release/tools/"

    %% Styles
    classDef hardware fill:#bbdefb,stroke:#0d47a1,color:#0d47a1;
    classDef daemon fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20;
    classDef middleware fill:#ffe0b2,stroke:#ef6c00,color:#e65100;
    classDef ui fill:#e1bee7,stroke:#6a1b9a,color:#4a148c;
    classDef datastore fill:#eceff1,stroke:#607d8b,color:#37474f;
    classDef external fill:#f5f5f5,stroke:#9e9e9e,color:#616161;
```
