sunnypilot Architecture Tour
sunnypilot is a fork of comma.ai's openpilot, an open source driver assistance system that runs on a dedicated device inside the car and drives the steering, gas, and brake through the car's own computers. This workshop is a tour of how that software is actually put together: how many separate programs are running at once, how they talk to each other without ever calling a function on one another directly, what happens between a camera frame arriving and the steering wheel moving, and where sunnypilot draws the line between "software suggests" and "hardware enforces."
You will finish able to open this codebase, know which of its many directories to look in for a given question, and trace a real recorded drive through the system with your own commands rather than by reading someone else's description of it.
This is Workshop 1 of a planned series; see Module 6 for where the rest of the series is headed and how each later workshop will build on what you learn here.
What you'll need to know already
This workshop assumes you're comfortable with Python, some C, git, and the Linux command line, and that you've built or debugged production software before. It does not assume any prior exposure to cars, driver-assistance systems, or robotics: Module 0 defines the domain vocabulary (what "ADAS" means, what a CAN bus is, what comma's "route" and "segment" terms mean) before it's used anywhere else.
What this tour covers
- Module 1 — every one of the ~40 processes that make up a running sunnypilot is started, watched, and restarted by one small program. You'll see the real list and the rules that decide which processes run when.
- Module 2 — those processes never call each other directly. You'll look at the messaging layer underneath all of them, and use it yourself to listen in on a live system from a plain Python script.
- Module 3 — a single instant from a real, recorded drive, followed from a camera frame through to a planned trajectory, using your own capture of the actual messages a running system produced.
- Module 4 — sunnypilot's own layer on top of openpilot for deciding, moment to moment, whether assistance is active, paused, or has just been overridden by the driver. You'll watch it flip states on a real drive and match each flip to the line of code that caused it.
- Module 5 — the point in the system where a decision stops being a suggestion and starts being physically constrained, and why that point is not where you might guess.
- Module 6 — how to reproduce every experiment in this workshop yourself, plus where the series goes next.
Prerequisites
Everything in this workshop was captured on this exact checkout, using its bundled uv-managed
Python environment and its already-built C++ tools. Module 6 has the full reproduction steps; the
short version is:
source .venv/bin/activate
run before any Python command in this workshop, and the tools/replay/replay binary already
built and ready to fetch a public demo drive with no car, hardware, or comma account required.