canair dtc
usage: canair dtc [-h] <kind> ...
[UDS] Read, clear or review Diagnostic Trouble Codes. Choose a kind:
read read stored DTCs (UDS 0x19 / KWP2000 0x18), or clear them with --clear (0x14)
log show the last logged scan, offline (no device)
A bare `canair dtc BMS` (or `canair dtc --all`, or `canair dtc` alone) is shorthand for `canair dtc read …`.
positional arguments:
<kind>
read Read or clear DTCs on one ECU, or scan every ECU (--all)
log Show the last logged DTC scan, offline (no device)
options:
-h, --help show this help message and exit
examples:
canair dtc BMS Read all stored DTCs (bare = read)
canair dtc --all Scan every ECU (logs + shows changes since last scan)
canair dtc BMS --clear Clear all DTCs on one ECU (asks to confirm)
canair dtc log Show the last logged full-sweep scan (offline)
canair dtc log BMS Show the last logged scan for one ECU (offline)
Run `canair dtc <kind> --help` for the flags of each kind.
canair dtc read
usage: canair dtc read [-h] [--all] [--no-log] [--no-snapshots] [--no-retry]
[--label LABEL] [--state STATES] [--save]
[--notes NOTES] [--mask HEX]
[--protocol {auto,uds,kwp}] [--supported] [--clear]
[--group HEX] [--yes] [--session] [--wake]
[--wican WICAN]
[--transport {slcan-tcp,wican-ws,elm327-tcp}]
[--no-fallback] [--wait] [--elm-timeout MS]
[--timeout SECONDS] [--no-learn-frames] [--json]
[--verbose] [--timings] [--reboot] [--unsafe] [--force]
[ECU]
Read stored Diagnostic Trouble Codes with UDS 0x19 (reportDTCByStatusMask) or KWP2000 0x18, or clear them with 0x14. Clearing mutates ECU fault memory and prompts for confirmation unless --yes is given. An ECU answers only in some power states (its vehicle_states in the profile), and many clear only with the ignition on and the engine or drive system off. Every read is recorded to the DTC log (`canair dtc log`), which lives in user state, not in the profile.
positional arguments:
ECU ECU name or TX ID (e.g. BMS or 7E4)
options:
-h, --help show this help message and exit
--all Scan every ECU in the profile for DTCs (protocol auto-
selected per ECU)
--no-log Don't record this scan to the DTC log (scans are
logged by default, reporting what cleared/appeared
since the last scan)
--no-snapshots Don't read the snapshots a UDS ECU stored with its
codes (19 03 / 19 04). By default each reported code's
snapshots are read and decoded with the profile's
PIDs; with --all that is a final step, which a
keypress (s or esc) skips on a terminal
--no-retry With --all, don't retry unresponsive ECUs (by default
a no-response ECU is retried once with a wake + longer
timeout so it isn't skipped)
--label LABEL Optional label for the logged scan entry (e.g. 'before
clearing')
--state, --vehicle-states STATES
Vehicle power state(s) during the scan, recorded on
the log entry (comma-separated, e.g. 'READY' or
'SLEEP, PLUGGED'; case-insensitive). Vocabulary from
vehicle_states.yaml (`canair states`).
--save Save the snapshot replies read to captures/, each
under its own 19 04 request (never as a live read of
the DID); --label/--state/--notes describe the session
--notes NOTES Session notes for --save
--mask HEX statusOfDTC mask for the UDS read (hex, default FF =
all; falls back to 08 if the ECU rejects FF with
requestOutOfRange)
--protocol {auto,uds,kwp}
DTC protocol: uds (0x19/0x14), kwp (KWP2000
0x18/0x14), or auto (from the profile's id_protocol).
Default: auto
--supported KWP2000 only: list every DTC the ECU supports (18 03
FF 00) instead of its stored ones. This is a
catalogue, not a fault list, so it is shown as raw hex
and never logged. Not combinable with --all or --clear
--clear Clear DTCs (ClearDiagnosticInformation 0x14) instead
of reading
--group HEX groupOfDTC to clear (hex: 3 bytes on UDS, 2 on
KWP2000). Default: every DTC (FFFFFF on UDS; FF00 on
KWP2000, then FFFF if the ECU rejects FF00)
--yes, -y Skip the clear confirmation prompt
--session Enter extended session (10 03)
--wake Wake ECUs from deep sleep first (the ECU's wake:
ritual, else 10 01)
--wican WICAN WiCAN address: ap or IP (default: config
transport.host / default_wican=ap)
--transport {slcan-tcp,wican-ws,elm327-tcp}
CAN transport: slcan-tcp (raw CAN), wican-ws (WiCAN
ELM327 WebSocket), or elm327-tcp (direct ELM327
adapter over TCP). Overrides the config
`transport.type` (default: slcan-tcp).
--no-fallback Don't auto-fall-back to other configured devices when
the selected one is unreachable (see config
transport.fallback).
--wait Keep retrying to reach the device indefinitely, then
start as soon as it comes online (Ctrl-C to stop). For
'monitor', also reconnects forever if the connection
drops mid-session (auto-failover to another same-
transport device is bounded by default; --wait makes
it unbounded).
--elm-timeout MS ELM327 ECU response timeout in ms (sent as ATSTxx
after init)
--timeout SECONDS Overall UDS response timeout in seconds (default 3.0
ELM / 2.0 raw). Overrides any per-ECU
response_timeout_ms for the whole run.
--no-learn-frames Don't write response_frames back into the profile's
ecus/ when this session confirms how many CAN frames a
PID's response occupies (the count that lets the
adapter answer without waiting out its full ECU
timeout). Use when reading a car the active profile
doesn't describe.
--json Output results as JSON
--verbose, -v Show raw transport traffic and expressions
--timings Print per-ECU/PID round-trip timing stats on exit (to
stderr)
--reboot Reboot WiCAN after session to restore AutoPID mode
(skipped on firmware v6, which resumes AutoPID by
itself)
--unsafe Bypass the dangerous-command blocklist: each refused
command asks for typed consent before it is sent.
Works only after the user sets safety.allow_unsafe to
true at a terminal (canair config set
safety.allow_unsafe true)
--force Ask a session already holding the connection to
release it, then wait for it
examples:
canair dtc BMS Read all stored DTCs (status mask FF)
canair dtc --all Scan every ECU (logs + shows changes since last scan)
canair dtc --all --no-log Scan every ECU without recording to the DTC log
canair dtc BMS --label fixed Read + log a single-ECU scan with a label
canair dtc --all --state ready Log a full scan tagged with the vehicle state
canair dtc --all --no-snapshots Scan every ECU without reading DTC snapshots
canair dtc CCM --save --label fault Read + keep the snapshot replies in captures/
canair dtc BMS --mask 08 Read confirmed DTCs only (mask 0x08)
canair dtc IGPM --session --wake Wake + read in extended session
canair dtc BMS --json Machine-readable output
canair dtc BMS --clear Clear all DTCs (asks to confirm)
canair dtc BMS --clear --yes Clear without the confirmation prompt
canair dtc BMS --protocol kwp Force KWP2000 readDTCByStatus (0x18)
canair dtc BMS --supported List every DTC a KWP2000 ECU supports (not a fault list)
canair dtc log
usage: canair dtc log [-h] [--json] [ECU]
Show the most recent logged DTC scan without touching the device (useful when the WiCAN is offline): each code decoded, and the change since the previous scan of the same scope. The scope is the full sweep (`canair dtc --all`) by default, or one ECU when named. The full-sweep view also lists every ECU read or cleared on its own since that sweep, so a later single-ECU scan is not hidden behind an older sweep.
Only scans recorded for the selected car (--variant) and its ECU revisions are used: a code read from another car, or from another revision of the ECU, says nothing about this one. The log lives in user state (<config dir>/dtc_log/<profile>.yaml), not in the profile, so reinstalling or re-cloning canair cannot erase it; `canair config` shows where.
positional arguments:
ECU ECU name or TX ID (omit for the full sweep)
options:
-h, --help show this help message and exit
--json Output as JSON
examples:
canair dtc log Last logged full sweep, and each ECU read on its own since
canair dtc log BMS Last logged scan of one ECU
canair dtc log --json Machine-readable (the scan, the previous one, the diff,
the ECUs read since)