Broadcast CAN frames (domain B)¶
canair handles two kinds of controller area network (CAN) data. It analyzes and defines them in different ways:
| Domain | What it is | Identity | Signal definition |
|---|---|---|---|
| A. Diagnostics | request/response Unified Diagnostic Services (UDS) or Keyword Protocol 2000 (KWP2000) over the ISO 15765-2 transport protocol (ISO-TP) | (ECU, PID/DID) |
a freeform WiCAN expression over Bnn bytes, in ecus/ |
| B. Broadcast frames | periodic frames that no request elicits | arbitration ID | a linear signal in signals/<bus>.yaml, compatible with the CAN database (DBC) format |
In domain A, the identity (ECU, PID/DID) is an electronic control unit (ECU) plus a parameter ID
(PID) or data identifier (DID).
Most of canair is domain A (the bring-your-own-car journey). This page covers domain B: the passively broadcast traffic. This traffic carries drive-mode, regen, thermal and body signals. Often these signals are only on the internal bus. An on-board diagnostics (OBD-II) diagnostic read never exposes them.
On many cars (the bundled Ioniq included) the OBD-II port is gateway-isolated. Passive sniffing there sees almost no broadcast traffic. The realistic source of frames is an imported log, not
canair sniffon the OBD port. The log comes from SavvyCAN, another tool, or a device wired to an internal bus. Import is the front door.
The workflow¶
1. Import a frame log¶
canair import can reads a raw frame log. It stores the log verbatim under the
captures/can/ directory of the profile. It indexes the metadata of the log in
captures/can/index.yaml (frame count, distinct arbitration IDs, bitrate, …). High-volume logs
stay native. canair does not explode them into the captures/*.json schema.
canair import can drive.blf --label "drive fwd/N/rev" --bitrate 500000
canair import can drive.asc # .asc / .blf / candump .log / .trc
canair import can savvycan.csv # SavvyCAN GVRET (.csv, auto-detected)
canair captures can # list imported logs
canair reads these formats: .asc, .blf, python-can .csv, candump .log, .trc and
SavvyCAN GVRET .csv. canair detects GVRET from its header. To force it, use
--format gvret.
2. Find signals — correlate / hunt¶
Frame bytes go into the same analysis engine as diagnostic captures. You reference a frame byte
as 0xID:rN. This is raw-CAN space. It has no ISO-TP framing and no protocol control
information (PCI) bytes, and it is distinct from WiCAN Bnn.
# Which broadcast bytes move together across a drive?
canair correlate can drive.blf --min-r 0.9
# Which byte of arbitration ID 0x220 tracks a byte you already know (e.g. wheel
# speed on 0x386)? Sweeps every byte × interpretation and ranks by correlation.
canair hunt can drive.blf --id 0x220 --against 0x386:r0
# Which positions are the SAME signal broadcast on two arbitration IDs?
# (e.g. wheel speed mirrored on 0x386 and 0x331). --bits for bit-level,
# --allow-offset to also accept a different zero/scale.
canair correlate can drive.blf --find-mirrors
Both commands reuse the correlation, interpretation-sweep and linear-fit machinery of the
diagnostic correlate uds and hunt uds. The output (ranked |r|, fit, unit guess) therefore
reads the same.
correlate cantakes--bits,--min-rand--json.hunt cantakes the required--idand--against, plus--min-n,--topand--json.
The can kind is the domain-B counterpart of the default uds kind. A bare canair correlate …
or hunt … still targets diagnostic captures.
3. Define signals¶
When you identify a byte or bit field, record it in the signals/ sidecar. This is the
domain-B analogue of the signals of a PID. A broadcast signal differs from the freeform WiCAN
expression. It is a linear model (physical = raw*scale + offset over a contiguous bit
range). It is deliberately DBC-compatible.
canair signals upsert powertrain 0x386 WHL_SPD_FL \
--start-bit 0 --length 14 --byte-order little --scale 0.03125 --unit km/h \
--source "IONIQ_PCAN_drive.csv (fetch: scripts/fetch/fetch_can_corpus.py)"
canair signals list # review
canair validate signals # structural check
The edits (via canair signals and src/canair/yaml_edit/signals.py) change only the target
entry and keep comments. canair validates each edit and reverts it automatically on failure.
Bit numbering and value types¶
--start-bit follows DBC numbering. For --byte-order big, it names the most significant bit
of the field. For example, a 16-bit big-endian field in data bytes 4-5 is
--start-bit 39 --length 16 --byte-order big.
A raw value is an unsigned integer unless you pass one of these flags:
--signed— two's complement (DBC@0-/@1-). Use it for anything that can go negative, such as a motor speed in reverse.--float— an IEEE 754 value, 32 or 64 bits long (DBCSIG_VALTYPE_).
Update an existing signal¶
If you upsert a signal that already exists, canair changes only what you pass. The rest of the
signal keeps its stored value: byte order, provenance, notes, verification and typed decoding. For
example, canair signals upsert powertrain 0x386 WHL_SPD_FL --verified only marks the signal as
verified.
--unsignedand--integerundo--signedand--float.- An empty
--unit "",--source ""or--notes ""removes that field. --clear FIELD(repeatable) removesscale,offset,minormaxtoo.
Message options¶
Message options work with any upsert: --msg-name, --tx-ecu, --msg-length and the frame
format.
--msg-lengthis the DBC data length code (DLC). It is 0-8 bytes, or a size for CAN with flexible data rate (CAN FD): 12, 16, 20, 24, 32, 48 or 64. It must be long enough for every signal.- An ID above
0x7FFis an extended (29-bit) frame. - A frame longer than 8 bytes is CAN FD without further flags.
--extendedmarks an extended frame that is numbered at or below0x7FF.--fdmarks a CAN FD frame of 8 bytes or fewer.- Arbitration IDs end at
0x1FFFFFFF.
Provenance and evidence¶
Record where the signal came from in --source. Use a reproducible provenance string: the log
you used, a reference sheet, or dbc:<file> when the signal came from a DBC import. Keep the
supporting evidence (correlations, sample counts, reasoning) in --notes.
4. Interop — DBC import / export¶
Bootstrap signals/ from an existing DBC. You can also share your DBC with SavvyCAN, cabana,
cantools or the Wireshark CAN dissector:
canair import dbc car.dbc --bus powertrain --dry-run # preview
canair import dbc car.dbc --bus powertrain # DBC → signals/
canair export dbc --bus powertrain -o mycar.dbc # signals/ → DBC
DBC repairs¶
canair loads real-world DBCs (with overlapping signals) in non-strict mode. If cantools rejects a
DBC as written, canair repairs it in memory and parses it again. canair never changes the file
itself. It lists every repair with its line (and under repairs in --json).
The repairs cover dialect quirks that are common in hand-maintained DBCs such as those of opendbc:
- a malformed
CM_comment (dropped, because canair does not import comments) - a 29-bit ID written without the DBC extended flag
- a number without its leading zero (
.25) - a
VAL_table without its closing; - missing
BS_:/BU_:header lines - a message or signal name that starts with a digit. This is the one repair you see in the
result: the name gains a
_prefix (0_COUNTER→_0_COUNTER).
The full list is in src/canair/interop/dbc/repair.py.
What a round trip carries¶
A round trip carries:
- Each signal's layout (start bit, length, byte order), signedness, integer or float type,
scale, offset, min/max and unit. It also carries the value table (DBC
VAL_) when the signal is an unscaled integer. canair imports that signal astype: enumwithvalues. - Each message's name, data length (
length, the DBC DLC) and frame format. The frame format is standard or extended, classic or CAN FD. canair writes it with the DBCVFrameFormatattribute.
A round trip does not carry:
- messages without signals
- multiplexing (the signals of a multiplexed message import as plain, overlapping signals)
- value tables on scaled or float signals. A DBC table uses the raw value as its key. The
valuesof canair use the decoded value. The import lists the signals that this affects. - comments, senders/receivers, attributes such as cycle times, and signal groups
canair validate signals rejects some messages, for example a signal that overruns its frame or a
scale of 0. The import skips such a message and lists it. The import does not fail as a whole.
One signals/<bus>.yaml keys messages by number. canair therefore refuses a DBC with a standard
and an extended frame of the same number. Import the two halves of such a DBC into separate buses.
scripts/check/check_dbc_corpus.py --fetch checks this against
commaai/opendbc. It imports, validates, exports and
re-decodes every DBC. It compares the result against the parse of cantools. The check is
opt-in and fetches into the gitignored references/can/.
Storing raw-CAN logs (what's committed vs. fetched)¶
Raw frame logs get large. A few minutes of one bus is megabytes. Some logs come from other people's cars under unclear licenses. canair splits the logs by origin and license:
| Origin | License | Where it lives | Committed? |
|---|---|---|---|
| Your own capture | yours | profiles/<car>/captures/can/ |
Yes, fully — via Git LFS when large |
| Third-party, redistributable (CC0/CC-BY/MIT/public-domain/explicit permission) | permits redistribution | profiles/<car>/captures/can/ (or references/can/) with the license recorded next to it |
Yes — via Git LFS when large |
| Third-party, no / unclear license (e.g. the uhi22 Ioniq-28 corpus) | none | gitignored references/can/ |
No — fetch on demand (scripts/fetch/fetch_can_corpus.py) + a tiny fair-use excerpt under tests/fixtures/can/ |
The rule of thumb: your data goes in. Other people's data goes in only if the license lets you
redistribute it. A partial slice of unlicensed data is still unlicensed. The committed
tests/fixtures/can/ excerpts are acceptable because they are minimal, hand-trimmed fair-use
samples. They are not acceptable because they are "only part" of the log. Git LFS is a storage
mechanism only. It does not grant any redistribution right, so it never changes the license
question.
Git LFS¶
Git LFS tracks large binary and high-volume frame logs, so the repository
history stays small. The tracking rules are in .gitattributes:
*.blf,*.asc,*.trcand everything underprofiles/*/captures/can/**are stored in LFS. The exception iscaptures/can/index.yaml. It stays in plain git, socanair validate cancan read it in a checkout without the LFS objects, as in continuous integration (CI).- The tiny
tests/fixtures/**excerpts are explicitly in plain git, so they stay diffable and inspectable.
Contributors need Git LFS installed (git lfs install). Without it, a fresh clone shows pointer
files instead of the log contents. The free tier of GitHub caps LFS storage and bandwidth. This is
another reason that unlicensed corpora stay fetch-on-demand and are not committed.
Where things live¶
captures/can/— imported frame logs, native, indexed byindex.yaml(schemasrc/canair/schema/can_index_schema.json). Git LFS stores large logs (see Storing raw-CAN logs).signals/<bus>.yaml— broadcast signal maps, one file per bus (schemasrc/canair/schema/signals_schema.yaml).
Both are optional and absent until you import broadcast data. canair validate can and
canair validate signals check them. They skip the check without a message when the files do not
exist. See plans/2026-07-24-raw-can-analysis.md for the design.