Contribute to the OBDb

Pelican pulls from the OBDb through GitHub, including being able to point at forks of the official OBDb repos. If you want to contribute to the OBDb, or just want to test custom parameter definitions, the easiest way is with a fork.

Create your fork

You need a GitHub account and the OBDb repository you want to fork. If your model has no repository, request one through the OBDb new repo form.

To create a fork:

1. Connect your OBD scanner.
2. In Settings, under Connected scanner, tap Car parameters.
3. Tap the three-dot menu, then tap Open in GitHub.
4. On GitHub, check that the repository matches your make and model.
5. Select Fork.
6. Select your account as the owner, then select Create fork.

GitHub opens your copy of the repository.

If Pelican opens a make repository, such as Toyota, find your model’s repository in the OBDb before you fork it.

Add a parameter definition

The PID Detector can help you find parameter IDs (PIDs) that your car answers. A reply alone doesn’t tell you how to turn its bytes into a reading; the definition must describe that conversion.

To add a definition in your fork:

1. Open signalsets/v3/default.json, or the file for your car’s model years if the repository has one.
2. Add the command and its signals, following the file format.
3. Commit your changes to your fork’s default branch.

Your fork now contains the definition. Pelican reads the default branch when you select your fork.

Use your fork in Pelican

Pelican lists forks of your model’s repository by their owners’ GitHub names. These forks can contain changes that the OBDb maintainers haven’t reviewed.

To select your fork:

1. In your car’s page, tap Parameters.
2. Tap the three-dot menu, then tap Change source.
3. Under Unofficial forks, use with caution, tap your GitHub name to select it.
4. Tap Done.

Pelican reloads your car’s parameters from the selected source. If a recent fork is missing, pull down to refresh the Change source list.

Test your changes

Check the readings on your car before you submit the definition:

1. In Parameters, find the parameter you added.
2. Compare its reading with a known value, such as the corresponding reading on your car’s dashboard.
3. Record your car’s model year, the scanner replies and the expected readings.

If you change the definition again, commit it to your fork’s default branch. Then fetch the latest parameters in Pelican and repeat the check.

Submit your changes

To share your tested definition:

1. On GitHub, open a pull request from your fork to the original OBDb repository.
2. Describe the change and include your car’s model year, scanner replies and test results.
3. Select Create pull request.

The pull request appears in the OBDb repository for review. The maintainers may ask for changes or more test results. After they merge it, other drivers can download the definition in Pelican.

Return to the OBDb source

After your changes are merged, select the official source to receive future OBDb updates:

1. In Car parameters, tap the three-dot menu, then tap Change source.
2. Select OBDb, then tap Done.

Pelican reloads your car’s parameters from the OBDb. You can also return to this source at any time while you test a fork.