Synthetic signals — Pelican driver's handbook

Synthetic signals calculate readings from other signals. Define them in the optional synthetics array of a signalset.

Each entry has a formula that uses other signal IDs. It can divide two readings or choose a reading based on an enumeration value.

Properties

The OBDb signals schema defines these properties for each entry:

Property	Type	Required	Description
`id`	`string`	Yes	Unique identifier for the synthetic signal
`name`	`string`	Yes	Human-readable name for the synthetic signal
`path`	`string`	Yes	Path for organizing the signal in a hierarchy
`min`	`number`	No	Minimum valid value for the synthetic signal
`max`	`number`	Yes	Maximum valid value for the synthetic signal
`unit`	`string`	Yes	Unit of measurement for the synthetic signal
`suggestedMetric`	`string`	No	User interface elements that can be connected to a signal
`formula`	`object`	Yes	Formula used to compute this synthetic signal from other signals

The unit uses a Unit value. Formula references use signal IDs, not display names.

Ratio formula

A ratio formula divides the reading of signal a by the reading of signal b. All three formula properties are required:

Property	Type	Required	Description
`op`	`string`	Yes	Must be "ratio".
`a`	`string`	Yes	First signal ID used in the formula
`b`	`string`	Yes	Second signal ID used in the formula

This example entry calculates a fraction from two example signal IDs:

{
  "id": "EXAMPLE_CHARGE_FRACTION",
  "name": "Charge fraction",
  "path": "Battery",
  "min": 0,
  "max": 1,
  "unit": "scalar",
  "formula": {
    "op": "ratio",
    "a": "EXAMPLE_REMAINING_CHARGE",
    "b": "EXAMPLE_FULL_CHARGE"
  }
}

Both source readings must use the same unit for this fraction. The result is a fraction, not a percentage.

Pelican limits the result to min through max when max is greater than min. Missing readings or a zero denominator produce no result.

Selection formula

A selection formula chooses a reading based on another signal’s enumeration value. For example, a tire module can report which sensor belongs to each wheel.

All three formula properties are required:

Property	Type	Required	Description
`op`	`string`	Yes	Must be "select".
`match`	`string`	Yes	The enumeration value (a map entry's value) that selects a key
`cases`	`object`	Yes	Key signal ID to the value signal ID it selects

This example formula selects the pressure reading for the slot whose position signal reports frontLeft:

{
  "op": "select",
  "match": "frontLeft",
  "cases": {
    "EXAMPLE_SLOT_1_POSITION": "EXAMPLE_SLOT_1_PRESSURE",
    "EXAMPLE_SLOT_2_POSITION": "EXAMPLE_SLOT_2_PRESSURE"
  }
}

The result is empty if no key matches, or if more than one key matches. The selected reading keeps its source unit; the synthetic’s unit doesn’t convert it.

Apps that predate select discard the whole signalset when they encounter this formula.