Skip to content

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.