Skip to content

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:

aliases:
  ioniq-2017: {variant: 28kwh}

An alias may also name the variant that the old name implied (variant:). {} implies nothing.

  • --profile ioniq-2017 and CANAIR_PROFILE=ioniq-2017 resolve to hyundai-ioniq-ae-ev. canair prints a one-line note that names the new name.
  • default_profile: ioniq-2017 in your config keeps working without the note. You can switch to the new name at any time with canair 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/ with extends: 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 contribute sends such a copy upstream under the current name of the profile.
  • canair profile list shows each rename as ioniq-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 car
  • variants.yaml, for names of one variant (for example, canair variants set-meta 38kwh "also_known_as=Ioniq vFL,Ioniq FL")
also_known_as: [Ioniq Electric, Ioniq EV, Classic Ioniq]

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:

  1. --profile NAME|PATH (global flag, before or after the subcommand)
  2. CANAIR_PROFILE environment variable
  3. default_profile in your config (set it with canair profile use NAME)
  4. 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 ID once. canair remembers the variant for each profile.
  • Pass the global --variant ID (or set CANAIR_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:

  1. --profiles-dir
  2. $CANAIR_PROFILES_DIR
  3. profiles_dir in config
  4. ~/.config/canair/profiles/ (your uncommitted profiles)
  5. 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:

canair profile overlay hyundai-ioniq-ae-ev

This command creates ~/.config/canair/profiles/hyundai-ioniq-ae-ev/. The directory contains an empty captures/ and a one-line marker. Nothing else:

extends: hyundai-ioniq-ae-ev

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, groups and ecu add refuse to run against a layered profile. They point you to canair 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-states refuse to run when a matched row belongs to the base. They name the file. Previewing with --dry-run is 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.