navcore_signalk/

wind.rs

//! The vessel's true wind, tracked from separate Signal K readings and
//! resolved on demand.
//!
//! Wind is not part of a fix -- it carries no position, and
//! [`fix::FixBuilder`] has no use for it -- but it is a live reading the
//! same way a fix's own course and speed are, which is what makes it a
//! poor fit for [`crate::Measurement::MaximumDraft`]'s own "arrives once,
//! kept forever" treatment. [`WindTracker`] is the shape this actually
//! wants: several separately timestamped readings, resolved to one
//! answer only when asked, with a stale reading treated as no reading at
//! all -- the same discipline [`fix::Sources`] already keeps for a fix,
//! applied here to a value that is not one.

use std::time::Duration;

use crate::delta::Measurement;

/// How long a wind reading stays current by default.
///
/// A little more forgiving than the three seconds a GPS fix is typically
/// given -- ordinary wind instruments update at a slower, less regular
/// cadence than a GPS's steady 1 Hz -- but the same principle: a reading
/// that stopped arriving must not go on describing the actual wind.
/// [`WindTracker::wind`] takes this as a parameter rather than baking it
/// in, so a caller with reason to judge differently is free to.
pub const DEFAULT_WIND_GOOD_FOR: Duration = Duration::from_secs(5);

/// The vessel's true wind, direct from the server's own calculation or
/// derived from apparent wind -- see [`WindTracker::wind`] for which, and
/// when.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Wind {
    /// Degrees true -- an absolute bearing the wind blows *from*, not an
    /// angle off the bow.
    pub direction_true_deg: f64,
    /// Knots.
    pub speed_true_kn: f64,
}

/// Keeps the latest of each of the four wind readings Signal K can carry,
/// each with when it arrived, and resolves them to one [`Wind`] on
/// demand.
#[derive(Debug, Clone, Copy, Default, PartialEq)]
pub struct WindTracker {
    direction_true: Option<(f64, Duration)>,
    speed_true: Option<(f64, Duration)>,
    angle_apparent: Option<(f64, Duration)>,
    speed_apparent: Option<(f64, Duration)>,
}

impl WindTracker {
    /// No readings yet.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Records one measurement, if it is a wind reading -- returns
    /// whether it was. Anything else is left for the caller to handle;
    /// this never touches [`fix::FixBuilder`] or any other measurement
    /// kind, the same separation [`crate::apply_measurement`] itself
    /// keeps by only ever recognising the four fields a fix is made of.
    ///
    /// `now` is the caller's own clock -- the same basis [`Self::wind`]
    /// later judges freshness against, passed in rather than read from
    /// the system clock so that a recorded stream of deltas replays
    /// identically.
    pub fn record(&mut self, measurement: Measurement, now: Duration) -> bool {
        match measurement {
            Measurement::WindDirectionTrue(deg) => {
                self.direction_true = Some((deg, now));
                true
            }
            Measurement::WindSpeedTrue(kn) => {
                self.speed_true = Some((kn, now));
                true
            }
            Measurement::WindAngleApparent(deg) => {
                self.angle_apparent = Some((deg, now));
                true
            }
            Measurement::WindSpeedApparent(kn) => {
                self.speed_apparent = Some((kn, now));
                true
            }
            _ => false,
        }
    }

