[IOTE-6][IOTE-326] Add weeks behavior flag to MSG_GNSS_TIME_OFFSET (#1405)

jakalm · web-flow · commit 3f933a22ac6c · 2024-03-28T09:44:10.000+01:00
# Description @swift-nav/devinfra Adding a new flag to the reserved `flags` field in the `MSG_GNSS_TIME_OFFSET` message to flag if the timestamp is affected by local timestamp rollover or not. For more information, see https://swift-nav.atlassian.net/wiki/spaces/~622a65696a4c4c0070b2567a/pages/3060662918/Amazon+INS+timestamp+issue+way+forward#Conclusion-and-decision. # API compatibility Does this change introduce a API compatibility risk? No, this has been a reserved field so should not be incompatible with current implementations of the protocol. ## API compatibility plan # JIRA Reference https://swift-nav.atlassian.net/browse/IOTE-325
diff --git a/c/include/libsbp/legacy/system.h b/c/include/libsbp/legacy/system.h
@@ -210,7 +210,7 @@ typedef struct SBP_ATTR_PACKED SBP_DEPRECATED {
   s32 milliseconds; /**< Milliseconds portion of the time offset [ms] */
   s16 microseconds; /**< Microseconds portion of the time offset [microseconds]
                      */
-  u8 flags;         /**< Status flags (reserved) */
+  u8 flags;         /**< Status flags */
 } msg_gnss_time_offset_t;
 
 /** Local time at detection of PPS pulse
diff --git a/c/include/libsbp/system/MSG_GNSS_TIME_OFFSET.h b/c/include/libsbp/system/MSG_GNSS_TIME_OFFSET.h
@@ -61,7 +61,7 @@ typedef struct {
   s16 microseconds;
 
   /**
-   * Status flags (reserved)
+   * Status flags
    */
   u8 flags;
 } sbp_msg_gnss_time_offset_t;
diff --git a/c/include/libsbp/system_macros.h b/c/include/libsbp/system_macros.h
@@ -856,6 +856,38 @@
 #define SBP_MSG_INS_UPDATES_ENCODED_LEN 10u
 
 #define SBP_MSG_GNSS_TIME_OFFSET 0xFF07
+#define SBP_GNSS_TIME_OFFSET_RESERVED_SET_TO_ZERO_MASK (0x7fu)
+#define SBP_GNSS_TIME_OFFSET_RESERVED_SET_TO_ZERO_SHIFT (1u)
+#define SBP_GNSS_TIME_OFFSET_RESERVED_SET_TO_ZERO_GET(flags)               \
+  ((u8)((u8)((flags) >> SBP_GNSS_TIME_OFFSET_RESERVED_SET_TO_ZERO_SHIFT) & \
+        SBP_GNSS_TIME_OFFSET_RESERVED_SET_TO_ZERO_MASK))
+#define SBP_GNSS_TIME_OFFSET_RESERVED_SET_TO_ZERO_SET(flags, val)           \
+  do {                                                                      \
+    (flags) = (u8)(                                                         \
+        (flags & (~(SBP_GNSS_TIME_OFFSET_RESERVED_SET_TO_ZERO_MASK          \
+                    << SBP_GNSS_TIME_OFFSET_RESERVED_SET_TO_ZERO_SHIFT))) | \
+        (((val) & (SBP_GNSS_TIME_OFFSET_RESERVED_SET_TO_ZERO_MASK))         \
+         << (SBP_GNSS_TIME_OFFSET_RESERVED_SET_TO_ZERO_SHIFT)));            \
+  } while (0)
+
+#define SBP_GNSS_TIME_OFFSET_WEEKS_BEHAVIOR_MASK (0x1u)
+#define SBP_GNSS_TIME_OFFSET_WEEKS_BEHAVIOR_SHIFT (0u)
+#define SBP_GNSS_TIME_OFFSET_WEEKS_BEHAVIOR_GET(flags)               \
+  ((u8)((u8)((flags) >> SBP_GNSS_TIME_OFFSET_WEEKS_BEHAVIOR_SHIFT) & \
+        SBP_GNSS_TIME_OFFSET_WEEKS_BEHAVIOR_MASK))
+#define SBP_GNSS_TIME_OFFSET_WEEKS_BEHAVIOR_SET(flags, val)                \
+  do {                                                                     \
+    (flags) =                                                              \
+        (u8)((flags & (~(SBP_GNSS_TIME_OFFSET_WEEKS_BEHAVIOR_MASK          \
+                         << SBP_GNSS_TIME_OFFSET_WEEKS_BEHAVIOR_SHIFT))) | \
+             (((val) & (SBP_GNSS_TIME_OFFSET_WEEKS_BEHAVIOR_MASK))         \
+              << (SBP_GNSS_TIME_OFFSET_WEEKS_BEHAVIOR_SHIFT)));            \
+  } while (0)
+
+#define SBP_GNSS_TIME_OFFSET_WEEKS_BEHAVIOR_NOT_AFFECTED_ON_LOCAL_TIMESTAMP_ROLLOVER \
+  (0)
+#define SBP_GNSS_TIME_OFFSET_WEEKS_BEHAVIOR_INCREMENTED_ON_LOCAL_TIMESTAMP_ROLLOVER \
+  (1)
 /**
  * Encoded length of sbp_msg_gnss_time_offset_t (V4 API) and
  * msg_gnss_time_offset_t (legacy API)
diff --git a/docs/sbp.pdf b/docs/sbp.pdf
diff --git a/haskell/src/SwiftNav/SBP/System.hs b/haskell/src/SwiftNav/SBP/System.hs
@@ -426,7 +426,7 @@ data MsgGnssTimeOffset = MsgGnssTimeOffset
   , _msgGnssTimeOffset_microseconds :: !Int16
     -- ^ Microseconds portion of the time offset
   , _msgGnssTimeOffset_flags      :: !Word8
-    -- ^ Status flags (reserved)
+    -- ^ Status flags
   } deriving ( Show, Read, Eq )
 
 instance Binary MsgGnssTimeOffset where
diff --git a/java/src/com/swiftnav/sbp/system/MsgGnssTimeOffset.java b/java/src/com/swiftnav/sbp/system/MsgGnssTimeOffset.java
@@ -40,7 +40,7 @@ public class MsgGnssTimeOffset extends SBPMessage {
     /** Microseconds portion of the time offset */
     public int microseconds;
 
