Skip to content

canair ecu

usage: canair ecu [-h] <kind> ...

[UDS] Inspect or edit the profile's ECU registry.
  show          list ECUs, or show one ECU's details and PID stats (default)
  add           register a new ECU in the active profile's ecus/ (offline)
  rename        rename an ECU (rewrites its key and ecus/ file)
  revisions     list or edit an ECU's revisions (protocol/decoding versions)
  set-variants  say which variants an ECU is fitted to

A bare `canair ecu` or `canair ecu BMS` is shorthand for `canair ecu show …`.

positional arguments:
  <kind>
    show          List ECUs, or show one ECU's details and PID stats
    add           Register a new ECU in the active profile (offline; no
                  device)
    rename        Rename an ECU (rewrites its key and ecus/ file)
    revisions     List or edit an ECU's revisions (versions that differ in
                  protocol or decoding)
    set-variants  Say which variants an ECU is fitted to (ECU presence)

options:
  -h, --help      show this help message and exit

  canair ecu                 # plain list of all ECUs (one per line)
  canair ecu BMS             # details + stats for the BMS
  canair ecu MDPS            # aliases resolve too (MDPS -> EPS)
  canair ecu 0x7E4           # hex TX id also works
  canair ecu 0x7EC           # hex RX id resolves too (the ECU's response address)
  canair ecu --states        # add a STATES column (states each ECU is readable in)
  canair ecu --sort states   # group the list by vehicle state
  canair ecu BMS --json      # machine-readable
  canair ecu --json          # all ECUs as JSON
  canair ecu HVAC edit       # open HVAC's ecus/ YAML in $EDITOR (TTY only)
  canair ecu rename Unknown-7D5 EPB   # rename an ECU (rewrites key + file)
  canair ecu revisions VCU   # an ECU's revisions (see `canair ecu revisions -h`)

Columns & legend:
  BUS    physical CAN bus segment(s) the ECU sits on (profile-specific codes,
         e.g. Hyundai B-CAN/P-CAN/C-CAN/MM-CAN/H-CAN/ALL); some ECUs span two
         (shown `H-CAN/P-CAN`). Blank (`—`) when unknown. The list is sorted by
         BUS by default. Shown as the last (widest, most-variable) column so
         the numeric columns stay aligned.
  PIDS   number of active (non-ignored) PIDs/DIDs defined.
  VERIF  verified/total parameters (green when all verified).
  CAPS   number of saved captures for the ECU.
  cap    in the per-PID detail view, "N cap" = number of saved captures for
         that individual PID.
  STATES the vehicle states the ECU is readable/awake in — its ECU-level
         `vehicle_states`, or the union of its PIDs' when that's unset. Opt-in
         (`--states`); shown after BUS.

  Sort with `--sort {bus,name,tx,proto,pids,verif,caps,states}`: string/hex
  columns (bus, name, tx, proto, states) ascending; numeric columns (pids,
  verif, caps) descending. `name` breaks ties.

canair ecu show

usage: canair ecu show [-h]
                       [--sort {bus,name,tx,proto,pids,verif,caps,states}]
                       [--states] [--json]
                       [ecu] [{pids,edit}]

List ECUs, or show one ECU's details and PID stats.

positional arguments:
  ecu                   ECU name, alias, or hex TX/RX id (omit to list all)
  {pids,edit}           'pids': compact per-PID view with each PID's latest
                        decoded state (e.g. `canair ecu BMS pids`); 'edit':
                        open the ECU's ecus/ YAML file in $EDITOR (TTY only —
                        agents must use `canair pids` instead; e.g. `canair
                        ecu HVAC edit`)

