BLF and ASC quick start: calculate energy from CAN messages

You can analyze CAN logs without first converting them to CSV or writing a Python entry function. Complete installation, then run this small, synthetic CAN example.

The basic configuration retains execution.process_count: 4 as the limit for later multi-volume inputs. This first example reads one ASC file in the default file order, within the current process. The directory example then demonstrates two continuous parts read in parallel. See execution settings for field meanings and resource choices.

1. Prepare the log and DBC

Use quickstart.asc and teaching.dbc. The ASC file uses channel 1, so its configuration also uses channel 1. Message 0x100 in the DBC contains the signal Power, measured in W.

The final record is not a power sample. With zero-order hold, each power value applies until the next update, within its validity period. This example integrates over [0, 6). Unequal sample spacing means the sample mean and time-weighted mean are different.

2. Save the configuration and run it

The complete file is analysis.yaml. Its input paths are relative to the directory containing that configuration file.

In YAML, indentation defines nesting. Here, two spaces indent a child field, and - starts a list item. A reference such as dataset.name describes the field's location: write name indented beneath dataset, not a literal key named dataset.name. See configuration notation.

config_version: 4                   # Current analysis configuration version
dataset:                            # Analysis identity and optional input range
  name: energy                      # Name of this analysis
sources:                            # Input sources used by this analysis
  - paths: data/can/quickstart.asc  # Relative to this YAML file
    dbc_by_channel:                 # DBC files indexed by user-facing CAN channel
      '1': data/can/teaching.dbc    # Public channel numbers start at 1
signals:                            # Signals available to expressions
  - name: power                     # Name used in expressions
    field:                          # Locate the original input field
      frame_id: '0x100'             # CAN message ID
      signal: Power                 # Signal name in the DBC
calculations:                       # Requested statistics or selected rows
  - name: energy                    # Result column name
    operation: integral             # Integrate power over time
    expr: power                     # Formula using the declared signal or derived names
  - name: sample_average            # Name used to identify and reference this object
    operation: sample_mean          # Equal weight for each sample
    expr: power                     # Formula using the declared signal or derived names
  - name: time_average              # Name used to identify and reference this object
    operation: time_weighted_mean   # Weight by valid time
    expr: power                     # Formula using the declared signal or derived names
execution:                          # Control how this analysis runs
  process_count: 4                  # At most four file-reading workers, capped by the number of files

The configuration names the analysis, selects the log, DBC, signal and three calculations, and sets the file-reading worker limit. Four is the recommended starting value used by this example; omitting the field still defaults to one. Choose another positive integer to suit available resources. There is no need to specify session, entity, source_type, time_type, a reference to the only source, or the default session scope. Signal type and unit come from the DBC; a unique channel is selected automatically. Omitting domain uses the observed range.

From the examples directory, run:

chronaxis validate analysis.yaml
chronaxis run analysis.yaml --output new-result

The output directory can be reused; each publication uses timestamped filenames. validate checks the declarations and required DBC metadata; run reads the actual messages and produces results. If the virtual environment is not activated, invoke its Python executable with -m chronaxis.

3. Check the results

Open new-result/会话结果_<timestamp>.csv (session results). The example output explains the columns.

All three values appear in one row, each with status 完整 (complete) and no reason text. Dataset, entity, and session names inherit energy; this identity is saved once in the manifest. For programmatic reading, see Python API usage.

4. Try directory input and BLF

input-can-directory.yaml reads part1.asc and part2.asc from quickstart-parts. With execution.process_count: 4, these two files use at most two reading workers. The main process still consumes them in natural filename order and carries signal and event state across the boundary. The results remain 38 J, 6 W, and 38 / 6 W.

chronaxis run input-can-directory.yaml --output directory-result

From the examples directory, generate an equivalent BLF example and mixed-format inputs in a new directory:

python prepare_can_examples.py --output can-demo
chronaxis run can-demo/blf.yaml --output blf-result

prepare_can_examples.py creates three equivalent datasets and commented asc.yaml, blf.yaml, and mixed.yaml plans, checks the generated YAML by running each plan, and writes only to the selected working directory. For your own BLF logs, use their paths directly; you do not need this teaching-data generator.

5. Use your own BLF, ASC, or log directory

1. Replace paths with a file or a directory of continuous logs. ASC and BLF are detected from their extensions. Directory input uses natural ordering, so part2 precedes part10.
2. Set dbc_by_channel to your DBC files. User-facing channel numbers start at 1.
3. Select frame_id and signal from the DBC. A message name is unnecessary. IDs accept 0x hexadecimal, 0b binary, and unprefixed decimal notation.
4. Set dataset.name. Add a domain only to analyze a restricted time range, and add other features when the task needs them.
5. Keep execution.process_count: 4 as a starting point for multiple files. Increasing this number does not split a single file among workers. See continuous-file multiprocessing for ordering and resource rules.

When valid_for is omitted, the validity period is three times the signal period obtained from the DBC. If no period is available, supply period or valid_for. Use actual signal definitions to determine units and current direction; names alone cannot establish them.

Use batch tasks for independent experiments. Do not concatenate independent files whose clocks each restart at zero. For decoded CSV columns, see input configuration.

analysis.json contains the same configuration in JSON. run_example.py checks the configuration formats and calculation backends. api_example.py demonstrates the Python interface.