Variants and ECU revisions¶
How one profile serves several cars, and how the code resolves the definitions for exactly one of
them. Read this page before you change the variant selection, the revision gating, the capture
tags or any loader of ecus/. The user-facing view is Variants. The
naming rules are in the profile-variants skill. The design, phase by phase, is in
plans/2026-10-30-profile-variants-and-rename.md.
Two levels¶
- A variant is a version of the car of the profile that an owner can name: a battery size, a
facelift or a market.
variants.yamllists the variants with typed metadata, the electronic control unit (ECU) revisions that each car can carry (revisions:) and theprofile.yamlsettings that differ for it (profile_overrides:, a whitelist). - An ECU revision is a version of one ECU that differs in protocol or decoding. An ECU file
declares revisions under
revisions:. A parameter identifier (PID) or signal gates on them withrevisions: [..].variants: [..]on an ECU says in which cars the ECU exists at all.
One check validates variants.yaml: variants/__init__.py::check_variants_doc. The loader,
validate variants and the editor (yaml_edit/variants.py) share it.
- The structure comes from
schema/variants_schema.yaml. Itsprofile_overridesvalues$reftheprofile.yamlrules. - Python adds only the ID and pair-order checks.
- The editor types each command-line value from its
VARIANT_FIELDSandPROFILE_OVERRIDE_FIELDStables. variants renamerewrites every tag and every ECUvariants:list that uses the ID.variants rmrefuses while one does (yaml_edit/variant_refs.py).
Which car: variants/selection.py::apply_variant¶
canair chooses the variant in this order. There is no default:
--variantCANAIR_VARIANTprofile_settings.<profile>.variantin the user config (profile use NAME --variant ID)- the variant that an old profile name implies (an
aliases:entry, read asProfile.alias) - the only variant, when the profile declares exactly one
all and untagged are scope keywords for analysis. Only the flag and the environment variable
accept them. canair carries the result on the Profile as variant and variant_source. The CLI
applies it once, when it resolves the active profile (cli/profile_context.py). A bare
resolve_profile never applies it.
require_variant refuses. It lists the variants and how to pick one. It refuses on a profile
with several variants when none is named. cli/car.py::require_car calls it for:
- every command that talks to the car (
cli/live/runtime.py::run_live, exceptdiscoverandidentitywithout--save) sniff- AutoPID generation
The test suite pins its car in the isolated config of tests/conftest.py.
Imports (import uds, import can) on such a profile require the flag, not the env var,
because the data is someone else's car (selection.require_named_car). An import drops the
revisions that the config pinned or a detection remembered.
Which revision: resolved once, at the load seam¶
ecus/pids.py::load_pids(profile) returns definitions that canair has already filtered and
overridden for the selected variant and for the revision of each ECU. load_raw_pids(profile)
returns them as written. Code that works on one car reads load_pids. Code that must see every
car reads load_raw_pids: validate, the editors and anything that handles variants and revisions
itself. A profile without revisions or presence gets its raw objects back untouched.
canair resolves the revision of an ECU in this order, most authoritative first
(variants/revisions.py::resolve):
- a pin:
--revision ECU=ID, orprofile_settings.<p>.revisions(profile use --pin) - the only possible revision: the selected variant allows one, or the ECU declares one
- a detection, remembered in user state
- undetermined. canair does not guess. It skips the revision-gated PIDs and signals of the ECU with one stderr note. The ungated ones still read.
Profile.cache_key covers the root, the variant, the pins and the detections, so no cache is
shared between two cars of one profile. Anything that keys a cache on a profile uses it.
Detection¶
live/revision_probe.py::detect_revisions runs from run_session_guarded, before dispatch.
- For each ambiguous ECU that the current
readormonitorsteps target, it sends the cheapestresponds:fingerprint. The matcher is the I/O-freevariants/fingerprints.py. - canair remembers a single match in user state (
variants/detected.py), carries it asProfile.revision_detections, and reloads the definitions. - canair never probes a determined ECU.
- A fingerprint is evidence, not a rule. No match, or several matches, leave the ECU undetermined.
canair identityreports the matching revision and the variants that allow it (identity_report).- AutoPID generation refuses while a revision is undetermined, because the device polls a fixed list and cannot detect a revision.
per_revision:¶
per_revision: on a PID or a signal replaces whitelisted fields for one revision
(PID_OVERRIDE_FIELDS and SIGNAL_OVERRIDE_FIELDS in variants/revisions.py). canair applies it
after gating.
The verified and response_frames of a definition speak for its reference revision. That is
the first declared revision that the definition applies to (reference_of). Another revision gets
only what its per_revision entry says. An undetermined ECU keeps no count and verifies nothing.
The frame-count write-back routes the same way (ecus/response_frames.py::revision_target). One
revision's count therefore never seeds a read of another revision and undercounts it. See
response frame counts.
pids upsert-param --revision R writes per_revision.R on an existing signal and gates a new
signal to [R].
Captures carry the car¶
- Tagging. canair tags a recording with
variant,revisions: {ECU: id}for the captured ECUs that have several revisions, and anattribution(selected,alias,only). Every save funnels throughcaptures/save.py::save_sessionand the meta of the journal, both viacurrent_capture_tagandcaptures/tags.py::capture_tag. The tag applies only to the own store of the active profile. The journal fixes the tag when it opens, so a later--recovercannot retag. -
Scoping.
captures/store.py::load_all_capturesscopes analysis when no explicit--diris given.- With a named car, it returns the sessions of that car plus the untagged ones.
- With no car, it returns every tagged session and no untagged one. A once-per-process stderr
note says how many untagged sessions canair left out. It also names the fix:
captures migrate-variants.
Analysis drops sessions that are tagged with another revision of a determined ECU (
variants/tags.py::revisions_in_scope). The byte-level analyses refuse a scope that spans two revisions (tags.require_one_revision, throughload_signal_captures(one_revision=…)). -
Untagged copies. An untagged copy of a tagged session is the same session with less information. The merge driver, the contribute overlay and the layered read keep the tagged copy (
variants/tags.py::strip_tag). - Ratchet.
validate captures --max-untagged Nfails when the untagged count grows.captures migrate-variants IDtags old history, attributedmigrated, and never retags.
Editors¶
| Command | Module |
|---|---|
variants … |
yaml_edit/variants.py |
ecu revisions, ecu set-variants |
yaml_edit/revisions.py (its rename rewrites gates, variants and capture tags) |
pids set-revisions |
the pids editors in yaml_edit/ |
ecu <ECU> rename |
also renames the key of the ECU in revisions: of every variant and in the capture revision tags |
The regression fixture is tests/fixtures/profiles/variants/.