pub struct CalibrationSession<'a> { /* private fields */ }Expand description
A calibration session against one ECU, over one transport.
Implementations§
Source§impl<'a> CalibrationSession<'a>
impl<'a> CalibrationSession<'a>
Sourcepub fn connect(
project: &'a CalibrationProject,
transport: Box<dyn XcpTransport + 'a>,
mode: ResourceMode,
) -> Result<Self, CalError>
pub fn connect( project: &'a CalibrationProject, transport: Box<dyn XcpTransport + 'a>, mode: ResourceMode, ) -> Result<Self, CalError>
Open a session on project over transport.
mode is the slave’s resource bitmask. When it is non-empty the
session requires ResourceMode::CAL_PAGE
and refuses to connect otherwise — a slave that advertises no CAL/PAG
resource cannot be calibrated, and finding that out at connect time
is much cheaper than finding it out at the first write. Pass the empty
mask ([ResourceMode::CONNECT_NORMAL]) to skip the check, which is
what a caller does when the transport is not completing a real CONNECT
handshake.
§Errors
CalError::Xcp — xcp_core::XcpError::AccessDenied — when the
resource mask excludes CAL/PAG.
Sourcepub const fn project(&self) -> &'a CalibrationProject
pub const fn project(&self) -> &'a CalibrationProject
The project this session calibrates.
Sourcepub fn transport(&self) -> &dyn XcpTransport
pub fn transport(&self) -> &dyn XcpTransport
The transport, borrowed.
Sourcepub fn transport_mut(&mut self) -> &mut (dyn XcpTransport + 'a)
pub fn transport_mut(&mut self) -> &mut (dyn XcpTransport + 'a)
The transport, mutably borrowed.
Sourcepub const fn resources(&self) -> ResourceMode
pub const fn resources(&self) -> ResourceMode
The negotiated resource mask.
Sourcepub fn set_cal_page(&mut self, page: u32) -> Result<(), CalError>
pub fn set_cal_page(&mut self, page: u32) -> Result<(), CalError>
Switch the slave’s active calibration page.
§Errors
CalError::Transport when the transport rejected the switch; the
session’s page is left unchanged in that case, so a failed switch
cannot silently redirect a later write to the wrong page.
Sourcepub fn upload_frames(&self, addr: u32, len: u8) -> Vec<u8> ⓘ
pub fn upload_frames(&self, addr: u32, len: u8) -> Vec<u8> ⓘ
The SET_MTA + UPLOAD frames for a read of len bytes at addr,
in the project’s deposit byte order.
Sourcepub fn download_frames(&self, addr: u32, data: &[u8]) -> Vec<u8> ⓘ
pub fn download_frames(&self, addr: u32, data: &[u8]) -> Vec<u8> ⓘ
The SET_MTA + DOWNLOAD frames for a write of data at addr, in
the project’s deposit byte order.
Sourcepub fn set_cal_page_frame(&self, page: u32) -> Vec<u8> ⓘ
pub fn set_cal_page_frame(&self, page: u32) -> Vec<u8> ⓘ
The SET_CAL_PAGE frame for page (switch on the ECU, all
segments).
Sourcepub fn read_characteristic(
&mut self,
module: &str,
name: &str,
) -> Result<f64, CalError>
pub fn read_characteristic( &mut self, module: &str, name: &str, ) -> Result<f64, CalError>
Read a characteristic and return the physical value of its first element.
§Errors
CalError::Transport on a bus failure, CalError::Unsupported
for an unresolvable conversion or a deposit the UPLOAD cannot carry,
plus the lookup errors.
Sourcepub fn read_characteristic_elements(
&mut self,
module: &str,
name: &str,
) -> Result<Vec<f64>, CalError>
pub fn read_characteristic_elements( &mut self, module: &str, name: &str, ) -> Result<Vec<f64>, CalError>
Read every element of a characteristic and return their physical values — the curve or map as one read.
§Errors
Sourcepub fn read_characteristic_raw(
&mut self,
module: &str,
name: &str,
) -> Result<Vec<u64>, CalError>
pub fn read_characteristic_raw( &mut self, module: &str, name: &str, ) -> Result<Vec<u64>, CalError>
Read every element of a characteristic and return its raw bit patterns.
§Errors
CalError::Transport, CalError::Unsupported (including a
deposit larger than one 255-byte UPLOAD), plus the lookup errors.
Sourcepub fn write_characteristic(
&mut self,
module: &str,
name: &str,
physical: f64,
) -> Result<(), CalError>
pub fn write_characteristic( &mut self, module: &str, name: &str, physical: f64, ) -> Result<(), CalError>
Write a physical value to a characteristic’s first element, and read it back to confirm the ECU latched it.
The value is limit-checked and inverted through the COMPU_METHOD before anything reaches the bus, so a rejected write costs no traffic.
§Errors
CalError::LimitViolation for an out-of-limit value,
CalError::OutOfBounds when the deposit cannot represent it,
CalError::Transport on a bus failure or a read-back mismatch,
plus the lookup errors.
Sourcepub fn write_characteristic_element(
&mut self,
module: &str,
name: &str,
index: usize,
physical: f64,
) -> Result<(), CalError>
pub fn write_characteristic_element( &mut self, module: &str, name: &str, index: usize, physical: f64, ) -> Result<(), CalError>
Write a physical value to one element of a characteristic and read it back to confirm.
§Errors
Sourcepub fn write_characteristic_raw(
&mut self,
module: &str,
name: &str,
index: usize,
raw: u64,
) -> Result<(), CalError>
pub fn write_characteristic_raw( &mut self, module: &str, name: &str, index: usize, raw: u64, ) -> Result<(), CalError>
Write a raw bit pattern to one element, without limit checking or read-back — the path a snapshot restore takes, where the value was already validated when it was captured.
A multi-element deposit is read, one element replaced, and written back whole: a calibration engineer adjusting curve point 3 must not lose points 1, 2, and 4.
§Errors
CalError::OutOfBounds when index is past the end of the
deposit, CalError::Transport on a bus failure, plus the lookup
errors.
Sourcepub fn read_measurement(
&mut self,
module: &str,
name: &str,
) -> Result<f64, CalError>
pub fn read_measurement( &mut self, module: &str, name: &str, ) -> Result<f64, CalError>
Read a measurement and return its physical value.
§Errors
CalError::Transport on a bus failure, CalError::Unsupported
for an unresolvable conversion, plus the lookup errors.
Sourcepub fn snapshot(&mut self, names: &[&str]) -> Result<Snapshot, CalError>
pub fn snapshot(&mut self, names: &[&str]) -> Result<Snapshot, CalError>
Capture the named characteristics, searching every module for each name (first declaration wins).
The snapshot records the page it was taken on, so
restore puts the ECU back where it found it.
§Errors
As read_characteristic_raw, and
CalError::UnknownCharacteristic for a name no module declares.
Sourcepub fn restore(&mut self, snapshot: &Snapshot) -> Result<(), CalError>
pub fn restore(&mut self, snapshot: &Snapshot) -> Result<(), CalError>
Restore a captured calibration set: switch to the snapshot’s page, then write every captured raw value back verbatim.
Raws are written, not physical values, so a restore is bit-exact and cannot drift through a second round of inversion.
§Errors
CalError::Transport, CalError::UnknownModule /
CalError::UnknownCharacteristic when the project no longer
declares a captured parameter, plus the write errors.
Sourcepub fn diff(&self, other: &Snapshot) -> Vec<CalibrationDelta>
pub fn diff(&self, other: &Snapshot) -> Vec<CalibrationDelta>
Diff this session’s baseline snapshot against other, one entry
per element.
&self cannot read the bus, so the “before” side is the baseline
installed by set_baseline (or
capture_baseline). With no baseline set,
every parameter is reported as new. Use diff_snapshots to diff two
snapshots you already hold.
within_limits is evaluated against the project’s current A2L
limits, so a baseline captured before a limit was tightened is
reported against the limit that now applies.
Sourcepub fn set_baseline(&mut self, snapshot: Snapshot)
pub fn set_baseline(&mut self, snapshot: Snapshot)
Install the baseline every diff measures against.
Sourcepub fn capture_baseline(&mut self) -> Result<(), CalError>
pub fn capture_baseline(&mut self) -> Result<(), CalError>
Capture a baseline over every characteristic of every module and install it.
§Errors
CalError::Transport, CalError::UnknownModule /
CalError::UnknownCharacteristic, CalError::Unsupported — as
snapshot.