Read ASC and raw CAN CSV

Distinguish two CSV inputs. signal_csv already contains physical columns such as time, voltage, and current. A raw_can_csv row still contains a message ID and hexadecimal bytes, which need DBC decoding. Equal filename extensions do not imply equal contents.

ASC/BLF continuations support execution.process_count and an independent file_merge selection. See continuous-file multiprocessing for complete examples and cross-file state. These added execution paths do not support raw CAN CSV.

A DBC defines CAN message fields: for example, the first byte of ID 0x100 may represent Voltage with scale 1 and unit V. It does not supply acquisition timestamps. It can define message periods used for defaults such as validity, but does not establish measurement points or current direction. ASC is a text message log; BLF is a binary log. Both reader paths feed decoded signals into the same analysis engine.

Sources below are items in the root sources list; signals refers to their decoded fields. Raw CSV reads mapped columns, while ASC reads message lines. Both produce signal updates with a common time representation.

Complete minimal examples and column mapping

Download input-asc-minimal.yaml, joint.asc, and joint.dbc, keeping the relative data layout. From the examples directory:

chronaxis run input-asc-minimal.yaml --output asc-minimal-result

This binds only Voltage and integrates it. The DBC applies 2 × raw + 1: bytes 1, 3, 1 become 3, 7, 3 V, each lasting 1 second, giving 13 V·s. Do not repeat the DBC scaling in signals.

input-raw-csv-minimal.yaml reads raw-can-example.csv using the same DBC and signal definition, also producing 13 V·s. Explicit id_base: 16 reads text 100 as hexadecimal, matching decimal DBC ID 256. Payload text such as 01 05 is bytes, not a voltage value.

input-raw-csv-mapping.yaml changes direction from a fixed true value to the direction column. Its value_map maps Rx→true and Tx→false. strip: true removes the leading/trailing spaces in the first row's Rx before matching. All rows are Rx here, so the voltage integral remains 13 V·s. Unlisted text produces a mapping error rather than becoming transmit or receive automatically.

chronaxis run input-raw-csv-minimal.yaml --output raw-csv-result
chronaxis run input-raw-csv-mapping.yaml --output raw-mapping-result

All three annotated files contain complete source, signal, and calculation declarations. Analysis output directories can be reused; filenames receive a timestamp suffix. The excerpts below adapt real input formats and do not replace those complete examples.

Complete source fields

Paths are relative to sources[]; for example, reader.decode_policy is sources[].reader.decode_policy. These fields apply to can_asc or raw_can_csv source items.

Explicit files retain order; matched files use natural order. Default sources may mix ASC/BLF; explicit can_asc selects only ASC. Time regression does not automatically become the next day. If a second file restarts at zero and is known to begin at session second 100, explicitly set its offset to 100s. Run independent experiments separately.

ASC: read common formats directly

This excerpt replaces the root sources list of a complete analysis. Supply actual sample.asc and sample.dbc; do not insert a second sources parent inside an existing item.

sources:               # Input sources used by this analysis
  - path: sample.asc   # Input file path, relative to the configuration
    dbc_by_channel:    # DBC files indexed by user-facing CAN channel
      '1': sample.dbc  # DBC for channel 1; channel keys are strings

Fields below are inside sources[].reader.

ASC time unit defaults to s and, if explicit, must be s. Encoding defaults to utf-8-sig; UTF-16/32 are unsupported. A line not matching the selected dialect fails; the reader does not try different parsers until one accepts it.

ASC channel 1 is configuration channel 1. ID suffix x marks extended frames; ID magnitude alone cannot decide. FD DLC differs from byte count: DLC 10 means 16 bytes, 15 means 64. A zero-byte FD data frame is not automatically a remote frame.

A classic frame may have a suffix such as Length = 238000 BitCount = 123 ID = 440. All three fields must be present in that order with nonnegative decimal values. The trailing ID must equal the main message ID: hexadecimal 1B8, for example, matches decimal 440. The suffix is recognized during the same read; missing fields, wrong order and inconsistent IDs still fail.

ASC also accepts the following records:

Error frames remain error frames: diagnostic IDs, DLCs and possibly damaged data are not decoded as normal messages. Unknown events, incomplete diagnostics and malformed data rows still fail with the file and physical line number.

Two meanings of absolute/relative time must be distinguished:

Without a reliable acquisition date, use relative analysis time. Do not substitute today's computer date for the log date.

Raw CSV: declare each column's meaning

This partial root sources section needs your actual input and DBC plus the rest of the analysis:

sources:                      # Input sources used by this analysis
  - path: sample.csv          # Input file path, relative to the configuration
    source_type: raw_can_csv  # Input adapter; CSV or memory must be declared explicitly
    dbc_by_channel:           # DBC files indexed by user-facing CAN channel
      '1': sample.dbc         # DBC for channel 1; channel keys are strings
    time:                     # Input timestamp interpretation
      unit: s                 # Unit of the input timestamp values
    reader:                   # Input-format parsing options
      time_format: numeric    # Format used to parse timestamp text
      id_base: 16             # Unprefixed ID text is hexadecimal
      layout:                 # Columns and fixed values in the raw message table
        fields:               # Column names used to read each raw message field
          timestamp: time     # Original CSV time header
          frame_id: id        # Original CSV ID header
          data: data          # Payload bytes, not decoded values

reader: time, ID, and payload parsing

Fields are inside sources[].reader; layout is another nested object. Do not place layout encoding/delimiter directly in this reader object. A payload such as 01 FF contains two bytes; the message ID is separate.