options:
  -h, --help            show this help message and exit
  --sort {bus,name,tx,proto,pids,verif,caps,states}
                        List ordering: 'bus' (default; group by CAN segment)
                        or by column: name/tx/proto/states (ascending),
                        pids/verif/caps (descending)
  --states              Add a STATES column: the vehicle states each ECU is
                        readable/awake in (ECU-level vehicle_states, else the
                        union of its PIDs')
  --json                Output as JSON

  canair ecu                 # plain list of all ECUs (one per line)
  canair ecu BMS             # details + stats for the BMS
  canair ecu MDPS            # aliases resolve too (MDPS -> EPS)
  canair ecu 0x7E4           # hex TX id also works
  canair ecu 0x7EC           # hex RX id resolves too (the ECU's response address)
  canair ecu --states        # add a STATES column (states each ECU is readable in)
  canair ecu --sort states   # group the list by vehicle state
  canair ecu BMS --json      # machine-readable
  canair ecu --json          # all ECUs as JSON
  canair ecu HVAC edit       # open HVAC's ecus/ YAML in $EDITOR (TTY only)
  canair ecu rename Unknown-7D5 EPB   # rename an ECU (rewrites key + file)
  canair ecu revisions VCU   # an ECU's revisions (see `canair ecu revisions -h`)

Columns & legend:
  BUS    physical CAN bus segment(s) the ECU sits on (profile-specific codes,
         e.g. Hyundai B-CAN/P-CAN/C-CAN/MM-CAN/H-CAN/ALL); some ECUs span two
         (shown `H-CAN/P-CAN`). Blank (`—`) when unknown. The list is sorted by
         BUS by default. Shown as the last (widest, most-variable) column so
         the numeric columns stay aligned.
  PIDS   number of active (non-ignored) PIDs/DIDs defined.
  VERIF  verified/total parameters (green when all verified).
  CAPS   number of saved captures for the ECU.
  cap    in the per-PID detail view, "N cap" = number of saved captures for
         that individual PID.
  STATES the vehicle states the ECU is readable/awake in — its ECU-level
         `vehicle_states`, or the union of its PIDs' when that's unset. Opt-in
         (`--states`); shown after BUS.

  Sort with `--sort {bus,name,tx,proto,pids,verif,caps,states}`: string/hex
  columns (bus, name, tx, proto, states) ascending; numeric columns (pids,
  verif, caps) descending. `name` breaks ties.

canair ecu add

usage: canair ecu add [-h] [--name NAME] [--description DESCRIPTION]
                      [--id-protocol ID_PROTOCOL] [--rx-id RX_ID]
                      [--mode MODE] [--target-address TARGET_ADDRESS]
                      [--source-address SOURCE_ADDRESS] [--fc-id FC_ID]
                      [--notes NOTES] [--overwrite] [--dir DIR]
                      TX

Register a new ECU as ecus/<name>.yaml in the active profile.

Offline counterpart to `canair discover --register` (which needs a live bus): use this to seed a known ECU into a blank profile — e.g. one shared with another model-year — ready for contributions. The write is validated and comment-preserving.

positional arguments:
  TX                    ECU TX id (hex, e.g. 7C6 or 0x7C6)

options:
  -h, --help            show this help message and exit
  --name NAME           ECU short name (default: Unknown-<TX>)
  --description DESCRIPTION
                        Human description
  --id-protocol ID_PROTOCOL
                        Identity protocol (UDS | KWP2000)
  --rx-id RX_ID         CAN response address override (hex, e.g. 0x784) — for
                        an ECU whose response addr isn't tx_id + the profile's
                        addressing.rx_offset
  --mode MODE           Addressing mode (normal_11bit | normal_29bit |
                        normal_fixed_29bit | normal_extended_11bit |
                        extended_29bit) — required to seed a 29-bit ECU
  --target-address TARGET_ADDRESS
                        ISO-TP target extension byte (hex) —
                        extended-11-bit/29-bit modes
  --source-address SOURCE_ADDRESS
                        ISO-TP tester (source) byte (hex, default 0xF1) —
                        extended-11-bit modes
  --fc-id FC_ID         Flow-control arbitration override (hex) — functional-
                        TX / physical-RX ECUs
  --notes NOTES         Free-text notes
  --overwrite           Overwrite existing identity fields
  --dir DIR             ecus/ directory (default: active profile)

examples:
  canair ecu add 7C6 --name CLU --description 'Cluster (instrument panel)'
  canair ecu add 0x7E4 --name BMS --id-protocol KWP2000
  canair ecu add 0x704 --name BMS --rx-id 0x784   # non-standard response addr
  canair ecu add 0x18DB33F1 --name EVC --mode normal_29bit --rx-id 0x18DAF1DB --fc-id 0x18DADBF1
  canair ecu add 770 --name IGPM --notes 'Seeded offline; no PIDs yet'

canair ecu rename

usage: canair ecu rename [-h] [--dir DIR] ECU NEW_NAME

Rename an ECU in the active profile.

An ECU's name is its top-level YAML key plus its ecus/<name>.yaml filename, so this rewrites the key and moves the file. The write is validated and comment-preserving. Use it to promote a placeholder (e.g. Unknown-7D5) to a real name once identified.

positional arguments:
  ECU         ECU to rename: current name, alias, or hex TX/RX id
  NEW_NAME    New ECU short name

options:
  -h, --help  show this help message and exit
  --dir DIR   ecus/ directory (default: active profile)

examples:
  canair ecu rename Unknown-7D5 EPB
  canair ecu rename 0x7D5 EPB          # resolve the old ECU by hex id

canair ecu revisions

usage: canair ecu revisions [-h] [--json] ECU <action> ...

``canair ecu revisions`` / ``canair ecu set-variants`` — an ECU's revisions and presence.

A *revision* is a version of one ECU that differs in protocol or decoding (a KWP2000 VCU
that became UDS, a BMS with another cell count); the first declared is the reference. A
PID or signal is gated to revisions with ``canair pids set-revisions``; a variant says
which revisions its car can carry with ``canair variants set-revisions``. Every edit is
validated and reverted on failure, and a rename rewrites every reference.

positional arguments:
  ECU                ECU name
  <action>
    list             List the ECU's revisions (default)
    add              Declare a revision (the first declared is the reference)
    set-fingerprint  Add a fingerprint: evidence that recognises the revision
    rename           Rename a revision, rewriting its gates, variants' lists
                     and capture tags
    rm               Remove a revision (refused while anything refers to it)

options:
  -h, --help         show this help message and exit
  --json             Output the list as JSON

examples:
  canair ecu revisions VCU                         # list VCU's revisions
  canair ecu revisions VCU add KWP --protocol KWP2000
  canair ecu revisions VCU add UDS --protocol UDS
  canair ecu revisions VCU set-fingerprint KWP --responds 1A90
  canair ecu revisions VCU set-fingerprint UDS --identity part_number='36601-0E1*'
  canair ecu revisions VCU rename UDS UDS-2018     # rewrites gates, variants, capture tags
  canair ecu revisions VCU rm UDS-2018             # refused while anything refers to it
  canair ecu set-variants HEATER 60kwh             # fitted only to the 60 kWh car
  canair ecu set-variants HEATER --clear           # fitted to every variant

canair ecu revisions list

usage: canair ecu revisions ECU list [-h] [--json]

options:
  -h, --help  show this help message and exit
  --json      Output as JSON

canair ecu revisions add

usage: canair ecu revisions ECU add [-h] [--protocol PROTOCOL] ID

positional arguments:
  ID                   Revision ID naming what differs (KWP, UDS)

options:
  -h, --help           show this help message and exit
  --protocol PROTOCOL  The revision's identity protocol (UDS | KWP2000)

canair ecu revisions set-fingerprint

usage: canair ecu revisions ECU set-fingerprint [-h] [--responds HEX]
                                                [--identity FIELD=GLOB]
                                                [--software GLOB] [--clear]
                                                ID

Add one fingerprint to a revision: a safe identity read only this revision
answers (--responds), identity fields matching glob patterns (--identity), or
the ECU's software version matching a glob (--software, read as RECORD:TEXT,
e.g. F195:1.04*). A live session matches them to detect the revision.

