Profiles¶
A profile is a directory that bundles everything canair knows about one vehicle. The tooling
works with any vehicle. The profile holds the knowledge that belongs to one vehicle. The repo ships
one or more profiles under
profiles/. See
Bundled profiles for the current list. The most developed profile is
profiles/hyundai-ioniq-ae-ev/, which was built on a 2017 Hyundai Ioniq Electric. See
the Ioniq Electric profile for what a mature profile looks
like.
Bundle layout¶
<profile>/
profile.yaml # profile-wide settings: car_model, ELM327 init, timeouts, …
vehicle_states.yaml # the vehicle's power-state vocabulary (SLEEP/ACC/READY/…)
can_buses.yaml # the CAN bus segment vocabulary for each ECU's can_bus:
groups.yaml # named selector groups, recalled as @name
variants.yaml # (optional) the car's variants — battery, facelift, market — see Variants
ecus/ # ONE FILE PER ECU — the single source of truth
bms.yaml # identity, scan log, DTC meanings, PIDs, signals, research
igpm.yaml
…
captures/ # recorded UDS payloads, split by date (never hand-edited)
can/ # (optional) imported raw broadcast-CAN frame logs + index.yaml
references/ # external reference material (other cars' logs, spreadsheets)
signals/ # (optional) broadcast signal maps, one <bus>.yaml per CAN bus
actions.yaml # (optional) guarded make-specific actions, e.g. sleep
out/ # generated AutoPID JSON (never hand-edited; regenerate)
The ecus/ directory is the core of a profile. Each ecus/<name>.yaml file fully describes one
electronic control unit (ECU). It holds these items:
- the identity of the ECU
- the history of what canair probed on the ECU
- the meanings of its diagnostic trouble codes (DTCs)
- its parameter identifiers (PIDs) and decoded signals
- a
research:backlog of the work that remains
Each ECU also records its id_protocol, which is either Unified Diagnostic Services (UDS) or
Keyword Protocol 2000 (KWP2000). See ECU protocols & PID prefixes.
The optional signals/ and captures/can/ directories belong to the raw Controller Area Network
(CAN) broadcast domain. This domain covers frames that canair observes passively, and their
linear signal maps in the style of a CAN database (DBC) file. It is separate from the diagnostic
request/response captures/. Both directories are absent unless you import broadcast data.
canair validate signals and canair validate can check them. These commands skip them without a
message when they do not exist.
Editing rules¶
Use the editor where one exists. The editor validates each write, keeps comments, and updates
references when you rename something. A hand edit also works. Check it with canair validate.
Captures and out/ are the exception. Never edit those by hand.
| Path | How you edit it |
|---|---|
ecus/ |
canair pids …, canair ecu add, canair discover --register |
captures/ |
written by canair … --save (or canair import uds) — never by hand |
vehicle_states.yaml |
canair states … (a rename also rewrites every reference to the state) |
groups.yaml |
canair groups … |
actions.yaml |
canair action add/set/rm |
variants.yaml |
canair variants … (a rename also rewrites every capture tag) |
signals/ |
canair signals … / canair import dbc |
out/ |
generated by canair wican autopid write — never by hand |
profile.yaml, can_buses.yaml |
edit directly, then canair validate |
canair pids edits change only what you ask for, keep comments, and pass schema validation. They
revert on their own if validation fails. You get safe edits, and the file keeps its structure and
its comments.
Naming a profile¶
A profile that the repo shares is named make-model-code-drivetrain. Every part is always present:
| Part | Examples |
|---|---|
| make | hyundai, nissan, xpeng |
| model | ioniq, ioniq-5, kona, leaf, g6 |
| code — the maker's model code for the generation | ae, ne, os, ze1, f30 |
| drivetrain | ev, erev, phev, hev, ice, fcev |
Examples are hyundai-ioniq-ae-ev, hyundai-ioniq-5-ne-ev and xpeng-g6-f30-ev.
Never use a year in the name. A model year is wrong for most of the cars that it names. A name without the code or the drivetrain must change when the model gets a successor or a new drivetrain.
The car is usually the best source for a model code. Its ECUs often report the code in their
identity strings. For example, the BMS of the Ioniq Electric answers AEEV__ BMS.
canair validate enforces the convention for bundled profiles. You can give your own profile any
name. canair profile create only prints a note when a name does not follow the convention.
Renamed profiles¶
When someone renames a profile, its profile.yaml keeps the old name under aliases:. The old
name keeps working everywhere that a profile is named:
An alias may also name the variant that the old name implied (variant:). {} implies nothing.
--profile ioniq-2017andCANAIR_PROFILE=ioniq-2017resolve tohyundai-ioniq-ae-ev. canair prints a one-line note that names the new name.default_profile: ioniq-2017in your config keeps working without the note. You can switch to the new name at any time withcanair profile use hyundai-ioniq-ae-ev. canair does not rewrite your config. An older canair that shares the config would not know the new name.- A capture layer that you created under the old name (
~/.config/canair/profiles/ioniq-2017/withextends: ioniq-2017) layers onto the renamed profile. Your recordings stay in view. - A real profile directory with the old name always wins. A copy that you adopted before the
rename stays your own profile.
canair contributesends such a copy upstream under the current name of the profile. canair profile listshows each rename asioniq-2017 → hyundai-ioniq-ae-ev.
Other names for a car¶
People rarely search for hyundai-ioniq-ae-ev. They search for "Classic Ioniq" or "Ioniq 28".
List these names under also_known_as: in these places:
profile.yaml, for names that fit every version of the carvariants.yaml, for names of one variant (for example,canair variants set-meta 38kwh "also_known_as=Ioniq vFL,Ioniq FL")
The docs site shows these names on the bundled profiles page and in the "At
a glance" table of a profile tour. It also puts them in the page description of the tour. The
search of the site and web search engines can then find the profile by these names.
canair profile show lists them too.
They are labels only. Unlike aliases: (former profile names), --profile "Classic Ioniq" does
not resolve. canair validate checks that the list is text with no repeats.
Selecting a profile¶
canair selects a profile with this precedence. The first match wins:
--profile NAME|PATH(global flag, before or after the subcommand)CANAIR_PROFILEenvironment variabledefault_profilein your config (set it withcanair profile use NAME)- the single discovered profile, if only one exists
Inside the profile, tell canair which of its variants your car is. You can do this in two ways:
- Run
canair profile use NAME --variant IDonce. canair remembers the variant for each profile. - Pass the global
--variant ID(or setCANAIR_VARIANT) on each command.
On a profile with several variants, live commands refuse to run until you do this. See Choosing your car.
Where profiles are discovered¶
canair searches these places in order:
--profiles-dir$CANAIR_PROFILES_DIRprofiles_dirin config~/.config/canair/profiles/(your uncommitted profiles)- the bundled
profiles/of the repo
User profiles shadow bundled profiles that have the same name. The repo does not commit user
profiles. One exception exists. If a user profile declares extends:, it becomes a layer over
the bundled profile instead. See
Layering your captures.
canair profile # interactive picker on a TTY (set the default); plain list when piped
canair profile list # discovered profiles; active one marked
canair profile show [NAME] # a profile's paths and settings
canair profile use NAME # set NAME as the default profile
canair profile create NAME --car-model "…" [--set-default]
canair profile adopt NAME # copy a read-only profile somewhere writable
canair profile overlay NAME # keep its definitions, record your captures alongside
Where your writes land¶
canair writes everything that it records or edits (captures, PIDs, states, groups) inside the profile directory that it resolved. The profile that you pick decides whether you can keep that data. A profile can live in three places, and one of them is a dead end:
| Profile lives in | Writable | Survives a reinstall | Good for |
|---|---|---|---|
~/.config/canair/profiles/<name>/ |
yes | yes | your own car — the default home for a profile you create |
your clone's profiles/<name>/ (via profiles_dir) |
yes | yes | working on a bundled profile you intend to contribute — the data is git-tracked |
the install snapshot's profiles/<name>/ |
writes appear to work | no — deleted | nothing |
The third row is the trap. You may install canair as a tool (uv tool install, pipx or pip).
The bundled profiles that ship with it then live inside site-packages.
A reinstall replaces that directory completely. A capture that you record against a bundled
profile with a bare canair is gone the next time you run canair update.
canair warns you when the write happens. canair update lists what a reinstall would delete. The
fix is to point your writes somewhere durable first:
# Working on a bundled profile from a git clone — data stays in the checkout:
canair config set profiles_dir /path/to/canair/profiles
# No clone (or you just want your own copy) — take the profile with you:
canair profile adopt hyundai-ioniq-ae-ev
profiles_dir is the persistent equivalent of --profiles-dir. Use it whenever a clone exists.
The profile stays git-tracked, so canair contribute can propose your captures upstream.
canair profile adopt copies the profile into ~/.config/canair/profiles/<name>. There it shadows
the bundled profile that has the same name. The copy is self-contained and durable. It stops
tracking upstream. Prefer profiles_dir if you plan to contribute.
Layering your captures over someone else's definitions¶
Adopting takes a full copy. Use it when you want to change the definitions. If you only want to record against a profile that someone else maintains, take a layer instead:
This command creates ~/.config/canair/profiles/hyundai-ioniq-ae-ev/. The directory contains an
empty captures/ and a one-line marker. Nothing else:
The extends: key turns a user profile with the same name from a shadow into a layer. From
then on, --profile hyundai-ioniq-ae-ev resolves to both directories at once:
| Comes from | What |
|---|---|
| the base (bundled, read-only) | ecus/, vehicle_states.yaml, can_buses.yaml, groups.yaml, signals/, and its committed captures/ |
| your layer | every capture you record, generated out/ |
Analysis reads both layers as one history. canair decode, correlate, hunt, align and
captures see the upstream captures and yours, in chronological order. canair counts a session
once when it exists in both layers. This happens when you contributed the session upstream and it
came back down.
canair refuses two operations, because the base is not yours to change:
- Editing definitions.
canair pids,signals,states,groupsandecu addrefuse to run against a layered profile. They point you tocanair profile adopt <name>. That command gives you a writable copy of the definitions too. - Mutating a base-layer capture.
captures uds --delete, the--set-*editors and--backfill-statesrefuse to run when a matched row belongs to the base. They name the file. Previewing with--dry-runis always allowed. You can freely edit rows in your layer.
canair profile show <name> prints both roots. canair profile list marks a layered profile with
layered over <base>.
The layer holds exactly what you recorded. For this reason, canair contribute ships your captures
on top of the definitions of the base with no extra work. You keep pulling definition updates from
upstream, and your own data accumulates where a reinstall cannot reach it.
During development: which canair sees your edits¶
canair resolves the repo-bundled profiles/ relative to the running canair code. It does not
use your current directory. Whether your edits to a bundled profile are live depends on which copy
of canair you run:
| You run | Runs the code in | Bundled profiles/ it reads |
|---|---|---|
uv run canair (from the repo root) |
your git working tree | the repo's profiles/ — edits are live |
a bare canair (uv tool install .) |
a frozen snapshot in uv's tool venv | a copy baked in at install time — edits are not seen |
When you contribute to a bundled profile, run uv run canair from the repo root. A bare
canair reads the snapshot from your last install. Edits to profiles/ in your checkout do not
appear until you reinstall (uv tool install . --reinstall). canair profile list and
canair status warn you when you run the snapshot copy.
No config flag makes a bare canair run the code of your checkout. Use uv run for that.
Setting profiles_dir (see above) points a bare canair at the profile data of your checkout.
This setting protects your work from loss. The code that runs is still the snapshot.