canair monitor¶
Alias: mon
usage: canair monitor [-h] [--interval SECONDS] [--schedule {dynamic,fixed}]
[--no-backoff] [--session] [--wake] [--keep-all |
--keep-changes | --keep N] [--save] [--label TEXT]
[--state TEXT] [--notes TEXT] [--rulers]
[--notation NAME] [--include-static]
[--actuate ECU[,ECU]] [--wican WICAN]
[--transport {slcan-tcp,wican-ws,elm327-tcp}]
[--no-fallback] [--wait] [--elm-timeout MS]
[--timeout SECONDS] [--no-learn-frames] [--verbose]
[--timings] [--reboot] [--unsafe] [--force]
[STEP ...]
[UDS] Monitor ECUs/signals live in a scrollable, refreshing view. Positional STEPs use the multi mini-language (same as `canair read`). With no STEP on a terminal, an interactive picker offers saved groups and ECUs, then PIDs.
positional arguments:
STEP Query selector(s), @group(s), or multi mini-language
step(s)
options:
-h, --help show this help message and exit
--interval SECONDS Poll interval in seconds for PIDs with no profile
`period:` — or for every PID with --schedule fixed
(default 5.0; scale it live in the TUI with =/-)
--schedule {dynamic,fixed}
dynamic (default): poll each PID at its own profile
`period:`, falling back to --interval; fixed: poll
every PID every cycle, --interval apart
--no-backoff Keep polling a PID that times out or is answered
slowly at its normal rate (default: poll it less often
until it recovers, so it can't hold up the rest)
--session Enter extended session (10 03)
--wake Wake ECUs from deep sleep first (the ECU's wake:
ritual, else 10 01)
--keep-all Record every polled payload (full time-series) — the
default. Repeated payloads are folded on disk, so the
capture file stays compact
--keep-changes Record only value-transitions per PID (run-length;
drops immediate repeats, so the polling cadence is not
recorded)
--keep N Show only the last N history rows per PID in the live
view
--save Save results to captures/
--label TEXT Session label for --save
--state TEXT Session state for --save
--notes TEXT Session notes for --save
--rulers Show a byte-index ruler above the hex (in the notation
from --notation / display.byte_notation)
--notation NAME byte-index notation for output labels: wican
(default), isotp, torque, bix. Overrides the
display.byte_notation config key.
--include-static Include static and slow PIDs (identity/calibration
blocks and per-cycle records such as 21F2) in a bare-
ECU sweep. By default `canair monitor ECU` omits PIDs
with status: static or slow; naming one explicitly
(ECU:21F2) always polls it.
--actuate ECU[,ECU] Let the actuator pane (A in the TUI) switch these
ECUs' IOControl outputs and run their routines;
repeatable or comma-separated. Without it the monitor
never actuates. Each request goes out between two poll
requests, and every output still on is released on
exit and after a reconnect. Needs a terminal
--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.
--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 monitor Pick ECUs, then PIDs, interactively (TTY only)
canair monitor BMS:2101 Monitor BMS PID 2101 at twice its profile rate
canair monitor BMS:2101 --interval 2 PIDs without a profile period refresh every 2s
canair monitor BMS:2101 --schedule fixed --interval 1 Every PID every 1s
canair monitor "VCU:2101 BMS:2101" Cross-ECU monitor
canair monitor @charging Monitor a saved group (see `canair groups`)
canair monitor @driving CLU:220B A group plus an extra selector
canair monitor "skm-wake acc" "query IGPM:BC03,BC06"
canair monitor BMS:2101 --save --label "…" --state "READY, PARKED" Record while monitoring
canair monitor IGPM:BC03 --actuate IGPM --save --label "…" Switch outputs, watch them
Polling: by default each PID is read every half of its own `period:` from the profile
(the period is the WiCAN AutoPID cadence; set one with `canair pids set-pid-period`), and a
PID without one every --interval seconds. --schedule fixed reads every PID on every cycle,
--interval apart.
A PID that stops answering or is answered very slowly holds up every other PID's next
poll, so it is polled 2x, 4x, then up to 32x less often until it answers promptly again
(its ECU's other PIDs keep their rate); its row and the status line say so. --no-backoff
keeps polling it at the normal rate.
In the TUI every command is in the menu bar (f10, alt+the underlined letter, or a click)
and in the command palette (ctrl+p, search by name); each item shows its key. The status
line has the link, poll, recording and car zones; a click on one opens its detail. The
bottom line shows the last message (an error stays until the next key), or the selected
signal and the keys of the focused pane. Most used keys: space pauses, p changes what is
polled, =/- poll faster/slower, ↑/↓ select a signal, e/v/x/F edit/verify/ship/filter,
s labels the recording (or saves a snapshot without --save), n finishes the --save
recording and starts the next, E opens the event log, ? shows every key, q quits.
For a single one-shot read (no live refresh) use `canair read` instead.