Clarify timestamping descriptions [AP-1087] (#1395)

# Description

@swift-nav/devinfra

<!-- Changes proposed in this PR -->

# API compatibility

Does this change introduce a API compatibility risk?

<!-- Provide a short explanation why or why not -->

## API compatibility plan

If the above is "Yes", please detail the compatibility (or migration)
plan:

<!-- Provide a short explanation plan here -->

# JIRA Reference

https://swift-nav.atlassian.net/browse/AP-1087

---------

Co-authored-by: Matt Woodward <46688854+woodfell@users.noreply.github.com>
Co-authored-by: Matt Woodward <matthew.woodward@swift-nav.com>

Author: 3 people

c/include/libsbp/imu/MSG_IMU_RAW.h

@@ -45,11 +45,10 @@ extern "C" {
  * indications on the device itself. Measurement units, which are specific to
  * the device hardware and settings, are communicated via the MSG_IMU_AUX
  * message. If using "time since startup" local time tags, the receiving end
- * will expect a `MSG_PPS_TIME` regardless of GNSS fix state. This also requires
- * that the MSG_PPS_TIME message be sent prior to any IMU RAW messages that are
- * based on the current (as measured at the PPS edge) local time timestamps. The
- * local time (as defined in the MSG_PPS_TIME message) must wrap around to zero
- * when reaching the extent of the u64 "Local time in microseconds" parameter.
+ * will expect either a MSG_GNSS_TIME_OFFSET or MSG_PPS_TIME to establish the
+ * relationship between IMU time and GNSS time. Regardless of the timestamping
+ * mode, the timestamp is required to roll over to zero when reaching one week
+ * (604800 seconds, or 604800000 milliseconds).
  */
 typedef struct {
   /**

c/include/libsbp/legacy/imu.h

@@ -42,12 +42,10 @@ SBP_PACK_START
  * the indications on the device itself. Measurement units, which are specific
  * to the device hardware and settings, are communicated via the MSG_IMU_AUX
  * message. If using "time since startup" local time tags, the receiving end
- * will expect a `MSG_PPS_TIME` regardless of GNSS fix state. This also
- * requires that the MSG_PPS_TIME message be sent prior to any IMU RAW
- * messages that are based on the current (as measured at the PPS edge) local
- * time timestamps. The local time (as defined in the MSG_PPS_TIME message)
- * must wrap around to zero when reaching the extent of the u64 "Local time in
- * microseconds" parameter.
+ * will expect either a MSG_GNSS_TIME_OFFSET or MSG_PPS_TIME to establish the
+ * relationship between IMU time and GNSS time.
+ * Regardless of the timestamping mode, the timestamp is required to roll over
+ * to zero when reaching one week (604800 seconds, or 604800000 milliseconds).
  * The time-tagging mode should not change throughout a run.
  */
 

c/include/libsbp/legacy/system.h

@@ -217,15 +217,16 @@ typedef struct SBP_ATTR_PACKED SBP_DEPRECATED {
  *
  * The PPS time message contains the value of the sender's local time in
  * microseconds at the moment a pulse is detected on the PPS input. This is to
- * be used for syncronisation of sensor data sampled with a local timestamp
+ * be used for synchronisation of sensor data sampled with a local timestamp
  * (e.g. IMU or wheeltick messages) where GNSS time is unknown to the sender.
  *
  * The local time used to timestamp the PPS pulse must be generated by the
  * same clock which is used to timestamp the IMU/wheel sensor data and should
- * follow the same roll-over rules.  A separate MSG_PPS_TIME message should be
- * sent for each source of sensor data which uses PPS-relative timestamping.
- * The sender ID for each of these MSG_PPS_TIME messages should match the
- * sender ID of the respective sensor data.
+ * follow the same roll-over rules (i.e. it should roll over to zero after
+ * 604800 seconds). A separate MSG_PPS_TIME message should be sent for each
+ * source of sensor data which uses local timestamping.  The sender ID for
+ * each of these MSG_PPS_TIME messages should match the sender ID of the
+ * respective sensor data.
  */
 
 typedef struct SBP_ATTR_PACKED SBP_DEPRECATED {

c/include/libsbp/legacy/vehicle.h

@@ -42,10 +42,10 @@ SBP_PACK_START
  * the odometry reference point and the definition and origin of the user
  * frame are defined through the device settings interface. There are 4
  * possible user-defined sources of this message which are labeled arbitrarily
- * source 0 through 3. If using "processor time" time tags, the receiving end
- * will expect a `MSG_GNSS_TIME_OFFSET` when a PVT fix becomes available to
- * synchronise odometry measurements with GNSS. Processor time shall roll over
- * to zero after one week.
+ * source 0 through 3.
+ * If using "processor time" time tags, the receiving end will expect either
+ * `MSG_GNSS_TIME_OFFSET` or `MSG_PPS_TIME` to sync incoming odometry data to
+ * GNSS time.  Processor time shall roll over to zero after one week.
  */
 
 typedef struct SBP_ATTR_PACKED SBP_DEPRECATED {
@@ -67,9 +67,10 @@ typedef struct SBP_ATTR_PACKED SBP_DEPRECATED {
  * 0 to 255. The timestamp associated with this message should represent the
  * time when the accumulated tick count reached the value given by the
  * contents of this message as accurately as possible. If using "local CPU
- * time" time tags, the receiving end will expect a `MSG_GNSS_TIME_OFFSET`
- * when a PVT fix becomes available to synchronise wheeltick measurements with
- * GNSS. Local CPU time shall roll over to zero after one week.
+ * time" time tags, the receiving end will also expect either
+ * `MSG_GNSS_TIME_OFFSET` or `MSG_PPS_TIME` to sync incoming wheeltick data to
+ * GNSS time.
+ * Local CPU time shall roll over to zero after one week.
  */
 
 typedef struct SBP_ATTR_PACKED SBP_DEPRECATED {

c/include/libsbp/system/MSG_PPS_TIME.h

@@ -42,7 +42,7 @@ extern "C" {
  *
  * The PPS time message contains the value of the sender's local time in
  * microseconds at the moment a pulse is detected on the PPS input. This is to
- * be used for syncronisation of sensor data sampled with a local timestamp
+ * be used for synchronisation of sensor data sampled with a local timestamp
  * (e.g. IMU or wheeltick messages) where GNSS time is unknown to the sender.
  *
  */

c/include/libsbp/vehicle/MSG_ODOMETRY.h

@@ -45,10 +45,7 @@ extern "C" {
  * odometry reference point and the definition and origin of the user frame are
  * defined through the device settings interface. There are 4 possible
  * user-defined sources of this message which are labeled arbitrarily source 0
- * through 3. If using "processor time" time tags, the receiving end will expect
- * a `MSG_GNSS_TIME_OFFSET` when a PVT fix becomes available to synchronise
- * odometry measurements with GNSS. Processor time shall roll over to zero after
- * one week.
+ * through 3.
  */
 typedef struct {
   /**

c/include/libsbp/vehicle/MSG_WHEELTICK.h

@@ -48,9 +48,8 @@ extern "C" {
  * The timestamp associated with this message should represent the time when the
  * accumulated tick count reached the value given by the contents of this
  * message as accurately as possible. If using "local CPU time" time tags, the
- * receiving end will expect a `MSG_GNSS_TIME_OFFSET` when a PVT fix becomes
- * available to synchronise wheeltick measurements with GNSS. Local CPU time
- * shall roll over to zero after one week.
+ * receiving end will also expect either `MSG_GNSS_TIME_OFFSET` or
+ * `MSG_PPS_TIME` to sync incoming wheeltick data to GNSS time.
  */
 typedef struct {
   /**

docs/sbp.pdf

@@ -45,12 +45,10 @@ msgImuRaw = 0x0900
 -- the indications on the device itself. Measurement units, which are specific
 -- to the device hardware and settings, are communicated via the MSG_IMU_AUX
 -- message. If using "time since startup" local time tags, the receiving end
--- will expect a `MSG_PPS_TIME` regardless of GNSS fix state. This also
--- requires that the MSG_PPS_TIME message be sent prior to any IMU RAW
--- messages that are based on the current (as measured at the PPS edge) local
--- time timestamps. The local time (as defined in the MSG_PPS_TIME message)
--- must wrap around to zero when reaching the extent of the u64 "Local time in
--- microseconds" parameter.
+-- will expect either a MSG_GNSS_TIME_OFFSET or MSG_PPS_TIME to establish the
+-- relationship between IMU time and GNSS time.
+-- Regardless of the timestamping mode, the timestamp is required to roll over
+-- to zero when reaching one week (604800 seconds, or 604800000 milliseconds).
 -- The time-tagging mode should not change throughout a run.
 data MsgImuRaw = MsgImuRaw
   { _msgImuRaw_tow :: !Word32

haskell/src/SwiftNav/SBP/Imu.hs

@@ -454,15 +454,16 @@ msgPpsTime = 0xFF08
 --
 -- The PPS time message contains the value of the sender's local time in
 -- microseconds at the moment a pulse is detected on the PPS input. This is to
--- be used for syncronisation of sensor data sampled with a local timestamp
+-- be used for synchronisation of sensor data sampled with a local timestamp
 -- (e.g. IMU or wheeltick messages) where GNSS time is unknown to the sender.
 --
 -- The local time used to timestamp the PPS pulse must be generated by the
 -- same clock which is used to timestamp the IMU/wheel sensor data and should
--- follow the same roll-over rules.  A separate MSG_PPS_TIME message should be
--- sent for each source of sensor data which uses PPS-relative timestamping.
--- The sender ID for each of these MSG_PPS_TIME messages should match the
--- sender ID of the respective sensor data.
+-- follow the same roll-over rules (i.e. it should roll over to zero after
+-- 604800 seconds). A separate MSG_PPS_TIME message should be sent for each
+-- source of sensor data which uses local timestamping.  The sender ID for
+-- each of these MSG_PPS_TIME messages should match the sender ID of the
+-- respective sensor data.
 data MsgPpsTime = MsgPpsTime
   { _msgPpsTime_time :: !Word64
     -- ^ Local time in microseconds