Repository files navigation

Most cars since 2016 have electronically-actuatable steering, gas, and brakes thanks toLKAS andACC.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 foropenpilot, 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 thesupported 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.

git clone https://github.com/commaai/opendbc.gitcd 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 runspip3 install -e .[testing,docs]# install dependenciesscons -j8# build with 8 corespytest.# run the testspre-commit run --all-files# 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.

• opendbc/dbc/ is a repository ofDBC files
• opendbc/can/ is a library for parsing and building CAN messages from DBC files
• opendbc/car/ is a high-level library for interfacing with cars using Python
• opendbc/safety/ is the functional safety for all the cars supported byopendbc/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.

The first step is to get connected to the car with a comma 3X 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.

Depending on , most of this basic structure will already be in place.

The entirery of a car port lives inopendbc/car/<brand>/:

• carstate.py: parses out the relevant information from the CAN stream using the car's DBC file
• carcontroller.py: outputs CAN messages to control the car
• <brand>can.py: thin Python helpers around the DBC file to build CAN messages
• fingerprints.py: database of ECU firmware versions for identifying car models
• interface.py: high level class for interfacing with the car
• radar_interface.py: parses out the radar
• values.py: enumerates the brand's supported cars

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 incabana.

Use thelongitudinal maneuvers report to evaluate your car's longitudinal control and tune it.

All opendbc development is coordinated on GitHub andDiscord. Check out the#dev-opendbc-cars channel andVehicle Specific section.

Short term

• pip install opendbc
• 100% type coverage
• 100% line coverage
• Make car ports easier: refactors, tools, tests, and docs
• Expose the state of all supported cars better:#1144

Longer term

• Extend support to every car with LKAS + ACC interfaces
• Automatic lateral and longitudinal control/tuning evaluation
• Auto-tuning forlateral and longitudinal control
• Automatic Emergency Braking

Contributions towards anything here are welcome.

When apanda powers up withopendbc safety firmware, by default it's inSAFETY_SILENT mode. While inSAFETY_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 exampleSAFETY_ALLOUTPUT) are disabled in release firmwares. In order to use them, compile and flash your own build.

Safety modes optionally supportcontrols_allowed, which allows or blocks a subset of messages based on a customizable state in the board.

The opendbc safety firmware is written for its use in conjunction withopenpilot andpanda. The safety firmware, through its safety model, provides and enforces theopenpilot safety. Due to its critical function, it's important that the application code rigor within thesafety folder is held to high standards.

These are theCI regression tests we have in place:

• A generic static code analysis is performed bycppcheck.
• In addition,cppcheck has a specific addon to check forMISRA C:2012 violations. Seecurrent coverage.
• Compiler options are relatively strict: the flags-Wall -Wextra -Wstrict-prototypes -Werror are enforced.
• Thesafety logic is tested and verified byunit tests for each supported car variant.

The above tests are themselves tested by:

• amutation test on the MISRA coverage
• 100% line coverage enforced on the safety unit tests

In addition, we run theruff linter andmypy on the car interface library.

Every car port is eligible for a bounty:

• $2000 -Any car brand / platform port
• $250 -Any car model port
• $300 -Reverse Engineering a new Actuation Message

In addition to the standard bounties, we also offer higher value bounties for more popular cars. See those atcomma.ai/bounties.

How do I use this? Acomma 3X is custom-designed to be the best way to run and develop opendbc and openpilot.

Which cars are supported? See thesupported cars list.

Can I add support for my car? Yes, most car support comes from the community. Read the guidehere.

Which cars can be supported? Any car with LKAS and ACC. More infohere.

How does this work? In short, we designed hardware to replace your car's built-in lane keep and adaptive cruise features. Seethis talk for an in-depth explanation.

Is there a timeline or roadmap for adding car support? No, most car support comes from the community, with comma doing final safety and quality validation. The more complete the community car port is and the more popular the car is, the more likely we are to pick it up as the next one to validate.

• port: refers to the integration and support of a specific car
• lateral control: aka steering control
• longitudinal control: aka gas/brakes control
• fingerprinting: automatic process for identifying the car
• LKAS: lane keeping assist
• ACC: adaptive cruise control
• harness: car-specific hardware to attach to the car and intercept the ADAS messages
• panda: hardware used to get on a car's CAN bus
• ECU: computers or control modules inside the car
• CAN bus: a bus that connects the ECUs in a car
• cabana: our tool for reverse engineering CAN messages
• DBC file: contains definitions for messages on a CAN bus
• openpilot: an ADAS system for cars supported by opendbc
• comma: the company behind opendbc
• comma 3X: the hardware used to run openpilot

• How Do We Control The Car? by@robbederks from COMMA_CON 2021
• How to Port a Car by@jyoung8607 from COMMA_CON 2023
• commaCarSegments: a massive dataset of CAN data from 300 different car models
• cabana: our tool for reverse engineering CAN messages
• can_print_changes.py: diff the whole CAN bus across two drives, such as one without any LKAS and one with LKAS
• longitudinal maneuvers: a tool for evaluating and tuning longitudinal control
• opendbc data: a repository of longitudinal maneuver evaluations

comma is hiring engineers to work on opendbc andopenpilot. We love hiring contributors.