Most cars since 2016 have electronically-actuatable steering, gas, and brakes thanks to LKAS and ACC.
The goal of this project is to support controlling the steering, gas, and brakes on every single one of those cars.
While the primary focus is on supporting ADAS interfaces for openpilot, we're also interested in reading and writing as many things as we can (EV charge status, lock/unlocking doors, etc) such that we can build the best vehicle management app ever.
This README and the supported cars list are all the docs for the opendbc project.
Everything you need to know to use, contribute, and extend opendbc are in these docs.
Quick start
git clone https://github.com/commaai/opendbc.git
cd opendbc
# you probably just want to use this. it's an all-in-one for dependency
# installation, compiling, linting, and tests. it's also what runs in CI
./test.sh
# here are the individual commands it runs
pip3 install -e .[testing] # install dependencies
scons -j8 # build with 8 cores
unittest-parallel # run the tests
lefthook run lint # run the linter
examples/ contains small example programs that can read state from the car and control the steering, gas, and brakes.
examples/joystick.py allows you to control a car with a joystick.
Project Structure
opendbc/dbc/ is a repository of DBC filesopendbc/can/ is a library for parsing and building CAN messages from DBC filesopendbc/car/ is a high-level library for interfacing with cars using Pythonopendbc/safety/ is the functional safety for all the cars supported by opendbc/car/
How to Port a Car
This guide covers everything from adding support to a new car all the way to improving existing cars (e.g. adding longitudinal control or radar parsing). If similar cars to yours are already compatible, most of this work is likely already done for you.
At its most basic, a car port will control the steering on a car. A "complete" car port will have all of: lateral control, longitudinal control, good tuning for both lateral and longitudinal, radar parsing (if equipped), fuzzy fingerprinting, and more. The new car support docs will clearly communicate each car's support level.
Connect to the Car
The first step is to get connected to the car with a comma four and a car harness.
The car harness gets you connected to two different CAN buses and splits one of those buses to send our own actuation messages.
If you're lucky, a harness compatible with your car will already be designed and sold on comma.ai/shop.
If you're not so lucky, start with a "developer harness" from comma.ai/shop and crimp on whatever connector you need.
Structure of a port
Depending on the brand, most of this basic structure will already be in place.
The entirety of a car port lives in opendbc/car/<brand>/:
carstate.py: parses out the relevant information from the CAN stream using the car's DBC filecarcontroller.py: outputs CAN messages to control the car<brand>can.py: thin Python helpers around the DBC file to build CAN messagesfingerprints.py: database of ECU firmware versions for identifying car modelsinterface.py: high level class for interfacing with the carradar_interface.py: parses out the radarvalues.py: enumerates the brand's supported cars
Reverse Engineer CAN messages
Start off by recording a route with lots of interesting events: enable LKAS and ACC, turn the steering wheel both extremes, etc. Then, load up that route in cabana.
Tuning
Longitudinal
Use the longitudinal maneuvers report to evaluate your car's longitudinal control and tune it.
Validation
Before submitting a port, go through the car porting checklist.
Contributing
All opendbc development is coordinated on GitHub and Discord. Check out the #dev-opendbc-cars channel and Vehicle Specific section.
Roadmap
Short term
Longer term
Contributions towards anything here are welcome.
Safety Model
When a panda powers up with opendbc safety firmware, by default it's in SAFETY_SILENT mode. While in SAFETY_SILENT mode, the CAN buses are forced to be silent. In order to send messages, you have to select a safety mode. Some of safety modes (for example SAFETY_ALLOUTPUT) are disabled in release firmwares. In order to use them, compile and flash your own build.
Safety modes optionally support controls_allowed, which allows or blocks a subset of messages based on a customizable state in the board.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