-    /** Status flags (reserved) */
+    /** Status flags */
     public int flags;
 
     public MsgGnssTimeOffset(int sender) {
diff --git a/javascript/sbp/system.js b/javascript/sbp/system.js
@@ -428,7 +428,7 @@ MsgInsUpdates.prototype.fieldSpec.push(['zerovel', 'writeUInt8', 1]);
  * @field weeks number (signed 16-bit int, 2 bytes) Weeks portion of the time offset
  * @field milliseconds number (signed 32-bit int, 4 bytes) Milliseconds portion of the time offset
  * @field microseconds number (signed 16-bit int, 2 bytes) Microseconds portion of the time offset
- * @field flags number (unsigned 8-bit int, 1 byte) Status flags (reserved)
+ * @field flags number (unsigned 8-bit int, 1 byte) Status flags
  *
  * @param sbp An SBP object with a payload to be decoded.
  */
diff --git a/kaitai/ksy/system.ksy b/kaitai/ksy/system.ksy
@@ -276,7 +276,7 @@ types:
         type: s2
       - id: flags
         doc: |
-          Status flags (reserved)
+          Status flags
         type: u1
   
   msg_pps_time:
diff --git a/python/sbp/system.py b/python/sbp/system.py
@@ -1120,7 +1120,7 @@ class MsgGnssTimeOffset(SBP):
   microseconds : int
     Microseconds portion of the time offset
   flags : int
-    Status flags (reserved)
+    Status flags
   sender : int
     Optional sender ID, defaults to SENDER_ID (see sbp/msg.py).
 
diff --git a/rust/sbp/src/messages/system.rs b/rust/sbp/src/messages/system.rs
@@ -401,11 +401,37 @@ pub mod msg_gnss_time_offset {
         /// Microseconds portion of the time offset
         #[cfg_attr(feature = "serde", serde(rename = "microseconds"))]
         pub microseconds: i16,
-        /// Status flags (reserved)
+        /// Status flags
         #[cfg_attr(feature = "serde", serde(rename = "flags"))]
         pub flags: u8,
     }
 
+    impl MsgGnssTimeOffset {
+        /// Gets the `reserved_set_to_zero` stored in `flags`.
+        pub fn reserved_set_to_zero(&self) -> u8 {
+            get_bit_range!(self.flags, u8, u8, 7, 1)
+        }
+
+        /// Sets the `reserved_set_to_zero` bitrange of `flags`.
+        pub fn set_reserved_set_to_zero(&mut self, reserved_set_to_zero: u8) {
+            set_bit_range!(&mut self.flags, reserved_set_to_zero, u8, u8, 7, 1);
+        }
+
+        /// Gets the [WeeksBehavior][self::WeeksBehavior] stored in the `flags` bitfield.
+        ///
+        /// Returns `Ok` if the bitrange contains a known `WeeksBehavior` variant.
+        /// Otherwise the value of the bitrange is returned as an `Err(u8)`. This may be because of a malformed message,
+        /// or because new variants of `WeeksBehavior` were added.
+        pub fn weeks_behavior(&self) -> Result<WeeksBehavior, u8> {
+            get_bit_range!(self.flags, u8, u8, 0, 0).try_into()
+        }
+
+        /// Set the bitrange corresponding to the [WeeksBehavior][WeeksBehavior] of the `flags` bitfield.
+        pub fn set_weeks_behavior(&mut self, weeks_behavior: WeeksBehavior) {
+            set_bit_range!(&mut self.flags, weeks_behavior, u8, u8, 0, 0);
+        }
+    }
+
     impl ConcreteMessage for MsgGnssTimeOffset {
         const MESSAGE_TYPE: u16 = 65287;
         const MESSAGE_NAME: &'static str = "MSG_GNSS_TIME_OFFSET";
@@ -478,6 +504,40 @@ pub mod msg_gnss_time_offset {
             }
         }
     }
