How wsantos/santospilot works
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.