cal-model
A2L calibration data model and session layer — characteristic binding, COMPU_METHOD conversions, limit validation, curve calibration.
Layer: L2 — domain · Estate deps: a2l-parse L1, xcp-core L1,
dbc-parse L0 · Runtime deps: thiserror only.
What this layer is
cal-model is the application half of the estate's automotive calibration
stack. The three L0/L1 substrates it sits on each do one thing:
| Substrate | Layer | What it gives this layer |
|---|---|---|
a2l-parse |
L1 | the A2L declaration: addresses, datatypes, limits, COMPU_METHODs |
dbc-parse |
L0 | the CAN layout: start bit, width, byte order, scaling |
xcp-core |
L1 | the XCP protocol: resource masks, command framing |
None of them knows the others exist, so a host that wants to calibrate has to do the joining. That is this crate:
A2L text ──a2l_parse──► PROJECT/MODULE/CHARACTERISTIC/MEASUREMENT
│ resolve every reference
▼
CalibrationProject ──── dbc_parse ───► SignalBinding
│
COMPU_METHOD ◄─────────────┤ apply / invert LOWER_LIMIT / UPPER_LIMIT
▼
CalibrationSession ──── XcpTransport ───► ECU
│ read / write / SET_CAL_PAGE
▼
Snapshot ──► diff ──► CalibrationDelta report
What's in it
| Module | Contents |
|---|---|
project |
CalibrationProject — from_a2l / from_a2l_file, reference resolution (an undeclared COMPU_METHOD or RECORD_LAYOUT is a typed error, never a guessed default), to_physical / to_raw / check_limits, attach_dbc, register_table, declare_elements, deposit coding (read_raw / write_raw) |
conversion |
CompuMethod — LINEAR, RAT_FUNC (evaluated as written, inverted by bisection), TABLE (TAB_INTP interpolation and TAB_NOINTP step lookup) and IDENTITY, with apply total and invert bracket-checked |
model |
Characteristic, Measurement, Module, CharKind — the resolved, addressable view of an A2L declaration, including signed-bit-pattern handling and datatype-derived bounds |
session |
XcpTransport (two methods, plus an optional set_page), CalibrationSession — read, read-whole-curve, verified write, SET_CAL_PAGE, Snapshot / restore / diff_snapshots / render_deltas |
signal |
SignalBinding — a characteristic or measurement bound to a DBC signal, with both byte orders' bit coding |
calibrate |
calibrate_curve — a monotone piecewise-linear fit through measured nodes; optimal_point / optimize_working_point — bounded, deterministic coordinate descent |
mock |
mock::MockTransport — an in-memory ECU (pages, recorded traffic, injectable failures), so a session can be exercised with no hardware |
error |
CalError — typed and exhaustive, 13 variants, source() through to the wrapped substrate errors |
sample |
the embedded two-ECU demo project: 15 characteristics (every kind, every conversion type), 5 measurements, a DBC, seed memory, and a factory calibration |
Design decisions worth knowing
Raw values are bit patterns. A signed SBYTE characteristic holding
−1 °C reads 0xFF. Sign extension happens in
Characteristic::raw_value, on the way into the conversion, and in
raw_bits, on the way out. This is what makes read-modify-write bit-exact:
nothing is re-derived from a float.
Inversion is bracket-checked. to_raw is not "undo the arithmetic". A
value is only writable if the raw that produces it exists inside the
deposit's datatype range, so inversion is checked against those bounds and
reports OutOfBounds otherwise. That is the check that stops a tool from
writing a value the ECU would latch as something else.
Writes are verified. write_characteristic limit-checks, inverts,
writes, then reads back and fails if the ECU did not latch it. A tool that
reports a write it cannot confirm is worse than one that reports an error.
Element counts and tabulations are supplied, not guessed. a2l_parse
does not retain the ASAP2 NUMBER / NO_AXIS_PTS keywords, and it skips the
COMPU_TAB blocks, so neither a curve's element count nor a TABLE
conversion's points arrive with the parse. Both are explicit
(declare_elements, register_table) rather than inferred — a wrong element
count reads the wrong number of bytes out of ECU memory, and a wrong tabulation
converts raw values the engineer never saw. sample::complete applies the
demo project's own values to any project you parsed yourself.
A degenerate limit range imposes no constraint. Generators emit
0.0 0.0 for ASCII identifiers; reading that as "the value must be exactly
zero" would be wrong, so lower >= upper means "unconstrained" — the same
convention dbc-parse applies to an empty [min|max].
IEEE-754 deposits are refused. Every raw/physical contract in this crate
is stated over integer bit patterns; a FLOAT32_IEEE deposit carries a
value of a different kind, so it is a typed error rather than a
misinterpretation.
Example
use ;
#
The calibrate example runs the whole cycle end to end — inventory with
limits, read-modify-write, a refused out-of-limit write, page switching,
the diff report, and a curve fit:
Tests
cargo test runs 167 tests across seven suites plus two doctests:
| Suite | Covers |
|---|---|
project |
the embedded description, lookups, typed misses, strict reference resolution, byte order, deposit coding, IEEE refusal |
conversion |
round-trips for LINEAR and RAT_FUNC (closed-form and bisection), table monotonicity and inversion, identity passthrough, limit checking, non-invertible and unresolvable conversions |
session |
read-modify-write against the mock, read-back verification, page isolation, snapshot/restore bit-exactness, diff reports, hand-computed byte-order extraction, transport error propagation |
calibrate |
monotone fits recovering synthetic data, non-monotone rejection, bounded 2-D optimisation, convergence reporting |
errors |
Display for every CalError variant, each variant reached from the public API, the Error / source() contract |
model |
every ASAP2 datatype and characteristic kind, signed bit-pattern handling, datatype-derived bounds, and the resolved model's accessors |
properties |
500-case linear round-trip, 200-case snapshot/restore idempotence, 300-case byte-order extraction against an independently written naive bit-walk, plus curve and error-rendering properties |
cargo fuzz run cal_parse covers the calibration layer over arbitrary input
(committed corpus; CI runs a 30-second smoke). Coverage is gated at 90 % by
the shared tier-a CI workflow.
Layer
Declared in Cargo.toml as [package.metadata.layers] tier = "L2" and
registered in WyattAu/engineering-standards (scripts/estate-tiers.json
and the L2 section of docs/layers.md). Every estate-internal edge points
down the stack, so the ceiling rule in docs/layers.md §Rules rule 1 holds
with the declared layer exactly.
License
MIT OR Apache-2.0 — see LICENSE-MIT and LICENSE-APACHE.