cu29_clock/
origin.rs

1//! Informational provenance and epoch of execution timestamps.
2
3use bincode::{Decode, Encode};
4use serde::{Deserialize, Serialize};
5
6/// Advertised upstream source, independent of transport and timestamp epoch.
7///
8/// This is diagnostic metadata, not a guarantee of traceability or accuracy.
9#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize, Encode, Decode)]
10pub enum ClockSource {
11    /// The architecture counter used by a local execution clock.
12    LocalMonotonic,
13    /// A controlled test or replay counter.
14    Mock,
15    /// An application-provided local real-time clock.
16    LocalRtc,
17    /// A global navigation satellite system receiver.
18    Gnss,
19    /// An advertised atomic clock source.
20    AtomicClock,
21    /// A terrestrial radio time service.
22    TerrestrialRadio,
23    /// An upstream PTP source whose root provenance is not specified further.
24    Ptp,
25    /// An upstream NTP source.
26    Ntp,
27    /// A manually set clock.
28    HandSet,
29    /// An internal oscillator.
30    InternalOscillator,
31    /// A provider-defined source code.
32    Other(u8),
33    /// The provider did not identify the source.
34    #[default]
35    Unknown,
36}
37
38/// Meaning of zero on the execution timeline. Every timestamp remains nanoseconds.
39#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize, Encode, Decode)]
40pub enum ClockEpoch {
41    /// Elapsed time since this execution clock started.
42    Local,
43    /// Nanoseconds since 1970-01-01 00:00:00 TAI, as used by PTP.
44    Tai {
45        /// Provider-advertised TAI minus UTC, when valid for this reference.
46        /// Informational only; RobotClock never applies this offset.
47        tai_minus_utc_seconds: Option<i16>,
48    },
49    /// Nanoseconds since 1980-01-06 00:00:00 GPS time.
50    Gps,
51    /// Unix-style UTC nanoseconds since 1970-01-01 00:00:00 UTC.
52    Utc,
53    /// An application-defined epoch identifier; interpretation belongs to the application.
54    Other(u32),
55    /// No epoch interpretation was supplied.
56    #[default]
57    Unknown,
58}
59
60#[cfg(feature = "clock-sync")]
61impl ClockEpoch {
62    pub(crate) fn same_timeline(self, other: Self) -> bool {
63        matches!((self, other), (Self::Tai { .. }, Self::Tai { .. })) || self == other
64    }
65}
66
67/// Compact metadata describing what [`crate::RobotClock::now`] returns.
68///
69/// Providers may supply GPS, TAI, UTC, or application-defined nanoseconds.
70/// The clock disciplines the supplied timeline without calendar conversion.
71#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize, Encode, Decode)]
72pub struct ClockOrigin {
73    /// Advertised upstream provenance.
74    pub source: ClockSource,
75    /// Epoch of the supplied timestamps.
76    pub epoch: ClockEpoch,
77}
cu29_clock/origin.rs

cu29_clock/
origin.rs
