This section documents the specialized toolsets used to develop, test, and port openpilot to new vehicle platforms. These tools bridge the gap between pure software development and physical vehicle integration by providing high-fidelity simulation environments and automated diagnostic scripts.
The MetaDrive bridge allows openpilot to run in a simulated 3D environment, enabling testing of the entire vision and control stack without physical hardware. It replaces the physical camera and CAN bus with simulated counterparts.
The simulation is orchestrated by the SimulatorBridge tools/sim/bridge/common.py37-39 which manages the lifecycle of the simulation world and the interface with openpilot processes. It initializes parameters like AlphaLongitudinalEnabled to ensure the full control stack is active tools/sim/bridge/common.py41-43
Key Components:
MetaDriveWorld: Manages the metadrive_process via a multiprocessing.Process tools/sim/bridge/metadrive/metadrive_world.py40-46 It handles the exchange of vehicle state and control commands using Pipe objects tools/sim/bridge/metadrive/metadrive_world.py27-29SimulatedCar: Acts as a bridge between the simulator and openpilot's CAN messaging system. It packs simulated vehicle data (speed, steering angle, cruise buttons) into CAN messages using CANPacker tools/sim/lib/simulated_car.py12-14 and publishes pandaStates to satisfy openpilot's safety requirements tools/sim/lib/simulated_car.py82-99SimulatedSensors: Provides simulated camera images to the vision stack. It uses send_camera_images to distribute frames at 20Hz tools/sim/bridge/common.py113-115metadrive_process: The core simulation loop that runs the MetaDrive environment, handles physics steps, and renders camera views as RGB arrays tools/sim/bridge/metadrive/metadrive_process.py51-155The following diagram illustrates how the simulation bridge interfaces with the core openpilot daemons.
Simulation Data Flow and Entity Mapping
Sources: tools/sim/bridge/common.py101-115 tools/sim/bridge/metadrive/metadrive_world.py40-46 tools/sim/lib/simulated_car.py17-19 tools/sim/bridge/metadrive/metadrive_process.py102-108
The simulation is typically launched via tools/sim/launch_openpilot.sh. Users can control the simulation manually via keyboard inputs captured in keyboard_poll_thread tools/sim/lib/keyboard_ctrl.py58-61 which sends QueueMessage types like CONTROL_COMMAND to the bridge tools/sim/bridge/common.py132-135
Keyboard Controls Mapping:
| Key | Function | Code Command |
|---|---|---|
1 | Cruise Resume | cruise_up tools/sim/lib/keyboard_ctrl.py63-64 |
2 | Cruise Set | cruise_down tools/sim/lib/keyboard_ctrl.py65-66 |
w/s | Gas/Brake | throttle_1.0 / brake_1.0 tools/sim/lib/keyboard_ctrl.py69-74 |
r | Reset | reset tools/sim/lib/keyboard_ctrl.py83-84 |
Porting openpilot involves defining a vehicle's CAN fingerprint and verifying that the CarInterface correctly interprets and commands the vehicle's ECUs.
The auto_fingerprint.py utility automates the process of adding firmware (FW) versions to the codebase from a recorded route tools/car_porting/auto_fingerprint.py12-14 It extracts carFw from carParams tools/car_porting/auto_fingerprint.py18-19 determines the platform using match_fw_to_car if not provided tools/car_porting/auto_fingerprint.py28-30 and formats the FW versions for the appropriate brand database tools/car_porting/auto_fingerprint.py45
Several tools are used to validate a new car port before on-road testing:
test_car_interfaces.py: Discovers common bugs in car interfaces (e.g., typos in signal names) without requiring a route tools/car_porting/README.md28-30test_car_model.py: Runs the car interface against a recorded route to check for missing signals, blocked panda messages, and safety mismatches tools/car_porting/test_car_model.py21-22 It uses TestCarModel as a base class to perform assertions such as test_panda_safety_carstate tools/car_porting/README.md51-57measure_steering_accuracy.py: Analyzes lateral control performance by comparing steeringAngleDeg (actual) against steeringAngleDesiredDeg (desired) across different speed groups tools/car_porting/measure_steering_accuracy.py16-22 It tracks errors, actuator saturation, and safety limits tools/car_porting/measure_steering_accuracy.py75-82Car Porting Analysis Flow
Sources: tools/car_porting/auto_fingerprint.py17-19 tools/car_porting/test_car_model.py10-17 tools/car_porting/measure_steering_accuracy.py61-68
The tools/car_porting/examples/ directory contains Jupyter notebooks for deep-dive signal analysis:
subaru_steer_temp_fault.ipynb: Demonstrates searching for EPS steering warnings and plotting them against steering angle to find mechanical limits tools/car_porting/examples/subaru_steer_temp_fault.ipynb33-37subaru_long_accel.ipynb: Plots the relationship between Brake_Pressure and Acceleration to validate actuator response tools/car_porting/examples/subaru_long_accel.ipynb30-32ford_vin_fingerprint.ipynb: Evaluates the feasibility of VIN-based fingerprinting for specific brands using the comma_car_segments database tools/car_porting/examples/ford_vin_fingerprint.ipynb21-24find_segments_with_message.ipynb: Searches the public segment database for specific CAN message IDs, useful for identifying cross-platform signal patterns tools/car_porting/examples/find_segments_with_message.ipynb114-116To validate the performance of longitudinal control (acceleration and braking), openpilot uses a specialized maneuver framework. This allows developers to test step responses and stopping behavior deterministically.
Maneuvers are defined in maneuversd.py as a series of Action objects with acceleration and time breakpoints. The Maneuver class calculates the required aTarget by interpolating based on the current frame.
The generate_report.py script processes logs to generate HTML reports. It calculates "target cross times"—the time it takes for the vehicle's actual acceleration to reach the commanded aTarget.
Key Metrics Tracked:
longitudinalPlan.aTarget, carControl.actuators.accel, and livePose.accelerationDevice.x.longActive was maintained and if the vehicle respected standstill requirements.Sources: tools/car_porting/README.md tools/car_porting/auto_fingerprint.py tools/car_porting/test_car_model.py tools/car_porting/measure_steering_accuracy.py tools/car_porting/examples/subaru_steer_temp_fault.ipynb tools/sim/bridge/common.py tools/sim/bridge/metadrive/metadrive_world.py
Refresh this wiki