Fingerprinting

◄ Home

Getting Car Unrecognized: Dashcam Mode on your device but have a supported make and model of car? Use the following guides to add support.

What is a fingerprint?

A fingerprint is the method openpilot uses to determine which vehicle it is connected to and adjust its behavior accordingly.

Current methods use vehicle ECU firmware logging. openpilot will shotgun a few firmware version retrieval schemes and use the returned firmware versions to identify and fingerprint the vehicle on each start up.

If openpilot detects a firmware version not previously logged, it will need to be added to the codebase.

Check and try unstable versions of openpilot first

1. Uninstall openpilot, if it's installed. Do this though the settings or rapidly tapping the device on boot and choosing to reset.
2. When it asks for openpilot or Custom Software, choose Custom Software.
3. Use installer.comma.ai/commaai/nightly for the URL.

If it works, you won't need to do much of this guide, the next stable release of openpilot will likely successfully identify your vehicle, and you should consider going back to stable release of openpilot when the new version of the stable release is released. If this still doesn't identify your vehicle, keep going through the page.

"Check Connections" is not the same as "Car Unrecognized"

If it says check connections, that's likely not a fingerprint issue, that is a connection issue. Check all cabling. If it says "Car Unrecognized", then you're in the right place.

Fingerprinting 2.0

Getting firmware versions with these instructions requires an official device. Users without an official device can get firmware versions by running some scripts with alternative instructions and then use the car firmware retrieved in place of the instructions for official devices.

Used for all officially supported makes such as Honda, Toyota, and is also supported for Hyundai, Volkswagen and Ford.

🙋: Hey! If you need help, consult your make's channel at the comma.ai community discord. Try to at least get to Step 3 on your own though but if you can't, that's OK, go reach out. If the make's community deems it necessary hardcode the fingerprint or you aren't getting any response on the channels, consider the Hardcoded Fingerprint comma.ai openpilot Continuous Micro-Fork Generator branches.

Step 1 : Record a Drive

Ensure your comma power v2 is hooked up to your car harness. Drive around your neighborhood for a bit, then return to upload the drive on WiFi to the comma servers.

Step 2 : Log into comma.ai useradmin

https://my.comma.ai/useradmin

Login to the same account you paired your comma device with. Google Login / Google Login, GitHub Login / GitHub Login, Apple Login / Apple Login. Otherwise, you'll see nothing.

Click the most recent drive:

Click the first segment (segment 0)

Step 3 : Find the firmware

In the log dropdown select carParams

Search the page for carFw

If "carFw" is empty, please check your harness's CAT5 connection to the comma power that is on the OBD-II port. If it is still empty after another drive, then try reseating and/or flipping the USB-C/ODB-C cable between the harness and your comma device. If the connections look good and it is still empty after yet another drive, check fuses. If that looks good, try a known good CAT5 cable. If that looks good but the entry is still empty and it is after another drive, maybe ask your make's Discord channel for guidance.

Step 4 : Add new firmware versions

Go to the openpilot GitHub repo. Fork the repo (upper right hand corner). Please make sure your repository name is "openpilot" which is default, don't change it.

In your openpilot fork, browse to opendbc_repo/opendbc/car/<car make>.

Check if you car is already listed in opendbc_repo/opendbc/car/<car make>/values.py. In class CAR(Platforms), you'll find a series of models. If you can find it, great. Otherwise, you'll have to add a corresponding entry. This is an example:

class CAR(Platforms):
  # Hyundai
  HYUNDAI_AZERA_6TH_GEN = HyundaiPlatformConfig(
    [HyundaiCarDocs("Hyundai Azera 2022", "All", car_parts=CarParts.common([CarHarness.hyundai_k]))],
    CarSpecs(mass=1600, wheelbase=2.885, steerRatio=14.5),
  )

These specs can also be found by searching these terms in the captured data during your drive.

In your opendbc_repo/opendbc/car/<car make>/fingerprints.py file, add the firmware in this format.

  CAR.MODEL: {
    (Ecu.type, 0xAddress-converted-to-hex, 0xSub-address-converted-to-hex-'None'-if-0): [
      b'fwVersion',
      b'existingFirmware',
    ],
  },

Use a decimal to hex converter to get the correct string to place after 0x.

If your vehicle is already listed, you can simply copy/paste the ECU firmware under the correct ECU type; the hex code will already be there. Otherwise, you'll need to add it to opendbc_repo/opendbc/car/<car make>/values.py as well.

Here is a filled out example for the Toyota Corolla in the case as if we wanted to add engine firmware from the example. 1792 in hex is 0x700. Add the necessary firmware to the corresponding list under the ECU type, address in hex, and subaddress if present entry.