+
+    /// Weeks behavior
+    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+    pub enum WeeksBehavior {
+        /// Not affected on local timestamp rollover
+        NotAffectedOnLocalTimestampRollover = 0,
+
+        /// Incremented on local timestamp rollover
+        IncrementedOnLocalTimestampRollover = 1,
+    }
+
+    impl std::fmt::Display for WeeksBehavior {
+        fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+            match self {
+                WeeksBehavior::NotAffectedOnLocalTimestampRollover => {
+                    f.write_str("Not affected on local timestamp rollover")
+                }
+                WeeksBehavior::IncrementedOnLocalTimestampRollover => {
+                    f.write_str("Incremented on local timestamp rollover")
+                }
+            }
+        }
+    }
+
+    impl TryFrom<u8> for WeeksBehavior {
+        type Error = u8;
+        fn try_from(i: u8) -> Result<Self, u8> {
+            match i {
+                0 => Ok(WeeksBehavior::NotAffectedOnLocalTimestampRollover),
+                1 => Ok(WeeksBehavior::IncrementedOnLocalTimestampRollover),
+                i => Err(i),
+            }
+        }
+    }
 }
 
 pub mod msg_group_meta {
diff --git a/spec/yaml/swiftnav/sbp/system.yaml b/spec/yaml/swiftnav/sbp/system.yaml
@@ -443,7 +443,15 @@ definitions:
             desc: Microseconds portion of the time offset
         - flags:
             type: u8
-            desc: Status flags (reserved)
+            desc: Status flags
+            fields:
+              - 1-7:
+                  desc: Reserved, set to zero
+              - 0:
+                  desc: Weeks behavior
+                  values:
+                    - 0: Not affected on local timestamp rollover
+                    - 1: Incremented on local timestamp rollover
 
  - MSG_PPS_TIME:
     id: 0xFF08

Original file line number	Diff line number	Diff line change
`@@ -428,7 +428,7 @@ MsgInsUpdates.prototype.fieldSpec.push(['zerovel', 'writeUInt8', 1]);`
`428`	`428`	`* @field weeks number (signed 16-bit int, 2 bytes) Weeks portion of the time offset`
`429`	`429`	`* @field milliseconds number (signed 32-bit int, 4 bytes) Milliseconds portion of the time offset`
`430`	`430`	`* @field microseconds number (signed 16-bit int, 2 bytes) Microseconds portion of the time offset`
`431`		`- * @field flags number (unsigned 8-bit int, 1 byte) Status flags (reserved)`
	`431`	`+ * @field flags number (unsigned 8-bit int, 1 byte) Status flags`
`432`	`432`	`*`
`433`	`433`	`* @param sbp An SBP object with a payload to be decoded.`
`434`	`434`	`*/`