pub struct Trigger { /* private fields */ }Expand description
A threshold with hysteresis that reports the moment it is crossed.
This is the helper behind “when the tank drops below 20 percent”: it holds a line, says once when a reading crosses it, and says once more when the reading has come back far enough to count. The hysteresis is the release band on the far side of the line, so a reading hovering at the threshold cannot fire the trigger over and over. Between the line and the release band the trigger holds its state.
A Thermostat answers the same question as a level to hold;
a trigger answers it as an event to act on, which is what a rule wants.
§Examples
use pamoja_kit::{Edge, Trigger};
// Water when the bed is drier than 30, and stop once it is wetter than 35.
let mut dry = Trigger::below(30.0, 5.0);
assert_eq!(dry.update(42.0), None); // well above the line
assert_eq!(dry.update(28.0), Some(Edge::Set)); // crossed it: fire once
assert_eq!(dry.update(33.0), None); // inside the release band: hold
assert!(dry.is_set());
assert_eq!(dry.update(36.0), Some(Edge::Cleared)); // past the band: clear once
assert_eq!(dry.update(20.0), Some(Edge::Set)); // and it can fire againImplementations§
Source§impl Trigger
impl Trigger
Sourcepub fn above(threshold: f32, hysteresis: f32) -> Self
pub fn above(threshold: f32, hysteresis: f32) -> Self
Creates a trigger that fires when a reading rises above a line.
It sets when the reading exceeds threshold and clears once the reading has
fallen below threshold less hysteresis.
§Arguments
threshold- the line a rising reading crosses. One that is not a number never fires.hysteresis- how far below the line the reading must fall to clear; its magnitude is used, and one that is not a number is taken as zero.
§Returns
A trigger that starts cleared.
Sourcepub fn below(threshold: f32, hysteresis: f32) -> Self
pub fn below(threshold: f32, hysteresis: f32) -> Self
Creates a trigger that fires when a reading falls below a line.
It sets when the reading drops under threshold and clears once the reading
has risen above threshold plus hysteresis.
§Arguments
threshold- the line a falling reading crosses. One that is not a number never fires.hysteresis- how far above the line the reading must rise to clear; its magnitude is used, and one that is not a number is taken as zero.
§Returns
A trigger that starts cleared.
Sourcepub fn update(&mut self, reading: f32) -> Option<Edge>
pub fn update(&mut self, reading: f32) -> Option<Edge>
Feeds a reading in and reports whether it changed the trigger’s state.
A reading that is not a finite number, such as the NaN a failed sensor reports, is ignored: it neither sets nor clears the trigger.
§Arguments
reading- the latest measured value.
§Returns
Edge::Set the moment the reading crosses the line, Edge::Cleared the
moment it comes back past the release band, and None while nothing changed.
Sourcepub fn is_set(&self) -> bool
pub fn is_set(&self) -> bool
Returns whether the condition currently holds.
§Returns
true from the reading that set the trigger until the one that clears it.
Sourcepub fn hysteresis(&self) -> f32
pub fn hysteresis(&self) -> f32
Returns the release band on the far side of the line.
§Returns
The hysteresis it was created with, as a magnitude.