BMCLI logging

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

Online (host-side) CAN/CAN FD and LIN traffic recording writes ASC or BLF. For on-device (offline) ASC or BLF logging to the device’s flash, use logging start --hardware or the equivalent offline logging start (see offline).

Multi-channel: --channel=A,B,C records all listed channels interleaved into ONE output file. Each frame is tagged with a LOGICAL channel number (1-based position in this recording, NOT the device’s physical port). The file header carries a // ch<N> = SN<serial>/port<physical> mapping comment so the logical numbers can be decoded.

Host ASC files use the same Vector-compatible formatter in standalone and daemon modes. The header contains // producer=BMCLI; build=<version>; mode=online; classic CAN and CAN FD fields, direction/remote flags, positive timestamp sign column, and logical channel numbers therefore do not depend on which execution mode created the file. All host ASC text lines use explicit CRLF bytes on every supported operating system.

logging start

Record CAN/CAN FD or LIN traffic to one or more host ASC/BLF files. In daemon mode, recording runs as a background singleton; a second start is rejected. Standalone and daemon execution use the same option validation, naming, segmentation, timestamp, finalization, and status model.

bmcli logging start --channel=10356/1 --path=log.asc
bmcli logging start --channel=10356/0,10356/1 --output=log.asc --duration=60  # alias retained
bmcli logging start --channel=10356/0,10356/1 --path=log.blf --log-format=blf --format=json
bmcli logging start --channel=10356/1 --path=log.asc --segment-duration=300
bmcli logging start --channel=10356/1 --path=log.blf --log-format=blf --path-mode=time --segment-size=104857600
bmcli logging start --channel=10356/1 --path=log.asc --segment-duration=60 --max-files=10 --wrap
bmcli logging start --hardware --channel=10356/0,10356/1 --path=log.asc  # on-device (== offline logging start)

Option	Default	Description
`--channel`	(required)	Channel(s): comma-separated `SN/port` (e.g. `10356/1`), `UID/port`, legacy index, or name.
`--path`	(required)	Canonical output path or naming template.
`--output`	—	Input alias for `--path`; specifying both is invalid even when values match.
`--log-format`	`asc`	Log file format: `asc` or `blf` in host and on-device modes. Global `--format` controls command output only.
`--duration`	infinite	Total recording duration in seconds; it does not control segmentation.
`--bitrate`	`500/2000`	Standalone CAN timing only: one rate means nominal=data and `N/D` is explicit.
`--path-mode`	`fixed` or inferred `index`	`fixed`, `index`, or `time`; see naming rules below.
`--segment-duration`	disabled	Segment duration in seconds, 1..604800. Rotation is checked with monotonic elapsed time.
`--segment-size`	disabled	Projected finalized segment size in bytes, 1048576..4294967296.
`--max-files`	unlimited	Retain 1..1000 finalized files in successful wrap steady state; requires at least one segmentation threshold.
`--wrap`	off	At the file limit, wrap the slot window; after publishing a new segment, evict the recorded old slot path. Requires `--max-files`.
`--overwrite`	off	Permit replacement at the exact generated final/`.partial` candidate. When enabled, BMCLI may replace an existing file at that generated path regardless of its origin.
`--hardware`	off	Record ON-DEVICE to generation-2.5 storage. Generation-3 devices support online recording only. Equivalent to `offline logging start`.

Host-side rules:

