Add support for your car to Comma.ai Openpilot

This documents how openpilot works with a car and how support is added. In this article, I am focusing on a Honda Odyssey, but the concepts described can be applied to a Toyota or a new make not supported by openpilot once you grok how they are used.

1. Database Container

The .dbc file is a key that describes all of the traffic on the car’s network. Openpilot requires this to read data from your car’s canbus. The DBC is referenced from opendbc which is used to decode traffic on the canbus in realtime.

There is a dbc required for each canbus (Examples: Powertrain CAN, ADAS CAN).

Example of a dbc addition

2. Fingerprint

The fingerprint identifies your car to openpilot, it is a list of all the ids (and length) on your car’s main canbus and their size in bytes. If you reference the dbc above, it is essentially an array of all the messages from that file. These are in decimal numbering.

If any of the messages on you car’s canbus 1 are not in this file or have a different size, the fingerprint will fail and not identify your car.

Example Commit

3. Car State

Reads values about your car’s current state. Openpilot uses this information to know fast your is going, how much your wheel is turned, etc.

This file and the other files listed below (interface, car can, and car controller) are specific to every manufacturer. If a port exists for another car with same make (like Honda or Toyota), these already exist so you just need to add to them.

Example Commit

5. Car Can

This file is structured as <make>can.py.

All can message preparation and message compilation for can messages written to the canbus are set in this file. Messages created for braking, applying gas, and steering are contained in this file. If there are messages that your radar must read, they also would be sent from here. If your car’s messages have checksums, they are calculated here.

Checksums

Hondas have a counter and checksum in the last byte of most messages. The last four bits of a message contain the checksum and the two bits before the checksum is a counter (There are exceptions, reference the fix() function in hondacan.py to see how they are calculated).

The counter counts up from 0 to 3 and resets back to zero. This the 2 bit value is highlighted in the gold color below.

The checksum is calculated using the message id and contents of the message. It is highlighted below in blue.