Signal bindings and validity

The root signals list turns an input column or DBC signal into a named analysis signal. Use source to reference sources[].name only when several sources are candidates. field locates the original field, and name is used by expressions. A signal definition controls conversion, validity checks, and how long the latest value can be held; subsequent rules and calculations reference its name.

An input value here has already been parsed from CSV text or decoded from CAN using a DBC. Components performing those operations are readers. ASC/BLF are detected by extension; CSV and memory inputs require sources[].source_type. DBC scaling and offsets have already been applied during decoding; conversion in signals is an additional step. An enumeration label, such as "idle", is the text analysis value assigned to a state code, not a field name in another file.

Numeric signals: run a minimal ASC or BLF configuration

Use signal-types.asc and teaching.dbc. Current_mA is measured in mA; Enabled codes 0/1 mean off/on. ModeCode has DBC enumeration entries 0/7 for idle/running. Decoded teaching data is:

The complete signal-number-minimal.yaml reads only current and calculates its maximum. Type and unit come from the DBC. See conversion for automatic unit conversion. To display the maximum as mA, the calculation explicitly sets unit: mA; omitting that output setting gives the inferred unit A (7 A here). The 200 ms validity is an explicit choice for this example; no additional settings need to be copied.

# Synthetic teaching configuration; use the bundled inputs to reproduce this example.
config_version: 4                     # Current analysis configuration version
dataset:                              # Analysis identity and optional input range
  name: signal_example                # Name used to identify and reference this object
sources:                              # Input sources used by this analysis
  - paths: data/can/signal-types.asc  # File, continuous file list or directory; relative to this configuration
    dbc_by_channel:                   # DBC files indexed by user-facing CAN channel
      '1': data/can/teaching.dbc      # DBC for channel 1; channel keys are strings
signals:                              # Signals available to expressions
  - field:                            # Locate the original input field
      frame_id: '0x101'               # CAN message identifier; decimal or prefixed hexadecimal/binary
      signal: Current_mA              # Exact signal name defined in the DBC
    name: current                     # Name used to identify and reference this object
    valid_for: 200ms                  # Maximum time for retaining the latest valid reading
calculations:                         # Requested statistics or selected rows
  - name: maximum_current             # Name used to identify and reference this object
    operation: sample_maximum         # Calculation to apply to the expression
    expr: current                     # Formula using the declared signal or derived names
    unit: mA                          # Output unit; display the maximum current in milliamperes
execution:                            # Execution settings for this analysis
  process_count: 4                    # Up to four file workers; this ASC with concatenate runs in the current process

From the examples directory, run chronaxis run signal-number-minimal.yaml --output out-number. maximum_current should be 7000 mA. For BLF, change the log path without changing the signal structure. An ordinary maximum needs no conversion, scope, or session declaration.

Extension: convert to amperes and recognize invalid values

signal-number-conversion.yaml uses the same log with additional conversion and quality requirements. First replace the previous signals section with:

signals:                       # Signals available to expressions
  - field:                     # Locate the original input field
      frame_id: '0x101'        # CAN message identifier; decimal or prefixed hexadecimal/binary
      signal: Current_mA       # Exact signal name defined in the DBC
    invalid_values: [65535.0]  # Decoded invalid value, before extra conversion
    name: current              # Name used to identify and reference this object
    valid_for: 200ms           # Maximum time for retaining the latest valid reading
    valid_range: [-100, 100]   # Inclusive range after conversion, in A
    conversion:                # Optional unit conversion after decoding
      input_unit: mA           # DBC-decoded unit
    unit: A                    # Target analysis unit; compatible registered units convert when scale/offset are omitted

Then remove unit: mA from the previous calculation. The complete calculations section is:

calculations:                  # Results requested by this example
  - name: maximum_current      # Identify the maximum-current result
    operation: sample_maximum  # Maximum of valid observed samples
    expr: current              # Current converted to A above; omit output unit