Without multi-file options, the mode is fixed. If a segmentation threshold, --max-files, or --wrap is supplied without an explicit mode, BMCLI infers index; --overwrite alone does not change the default. Explicit fixed conflicts with segmentation, max-files, or wrap. --max-files requires a threshold, and --wrap requires max-files.
fixed uses the exact path. index inserts a 1-based number before the extension. With max-files the width is digits(max-files) (trace.01.asc through trace.10.asc for 10); without it, natural numbers are unpadded.
time inserts synchronized 64-bit PTP UTC as YYYYMMDD_HHMMSS. The first candidate in a formatted second has no disambiguator; subsequent candidates use .2, .3, and so on without padding or a digit limit. Returning to an earlier second continues that second’s counter. When device PTP is unavailable or still contains uptime instead of UTC, recording uses the existing BMAPI host timestamp mapping (or host UTC for the initial empty-channel origin). It does not change the device clock. A cold channel therefore does not require a warm-up frame to avoid a 1970 filename or a huge first-frame offset. This fallback does not establish precision synchronization between independent analyzers.
BMCLI first fixes the logical candidate and then applies collision policy; it never skips to a different index/time suffix to avoid an existing file. Output is written through an exclusively created .partial file, finalized, and atomically published. An incomplete .partial is not reported as a successful recording.
Duration rotates before the next object when elapsed is >= the threshold. Size rotates when the next object’s projected finalized size is > the threshold. A first object larger than the threshold is accepted into an empty segment. When a non-wrapping file limit is reached, that trigger object is rejected before acceptance and recording stops normally with file_limit.
The host-only path-mode, segmentation, max-files, wrap, and overwrite options cannot be combined with --hardware. BMCLI does not expose append, create-new-file-on-start, timestamp-mode, relative timestamps, filters, ID triggers, comments, BBD, or BUSMASTER LOG in this command.

logging stop

bmcli logging stop        # stop host-side recording
bmcli logging stop --hardware --channel=<generation-2.5-SN/port>   # stop on-device recording

Stopping host-side recording is a host-file-write operation: it requests the host worker to stop and finalize its file and does not transmit a bus frame. --hardware stops on-device recording and is separately advertised in JSON Help as a device-disruptive permission override because it changes analyzer state.

logging status

Survey of all recording-capable entities. Does NOT require --channel.

$ bmcli logging status
[host] active channel_mask=0x0005 channel_count=2 file=all.asc elapsed=12s msgs=1234 gaps=0 dropped=0 errors=0 last_error=(none)
[dev 10356] offline=on  mode=always_on channel_mask=0x0005 channel_count=2 path=log.asc storage=12/64 MB free
[dev 10357] offline=off

[host] — host-side (online) recording, tracked by the daemon (standalone mode: a foreground recording IS this process, so nothing to survey).
[dev SN] — each USB device’s on-device recording state via BM_GetLogging. Devices are independent (per-device on/off). Devices without offline storage show n/a.

Optional --channel=<spec> filters to the matching entity. --format=json produces structured output; devices without offline storage report supported=false; channel_mask, channel_count, and the legacy channels field are all null because the device has no corresponding configuration semantics.

In daemon mode, logging start, logging stop, and logging status honor the global --format=json and --format=jsonl output contracts. Each bounded success is one complete JSON object (one line for JSONL). Status returns one object containing a host object and a devices array; it never prefixes or appends human-readable survey lines to structured stdout.

Host JSON status exposes normalized recording_id, state/active, channel_mask, channel_count, legacy channels, and channel_specs. channels remains the BMCLI 1.x compressed 1-based logical-channel array; channel_specs is ordered by 0-based daemon slot and maps every selected mask bit to its stable device serial and physical port. The invariant is channel_count == popcount(channel_mask) == len(channels) == len(channel_specs). The remaining host fields include format, canonical path, path mode, thresholds, max-files, wrap/overwrite, current segment number/slot/paths/state/bytes/messages/elapsed, finalized and rotation totals, accepted/written/failed/rejected message counters, bytes, gaps/dropped/errors, and stable rotation/stop/error reasons. messages equals written_messages; message_count remains a compatibility alias. Open, write, flush, close, publish, and broker failures move the worker to stopped and remain visible until the next successful start. Standalone logging likewise exits nonzero when a write/finalization fails; it never reports an incomplete file as successful.

For each supported on-device logging entry, channel_mask is the BMAPI channel bitmap and channel_count is its set-bit count. The numeric BMCLI 1.x channels field is retained as a legacy/deprecated alias whose value equals channel_mask; it is not a channel count. Text output uses the explicit channel_mask= and channel_count= labels.

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