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/// Build the demo project: [`SAMPLE_A2L`] parsed, its tables registered, and
150/// its element counts declared.
151///
152/// # Errors
153///
154/// [`CalError::A2l`](crate::CalError::A2l) or
155/// [`CalError::Unsupported`](crate::CalError::Unsupported) only if the
156/// embedded fixtures are themselves malformed — a bug this crate's own tests
157/// would catch first.
158pub fn sample_project() -> Result<crate::CalibrationProject, crate::CalError> {
159 let mut project = crate::CalibrationProject::from_a2l(SAMPLE_A2L)?;
160 for (name, points) in tables() {
161 project.register_table(name, points)?;
162 }
163 for (module, name, elements) in element_counts() {
164 project.declare_elements(module, name, elements)?;
165 }
166 Ok(project)
167}