5. Capture¶
Decoding needs data under known conditions. One reading tells you almost nothing. A byte shows its meaning only when you watch it change while the car does something. A capture records payloads and tags them with what the car was doing. The analysis tools then have data to work with.
Save what you read¶
Add --save to any read to record it with context:
--labelis a free-text description of the moment ("plugged in, charging").--stateis the vehicle power state (driving,charging,ready,sleep, …). canair can suggest the state from the decoded values. See Vehicle states.--notesis anything else that you want to remember.
--save works with read, monitor, scan and discover. canair journals each save while
the data streams. A session that crashes or disconnects loses no data. To recover leftovers, run
canair captures uds --recover.
No device on hand? Import a reading¶
You may have a payload from another source: a forum post, a GitHub issue, or a reading that
someone took with another tool. canair import uds records it in your profile. It uses the same
machinery as --save. The result looks the same as a capture from a device, and you can decode it
immediately:
canair import uds CLU:22B002=62B002E0000000FFB7008D08000000 \
--label "Odometer" --state acc2 --notes "Verified 36104 km on dash"
Each capture has the form ECU:PID=PAYLOAD:
ECUis the short name of the ECU or its hex TX ID.PIDis the PID or DID.PAYLOADis the reassembled UDS payload, with the SID first.
Pass several captures to group them in one session. canair resolves the ECU address and rejects payloads that are not hex. It warns if the SID and DID echo of the payload does not match the PID (a misfiled frame). This is how canair onboards community readings without a live bus.
Import a whole frame log¶
Someone may have logged the diagnostic bus while their tool polled the car. Examples are a
Bluetooth dongle that runs an app with custom PIDs, or a workshop tester. The person then shared
the log. The Kona EV logs are one such
public (CC0) corpus. Every reply in a log is a capture that canair read --save would have
recorded. Extract them all at once:
canair import uds --from-log dongle-polling.csv --bus 1 \
--label "Dongle polling, READY" --state ready --date 2023-01-12 \
--until-ts 2565 --dry-run # preview; drop --dry-run to write
canair reads the log with the same readers as import can: GVRET .csv, .asc, .blf, candump
.log and .trc. Each positive reply to a data read (22 DID, or 21 LID on KWP2000) from an
ECU in the profile becomes one capture. The capture keeps its own timestamp. canair files it
under what the reply says it answers.
canair counts and reports everything that it leaves out. It never guesses. It leaves out:
- multi-frame replies with a lost frame (canair also notes these in the
qualityof the session) - replies to batched requests (
22 D1 D2 …), which canair cannot split safely - negative responses, unless you pass
--keep-nrc - replies from CAN IDs that are not in the profile (the report names them. Run
canair ecu addfor them, then run the import again)
A log has no absolute clock, unless someone recorded it on the wall clock. --date and --time
stamp the first reply. The other replies follow the timing of the log.
--from-ts and --until-ts (in the timestamps of the log) cut away a stretch that is known to be
bad. An example is the point where a capture tool starts to drop messages.
canair does not guess states from the log. Pass --state, or run
canair captures uds --backfill-states afterwards.
canair refuses to import the same log twice. It supports only normal addressing. It does not support the extended-addressing profiles whose frames carry a target-address byte before the PCI byte.
Capture contrast, not just data¶
The most useful thing you can do is capture the same PID in different conditions. Some examples:
- A byte that is constant while parked but ramps while you accelerate is a torque or speed candidate.
- A byte that flips only when you lock the doors is a body signal.
Plan runs that create contrast:
- Driving: accelerate, cruise, brake, coast.
- Charging: unplugged → plugged → charging → full.
- Body: lock and unlock, lights on and off, doors open and closed.
Also capture a reference signal that you already understand, next to the unknown signal. Examples
are GPS-confirmed speed or a known speed PID. The reference makes hunt and
correlation work.
Review what you've collected¶
canair captures uds --sessions # table of contents: when, what state, which ECUs
canair captures uds MyECU --summary # stats per PID
canair captures uds MyECU:2101 --diff # byte-level diff across captures
A bare canair captures MyECU 2101 still works. It is a shorthand for canair captures uds …
(the diagnostic domain). canair captures can lists the imported raw broadcast-CAN frame logs.
Note
Never edit the capture files in captures/ by hand. --save and import uds write
them, and canair manages them. See Captures & states.
Captures are shareable evidence
Well-labelled captures help the whole project. Others use them as raw material to decode and cross-check signals on the same car. Consider contributing a representative subset with your profile.
Next: 6. Analyze →