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 <[email protected]>
Co-authored-by: Matt Woodward <[email protected]>

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 {
   /**

haskell/src/SwiftNav/SBP/Imu.hs

@@ -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/System.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

haskell/src/SwiftNav/SBP/Vehicle.hs

@@ -44,10 +44,10 @@ msgOdometry = 0x0903
 -- 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.
 data MsgOdometry = MsgOdometry
   { _msgOdometry_tow    :: !Word32
     -- ^ Time field representing either milliseconds in the GPS Week or local
@@ -88,9 +88,10 @@ msgWheeltick = 0x0904
 -- 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.
 data MsgWheeltick = MsgWheeltick
   { _msgWheeltick_time :: !Word64
     -- ^ Time field representing either microseconds since the last PPS,

java/src/com/swiftnav/sbp/imu/MsgImuRaw.java

@@ -28,11 +28,10 @@
  * The sense of the measurements are to be aligned with 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.
- * The time-tagging mode should not change throughout a run.
+ * 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.
  */
 public class MsgImuRaw extends SBPMessage {
     public static final int TYPE = 0x0900;

java/src/com/swiftnav/sbp/system/MsgPpsTime.java

@@ -26,15 +26,15 @@
  * construct it inline using a dict of its fields.
  *
  * <p>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 (e.g. IMU or wheeltick messages) where GNSS time is unknown to the
- * sender.
+ * moment a pulse is detected on the PPS input. This is to 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.
  *
  * <p>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.
+ * used to timestamp the IMU/wheel sensor data and should 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.
  */
 public class MsgPpsTime extends SBPMessage {
     public static final int TYPE = 0xFF08;

java/src/com/swiftnav/sbp/vehicle/MsgOdometry.java

@@ -28,9 +28,9 @@
  * reference point(s) specified by the user. The offset for 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.
+ * 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.
  */
 public class MsgOdometry extends SBPMessage {
     public static final int TYPE = 0x0903;

java/src/com/swiftnav/sbp/vehicle/MsgWheeltick.java

@@ -31,9 +31,9 @@
  * source of this message is identified by the source field, which is an integer ranging from 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.
+ * using "local CPU 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.
  */
 public class MsgWheeltick extends SBPMessage {
     public static final int TYPE = 0x0904;

javascript/sbp/imu.js

@@ -30,13 +30,12 @@ let UInt64 = require('cuint').UINT64;
  * gyroscope readings. The sense of the measurements are to be aligned with 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. The time-tagging mode
- * should not change throughout a run.
+ * using "time since startup" local time tags, the receiving end 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.
  *
  * Fields in the SBP payload (`sbp.payload`):
  * @field tow number (unsigned 32-bit int, 4 bytes) Milliseconds since reference epoch and time status.

javascript/sbp/system.js

@@ -460,13 +460,14 @@ MsgGnssTimeOffset.prototype.fieldSpec.push(['flags', 'writeUInt8', 1]);
  *
  * 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 (e.g. IMU
+ * 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.
+ * 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.
  *
  * Fields in the SBP payload (`sbp.payload`):
  * @field time number (unsigned 64-bit int, 8 bytes) Local time in microseconds

javascript/sbp/vehicle.js

@@ -31,9 +31,9 @@ let UInt64 = require('cuint').UINT64;
  * 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.
+ * 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.
  *
  * Fields in the SBP payload (`sbp.payload`):
  * @field tow number (unsigned 32-bit int, 4 bytes) Time field representing either milliseconds in the GPS Week or local CPU time
@@ -75,9 +75,10 @@ MsgOdometry.prototype.fieldSpec.push(['flags', 'writeUInt8', 1]);
  * by the source field, which is an integer ranging from 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.
+ * possible. If using "local CPU 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.
  *
  * Fields in the SBP payload (`sbp.payload`):
  * @field time number (unsigned 64-bit int, 8 bytes) Time field representing either microseconds since the last PPS, microseconds in