Try to add it lexicographically and make sure the list is sorted. This isn't necessary for operation but it is necessary if you want to upstream the fingerprints to comma.

  CAR.COROLLA_TSS2: {
    (Ecu.engine, 0x700, None): [
      b'\x01896630ZG2000\x00\x00\x00\x00',
      b'\x01896630ZG5000\x00\x00\x00\x00',
      b'\x01896630ZG5100\x00\x00\x00\x00',
      b'\x01896630ZG5200\x00\x00\x00\x00',
      b'\x01896630ZG5300\x00\x00\x00\x00',
      b'\x01896630ZP1000\x00\x00\x00\x00',
      b'\x01896630ZP2000\x00\x00\x00\x00',
      b'\x01896630ZQ5000\x00\x00\x00\x00',
      b'\x01896630ZU9000\x00\x00\x00\x00',
      b'\x01896630ZX4000\x00\x00\x00\x00',
      b'\x018966312L8000\x00\x00\x00\x00', /* <-- notice that the firmware from car params is added here. */
      b'\x018966312M0000\x00\x00\x00\x00',
      b'\x018966312M9000\x00\x00\x00\x00',
      b'\x018966312P9000\x00\x00\x00\x00',
      b'\x018966312P9100\x00\x00\x00\x00',
      b'\x018966312P9200\x00\x00\x00\x00',
      b'\x018966312P9300\x00\x00\x00\x00',
      b'\x018966312Q2300\x00\x00\x00\x00',
      b'\x018966312Q8000\x00\x00\x00\x00',
      b'\x018966312R0000\x00\x00\x00\x00',
      b'\x018966312R0100\x00\x00\x00\x00',
      b'\x018966312R1000\x00\x00\x00\x00',
      b'\x018966312R1100\x00\x00\x00\x00',
      b'\x018966312R3100\x00\x00\x00\x00',
      b'\x018966312S5000\x00\x00\x00\x00',
      b'\x018966312S7000\x00\x00\x00\x00',
      b'\x018966312W3000\x00\x00\x00\x00',
      b'\x018966312W9000\x00\x00\x00\x00',
    ],
...

Ensure that every single ecu has its firmware in this file.

Commit your change to your repo.

Test your changes by installing your forked openpilot branch. On the C3 device, uninstall openpilot and reinstall with the following url with your GitHub username and branch name subsituted:

https://installer.comma.ai/<your github username>/<branch name>

Tip: https:// is not really required. You're welcome.

Branch names with slashes will not work on 0.9.5 ex: bugfix/branch-name will not work. However bugfixbranchname will work.

Once you've confirmed openpilot works, create a pull request to upstream your changes to the official openpilot code. Once your pull request has been merged, usually within a day or two, your car will be included in the next openpilot release and you'll be able to run the official code again.

Fingerprinting 2.0 (Alternative for banned, non-official, or non-comma.ai devices)

In general, these instructions are to get the carFw that comma.ai device users would normally get through comma connect.

This does not require login to comma connect, in case it is down, you are unable to pair, or unable to use:

1. Setup SSH in your device

2. Open one SSH connection/session/window:

3. Run tmux on the device as follows:

tmux a

4. If you are presented with a re-occurring output window, open a new tmux window to get a command prompt, by using the back-tick key plus "c"

(NOTE: comma replaced the tmux key "Ctrl-b" with the back-tick key, "`". Ref "Tmux Cheat Sheet & Quick Reference" for other commands on tmux)

` c

5. This will present a command-prompt in the new tmux window. Run the following:

cd /data/openpilot/selfdrive/pandad
pkill ./manager.py
./pandad

6. In another connection/session/window:

cd /data/openpilot/selfdrive/debug/car/
python fw_versions.py

7. Start Car when message shows getting Vin then run python fw_versions.py again.

8. Use information from the script outputs like the main set of instructions for fingerprinting 2.0 above as the carFw.

Fingerprinting 1.0

The deprecated version of fingerprinting. Used for most other community supported makes.

Fingerprint 1.0 updates on makes where Fingerprint 2.0 are supported will not be merged into official code. Perform Fingerprint 2.0 on supported makes where possible.

Creating Fingerprint 1.0 (deprecated)

1. Turn off car and connect your C2/C3/C3X to the car.

2. Disable openpilot in UI settings so that your car is using the stock system.

3. Run these commands in 2 separate sessions (SSH into comma device, run "tmux a" and press "` + c" to create new sessions)... in first session run: /data/openpilot/selfdrive/pandad/pandad in second session run (one line): PYTHONPATH=/data/openpilot PREPAREONLY=1 /data/openpilot/selfdrive/debug/get_fingerprint.py

4. Turn on the car's ignition, and wait up to ~20 seconds to ensure all the appropriate DBC messages are seen, like this...

   number of messages 53: fingerprint 2: 8, 64: 8, 65: 8, 72: 8, 73: 8, 280: 8, 281: 8, 290: 8, 312: 8, 313: 8, 314: 8, 315: 8, 316: 8, 326: 8, 544: 8, 545: 8, 546: 8, 552: 8, 554: 8, 557: 8, 576: 8, 577: 8, 722: 8, 801: 8, 802: 8, 805: 8, 808: 8, 816: 8, 826: 8, 837: 8, 838: 8, 839: 8, 842: 8, 912: 8, 915: 8, 940: 8, 1614: 8, 1617: 8, 1632: 8, 1650: 8, 1657: 8, 1658: 8, 1677: 8, 1697: 8, 1743: 8, 1759: 8, 1785: 5, 1786: 5, 1787: 5, 1788: 8, 2015: 8, 2016: 8, 2024: 8

5. Turn on and off the car few times (some messages are only sent on start) and run the car for at least a minute to make sure all messages are received.

6. <CTRL> + C to break out of the process.

7. Copy the DBC messages obtained in step 4 into the "FINGERPRINTS" section of /data/openpilot/opendbc_repo/opendbc/car/<car make>/fingerprints.py Create new sub-section for car or overwrite pre-existing fingerprint of similar car.

8. If this is a brand new car port, you will also need to update /data/openpilot/opendbc_repo/opendbc/car/<car make>/values.py.

9. Turn off car's ignition, then reboot comma device.