For a continuous log moving from 23:59:59 to 00:00:01, the clock drops nearly 24 hours. Explicit rollover_min_drop: "43200s" interprets a drop of at least 12 hours as next day, giving a 2-second interval. Without it, this is a regression error. A 1-second regression still fails with this setting.

Minimal column mapping

Common tables need only time, ID, and payload mappings; each column need not be wrapped in column:

sources:                      # Input sources used by this analysis
  - source_type: raw_can_csv  # Input adapter; CSV or memory must be declared explicitly
    path: data/raw.csv        # Input file path, relative to the configuration
    dbc_by_channel:           # DBC files indexed by user-facing CAN channel
      '1': network.dbc        # DBC for channel 1; channel keys are strings
    time:                     # Input timestamp interpretation
      unit: s                 # Unit of the input timestamp values
    reader:                   # Input-format parsing options
      time_format: numeric    # Format used to parse timestamp text
      layout:                 # Columns and fixed values in the raw message table
        fields:               # Column names used to read each raw message field
          timestamp: time     # Column containing the original timestamp
          frame_id: id        # CAN message identifier; decimal or prefixed hexadecimal/binary
          data: data          # Column containing payload bytes

timestamp: time equals timestamp: {column: time}. Integer shorthand such as timestamp: 1 selects the first column. Constants require {fixed: VALUE}. The unique DBC channel is supplied automatically; frames default to frame_kind: data, with length from actual bytes. Omitted direction remains unknown, allowing ordinary numeric analysis; complete raw-frame export needs actual direction. Standard/extended and CAN/FD flags may be omitted only when bindings and DBC identify them uniquely. Explicit lengths, kinds, and flags are strictly checked rather than replaced by defaults.

layout: headers, encoding, and delimiter

Raw CSV uses sources[].reader.layout.encoding and .delimiter; decoded signal_csv places them directly in reader. These are different layouts.

Standard CSV double quotes are handled by the reader. This version provides no configurable quotechar or quoting options.

fields: frame attributes

The full path is sources[].reader.layout.fields.<ATTRIBUTE>. In frame_id: id, frame_id is the program attribute and id is the original CSV header; do not rename the original ID column to name.

Types below are obtained after parsing cell text. Select a column directly or use a column/fixed object. Common direction text Rx/Tx and 接收/发送 is recognized directly; use value_map for other codes.

Omitting type columns works only where analysis bindings and DBC uniquely identify the type. A DBC marked FD may accompany actual classic CAN, so neither DBC marking nor a short payload alone establishes it. Provide binding is_fd, or a truthful original column/constant. Standalone raw-frame reading without DBC still needs type information. Exported unbound messages also require reliable type information. ASC/BLF use their actual embedded flags.

Configuration ID syntax does not change file ID syntax: unprefixed ASC IDs may be hexadecimal; CSV follows id_base.

Data-frame DLC must agree with byte count. Remote frames must be classic CAN with empty data and an explicit requested DLC; an explicit payload_length must be zero because no bytes are present. Error frames require empty data and omitted/zero DLC. Zero bytes alone do not make a remote frame.

Value selection: column, fixed, value_map, and strip

These belong inside an individual mapping object, such as sources[].reader.layout.fields.is_rx.value_map, not directly under layout or fields. Expand shorthand only when extra settings are needed.

Mapping keys/string targets are at most 256 characters; fixed strings at most 16384. Fixed integers range from −2⁶³ to 2⁶⁴−1, with smaller ID/length-specific limits still enforced. Never supply both column and fixed. Mapping can transform fixed "Rx" to true, though directly supplying Boolean true is clearer.

Unused CSV columns are not parsed; missing required columns fail. When only required messages matter and neither full raw frames nor whole-source time is needed, raw CSV checks ID first. Nonmatching rows skip payload/frame-type parsing and usually time. With midnight rollover enabled, their times are still read so the date transition is not missed. Target rows retain format, time, and length checks. Full raw export or whole-source time requires all read records to be checked. Errors identify record locations; correct the input before rerunning.

Select signals and inspect source information

Signal field requires frame_id and signal; unique DBC channels allow omitted channel and frame type can be inferred as described under CAN fields. A signal name alone is insufficient because different messages may reuse it. Source information retained in output depends on requested analysis/export features; unrequested records are not kept merely to explain provenance.

Some DBC messages use a selector to alternate signals in the same bytes—for example, temperature in one frame and voltage in another. This is multiplexing. If the declared temperature is absent in the current frame, the reader produces an invalid update rather than retaining the previous temperature as currently valid.

Other valid records still expire according to valid_for; after expiry and before the next valid update, the value is unknown. For signals or raw messages as outputs, configure the two export types. Input format does not determine output format.

ASCSpec/ASCRead, CANCSVSpec/CANCSVRead, and CANTextDecodeRead are Chinese implementation references with low-level arguments, returns, and exceptions. Usually AnalysisRunner handles the files for you.

Backwards timestamps in unrelated messages

Default reader.input_check: auto requires only selected ASC channels/IDs to remain ordered. Other frames still establish earliest/latest observation during the same read. An unrelated Tx frame's microsecond regression does not stop analysis and its time is not modified. Full checking or raw export requiring complete order still rejects whole-source regression. Required-message regressions, including across continuous files, always fail; no automatic sorting, clamping, or cleaning occurs.

ASC-header relative timestamps are per-record increments and must accumulate. They differ from relative analysis time in time.time_type. Calendar transitions use explicit ASC dates/trigger blocks rather than guesses from ordinary regressions. Raw CSV keeps its declared time layout and channel_origin interpretation.