The signal converts 5000 mA to 5 A, and the calculation displays 7 A using its default output unit. Keeping unit: mA on the calculation would still display 7000 mA. These extra fields demonstrate conversion and invalid codes; ordinary calculations do not need them. The DBC scales Current_mA by 0.5 and returns a float, so the sentinel is the decoded float 65535.0. valid_range is checked in amperes: 101 A is invalid, while 100 A is valid. The example has no invalid values, so the maximum remains 7 A.

Complete field reference

This table describes one signal declaration; message groups use the separate structure below. Paths are relative to signals[]: conversion.scale means signals[].conversion.scale, not a scale beside name. CAN field objects are described under message location; CSV/memory field is a string containing the original field name.

Omitted optional fields use their defaults. Except for metadata explicitly allowing null, do not use null instead of omission.

For example, two updates of 10 A at one second merge when their types and quality agree. Updates of 10 A and 20 A fail under error; last_by_sequence selects the larger source sequence, not the worker arrival order. Reusing the same source sequence for one alias is still invalid. This rule concerns ordinary signal updates; per-message accumulation keeps each message contribution even when values are equal.

Add either excerpt to one existing signals item; neither is a complete signal definition. The first records a project-defined meaning. The second enables preset role lookup only when the remaining units, direction and measurement location satisfy the role table.

semantic_id: example.power       # Project-defined meaning of the power signal
semantic_contract_version: "2"  # Project's version of that business definition

semantic_id: battery.current     # Current meaning specified by the preset role table
semantic_contract_version: "1"  # Business version required for current preset auto lookup

A nonempty version such as "2" without semantic_id fails configuration loading. semantic_id alone may record a business meaning but does not establish eligibility for preset auto lookup.

CAN defaults and grouped message bindings

CAN dtype and unit can be omitted. DBC lookup infers numeric types for numeric states, so conditions may use state == 1 or state == 0x1. To use state text, declare dtype: enum; omitting choices then uses the DBC enumeration. A manual choices table replaces the DBC table without merging it.

A float DBC output, even 1.0, cannot currently be an enum code. Manual choices does not remove this restriction. Use a numeric type such as float64 and a numeric comparison; do not truncate or round to bypass it.

The loader reads the DBC when default metadata is missing and reuses the same database within that load. A missing DBC unit is unknown, not a confirmed physical unit. CSV and memory have no DBC and still need explicit type and unit. Reload the plan after changing its DBC.

Signals from one message can share location and period. This example uses separate companion files pack.asc, pack.dbc, and analysis.yaml in the same directory. Message 0x120 contains PackVoltage and ChargeState; this excerpt cannot be inserted into the earlier teaching.dbc example.

The following section is already in the complete configuration. The DBC period of 100 ms gives voltage a default validity of 300 ms; state overrides it to 200 ms.

signals:                     # Signals available to expressions
  - frame_id: 0x120          # Shared message location
    signals:                 # Signals available to expressions
      - name: voltage        # Name used to identify and reference this object
        signal: PackVoltage  # Exact signal name defined in the DBC
      - name: state          # Name used to identify and reference this object
        signal: ChargeState  # Exact signal name defined in the DBC
        dtype: enum          # Use the DBC enumeration
        valid_for: 200ms     # Override only this signal's validity

Actual outputs: session results and event results. From their input/configuration directory run chronaxis run analysis.yaml --output pack-result. Voltage is 40, 42, and 41 V at 0, 0.1, and 0.2 seconds; peak_voltage is 42 V. State is idle, charging, idle, producing a charging rising edge at 0.1 seconds. An unrelated message at 0.4 seconds only establishes the source endpoint.

Groups can also share channel, is_extended, is_fd, valid_for, and same_time_policy. Children do not repeat source or message location. Their type, unit, choices, conversion, and quality settings remain independent. Grouping reduces declarations; it does not combine signal values or update times.

Fields in a message group and its children

A message group is an alternative item structure in signals, not a single signal with group-level name/field.

For CAN source bus plus CSV source meter, place source: bus beside the group's frame_id, not inside each child. Having one CAN source does not mean the whole plan has one source.

Boolean input by source

