Typed (multi-modal) signals¶
Most vehicle signals are continuous linear numbers, such as a temperature, a speed or a state
of charge. The default signal model of canair describes these with a WiCAN expression (a formula
over byte indices) and an optional unit/min/max. The whole analysis suite
(decode/correlate/hunt/investigate) reasons about them as scalar floats.
But some signals are not numbers on a line:
- a mode / enum — fan level 1-8, gear P/R/N/D, a climate mode
- a flag set / bitmask — a day-of-week schedule mask, a set of door bits
- text — a part number or serial read as ASCII
- a date — a manufacture or preheat-schedule date
- a struct — a whole record (for example, schedule = day-mask + hour + minute)
For these signals, min/max and Pearson correlation have no meaning. The numeric spacing between
Drive=3 and Neutral=2 carries no physical meaning. canair models them with an optional signal
type: and a small companion map.
The parallel decoder¶
The WiCAN expression stays a pure float. The WiCAN device ships it, and numeric analysis
consumes it. type: attaches a parallel typed decoding on top
(src/canair/expression/decode_value.py). The expression yields the raw integer, and the typed
layer interprets it for display and categorical analysis. This never changes the device output or
the numeric path.
type: |
Companion field | Renders as |
|---|---|---|
numeric |
(default) | the float value + unit (unchanged) |
enum |
values: {raw: label} |
drive (40) |
bitmask |
bits: {bit_index: label} (0=LSB) |
rear_left_locked\|rear_right_locked |
ascii |
— | the decoded text |
date |
— | 2017-06-06 (BCD or binary) |
bcd |
— | the decoded decimal |
struct |
fields: (ordered sub-signals) |
{days=tue, hour=7, minute=30} |
Defining a typed signal¶
Use canair pids upsert-param:
# An enum: the gear byte on VCU 2101 (B10 reads 0x21 in Park, 0x28 in Drive)
canair pids upsert-param VCU 2101 GEAR B10 \
--type enum --value 0x21=park --value 0x22=reverse \
--value 0x24=neutral --value 0x28=drive --unverified
# A bitmask: the door byte on IGPM 22BC03 (B10; bit 6 has never been set, so stays unlabelled)
canair pids upsert-param IGPM 22BC03 DOOR_STATUS B10 \
--type bitmask --bit 0=rear_left_open --bit 1=rear_left_locked \
--bit 2=rear_right_open --bit 3=rear_right_locked --bit 4=passenger_open \
--bit 5=driver_open --bit 7=trunk_open --unverified
The bundled Ioniq profile already decodes both bytes. It decodes VCU GEAR. It decodes IGPM B10
bit by bit as DOOR_*_OPEN, DOOR_LOCK_RL/DOOR_LOCK_RR and TRUNK_OPEN. These two commands
therefore show the syntax. They do not show a signal that is still to be found. With the rear
doors locked and every door shut, DOOR_STATUS would render as
rear_left_locked|rear_right_locked.
--value and --bit are repeatable KEY=LABEL pairs. KEY may be decimal or 0x-hex. If you
omit --type, canair infers it. --value sets the type to enum. --bit, without --value,
sets it to bitmask. If you pass both, --value wins and the type is enum.
You currently define struct signals (ordered fields:) in the YAML directly. Each sub-field is
itself a typed mini-signal over the same payload.
Byte-run types: ascii and date¶
ascii and date are the two types that read a run of bytes and not a scalar. Their
expression is a plain range, such as [B04:B22], and not a formula:
# The VIN: KWP2000 record 1A90 returns SID + record byte + 17 ASCII chars
canair pids upsert-param VCU 1A90 VIN "[B04:B22]" --type ascii --unverified
Two consequences follow:
-
The range may cross a frame boundary of the controller area network (CAN). Byte indices are in WiCAN notation. This notation includes the ISO 15765-2 transport protocol (ISO-TP) protocol control information (PCI) bytes at
B00/B01, thenB08,B16, … The run decoder drops those bytes.[B04:B22]therefore yields 17 consecutive data bytes, even thoughB08andB16sit inside it. This is the only way to express a 17-character vehicle identification number (VIN).For this reason,
canair validate pidsdoes not raise its "range spans a PCI byte" warning forasciianddate. It still raises the warning for numeric types, which read consecutive raw bytes. -
You may omit a range, but the result is imprecise. With no
[Bn:Bm]expression, the decoder uses the whole payload minus its Unified Diagnostic Services (UDS) header. It takes the header width from the service of the response (0x5A→ 2 bytes,0x62→ 3). Prefer an explicit range. The fallback can only guess where your data begins.
canair strips trailing AA/00/FF padding. A run that decodes to mostly non-printable bytes
renders as hex and not as mojibake. A wrong offset therefore shows up as obvious garbage and not
as silently plausible text.
Analyzing categorical signals¶
canair decode ECU PIDrenders typed signals as their labels. It shows the set of distinct decoded values and not a numeric range.canair decode ECU PID --discriminate statescores an enum or bitmask signal with Cramér's V (nominal association) instead of the interval-scale F. This answers "which byte separates the power states?" correctly.canair correlate … --method cramers_v|mutual_info(also ondecode --corr) ranks by categorical association. It answers "which byte tracks this known mode?" Pearson correlation cannot answer this question for a fan, mode or flag byte.canair investigate ECU PID --events --field NAMEcollapses a typed field into one logical signal. It prints one transition per decoded-value change (park (33) → drive (40)at a timestamp). It does not print scattered per-byte edges. This suits schedule, mode and date fields.
See the analyze journey for a worked example. See the write-command workflow for how to reverse-engineer settings that the head unit writes.