    /// The vessel's true wind, however it can currently be determined.
    ///
    /// `now` and `good_for` decide freshness together -- see
    /// [`DEFAULT_WIND_GOOD_FOR`] for a reasonable `good_for` when the
    /// caller has no reason to choose its own. `heading_deg` and
    /// `sog_kn` are the vessel's own motion, needed only for the
    /// fallback path below.
    ///
    /// Prefers the server's own `directionTrue`/`speedTrue` when both
    /// are fresh: an installation that computes true wind for itself
    /// may know things this cannot -- current, calibration, a better
    /// sensor. Falls back to deriving it from apparent wind and the
    /// vessel's own motion, via [`nav_math::wind`], when the server
    /// does not.
    ///
    /// `None` when neither path has anything fresh enough, or -- for
    /// the fallback path -- when there is no heading to measure the
    /// apparent angle against. Never a stale number quietly reused.
    ///
    /// # The one approximation this makes
    ///
    /// Deriving true wind from apparent wants speed *through water* --
    /// [`nav_math::wind`]'s own doc calls this "the sailing wind", the
    /// one polar data and laylines are indexed by. Plenty of vessels
    /// have no paddlewheel reading, only speed over ground; `sog_kn`
    /// stands in for it here, and the two differ by the current vector,
    /// which is exactly the error this introduces. Reason enough to
    /// prefer the server's own calculation whenever it publishes one.
    #[must_use]
    pub fn wind(&self, now: Duration, heading_deg: Option<f64>, sog_kn: f64, good_for: Duration) -> Option<Wind> {
        let fresh = |reading: Option<(f64, Duration)>| {
            reading.filter(|&(_, at)| now.saturating_sub(at) <= good_for).map(|(value, _)| value)
        };

        if let (Some(direction_true_deg), Some(speed_true_kn)) =
            (fresh(self.direction_true), fresh(self.speed_true))
        {
            return Some(Wind { direction_true_deg, speed_true_kn });
        }

        let heading_deg = heading_deg?;
        let angle_deg = fresh(self.angle_apparent)?;
        let speed_kn = fresh(self.speed_apparent)?;
        let apparent = nav_math::wind::Wind { speed_kn, angle_deg };
        let true_wind = nav_math::wind::true_from_apparent(apparent, sog_kn);
        Some(Wind {
            direction_true_deg: nav_math::wind::direction_deg(heading_deg, true_wind.angle_deg),
            speed_true_kn: true_wind.speed_kn,
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn reported_true_wind_is_preferred_over_a_derivation_from_apparent() {
        let mut tracker = WindTracker::new();
        tracker.record(Measurement::WindDirectionTrue(270.0), Duration::ZERO);
        tracker.record(Measurement::WindSpeedTrue(12.0), Duration::ZERO);
        // Present too, and would derive a very different answer if used --
        // proving the reported pair actually wins rather than merely
        // being available.
        tracker.record(Measurement::WindAngleApparent(45.0), Duration::ZERO);
        tracker.record(Measurement::WindSpeedApparent(20.0), Duration::ZERO);

        let wind = tracker
            .wind(Duration::ZERO, Some(0.0), 6.0, DEFAULT_WIND_GOOD_FOR)
            .expect("reported true wind");
        assert!((wind.direction_true_deg - 270.0).abs() < 1e-9, "{wind:?}");
        assert!((wind.speed_true_kn - 12.0).abs() < 1e-9, "{wind:?}");
    }

    #[test]
    fn true_wind_is_derived_from_apparent_when_none_is_reported() {
        let mut tracker = WindTracker::new();
        // Beating: 38 degrees apparent at 14 kn, boat doing 6.5.
        tracker.record(Measurement::WindAngleApparent(38.0), Duration::ZERO);
        tracker.record(Measurement::WindSpeedApparent(14.0), Duration::ZERO);

        // Heading due north: the true wind angle off the bow becomes the
        // true wind direction directly.
        let wind = tracker
            .wind(Duration::ZERO, Some(0.0), 6.5, DEFAULT_WIND_GOOD_FOR)
            .expect("derived true wind");
        let expected = nav_math::wind::true_from_apparent(
            nav_math::wind::Wind { speed_kn: 14.0, angle_deg: 38.0 },
            6.5,
        );
        assert!((wind.direction_true_deg - expected.angle_deg).abs() < 1e-6, "{wind:?}");
        assert!((wind.speed_true_kn - expected.speed_kn).abs() < 1e-6, "{wind:?}");
    }

    #[test]
    fn deriving_true_wind_needs_a_heading() {
        let mut tracker = WindTracker::new();
        tracker.record(Measurement::WindAngleApparent(38.0), Duration::ZERO);
        tracker.record(Measurement::WindSpeedApparent(14.0), Duration::ZERO);

        // Apparent wind is relative to the bow; with no compass there is
        // nothing to turn it into an absolute direction with, and
        // guessing from course over ground would silently mix leeway and
        // current into a number that looks like a measurement.
        assert!(tracker.wind(Duration::ZERO, None, 6.5, DEFAULT_WIND_GOOD_FOR).is_none());
    }

    #[test]
    fn a_wind_reading_that_stopped_arriving_is_not_used() {
        let mut tracker = WindTracker::new();
        tracker.record(Measurement::WindDirectionTrue(270.0), Duration::ZERO);
        tracker.record(Measurement::WindSpeedTrue(12.0), Duration::ZERO);

        // Fresh right after it arrived.
        assert!(tracker.wind(Duration::from_secs(2), None, 0.0, DEFAULT_WIND_GOOD_FOR).is_some());
        // Older than good_for: the one rule this exists for -- a value
        // that stopped updating must never look current.
        assert!(tracker.wind(Duration::from_secs(10), None, 0.0, DEFAULT_WIND_GOOD_FOR).is_none());
    }

    #[test]
    fn nothing_reported_at_all_is_no_wind_rather_than_a_guess() {
        let tracker = WindTracker::new();
        assert!(tracker.wind(Duration::ZERO, Some(90.0), 6.0, DEFAULT_WIND_GOOD_FOR).is_none());
    }

    #[test]
    fn recording_a_non_wind_measurement_is_reported_as_such() {
        let mut tracker = WindTracker::new();
        assert!(!tracker.record(Measurement::MaximumDraft(2.0), Duration::ZERO));
    }
}