CSV matches reader.missing_values before Boolean parsing. Thus a declared missing token NA becomes invalid rather than a Boolean-format error. Input codes must be unique by type and value; several codes may map to the same result, such as [[0,false],[1,true],[2,true]]. CSV also rejects text ambiguity: integer 1 and string "1" cannot both be input codes.

Choose conversion, encoding, and quality fields

First establish what CSV parsing or DBC decoding produces. These six settings address different needs. Raw CAN table value_map maps frame structure fields, not analysis signal codes.

Booleans and enumerations

Booleans represent true/false. Enumerations represent discrete state names such as idle and running, chosen according to equipment definitions; expressions must use the same spelling. Neither supports numeric scaling.

Using this page's signal-types.asc and DBC, signal-bool-minimal.yaml and signal-enum-minimal.yaml each contain a complete dataset, source, signals, and rising-edge rule. Run chronaxis run FILE.yaml --output NEW-DIRECTORY.

The Boolean example maps Enabled integer 0 to false and 1 to true: condition: enabled rises at 100 ms. The enum example obtains ModeCode 0→idle, 7→running from the DBC: condition: mode == "running" also produces one event at 100 ms. The 300 ms observation is the analysis endpoint and is outside the half-open session range.

signal-state-combined.yaml binds both signals and produces one enabled_running event at 100 ms. Replace the numeric example's signals, remove its calculations, and use the rule below. Both fields exist in this page's log/DBC. Manual choices demonstrate overriding DBC mapping; the ordinary minimal enum example omits them.

signals:                                      # Signals available to expressions
  - choices:                                  # Map input codes to Boolean or enum analysis values
      - [0, false]                            # Input integer → Boolean
      - [1, true]
    field:                                    # Locate the original input field
      frame_id: '0x102'                       # CAN message identifier; decimal or prefixed hexadecimal/binary
      signal: Enabled                         # Exact signal name defined in the DBC
    name: enabled                             # Name used to identify and reference this object
    valid_for: 200ms                          # Maximum time for retaining the latest valid reading
  - choices:                                  # Map input codes to Boolean or enum analysis values
      - [0, idle]                             # Input integer → state label
      - [7, running]
    field:                                    # Locate the original input field
      frame_id: '0x103'                       # CAN message identifier; decimal or prefixed hexadecimal/binary
      signal: ModeCode                        # Exact signal name defined in the DBC
    name: mode                                # Name used to identify and reference this object
    valid_for: 200ms                          # Maximum time for retaining the latest valid reading
    dtype: enum                               # Analysis value type
rules:                                        # Conditions or transitions that produce events
  - condition: enabled and mode == "running"  # Boolean expression used to select an activity
    name: enabled_running                     # Name used to identify and reference this object
    rule_type: rising_edge                    # Event detection algorithm

Each choice has exactly two values: input code and analysis value. [7,running] does not mean column 7; field selects the column. Bool targets must be YAML Booleans, not string "true"; enum targets must be nonempty text. A parseable but unmapped code becomes an invalid update and replaces the old state.

Codes match by type: integer 1, Boolean true, and string "1" differ. CSV contains text, so declaring both integer 1 and string "1" creates an ambiguous cell representation and is rejected when constructing the source. Normal code text must not also be a missing-value token. Without choices, bool accepts only native Boolean input, never arbitrary nonzero numbers. Enum requires a manual table or readable DBC enumeration. Unparseable CSV text may fail the read; mapping does not turn every malformed value into unknown.

DBC decoding and additional signal conversion

A CAN reader extracts bit-encoded values, then applies the DBC factor and offset. A CSV reader parses text as numbers or codes. Signal conversion acts on that reader output: analysis value = reader value × scale + offset. Do not repeat conversion already performed by the DBC.

Registered units include electrical units, time, temperature, temperature differences, angle, rotation speed, pressure, and compound units. See expression unit rules for the full scope. For example, degC → K permits offset 273.15; absolute temperatures and temperature differences are distinct.

