Clarified wheel tick output interval parameter description. (#280)

python/fusion_engine_client/messages/configuration.py

@@ -529,21 +529,50 @@ class WheelConfig(NamedTuple):
         applied_speed_type: AppliedSpeedType = AppliedSpeedType.REAR_WHEELS
         ## Indication of which of the vehicle's wheels are steered.
         steering_type: SteeringType = SteeringType.UNKNOWN
-        ## The nominal rate at which wheel speed measurements will be provided (in seconds).
+        ##
+        # The rate at which wheel speed/tick measurements will be sent to the device (in seconds).
+        #
+        # @note
+        # This parameter is required when using software wheel measurements. It may not be `NAN` if wheel measurements
+        # are enabled, and cannot be determined automatically by the device.
         wheel_update_interval_sec: float = math.nan
-        ## The nominal rate at which wheel tick measurements will be provided (in seconds).
+        ##
+        # Override the rate at which wheel tick measurements will be used by the navigation engine (in seconds).
+        #
+        # If this parameter is `NAN`, the best rate will be selected automatically by
+        # the device based on the input rate (@ref wheel_update_interval_sec) and the
+        # wheel tick quantization (@ref wheel_ticks_to_m).
+        #
+        # @warning
+        # For most system configurations, we recommend setting this value to `NAN` to let the device choose the
+        # appropriate setting. Use this setting with caution.
         wheel_tick_output_interval_sec: float = math.nan
-        ## Ratio between angle of the steering wheel and the angle of the wheels on the ground.
+        ##
+        # Ratio between angle of the steering wheel and the angle of the wheels on the ground.
+        #
+        # Used when applying measurements from steered wheels only, ignored otherwise.
         steering_ratio: float = math.nan
-        ## The scale factor to convert from wheel encoder ticks to distance (in meters/tick).
+        ##
+        # The scale factor to convert from wheel encoder ticks to distance (in meters/tick).
+        #
+        # Used for @ref WheelSensorType::TICKS and @ref WheelSensorType::VEHICLE_TICKS, ignored for wheel speed input.
         wheel_ticks_to_m: float = math.nan
-        ## The maximum value (inclusive) before the wheel tick measurement will roll over.
+        ##
+        # The maximum value (inclusive) before the wheel tick measurement will roll over.
+        #
+        # Used for @ref WheelSensorType::TICKS and @ref WheelSensorType::VEHICLE_TICKS, ignored for wheel speed input.
         wheel_tick_max_value: int = 0
-        ## `True` if the reported wheel tick measurements should be interpreted as signed integers, or `False` if they
-        ## should be interpreted as unsigned integers.
+        ##
+        # `True` if the reported wheel tick measurements should be interpreted as signed integers, or `False` if they
+        # should be interpreted as unsigned integers.
+        #
+        # Used for @ref WheelSensorType::TICKS and @ref WheelSensorType::VEHICLE_TICKS, ignored for wheel speed input.
         wheel_ticks_signed: bool = False
-        ## `True` if the wheel tick measurements increase by a positive amount when driving forward or backward.
-        ## `False` if wheel tick measurements decrease when driving backward.
+        ##
+        # `True` if the wheel tick measurements increase by a positive amount when driving forward or backward.
+        # `False` if wheel tick measurements decrease when driving backward.
+        #
+        # Used for @ref WheelSensorType::TICKS and @ref WheelSensorType::VEHICLE_TICKS, ignored for wheel speed input.
         wheel_ticks_always_increase: bool = True
 
     WheelConfigConstruct = Struct(

src/point_one/fusion_engine/messages/configuration.h

@@ -858,15 +858,24 @@ enum class WheelSensorType : uint8_t {
   NONE = 0,
   // RESERVED = 1,
   /**
-   * Individual wheel rotational angles, reported as accumulated encoder
-   * ticks.
+   * Individual rotational angle measurements for multiple wheels, reported as
+   * accumulated encoder ticks. See @ref WheelTickInput.
    * */
   TICKS = 2,
-  /** Individual wheel speeds, reported in meters/second. */
+  /**
+   * Individual speed measurements for multiple wheels, reported in
+   * meters/second. See @ref WheelSpeedInput.
+   */
   WHEEL_SPEED = 3,
-  /** A single value indicating the vehicle speed (in meters/second). */
+  /**
+   * A single value indicating the vehicle speed (in meters/second). See @ref
+   * VehicleSpeedInput.
+   */
   VEHICLE_SPEED = 4,
-  /** A single wheel rotational angle, reported as accumulated encoder ticks. */
+  /**
+   * A single wheel rotational angle, reported as accumulated encoder ticks. See
+   * @ref VehicleSpeedInput.
+   */
   VEHICLE_TICKS = 5,
 };
 
@@ -1061,26 +1070,47 @@ struct P1_ALIGNAS(4) WheelConfig {
   uint8_t reserved1[1] = {0};
 
   /**
-   * The nominal rate at which wheel speed measurements will be provided (in
-   * seconds).
+   * The rate at which wheel speed/tick measurements will be sent to the device
+   * (in seconds).
+   *
+   * @note
+   * This parameter is required when using software wheel measurements. It
+   * may not be `NAN` if wheel measurements are enabled, and cannot be
+   * determined automatically by the device.
    */
   float wheel_update_interval_sec = NAN;
 
   /**
-   * The nominal rate at which wheel tick measurements will be provided (in
-   * seconds).
+   * Override the rate at which wheel tick measurements will be used by the
+   * navigation engine (in seconds).
+   *
+   * If this parameter is `NAN` (default), the best rate will be selected
+   * automatically by the device based on the input rate (@ref
+   * wheel_update_interval_sec) and the wheel tick quantization (@ref
+   * wheel_ticks_to_m).
+   *
+   * @warning
+   * For most system configurations, we recommend setting this value to `NAN` to
+   * let the device choose the appropriate setting. Use this setting with
+   * caution.
    */
   float wheel_tick_output_interval_sec = NAN;
 
   /**
    * Ratio between angle of the steering wheel and the angle of the wheels on
    * the ground.
+   *
+   * Used when applying measurements from steered wheels only, ignored
+   * otherwise.
    */
   float steering_ratio = NAN;
 
   /**
    * The scale factor to convert from wheel encoder ticks to distance (in
-   * meters/tick). Used for @ref WheelSensorType::TICKS.
+   * meters/tick).
+   *
+   * Used for @ref WheelSensorType::TICKS and @ref
+   * WheelSensorType::VEHICLE_TICKS, ignored for wheel speed input.
    */
   float wheel_ticks_to_m = NAN;
 
@@ -1095,6 +1125,9 @@ struct P1_ALIGNAS(4) WheelConfig {
    *
    * Signed values are assumed to be asymmetric, consistent with a typical 2's
    * complement rollover.
+   *
+   * Used for @ref WheelSensorType::TICKS and @ref
+   * WheelSensorType::VEHICLE_TICKS, ignored for wheel speed input.
    */
   uint32_t wheel_tick_max_value = 0;
 
@@ -1103,14 +1136,19 @@ struct P1_ALIGNAS(4) WheelConfig {
    * signed integers, or `false` if they should be interpreted as unsigned
    * integers.
    *
-   * See @ref wheel_tick_max_value for details.
+   * Used for @ref WheelSensorType::TICKS and @ref
+   * WheelSensorType::VEHICLE_TICKS, ignored for wheel speed input. See
+   * @ref wheel_tick_max_value for details.
    */
   bool wheel_ticks_signed = false;
 
   /**
    * `true` if the wheel tick measurements increase by a positive amount when
    * driving forward or backward. `false` if wheel tick measurements decrease
    * when driving backward.
+   *
+   * Used for @ref WheelSensorType::TICKS and @ref
+   * WheelSensorType::VEHICLE_TICKS, ignored for wheel speed input.
    */
   bool wheel_ticks_always_increase = true;