Extended PIDs

Extended PIDs let Pelican read car data beyond the SAEJ1979 standard PIDs. These manufacturer-defined parameter IDs (PIDs) can provide more detail, such as battery data for an electric car. Pelican gets their definitions from the OBDb.

The OBDb

The OBDb is a community database of car diagnostic parameters. A parameter definition tells Pelican what to ask your car and how to turn the reply into a reading. Contributors share these facts so that other drivers can use them.

The OBDb stores definitions in GitHub repositories. Each repository contains files for a car make or model. The available readings depend on your car’s model, year and equipment, and on the definitions that contributors have tested.

How the OBDb is organized

Most model repositories use a make-model name, such as Ford-Mustang. These repositories contain definitions for that model, with separate files where different model years need different definitions.

The main files in the Ford-Mustang repository are:

Ford-Mustang/
├── README.md
├── LICENSE
├── generations.yaml
├── signalsets/
│   └── v3/
│       └── default.json
└── tests/
    └── test_cases/

README.md introduces the repository, and LICENSE sets the terms for reuse. generations.yaml describes the model’s generations and their year ranges.

signalsets/v3/default.json contains the commands and parameter definitions that Pelican reads. The file format explains its contents. tests/test_cases/ contains scanner replies and expected readings used to check the definitions.

Make repositories, such as Ford, contain definitions shared across models. If your model’s repository is missing or has no commands, Pelican tries the make repository instead.

Model generations

generations.yaml groups model years into generations, the versions of a model between major redesigns. Cars in one generation often share diagnostic commands, although engines and equipment can differ.

Pelican’s car support pages use these ranges to list model years.

The file uses YAML, with a generations list and a references list of sources. This shortened example uses two generations from Ford-Mustang’s generations.yaml:

references:
  - https://en.wikipedia.org/wiki/Ford_Mustang
generations:
  - name: "Sixth Generation (S550)"
    start_year: 2015
    end_year: 2023
    description: "Includes EcoBoost, GT and Shelby variants."
  - name: "Seventh Generation (S650)"
    start_year: 2024
    end_year: null
    description: "Includes EcoBoost, GT and Dark Horse variants."

Each generation has these fields:

• name: the generation’s name or chassis code.
• start_year: the first model year, included in the range.
• end_year: the last model year, included in the range, or null for a generation still in production.
• description: a short description of the generation and its variants.

Shared parameter repositories

Two repositories document parameters that apply beyond one make-model repository:

• SAEJ1979 defines standard OBD parameters, such as engine speed and coolant temperature.
• NissanInfiniti defines parameters shared by Nissan and Infiniti cars.

Pelican includes support for these parameters alongside the definitions it downloads for your model. Pelican asks your car which commands it supports from each set.