Version 4 infers a conversion only when both scale and offset are omitted. Supplying either means a complete user-specified conversion, with the other defaulting to 1 or 0 respectively. Different unknown units need explicit, justified coefficients and remain unverified. An integer signal is promoted to float64 when its conversion multiplier or offset has a fractional part; an integer that cannot be represented exactly is marked PRECISION_LOSS. Public signals have no direction_factor field.

If calibration or direction reversal is required, explicitly preprocess input before Chronaxis—for example, multiply confirmed discharge-positive current by -1 into a new CSV column, then bind A → A with scale 1 and offset 0. Preserve the original file and record the formula. See the charging preset's role requirements.

Original types and invalid values

Before extra conversion, values have already been parsed/decoded; they may differ from both file text and raw CAN bits. invalid_values matches native type and value. Target dtype: float64 does not first turn every input into a float for matching.

missing_values matches original CSV text; invalid_values matches parsed type and value. If DBC decoding converts raw code 65535 to 6553.5, declare the decoded value and type rather than copying raw bits.

Read failures and invalid updates

Processing order is: parse/decode → check missing/non-finite values, input quality, and invalid sentinels → extra numeric conversion or bool/enum mapping → target type and range checks. See Booleans and enumerations for code/text details.

PlanValidationError identifies invalid declaration paths. Invalid values reaching signal normalization are reflected in result status, reason, and quality. Arbitrary read failures cannot all be treated as UNKNOWN and ignored. See troubleshooting and results.

valid_for: how long the latest value can be held

Omitted valid_for uses three times the current signal's period: first explicit period, otherwise its DBC message period. Decoded CSV and memory signals can declare period. If a needed period is unavailable, provide period or valid_for; the program does not infer it from adjacent records. The ordinary chronaxis run and AnalysisRunner.run entry points complete validity for used signals at startup, including plans that only perform per-message calculations; they therefore require a usable signal period, valid_for, or DBC message period. The high-performance integrator entry fast run uses only the current message and holds no previous value, so no signal period or validity is needed for that purpose. A custom formula time parameter, such as parameters.frame_duration, does not populate signal period.

A 100 ms voltage period gives 300 ms default validity; a 10 ms current period gives 30 ms. Each signal is independent: the driving signal's period does not become every signal's period. Explicit valid_for: 500ms overrides the default. Expiry always uses actual message time. Voltage updated at 1 second with 300 ms validity expires at 1.3 seconds, even if fixed-period accumulation advances more slowly.

Signal period does not automatically change a calculation's interval selection or an export resampling grid. Configure those features separately when required.

valid_for: 3s permits an update to be held for at most 3 seconds while observation supports it. A new update replaces the old one; without an update, the value becomes unknown exactly at expiry. This is neither sample frequency, event timeout, nor minimum_duration confirmation time.

Quick-start power updates occur at 0, 1, 3, and 4 seconds with 2, 4, 8, and 10 W. Their gaps are 1, 2, and 1 seconds. The unrelated 0x7FE frame at 6 seconds establishes the source endpoint, not a fifth power sample. The last [4,6) interval holds 10 W when validity permits:

The old value excludes its expiry endpoint. An effective new update exactly then supplies the value from that time. If NA arrives at 2 seconds, even 3-second validity cannot retain the old 4 W: the value becomes unknown at 2 seconds. Observation ending at 6 seconds does not let validity create data beyond 6 seconds.

Related pages: inputs, expressions, and business presets.

Read an enum's original integer code

Use mode == 'ready' for a label comparison; no code type is needed. If a DBC labels both 7 and 9 as ready but only code 9 should count, use enum_code(mode) == 9 in version 4. For an unscaled integer CAN signal the DBC supplies signedness. Otherwise, when the original integer type is not known, declare code_dtype: uint64 or int64 on the enum signal to match the data. A text label alone cannot tell you whether its original code was 7 or 9.

Before the first sample arrives, integer, Boolean, and enum signals remain unknown. A choices mapping only explains codes after they arrive. An unmapped code or explicit invalid update replaces the previous valid state. A DBC label such as Invalid does not automatically mark a value invalid; invalid_values must use the decoded value before extra conversion, not an unscaled raw code.