canair scan
usage: canair scan [-h] <kind> ...
[UDS] Scan an ECU. Choose a kind:
range sweep a PID/DID range (general purpose)
iocontrol IOControl discovery (UDS 0x2F; KWP2000 0x30 asks first)
routines SAFE RoutineControl discovery (UDS 0x31 SF03 / KWP2000 0x33, auto)
sessions SAFE diagnostic session-type discovery (0x10, auto UDS/KWP2000)
memory map which address ranges answer ReadMemoryByAddress (0x23; asks first)
A bare `canair scan BMS` (or `canair scan` alone) is shorthand for `canair scan range …`.
positional arguments:
<kind>
range Sweep a range of PIDs/DIDs on an ECU
iocontrol IOControl discovery (UDS 0x2F; KWP2000 0x30 asks first)
routines SAFE RoutineControl discovery (UDS 0x31 SF03 / KWP2000 0x33,
auto)
sessions SAFE diagnostic session-type discovery (0x10, auto UDS/KWP2000)
memory Map which address ranges answer ReadMemoryByAddress (0x23)
options:
-h, --help show this help message and exit
examples:
canair scan BMS # sweep a PID range on BMS (bare = range)
canair scan range # interactive wizard (pick ECU/service/range)
canair scan range IGPM --range BC01-BC0B # scan a specific DID range
canair scan iocontrol IGPM # SAFE actuator (IOControl) discovery
canair scan routines BCM # SAFE routine discovery
canair scan sessions BMS # SAFE diagnostic session-type discovery
canair scan memory BCM --range FEDE0000-FEDFFFFF # map readable memory (asks first)
Run `canair scan <kind> --help` for the flags of each kind.
canair scan range
usage: canair scan range [-h] [-i] [--service SVC] [--range START-END[,...]]
[--slots N] [--append HEX] [--session] [--yes]
[--wake] [--save] [--label TEXT] [--state TEXT]
[--notes TEXT] [--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]
Scan one or more ranges of PIDs/DIDs on an ECU. One scan at a time only. Without --range, a UDS ECU's DID families are swept: every high byte the profile shows it using (its 22/2F PIDs and its IOControl DIDs), the whole family by default (--slots narrows it).
positional arguments:
ECU ECU name or TX ID (e.g. BMS or 7E4). Omit for the
interactive wizard.
options:
-h, --help show this help message and exit
-i, --interactive Force the interactive wizard even when an ECU is given
--service SVC UDS service: a preset name (live-data, read-did,
iocontrol, routine) or a hex byte (default: smart per-
ECU)
--range START-END[,...]
PID/DID range in hex, or a comma list of ranges
(default: smart per-ECU)
--slots N With the smart default: sweep only the first N DIDs of
each DID family (1-256, default 256 = the whole
family). Can't be combined with --range.
--append HEX Hex bytes to append after each DID
--session Enter extended session (10 03)
--yes, -y Send a service that can change the car's state
(IOControl, RoutineControl, a DTC clear) without
asking first (required when stdin is not a terminal)
--wake Wake ECUs from deep sleep first (the ECU's wake:
ritual, else 10 01)
--save Save results to captures/
--label TEXT Session label for --save (asked for when omitted; with
no terminal the session is saved under a generated
label)
--state TEXT Session state for --save
--notes TEXT Session notes for --save
--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
getting started:
canair scan range # interactive wizard — pick ECU/service/range
canair scan BMS # smart defaults for that ECU (bare = range)
canair scan range IGPM # UDS ECU → read-did over its known DID families
canair scan range PSM --slots 32 # first 32 DIDs of each family (xx00-xx1F)
service presets (pass to --service, or use a raw hex byte):
live-data 0x21 KWP2000 paged live data (powertrain ECUs: BMS, VCU, MCU)
read-did 0x22 UDS ReadDataByIdentifier (body/comfort ECUs)
iocontrol 0x2F UDS InputOutputControlByIdentifier (actuators)
⚠ may actuate physical hardware — prefer `canair scan iocontrol` (safe subfunction only) and keep the car in a safe state
iocontrol-kwp 0x30 KWP2000 InputOutputControlByLocalIdentifier (powertrain actuators)
⚠ may actuate physical hardware — prefer `canair scan iocontrol BMS` (auto-selects 0x30, safe IOCP 0x00 only) and keep the car in a safe state
routine 0x31 UDS RoutineControl (diagnostic routines)
⚠ prefer `canair scan routines` (probes requestRoutineResults only)
examples:
canair scan range BMS --service live-data --range 01-FF
canair scan range 7E4 --service read-did --range BC01-BC0B
canair scan range SKM --service read-did --range B000-B01F,B100-B11F
canair scan range IGPM --service iocontrol --range E000-E0FF --append 03 --session
tips:
* Run ONE scan at a time — parallel scans lock up the WiCAN.
* Start with a small --range to gauge ECU response time, then widen.
* Add --save --label "..." to record results to captures/.
* For SAFE actuator/routine discovery use `canair scan iocontrol`/`routines`.
* A service that can change the car's state asks first (--yes to skip). RoutineControl
(0x31) is refused on a KWP2000 ECU, where it starts a routine.
canair scan iocontrol
usage: canair scan iocontrol [-h] [--did-range START-END]
[--throttle-ms THROTTLE_MS] [--session] [--wake]
[--mode HEX] [--yes] [--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 [ECU ...]
Probe returnControlToECU across an id range on one or more ECUs. The service is auto-selected per ECU from its id_protocol: UDS ECUs use InputOutputControlByIdentifier (0x2F, 16-bit DID); KWP2000 ECUs (BMS, VCU, MCU, AAF) use InputOutputControlByLocalIdentifier (0x30, 8-bit LID). Only returnControlToECU (00) is ever sent, never an actuating option. On UDS that is the standard release. ISO 14230-3 leaves the 0x30 option byte manufacturer-defined, so a KWP2000 sweep may actuate outputs: it asks for confirmation first (--yes to skip; it refuses non-interactively without it). On a profile with the nissan_c0_session quirk, KWP2000 ECUs get Nissan's layout instead, with no prompt: 30 {LID} 01 00 (is value 00 supported?) inside the Nissan session 10 C0, because there 30 {LID} 00 begins a one-shot command. Hits are written to pids/<ecu>.yaml under an iocontrol_discoveries: section.
positional arguments:
ECU ECUs to scan (at least one required)
options:
-h, --help show this help message and exit
--did-range START-END
Id range: DID for UDS (per-ECU defaults), LID 00-FF
for KWP2000 (default 00-FF)
--throttle-ms THROTTLE_MS
Delay in ms between probes (default 150)
--session Open a diagnostic session before scanning
--wake Wake ECUs from deep sleep first (the ECU's wake:
ritual, else 10 01)
--mode HEX Session mode for --session (default 03 = UDS extended;
81 = KWP2000 standard, e.g. BMS; on a profile with the
nissan_c0_session quirk KWP2000 ECUs default to C0 and
always open a session)
--yes, -y Skip the confirmation a KWP2000 0x30 sweep asks for,
since 30 {LID} 00 is not known to drive nothing (every
profile without the nissan_c0_session quirk)
--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 scan iocontrol IGPM # UDS 0x2F DID scan
canair scan iocontrol BMS # KWP2000 0x30 LID scan (asks first)
canair scan iocontrol BMS --session --mode 81 # sweep inside KWP2000 session
canair scan iocontrol IGPM BCM --did-range B000-BFFF
canair scan routines
usage: canair scan routines [-h] [--rid-range START-END]
[--throttle-ms THROTTLE_MS] [--session] [--wake]
[--mode HEX] [--yes] [--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 [ECU ...]
Probe routine results across a range on one or more ECUs. The service is auto-selected per ECU from its id_protocol: UDS ECUs use RoutineControl (0x31, requestRoutineResults SF 0x03); KWP2000 ECUs (BMS, VCU, MCU, AAF) use RequestRoutineResultsByLocalIdentifier (0x33). 0x31 (StartRoutine on KWP2000) is NEVER sent to a KWP2000 ECU — only the read-only results service. Hits are written to pids/<ecu>.yaml under a routines: section.
positional arguments:
ECU ECUs to scan (at least one required)
options:
-h, --help show this help message and exit
--rid-range START-END
RID range for UDS (default F000-F0FF); KWP2000 ECUs
use LID 00-FF
--throttle-ms THROTTLE_MS
Delay in ms between probes (default 150)
--session Open a diagnostic session before scanning
--wake Wake ECUs from deep sleep first (the ECU's wake:
ritual, else 10 01)
--mode HEX Session mode for --session (default 03 = UDS extended;
81 = KWP2000 standard, e.g. BMS)
--yes, -y Skip the confirmations: the one a KWP2000 sweep asks
for where 0x33 is not known to be side-effect-free (a
nissan_c0_session profile), and the one for an ECU
whose protocol the profile does not record (run
`canair identity ECU` to record it)
--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 scan routines IGPM # UDS 0x31 SF03
canair scan routines BMS # KWP2000 0x33 LID scan (auto)
canair scan routines BMS --session --mode 81 # sweep inside KWP2000 session
canair scan routines IGPM BCM --rid-range F000-F0FF
canair scan sessions
usage: canair scan sessions [-h] [--modes HEX[,HEX...]]
[--throttle-ms THROTTLE_MS] [--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 [ECU ...]
Probe which DiagnosticSessionControl (service 0x10) session types an ECU supports. The session-mode set is auto-selected per ECU from its id_protocol: UDS ECUs are probed with 01 (default) + 03 (extended); KWP2000 ECUs (BMS, VCU, MCU, AAF) with 81 (standard) + 82 + 83 (extended), plus any OEM session a profile quirk permits on KWP2000 (C0 with nissan_c0_session). Every mode is checked against the safety policy for the ECU's protocol first and a refused one is skipped — the programming sessions (UDS 0x02, also 0x82 on a UDS ECU; KWP2000 0x85) are NEVER probed. Results are written to ecus/<ecu>.yaml under a sessions: section.
positional arguments:
ECU ECUs to scan (at least one required)
options:
-h, --help show this help message and exit
--modes HEX[,HEX...] Comma-separated 0x10 sub-functions to probe,
overriding the per-ECU protocol default (e.g. 01,03 or
81,82,83). Modes the safety policy refuses for the
ECU's protocol (02/85, 82 on UDS, the OEM band) are
skipped.
--throttle-ms THROTTLE_MS
Delay in ms between probes (default 200)
--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 scan sessions IGPM # UDS: probe 10 01 / 10 03
canair scan sessions BMS # KWP2000: probe 10 81 / 82 / 83 (auto)
canair scan sessions BMS VCU MCU # several ECUs in one run
canair scan sessions IGPM --modes 01,03,10 # override the probed modes
canair scan memory
usage: canair scan memory [-h] [--range START-END[,…]] [--step HEX]
[--no-block] [--block-limit N] [--dry-run]
[--format ALFID|kwp] [--session] [--mode HEX]
[--throttle-ms THROTTLE_MS] [--yes] [--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
Map which address ranges of one ECU answer memory reads. The scan reads one byte every --step bytes, bisects each change to its exact address, then finds the largest block that comes back whole inside a readable region, doubling from 16 bytes up to --block-limit and stopping at the first that fails. It stops on serviceNotSupported, on securityAccessDenied (canair never unlocks), on conditionsNotCorrect to every read, and when the ECU stops answering. A silent address is mapped as no_answer when the ECU still answers at the last readable one, and past it the probes step to the next aligned boundary. The map, the format and the block are written to the ECU's memory: section (--dry-run: not). With no --range the scan maps the whole space of the ECU's memory format when its addresses are 3 bytes or fewer (every KWP2000 ECU: 0x000000-0xFFFFFF) at about 256 probes; a wider space (4-byte UDS addresses) needs --range from the microcontroller's memory map. Asks before the first read, naming the range (--yes to skip).
positional arguments:
ECU ECU name or TX id
options:
-h, --help show this help message and exit
--range START-END[,…]
Hex address ranges to map (default: the format's whole
space, if it has addresses of 3 bytes or fewer)
--step HEX Probe every HEX bytes before bisecting (default 1000
with --range; about 256 probes across the default
space)
--no-block Skip the search for the largest block
--block-limit N Largest block the search tries (default 128). Some
ECUs hang on a read larger than they support until
their supply is cycled; raise it with care
--dry-run Print the map but do not write it to ecus/
--format ALFID|kwp Memory format when the ECU declares none: a UDS ALFID
(24 = 2-byte size, 4-byte address) or kwp. Saved by
`canair memory set` or `canair scan memory`.
--session Open a diagnostic session first (--mode, else the
ECU's memory.session, else 03)
--mode HEX Session mode for --session
--throttle-ms THROTTLE_MS
Delay in ms between reads (default 20)
--yes, -y Skip the confirmation before the first read
--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 scan memory OBC
canair scan memory BCM --range FEDE0000-FEDFFFFF
canair scan memory HVAC --range 000000-00FFFF --format 13 --step 100
canair scan memory MCU --range 000000-0FFFFF --step 10000 --no-block