positional arguments:
  ID                    Revision ID to add the fingerprint to

options:
  -h, --help            show this help message and exit
  --responds HEX        A safe read only it answers (e.g. 1A90)
  --identity FIELD=GLOB
                        An identity field and the pattern it matches
                        (repeatable, one fingerprint)
  --software GLOB       The software version it reports, as RECORD:TEXT (e.g.
                        'F195:1.04*')
  --clear               Drop the existing fingerprints first

canair ecu revisions rename

usage: canair ecu revisions ECU rename [-h] OLD NEW

positional arguments:
  OLD         Current revision ID
  NEW         New revision ID

options:
  -h, --help  show this help message and exit

canair ecu revisions rm

usage: canair ecu revisions ECU rm [-h] ID

positional arguments:
  ID          Revision ID to remove

options:
  -h, --help  show this help message and exit

canair ecu set-variants

usage: canair ecu set-variants [-h] [--clear] ECU [VARIANT ...]

Record that an ECU is fitted only to some of the profile's variants (its variants: list). Commands for another car then leave it out. --clear: fitted to every variant (the default).

positional arguments:
  ECU         ECU name
  VARIANT     Variant IDs (or comma list)

options:
  -h, --help  show this help message and exit
  --clear     Fitted to every variant

examples:
  canair ecu set-variants HEATER 60kwh
  canair ecu set-variants HEATER --clear