Skip to main content

cal_model/
sample.rs

1//! The embedded demo project: a realistic two-ECU powertrain description
2//! and the CAN database that binds it.
3//!
4//! These are the fixtures the crate's own tests, doctests, and the
5//! `calibrate` example run against. They are embedded (`include_str!`) so
6//! every downstream user gets a working example without a data directory,
7//! and they are deliberately *realistic*: vendor `IF_DATA`, `AXIS_DESCR`,
8//! and `COMPU_TAB` blocks the A2L parser must skip, every conversion type,
9//! and limits on every adjustable.
10//!
11//! # `COMPU_TAB` points are registered, not parsed
12//!
13//! The A2L text carries its `COMPU_TAB`/`COMPU_VTAB` blocks for fidelity,
14//! but `a2l_parse` skips them (they are unknown sub-blocks of
15//! `COMPU_METHOD`). [`tables`] holds the same points as data;
16//! [`sample_project`] registers them so the TABLE conversions resolve.
17//!
18//! # Element counts are declared
19//!
20//! `a2l_parse` does not retain the ASAP2 `NUMBER`/`NO_AXIS_PTS` keywords, so
21//! [`element_counts`] carries them for
22//! [`CalibrationProject::declare_elements`](crate::CalibrationProject::declare_elements)
23//! — again, a declaration rather than a guess.
24
25/// A realistic two-ECU A2L description: 15 characteristics (including a
26/// `CURVE`, two `MAP`s, a `VAL_BLK`, and an `ASCII` identifier), 5
27/// measurements, and COMPU_METHODs covering every conversion type
28/// (`LINEAR`, `RAT_FUNC` in both its reducible and quadratic forms, `TABLE`
29/// in both interpolated and stepped form, and `IDENTITY`).
30pub const SAMPLE_A2L: &str = include_str!("../data/powertrain.a2l");
31
32/// The CAN database that binds [`SAMPLE_A2L`]'s characteristics to message
33/// signals — Intel and Motorola layouts, `UWORD`/`UBYTE` widths.
34pub const SAMPLE_DBC: &str = include_str!("../data/powertrain.dbc");
35
36/// The `COMPU_TAB` points of [`SAMPLE_A2L`], as `(name, points)` pairs.
37#[must_use]
38pub fn tables() -> Vec<(&'static str, Vec<(f64, f64)>)> {
39    vec![
40        (
41            "boost_curve_tab",
42            vec![
43                (0.0, 0.0),
44                (1000.0, 45.0),
45                (2000.0, 78.0),
46                (3000.0, 105.0),
47                (4000.0, 128.0),
48                (5000.0, 142.0),
49                (6000.0, 150.0),
50            ],
51        ),
52        (
53            "gear_vtab",
54            vec![(0.0, 0.0), (1.0, 1.0), (2.0, 2.0), (3.0, 3.0), (4.0, 4.0)],
55        ),
56        (
57            "gear_pos_tab",
58            vec![(0.0, 0.0), (10.0, 1.0), (25.0, 2.0), (45.0, 3.0)],
59        ),
60        (
61            "ratio_vtab",
62            vec![(1.0, 0.0), (2.0, 1.0), (3.0, 2.0), (4.0, 3.0)],
63        ),
64    ]
65}
66
67/// The ECU memory the demo project starts from: `(address, bytes)` seeds,
68/// one per address the tests and example read before their first write.
69///
70/// Addresses come from [`SAMPLE_A2L`]; the values are a plausible factory
71/// calibration (800 rpm idle, 100 Nm torque cap, no boost, rev cut on).
72///
73/// The sample layouts declare `FNC_VALUES 1`, so every characteristic's
74/// deposit record starts with one reserved byte; each seed carries it.
75#[must_use]
76pub fn seed_memory() -> Vec<(u32, Vec<u8>)> {
77    // The leading 0x00 of each characteristic seed is the reserved byte
78    // ahead of `FNC_VALUES POSITION 1`.
79    vec![
80        // engine: eng_load = 400 counts · 0.1 %/count − 10 % = 30.0 %
81        (0x72_01_00, vec![0x00, 0x90, 0x01]),
82        // engine: eng_torque_max = (0.5·200 + 100)/2 = 100 Nm
83        (0x72_01_04, vec![0x00, 0xC8, 0x00]),
84        // engine: idle_target_rpm = 3200 counts · 0.25 rpm = 800 rpm
85        (0x72_01_08, vec![0x00, 0x80, 0x0C]),
86        // engine: boost_target = 0 counts of the quadratic rational = 0 kPa
87        (0x72_01_0C, vec![0x00, 0x00, 0x00]),
88        // engine: rev_limit_cut = 1 (enabled)
89        (0x72_01_10, vec![0x00, 0x01]),
90        // engine: ecu_serial = 'A' (identity raw passthrough)
91        (0x70_01_00, vec![0x00, 0x41]),
92        // engine: boost_curve — 8 elements (UWORD), all 45.0 kPa
93        // (raw 1000 on the boost_tab interpolation)
94        (
95            0x72_10_00,
96            vec![
97                0x00, 0xE8, 0x03, 0xE8, 0x03, 0xE8, 0x03, 0xE8, 0x03, 0xE8, 0x03, 0xE8, 0x03, 0xE8,
98                0x03, 0xE8, 0x03,
99            ],
100        ),
101        // engine: inj_map — 4 elements (UWORD), all 20.0 %
102        // (300 counts · 0.1 − 10)
103        (
104            0x72_20_00,
105            vec![0x00, 0x2C, 0x01, 0x2C, 0x01, 0x2C, 0x01, 0x2C, 0x01],
106        ),
107        // engine: knock_table — 3 elements (UWORD), all 78.0 kPa
108        // (raw 2000 on the boost_tab interpolation)
109        (0x72_30_00, vec![0x00, 0xD0, 0x07, 0xD0, 0x07, 0xD0, 0x07]),
110        // engine measurements (ECU_ADDRESS records, no leading byte)
111        (0x32_00_01, vec![0x00, 0x04]), // engine_speed: 1024 · 0.25 = 256 rpm
112        (0x32_01_00, vec![0x64]),       // coolant_temp: 100 · 0.1 − 10 = 0.0 degC
113        (0x32_02_00, vec![0xC8, 0x00]), // boost_actual: 0.0001·40000 + 100 = 104 kPa
114        // transmission: primary_ratio = 25000 counts · 1e-4 = 2.5
115        (0x73_01_00, vec![0x00, 0xA8, 0x61]),
116        // transmission: shift_pressure = 800 / 4 = 200 kPa
117        (0x73_01_04, vec![0x00, 0x20, 0x03]),
118        // transmission: shift_time_ms = 120 · 0.5 − 20 = 40 ms
119        (0x73_01_08, vec![0x00, 0x78, 0x00]),
120        // transmission: clutch_force = 0.0005·250000 + 0.2·500 = 225 N
121        (0x73_01_0C, vec![0x00, 0xF4, 0x01]),
122        // transmission: gear_code = 2
123        (0x73_01_10, vec![0x00, 0x02]),
124        // transmission: shift_map — 4 elements (UWORD), all 60.0 ms
125        // (160 counts · 0.5 − 20)
126        (
127            0x73_20_00,
128            vec![0x00, 0xA0, 0x00, 0xA0, 0x00, 0xA0, 0x00, 0xA0, 0x00],
129        ),
130        // transmission measurements
131        (0x33_00_01, vec![0x10, 0x27]), // turb_speed: 10000 · 1e-4 = 1.0
132        (0x33_01_00, vec![0x64, 0x00]), // out_speed: 100 (identity)
133    ]
134}
135
136/// The element counts of the sample project's multi-element
137/// characteristics — the `NUMBER`/`NO_AXIS_PTS` declarations that
138/// `a2l_parse` does not retain.
139#[must_use]
140pub fn element_counts() -> Vec<(&'static str, &'static str, usize)> {
141    vec![
142        ("engine", "boost_curve", 8),
143        ("engine", "inj_map", 4),
144        ("engine", "knock_table", 3),
145        ("transmission", "shift_map", 4),
146    ]
147}
148
149/// Register [`tables`] and declare [`element_counts`] on an already-parsed
150/// project.
151///
152/// Every caller that loads [`SAMPLE_A2L`] — or a file with the same
153/// declarations — needs both: `a2l_parse` skips the `COMPU_TAB` blocks and
154/// does not retain `NUMBER`/`NO_AXIS_PTS`, so neither the tabulation points
155/// nor a curve's element count arrive with the parse. A host that has its own
156/// source for either (an exporter, a `.ara` companion file) should call
157/// [`register_table`](crate::CalibrationProject::register_table) and
158/// [`declare_elements`](crate::CalibrationProject::declare_elements)
159/// directly instead.
160///
161/// # Errors
162///
163/// [`CalError::Unsupported`](crate::CalError::Unsupported) when a named
164/// characteristic or module is absent, or a table's points are not ascending.
165pub fn complete(project: &mut crate::CalibrationProject) -> Result<(), crate::CalError> {
166    for (name, points) in tables() {
167        project.register_table(name, points)?;
168    }
169    for (module, name, elements) in element_counts() {
170        project.declare_elements(module, name, elements)?;
171    }
172    Ok(())
173}
174
175/// Build the demo project: [`SAMPLE_A2L`] parsed, completed by
176/// [`complete`].
177///
178/// # Errors
179///
180/// [`CalError::A2l`](crate::CalError::A2l) or
181/// [`CalError::Unsupported`](crate::CalError::Unsupported) only if the
182/// embedded fixtures are themselves malformed — a bug this crate's own tests
183/// would catch first.
184pub fn sample_project() -> Result<crate::CalibrationProject, crate::CalError> {
185    let mut project = crate::CalibrationProject::from_a2l(SAMPLE_A2L)?;
186    complete(&mut project)?;
187    // Attach the DBC too. Without this the fixture parsed the A2L side and left
188    // every signal unbound, so `signal_bindings` was empty for every module and
189    // the "A2L + DBC → calibration session" path the crate exists for was never
190    // exercised by the thing a consumer reaches for first. Found by the
191    // estate-integration `round16_debt` suite, which binds nothing and gets
192    // nothing.
193    project.attach_dbc(dbc_parse::Dbc::parse(SAMPLE_DBC)?)?;
194    Ok(project)
195}