Skip to content

canair import

usage: canair import [-h] {uds,can,dbc} ...

[UDS+CAN] Import external CAN data into the active profile. Choose a kind:

  uds   device-free UDS capture (ECU:PID=PAYLOAD, domain A), or every reply
        in a diagnostic-bus frame log (--from-log)
        -> captures/*.json via the shared save machinery
  can   raw broadcast-CAN frame log (.asc/.blf/.csv/candump .log/.trc)
        -> captures/can/ native store + index.yaml (domain B)
  dbc   DBC signal definitions -> the profile's signals/ model (domain B)

uds is the domain-A (request/response) half; can/dbc are the domain-B
(passive broadcast) half. Frame logs are stored verbatim and indexed (not
exploded into the captures/*.yaml schema). SavvyCAN GVRET (.csv) is
auto-detected by header.

positional arguments:
  {uds,can,dbc}
    uds          Record externally-provided UDS payloads into captures/
                 (device-free)
    can          Import a raw broadcast-CAN frame log into captures/can/
    dbc          Import DBC broadcast signal definitions into the signals/
                 model

options:
  -h, --help     show this help message and exit

canair import uds

usage: canair import uds [-h] --label LABEL [--state STATE] [--notes NOTES]
                         [--capture-note CAPTURE_NOTE] [--time HH:MM:SS]
                         [--date YYYY-MM-DD] [--json] [--dir DIR]
                         [--from-log FILE]
                         [--log-format {auto,asc,blf,csv,log,gvret,trc}]
                         [--bus N] [--from-ts SEC] [--until-ts SEC]
                         [--keep-nrc] [--dry-run]
                         [ECU:PID=PAYLOAD ...]

Record externally-provided UDS payloads into the active profile (device-free capture import).

positional arguments:
  ECU:PID=PAYLOAD       One or more captures, e.g. CLU:22B002=62B002... (ECU
                        short name or hex TX id; PID/DID; reassembled UDS
                        payload, SID-first). Omit with --from-log

options:
  -h, --help            show this help message and exit
  --label LABEL         Session label (what this reading is)
  --state STATE         Vehicle power state(s) during capture (e.g. acc2,
                        ready). Repeatable.
  --notes NOTES         Session notes (context, source/attribution)
  --capture-note CAPTURE_NOTE
                        Per-capture note applied to each imported payload
  --time HH:MM:SS       Capture time (default: the import instant, like --date
                        defaults to today). A payload capture is always
                        timestamped so it can participate in time-aligned
                        analysis. With --from-log: the first reply's time
  --date YYYY-MM-DD     Capture date (default: today; sets the target file)
  --json                Machine-readable JSON output
  --dir DIR             Captures directory (default: active profile)

frame-log extraction:
  Record the data-read replies found in a CAN frame log instead of pasted payloads. --date and --time then stamp the FIRST reply (later ones follow the log's own clock); a log on the wall clock supplies both itself.

  --from-log FILE       Frame log of the diagnostic bus (.csv GVRET/python-
                        can, .asc, .blf, .log, .trc)
  --log-format {auto,asc,blf,csv,log,gvret,trc}
                        Log format (default: auto-detect by extension; .csv is
                        sniffed for GVRET)
  --bus N               Only frames from this log channel/bus number (default:
                        all)
  --from-ts SEC         Ignore frames before this log timestamp (seconds, as
                        in the log)
  --until-ts SEC        Ignore frames after this log timestamp (e.g. where the
                        log turns intermittent)
  --keep-nrc            Also record negative responses (7F ..) to single-
                        identifier reads
  --dry-run             Report what would be recorded without writing anything

  # One verified odometer reading with context
  canair import uds CLU:22B002=62B002E0000000FFB7008D08000000 \
      --label "Odometer" --state acc2 --time 09:38:15 \
      --notes "Verified 36104 km on dash by timwelchnz (GitHub wican-fw#478)"

  # Several PIDs captured together into one session
  canair import uds BMS:2101=6101FFF8... BMS:2102=6102... --label "SOC snapshot"

  # Every reply a dongle collected, from a GVRET/.asc/.blf log of the diagnostic bus
  canair import uds --from-log tap.csv --bus 1 --label "Dongle polling, READY" \
      --state ready --date 2023-01-12 --until-ts 2565 --dry-run

canair import can

usage: canair import can [-h] [--format {auto,asc,blf,csv,log,gvret}]
                         [--label LABEL] [--state STATE] [--notes NOTES]
                         [--source SOURCE] [--bitrate BITRATE] [--date DATE]
                         [--force] [--json]
                         file

positional arguments:
  file                  Path to a .asc/.blf/.csv/candump .log/.trc frame log

options:
  -h, --help            show this help message and exit
  --format {auto,asc,blf,csv,log,gvret}
                        Log format (default: auto-detect by extension; .csv is
                        sniffed for GVRET).
  --label LABEL         Session label for the index entry
  --state STATE         Vehicle power state(s) while logging (comma-separated,
                        e.g. 'driving')
  --notes NOTES         Free-text notes for the index entry
  --source SOURCE       Provenance (capture tool, or upstream URL)
  --bitrate BITRATE     Bus bitrate in bit/s (e.g. 500000)
  --date DATE           Log date YYYY-MM-DD (default: from log, else omitted)
  --force               Overwrite an already-imported log of the same name
  --json                Machine-readable result

canair import dbc

usage: canair import dbc [-h] [--bus BUS] [--tx-ecu TX_ECU] [--ids IDS]
                         [--dry-run] [--json]
                         file

Import DBC broadcast signal definitions into the signals/ model. A DBC that
cantools rejects as written (a malformed comment, a 29-bit ID without the
extended flag, a name starting with a digit, ...) is repaired in memory, never
on disk, and every repair is listed with its line.

positional arguments:
  file             Path to a .dbc file

options:
  -h, --help       show this help message and exit
  --bus BUS        Target bus (signals/<bus>.yaml; default: DBC filename)
  --tx-ecu TX_ECU  Annotate imported messages with this ECU
  --ids IDS        Comma-separated arbitration IDs to import (default: all)
  --dry-run        Print the diff without writing
  --json           Machine-readable result