Collector: CAN and CAN FD

CAN and CAN FD (DBC)

Use this source to record a CAN or CAN FD bus directly: test benches, engine and drivetrain development, motorsport, battery and e-motor labs. The collector listens on a CAN adapter, decodes every frame with your DBC file and stores each signal as a channel named Message.Signal. It never sends data frames, and by default it asks the adapter to open in listen-only mode (listen_only: true). In listen-only mode the adapter does not acknowledge frames and sends no error frames, even at a wrong bitrate, so it cannot disturb the other nodes. Without it a CAN controller acknowledges every frame it receives and, at a wrong bitrate, transmits error frames that can push other nodes to error-passive or bus-off. Listen-only is guaranteed only for the adapters marked below; for the others the collector logs a warning at start and reports listen_only: 0 in its health values. Attach to a running vehicle only with an adapter that is listen-only.

Install it with pip install "kymoscope-collector[can]".

Live bus

sources:
  - name: Test bench CAN
    type: can
    interface: pcan            # socketcan, pcan, vector, kvaser, ixxat, slcan, gs_usb, ...
    channel: PCAN_USBBUS1
    bitrate: 500000
    dbc: [powertrain.dbc, body.dbc]

Scaling, offset, signedness, float signals and the byte order come from the DBC. Multiplexed signals are stored only when their multiplexer value is present in the frame. Signals with a value table (VAL_) are stored as their number and the labels ("First", "Second") are attached to the channel. ARXML, KCD and SYM files work in place of a DBC, and several files can be combined.

Interfaces and drivers

Any other interface supported by python-can works with its name and the options it documents, passed through bus_options. Listen-only is also set for Systec (passive state), CANtact (monitor) and Seeed Studio (silent); any other interface is opened as it is and the collector warns.

CAN FD, filters and rates

sources:
  - name: Battery pack CAN FD
    type: can
    interface: socketcan
    channel: can0              # bring it up first: ip link set can0 up type can bitrate 500000 dbitrate 2000000 fd on
    fd: true
    dbc: pack.dbc
    filters: [BMS_Status, 0x1A0]        # message names or ids; all messages of the DBC when left out
    signals: [CellVoltageMin, BMS_Status.Soc]   # allow-list; all signals when left out
    rate_limit_hz: 100                  # at most 100 values/s per signal; every frame is stored when left out

Log files

replay reads a recorded log instead of a bus, which is useful to try a DBC or to load a test that was logged elsewhere. All of the file is read once at start; after a restart it is not sent again unless the file changed (its size or modification time). kymoscope-collector backfill works on it with a time range.

sources:
  - name: Bench log
    type: can
    replay: run-0412.blf       # .blf, .asc or .trc
    dbc: powertrain.dbc

.blf logs carry absolute times. .asc and .trc logs carry times relative to the start of the measurement: the start is taken from the .asc header (Begin Triggerblock, local time of the machine that wrote it) or from replay_start (Unix seconds or an ISO date such as 2026-10-24T09:15:00+02:00), and otherwise it is the moment the collector starts.

Time stamps

Each value takes the time stamp the adapter gives the frame. Adapters with hardware time stamps (PCAN, Vector, Kvaser, Ixxat, SocketCAN) stamp the frame when it arrives on the wire, so the spacing between frames is exact even if the computer is busy; the time is expressed in the clock of the computer (UTC). Adapters without hardware stamping (slcan, serial, network) give the time the computer received the frame. If a driver delivers a time that is not a real date (counting from zero), the collector uses its own clock at the moment it reads the frame.

Options

Finding the channels

kymoscope-collector discover --config collector.yaml --source "Test bench CAN" --out tags.csv lists every signal of the DBC (after filters and signals) with its unit; it does not need the adapter to be connected.

Troubleshooting

• The source keeps retrying to open the adapter: the driver is not installed, the channel is wrong or another program (CANalyzer, the vendor tool) holds the adapter. Some adapters allow only one program at a time.
• Connected, but no values: wrong bitrate (a CAN controller at the wrong bitrate sees only error frames, counted in error_frames), the bus is silent, or the ids are not in your DBC (counted in unknown_ids). Extended ids (29 bit) must be defined as extended in the DBC.
• Bus-off: after a bus-off report from the driver the collector closes and reopens the adapter, counting reconnects. A bus that goes bus-off repeatedly has a wiring, termination or bitrate problem.
• Health values for this source: connected, reconnects, frames_per_s, values_per_s, unknown_ids (distinct ids not in the DBC), error_frames, bus_state (0 active, 1 passive, 2 bus-off or error), decode_errors, dropped_rate_limit, dropped (frames lost because the queue was full), listen_only (1 when the adapter is known to be listen-only, 0 otherwise).