1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
//! A2L calibration data model and session layer — characteristic binding,
//! COMPU_METHOD conversions, limit validation, curve calibration.
//!
//! `cal-model` is the estate's **L2 application layer** for the automotive
//! calibration stack. It sits on three L0/L1 substrates and turns their
//! declarations into an actionable calibration session:
//!
//! | Substrate | Layer | What it contributes |
//! |---|---|---|
//! | [`a2l_parse`] | L1 | the A2L description: 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 |
//!
//! # The layer's job
//!
//! ```text
//! 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
//! ```
//!
//! Five things happen here that no substrate does:
//!
//! 1. **Reference resolution.** A characteristic whose `COMPU_METHOD` or
//! `RECORD_LAYOUT` is undeclared, or whose `COMPU_TAB_REF` has no
//! registered points, is a typed [`CalError::Unsupported`] — never a
//! silently defaulted conversion. A wrong conversion writes the wrong
//! number into an ECU.
//! 2. **Inversion.** [`to_physical`](CalibrationProject::to_physical) is
//! evaluation; [`to_raw`](CalibrationProject::to_raw) is the part that
//! matters, and it bracket-checks against the deposit's datatype range so
//! the tool cannot ask for a value the ECU cannot hold.
//! 3. **Transport framing.** [`XcpTransport`] is deliberately two methods
//! wide, which makes a session testable against [`mock::MockTransport`]
//! while [`CalibrationSession::upload_frames`] and friends hand a real
//! bridge the exact `xcp_core` frames to send.
//! 4. **Verified writes.** A session write reads the value back and fails if
//! the ECU did not latch it.
//! 5. **Calibration arithmetic.** [`calibrate_curve`] fits a monotone
//! piecewise-linear curve through measured nodes;
//! [`optimize_working_point`] finds a bounded working point by
//! deterministic coordinate descent.
//!
//! # Raw values are bit patterns
//!
//! Every raw value in this crate is the **memory bit pattern**, so a signed
//! `SBYTE` characteristic holding −1 °C reads `0xFF`. Sign extension happens
//! in [`Characteristic::raw_value`], on the way into the conversion, and in
//! [`Characteristic::raw_bits`], on the way out. This is what makes a
//! read-modify-write cycle bit-exact: nothing is re-derived from a float.
//!
//! # Example
//!
//! ```
//! use cal_model::{
//! CalibrationProject, CalibrationSession, CalError, ResourceMode, XcpTransport, SAMPLE_A2L,
//! };
//! # fn main() -> Result<(), CalError> {
//!
//! // 1. Load the description and resolve every reference it makes.
//! let mut project = CalibrationProject::from_a2l(SAMPLE_A2L)?;
//! project.register_table("boost_curve_tab", vec![(0.0, 0.0), (6000.0, 150.0)])?;
//! assert_eq!(project.module("engine")?.characteristics.len(), 9);
//!
//! // 2. Look a parameter up and convert both ways.
//! let idle = project.characteristic("engine", "idle_target_rpm")?;
//! assert_eq!(idle.address, 0x720108);
//! // 3200 counts · 0.25 rpm/count = 800 rpm.
//! let physical = project.to_physical("engine", "idle_target_rpm", 3200)?;
//! assert!((physical - 800.0).abs() < 1e-9, "{physical}");
//! assert_eq!(project.to_raw("engine", "idle_target_rpm", 800.0)?, 3200);
//!
//! // 3. Limits are enforced on the way in.
//! project.check_limits("engine", "idle_target_rpm", 3200)?;
//! assert!(project.check_limits("engine", "idle_target_rpm", 0).is_err());
//!
//! // 4. Calibrate against a bench ECU: write, read back, diff.
//! let bench = cal_model::mock::MockTransport::seeded(&cal_model::seed_memory());
//! let mut session = CalibrationSession::connect(
//! &project, Box::new(bench), ResourceMode::CONNECT_NORMAL,
//! )?;
//! // The seed memory holds 800 rpm; the write is limit-checked (500…1200),
//! // inverted through `rpm_lin`, and read back before it is reported.
//! session.write_characteristic("engine", "idle_target_rpm", 900.0)?;
//! let live = session.read_characteristic("engine", "idle_target_rpm")?;
//! assert!((live - 900.0).abs() < 1e-9, "{live}");
//!
//! // 5. Snapshot, adjust, and report the diff.
//! let before = session.snapshot(&["idle_target_rpm", "eng_torque_max"])?;
//! session.write_characteristic("engine", "idle_target_rpm", 950.0)?;
//! let after = session.snapshot(&["idle_target_rpm", "eng_torque_max"])?;
//! let deltas = cal_model::diff_snapshots(Some(&before), &after, &project);
//! assert_eq!(deltas[0].before, 900.0);
//! assert_eq!(deltas[0].after, 950.0);
//! assert!((deltas[0].delta - 50.0).abs() < 1e-9);
//! assert!(deltas[0].within_limits);
//! # Ok(())
//! # }
//! ```
// A2L/ASAM grammar keywords (CHARACTERISTIC, COMPU_METHOD, ECU_ADDRESS …)
// are proper nouns of the formats this crate reads; backticking every
// occurrence would bury the prose. Allowed with this justification per the
// fleet pedantic policy.
pub use ;
pub use CompuMethod;
pub use ByteOrder;
pub use CalError;
pub use ;
pub use CalibrationProject;
pub use ;
pub use ;
pub use SignalBinding;
pub use ResourceMode;
/// Re-export of the A2L substrate, so a consumer needs one dependency.
pub use a2l_parse as a2l;
/// Re-export of the DBC substrate, so a consumer needs one dependency.
pub use dbc_parse as dbc;
/// Re-export of the XCP substrate, so a consumer needs one dependency.
pub use xcp_core as xcp;