Skip to content
BUSMUST
中文Support

BMCLI stat

Reference version: BMCLI 1.6.3. Command names, parameters and machine-readable fields retain their source spelling.

Daemon-owned CAN/CAN FD bus statistics. Each open CAN channel has an independent session; --channel is always required so scripts never depend on an implicit current slot. STAT is a background observer: it uses its own named RxBroker cursor and does not claim the channel or open another physical BM_Read queue. It can therefore remain active while host logging, bounded message recv, foreground sends, ISO-TP, or UDS use their own broker cursors.

Terminal window
# Clear prior values and begin one session.
bmcli stat start --channel=10356/0


# Read a live snapshot as stable machine-readable JSON.
bmcli stat show --channel=10356/0 --format=json


# Freeze the session. Later show calls return the same frozen values.
bmcli stat stop --channel=10356/0


# Clear and begin again in one command.
bmcli stat restart --channel=10356/0 --format=json

show before start succeeds with state=not_started and zero statistics. stop is idempotent. An explicit channel close or CAN bitrate change clears the session; internal BUSOFF recovery keeps the session and reports the broker epoch change through integrity.discontinuities.

The frames object contains total, TX, RX, Classic CAN, CAN FD, BRS, standard/extended data, and standard/extended remote counts. TX counts are real RxBroker BM_ACK_DATA completion events; BMCLI does not count a send request as a transmitted frame. On loopback hardware, one accepted frame is therefore normally observed once as TX and once as RX.

bus_load.current_percent uses a fixed 1000 ms refresh window. A live or stopped partial bucket is normalized to the full 1000 ms bucket, so a frame observed shortly before show/stop cannot create an artificial load spike. Classic CAN reuses the BUSMASTER worst-case bit-count tables. CAN FD separates the arbitration and data phases; BRS frames use the channel data bitrate for the data phase. average_percent is the accumulated estimated wire time divided by elapsed time since start/restart, and peak_percent is the highest completed or frozen current window. The result is a protocol wire-time estimate, not an oscilloscope measurement. It deliberately favors low overhead over precision: the one-second refresh and worst-case tables may fluctuate by roughly 5% without indicating a fault. STAT reuses the daemon’s existing monitor pump, performs constant-time counters/table arithmetic per frame, and does not add a dedicated high-frequency worker or a second BMAPI receive poller.

controller_error_counters reports the CAN controller’s current TEC/REC values and the highest values observed at STAT command boundaries during the session. The firmware maps BM_STAT_TX_ERROR and BM_STAT_RX_ERROR directly to TEC and REC; these values can rise and fall and are therefore not accumulated or presented as captured CAN error frames. Sampling stays on command boundaries so STAT does not add a background BMAPI control-transfer poll. integrity.complete is false when the independent RxBroker consumer observes a gap, dropped frame, or epoch discontinuity; wire_time_unavailable_frames reports counted frames whose timing could not be estimated.

Text output is one key=value line. JSON/JSONL return one object and CSV returns one header plus one data row. Numeric load fields use percent units; bitrate fields use kbps. Every format reports both the resolved daemon channel slot and the requested channel_spec.

Source of truth: BMCLI 1.6.3 repository documentation. Run bmcli help <category> <action> --format=json for the exact contract of the installed version.