This document provides an overview of the development and debugging tools available in openpilot. These tools enable developers to analyze CAN bus data, debug system behavior, validate changes, and iterate on implementations efficiently. For detailed information about testing frameworks and CI/CD infrastructure, see Development and Testing.
The openpilot development toolchain consists of interactive GUI applications for data analysis, specialized command-line utilities for system introspection, and a unified CLI entry point op.sh for environment management.
| Category | Primary Tools | Purpose |
|---|---|---|
| CLI Entry Point | op.sh | Unified script for setup, dependency management, and tool execution tools/op.sh22-33 |
| Interactive Analysis | Cabana | CAN bus analysis, DBC editing, signal visualization tools/README.md49 |
| Log Replay | Replay | High-fidelity re-running of recorded drives with service publishing tools/README.md54 |
| Visualization | PlotJuggler / JotPluggler | Time-series telemetry plotting and synchronized visualization tools/README.md53 |
| Command-Line Debug | dump.py | Real-time cereal message inspection |
| Remote Access | ssh.py / adb_ssh.sh | Helpers for connecting to devices over comma prime SSH proxy or ADB tools/scripts/ssh.py12-19 tools/scripts/adb_ssh.sh4-32 |
Sources: tools/op.sh1-33 tools/README.md46-59 tools/scripts/adb_ssh.sh1-43 tools/scripts/ssh.py1-58
The following diagram illustrates how various data sources interface with the primary development tools through unified log and route abstractions.
Title: Tooling Data Flow and Code Entities
Sources: tools/cabana/mainwin.cc30-36 tools/lib/logreader.py150-165 tools/lib/route.py24-32
Cabana is a Qt-based GUI application for analyzing CAN bus data and editing DBC files. It supports multiple data sources and provides real-time visualization. The MainWindow orchestrates several specialized widgets to facilitate reverse engineering tools/cabana/mainwin.cc30-36
Key Components:
AbstractStream, supporting hardware, network, and log-based streams.For details, see Cabana CAN Analysis Tool.
Sources: tools/cabana/mainwin.h19-101 tools/README.md49
This suite of tools focuses on replaying and visualizing historical drive data stored in rlog or qlog formats.
Core Utilities:
For details, see Log Analysis and Debugging Tools.
Sources: tools/README.md46-59 tools/lib/logreader.py1-200
These tools handle the low-level communication required to identify vehicles and interact with Electronic Control Units (ECUs).
adb_ssh.sh script dynamically calculates port offsets for all openpilot services defined in SERVICE_LIST and forwards them over ADB using adb forward, enabling remote debugging of live services tools/scripts/adb_ssh.sh5-32ssh.py helper facilitates connecting to devices over the comma prime SSH proxy using CommaApi to resolve dongle IDs tools/scripts/ssh.py12-57For details, see Vehicle Fingerprinting and ECU Tools.
Sources: tools/scripts/adb_ssh.sh1-43 tools/scripts/ssh.py1-58
The op.sh script is the recommended entry point for developers. It manages the Python virtual environment, system dependencies, and build state tools/op.sh22-33
Title: Developer Environment Workflow
Sources: tools/op.sh195-238 tools/README.md18-34 scripts/post-commit1-8
Cabana persists user preferences (like FPS, theme, and chart heights) using the Settings class and Qt's QSettings tools/cabana/settings.cc20-48
| Setting | Default | File Pointer |
|---|---|---|
fps | 10 | tools/cabana/settings.h28 |
max_cached_minutes | 30 | tools/cabana/settings.h29 |
theme | 0 (Automatic) | tools/cabana/settings.h34 |
chart_height | 200px | tools/cabana/settings.h30 |
Sources: tools/cabana/settings.cc1-60 tools/cabana/settings.h13-57