Variants¶
A profile describes one model generation with one drivetrain. An example is the
Hyundai Ioniq Electric (AE). Cars inside one profile still differ in ways that an owner can name.
Examples are a 28 kWh pack or the 38 kWh facelift, and a market with different diagnostics. These
differences are the variants of the profile. The profile declares them in its variants.yaml.
What variants do
Variants record which versions of the car exist and what canair knows about each version. You name yours once. canair tags captures with the variant they came from.
An electronic control unit (ECU) can declare revisions. A variant can say
which of these revisions its car carries. It can also say which ECUs the car has and which
profile.yaml settings differ for it.
canair detects the revision of an ECU from the car itself. You can pin the revision when detection cannot settle it.
The design and the record of each build phase are in
plans/2026-10-30-profile-variants-and-rename.md.
What is a variant, and what is not¶
A variant is a version of the car that the owner can name. The owner finds the name in the brochure, on the door-pillar label or from the battery size. The version must also matter to the diagnostics or to keeping captures apart.
| Difference | Where it belongs |
|---|---|
| Battery size, facelift, a market with different diagnostics | a variant |
| Model year | never by itself — makers change parts on production dates, not model years |
| Trim and equipment (blind-spot detection, heat pump, …) | neither: an ECU that is not fitted does not answer |
| Another generation, drivetrain or model | a separate profile (see Naming a profile) |
IDs¶
A variant ID is local to its profile. It names only what differs and never names the profile.
Write 28kwh, not ioniq-ev-28. The ID is lower-case words joined by -. It has at least one
letter, because a bare 28 would read back as a number. It never contains a year.
The convention is the battery capacity that the car is sold by, as a whole number of kWh.
Examples are 28kwh, 38kwh for 38.3 kWh, and 87kwh for 87.5 kWh. When two variants share a
pack, add the next difference (38kwh-us). canair validate checks a battery-named ID against the
battery that it states.
The file¶
variants:
28kwh:
name: Ioniq Electric 28 kWh (pre-facelift)
model_code: AEEV
generation: AE
production: ["2016", "2019-05"]
markets: [EU, US, KR]
battery: {usable_kwh: 28, series_cells: 96, chemistry: Li-polymer, cooling: air}
status: verified
sources: [this profile's own captures (a 2017 car, NL market)]
38kwh:
name: Ioniq Electric 38 kWh (facelift)
designation: IONIQ EV PE
production: ["2019-06", "2022"]
battery: {usable_kwh: 38.3}
status: seed
| Field | Meaning |
|---|---|
name |
Human-readable name (required) |
also_known_as |
Other names that owners call this version (Ioniq 28, Ioniq vFL). The profile pages show them. Labels only |
model_code |
The maker's model code. The ECUs of the car often report it (AEEV) |
designation |
The maker's name for this version (IONIQ EV PE, the facelift name of Hyundai) |
generation |
Generation code (AE, OS, ZE1) |
production |
Build window, "YYYY" or "YYYY-MM". This is the meaningful window, because running changes follow production dates |
model_years |
Informational. Markets disagree on the model year |
markets |
Where the maker sold the car |
battery |
usable_kwh, gross_kwh, nominal_voltage (V), series_cells, parallel_cells, modules, chemistry, cell_format, cell_supplier, cooling |
trims |
Informational only |
revisions |
ECU → the revisions of that ECU that this car can carry (BMS: [UDS]). An unlisted ECU may have any revision |
profile_overrides |
profile.yaml settings that differ for this car. The override replaces the whole setting: car_model, physical_bands, response_timeout_ms, init, multi_did_max, quirks |
status |
verified (proven on a car), community (from community sources), seed (placeholder) |
sources |
Where the facts came from |
notes |
Free text |
The authoritative field list is src/canair/variants/__init__.py.
src/canair/schema/variants_schema.yaml documents it.
Editing¶
Edit variants.yaml with canair variants. canair checks every
edit and reverts it on failure. A rename also rewrites the captures that carry the old ID as a tag.
canair variants # list
canair variants show 38kwh
canair variants add 38kwh --name "Ioniq Electric 38 kWh (facelift)" \
production=2019-06,2022 battery.usable_kwh=38.3 status=seed
canair variants set-meta 28kwh markets=EU,US,KR \
"sources=first source" "sources=second source, with a comma"
canair variants unset-meta 28kwh trims
canair variants set-meta 38kwh profile_overrides.car_model="Ioniq Electric 38 kWh"
canair variants set-revisions 38kwh BMS UDS
canair variants rename 28kwh 28kwh-eu
canair variants rm 38kwh
Use these rules to set fields:
- Separate the items of a short list (
markets,trims,also_known_as) with commas. - Give
sourcesone source for eachsources=…. A source can then contain a comma. - Set a
profile.yamloverride one at a time, asprofile_overrides.<setting>=…. - Setting a field replaces it.
canair profile show lists the variants of a profile. The
profile explorer shows them in its toolbar.
Choosing your car¶
Name your car once for each profile. canair remembers the name:
canair profile use hyundai-ioniq-ae-ev --variant 28kwh # on a terminal, omit --variant to pick
canair --variant 38kwh read BMS # or for one command
canair profile # picker: re-select the current profile
# to change only the car
canair uses the first of these that applies:
- The global
--variant IDflag. CANAIR_VARIANT.profile_settings.<profile>.variantin your config. The commandprofile use … --variantwrites it.- The variant that an old profile name implies, when you used one.
ioniq-2017names the 28 kWh car, so a setup that still uses it keeps working unchanged. - The only variant, when the profile declares just one.
There is no default. A profile can have several variants and you may choose none. Then these commands do nothing and say how to pick:
- every command that talks to the car
- every command that records a capture
- every command that generates the AutoPID profile
The words after so canair won't name the blocked action. This example is for a command that
talks to the car:
error: hyundai-ioniq-ae-ev describes 2 variants and none is selected, so canair won't talk to the car.
28kwh Ioniq Electric 28 kWh (pre-facelift) · built 2016 – 2019-05 · 28 kWh usable · verified
38kwh Ioniq Electric 38 kWh (facelift) · built 2019-06 – 2022 · 38.3 kWh usable · seed
Pick yours once: canair profile use hyundai-ioniq-ae-ev --variant 28kwh
Or for one command: canair --variant 28kwh <command> …
Not sure which you have? canair identity BMS (names the match)
discover and identity still run without a choice, because they are how you find out. They must
not use --save. Editing definitions, status, config and read-only analysis also need no
choice. canair status and canair profile show report the variant in effect and where it came
from.
Tagging captures with the car¶
A capture is evidence about one car. In a profile with several variants, a session says which car
it came from. It carries a variant tag and an attribution that records how canair decided.
canair tags every recording with the car you chose. A chosen variant must be one of the variants of the profile. An unknown variant is an error that lists the valid ones.
| Where | What the tag does |
|---|---|
--save on any live command |
canair tags the session. The attribution is selected (you named it), alias (an old profile name implied it — shown as unconfirmed) or only (the one variant of the profile) |
canair import uds / import can |
on a multi-variant profile the global --variant is required (an import comes from someone else's car, so CANAIR_VARIANT does not count) |
canair dtc |
each logged scan records the variant and the ECU revisions. canair dtc log, the open codes in canair ecu and the totals count only the scans of your car |
analysis (decode, captures, correlate, …) |
scoped to the sessions of your car, plus untagged sessions, which canair reads as your car (with a note). With no car chosen, canair reads every tagged session and no untagged session. --variant all and --variant untagged override this |
The tag is part of the recording. A session that canair recovers after a crash keeps the car that it was recorded with, whatever a later run selects.
canair captures uds --sessions shows the tag of each session. On a profile with several variants,
it also marks untagged sessions. canair validate captures counts the untagged sessions. CI fails
if that count grows (--max-untagged N). The command also warns about a tag that names a variant
the profile does not declare.
Tagging existing history¶
History that canair recorded before a profile declared its variants is untagged. Stamp the sessions that you know came from one car. Do this once for each car:
canair captures migrate-variants 28kwh --dry-run # preview
canair captures migrate-variants 28kwh --since 2026-01-01 --label commute
The command tags only sessions that have no tag yet (attributed migrated). It writes only the
captures of the profile itself.
To correct the tag of one session afterwards, use canair captures uds --set-variant ID with a
scope filter. canair attributes this tag as asserted. --set-variant '' removes the tag. The
global --variant untagged selects every untagged session.
Tags survive merges¶
A copy of a session that lacks the tag is the same recording with less information. These parts of canair all keep the tagged copy:
- the capture merge driver
canair contribute- a read of a layered profile
An older, untagged copy of your history can therefore never strip the tags from it.
canair variants rename rewrites every tag that uses the variant (captures, the raw-CAN log index
and the DTC log). It also rewrites every ECU fitted to the variant. canair variants rm refuses
while any of them still uses the variant.
ECU revisions¶
A variant describes the car. A revision describes one ECU. ECUs change on their own production dates. A dealer-replaced ECU also follows the newer rules in an older car. A running change is therefore two revisions of that ECU and not two variants. An example is a Vehicle Control Unit (VCU) that changed from Keyword Protocol 2000 (KWP2000) to Unified Diagnostic Services (UDS) mid-year.
A revision exists only if some definition differs. A new part number with the same diagnostics is another fingerprint of an existing revision. It is not a new revision.
VCU:
tx_id: 0x7E2
revisions:
KWP: # listed first: the reference revision
identity: {id_protocol: KWP2000}
fingerprints:
- {responds: "1A90"} # a safe read only this revision answers
uds:
identity: {id_protocol: UDS}
fingerprints:
- {identity: {part_number: "36601-0E1*"}}
pids:
"2101":
revisions: [KWP] # only the KWP VCU answers it
parameters: {...}
"22E001":
revisions: [UDS]
parameters: {...}
- IDs follow the variant rule and name what differs (
KWP/UDS,150s). They are local to the ECU. Unlike a variant ID, a revision ID may use capitals. canair keeps its case. A pin or command argument matches it in any case (--revision BMS=udsfindsUDS). - A revision may override these fields of the ECU:
sessions,wake,multi_did,multi_did_max,response_timeout_ms,addressing,rx_idandidentity.id_protocol. - The first declared revision owns the recorded identity (part number, calibration, notes, …).
canair read the identity from that revision. On a car whose ECU is another revision,
canair ecushows no identity. It does not show the values of the other revision. Onlydescription,aliasandid_protocolcarry over. - Gating:
revisions:on a PID or signal lists the revisions that it applies to. If the list is absent, the PID or signal applies to every revision. A signal can apply only to revisions that its PID also lists.canair validatereports an error when a signal lists a revision that is not in therevisions:list of its PID (a signal can only apply where its PID does). - Two PIDs of one ECU may ship the same signal name when their revisions are disjoint. This is how
VCU.VEHICLE_SPEEDstays one name across a protocol change, for state predicates and Home Assistant. - Presence:
variants: [60kwh]on an ECU says that only those cars have it. - Fingerprints decide which revision an ECU is.
canair identitymatches a full reading.readandmonitorsend the cheapestresponds:probe (see detection).
The bundled Ioniq is the worked case. Its BMS has a KWP revision and a UDS revision:
KWPhas every page that the 28 kWh car answers,2101…21F2.UDShas the Kona-family220101and220105pages. The 38 kWh facelift most likely answers them. They come from the Kona profile and are all unverified.
28kwh allows only KWP. 38kwh allows only UDS.
What differs per revision, and what was verified where¶
A PID or signal that two revisions share can differ field by field with per_revision::
SOC_BMS:
expression: "B09/2"
verified: true # verified on the reference revision
per_revision:
uds: {expression: "B10/2"} # unverified on uds until it says verified: true
- A PID may override
period,response_frames,verified,notes,sourceandsource_links. - A signal may override
expression,unit,min,max,type(withvalues,bitsorfields),verified,notes,sourceandsource_links. - Gates and
parameters:cannot be overridden. Override each signal instead. - Evidence belongs to a revision. The
verifiedandresponse_framesof a definition describe its reference revision. This is the first declared revision that the definition applies to. On any other revision, the definition is unverified and has no frame count. Aper_revisionentry can say otherwise. A signal that is verified on one car therefore never counts as verified on another car. The verified-only AutoPID output for a non-reference revision ships only what canair verified there. -
A live session can learn the frame count of a PID. canair writes the count for the revision that the session read:
- on the reference revision, as the
response_framesof the PID itself - on another revision, as
per_revision.<id> - nowhere, when the revision is undetermined
A count from one layout would be an undercount if it seeded a read of another layout. An undercount desynchronises an ELM327 adapter. -
canair pids upsert-param ECU PID NAME EXPR --revision UDS …writesper_revision.UDSon an existing signal. On a new signal, it creates the signal gated to[uds]. - on the reference revision, as the
Which revision your car has¶
canair picks the revision of an ECU from the first of these that applies:
- A pin. Run
canair profile use NAME --pin VCU=uds(canair remembers it asprofile_settings.<profile>.revisions). Or pass--revision VCU=UDSfor one command. - The only revision that your variant allows (its
revisions:entry), or the only revision of the ECU. - A detected revision. This is the revision that the ECU identified itself as (see below). canair remembers it from an earlier session.
- Otherwise, the revision is undetermined. canair does not guess. It skips the revision-specific PIDs and signals of that ECU, with one note that names the fix. The other PIDs of the ECU still read.
Detection. Sometimes read or monitor is about to read an ECU that is still ambiguous. canair
then first sends the ECU the cheapest responds: fingerprint of its revisions. This is a safe
identity read. canair sends one for each ECU and never one for each PID. canair settles the
revision when exactly one revision matches.
A KWP2000 ECU answers 1A90 and refuses a UDS 22F187. canair can therefore tell a protocol
change apart without knowing a single part number.
canair remembers the result for each profile and variant in
~/.config/canair/state/detected_revisions.yaml. The file is local, canair never contributes it,
and you can safely delete it. The next session then sends nothing.
A sleeping ECU answers nothing and stays undetermined. Pin the revision if you cannot wake the ECU. canair never probes an ECU that has one possible revision on your car.
canair identity ECU reports which revision its reading matches and which variants allow that
revision. It works with or without a chosen car. Use it to find out which car you have.
- A reading that contradicts a remembered detection replaces the detection.
- A reading that matches no revision is reported as a question. The profile may not know that revision yet. canair never files such a reading as a new revision.
Every command sees the definitions that canair resolved this way. A 40 kWh car therefore never
polls the PIDs of the UDS VCU. canair status, canair profile show and
canair ecu revisions VCU report the revision of each ECU and where it came from.
Captures and analysis¶
A recording tags each captured ECU that declares several revisions with the revision that the ECU
was on (revisions: {VCU: UDS}). The attribution is pinned, only or detected. The values
migrated and asserted mark tags that a migration or an explicit assertion added.
Analysis then reads only the sessions that agree with the resolved revisions of your car. It reads an untagged session as yours.
Byte-level analyses are investigate, hunt, correlate, coverage, and
decode --dump-bytes/--try. They refuse a scope that spans two revisions of an ECU that they
analyse, because a byte offset means nothing across two layouts. Scope them with
--revision ECU=ID.
With no car chosen (or with --variant all), an ECU with several possible revisions is
undetermined. Analysis then leaves out its revision-specific definitions, and the note says so.
Name your car (--variant ID), or add --revision ECU=ID.
Editing¶
canair ecu revisions VCU # list
canair ecu revisions VCU add UDS --protocol UDS
canair ecu revisions VCU set-fingerprint UDS --responds 22F187
canair ecu revisions VCU rename UDS UDS-2018 # rewrites gates, variants, capture tags
canair ecu revisions VCU rm UDS-2018 # refused while anything uses it
canair pids set-revisions VCU:22E001 UDS # gate a PID (ECU:PID:SIGNAL: a signal)
canair ecu set-variants HEATER 60kwh # presence
canair variants set-revisions 40kwh VCU KWP
canair validate checks every reference and the subset rule. It also checks that each state
predicate resolves on every variant and revision that the profile describes. A predicate that names
a signal which only one revision has would otherwise turn its state dark on the other car alone.