From 39cc7e153baad8cc92f1bed052523b4e3debbb6e Mon Sep 17 00:00:00 2001 From: Adam Shapiro Date: Thu, 19 Oct 2023 16:11:17 -0400 Subject: [PATCH] Clarified wheel tick output interval parameter description. --- .../messages/configuration.py | 47 ++++++++++++--- .../fusion_engine/messages/configuration.h | 60 +++++++++++++++---- 2 files changed, 87 insertions(+), 20 deletions(-) diff --git a/python/fusion_engine_client/messages/configuration.py b/python/fusion_engine_client/messages/configuration.py index f870f40f..24ac6575 100644 --- a/python/fusion_engine_client/messages/configuration.py +++ b/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::VEHCILE_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::VEHCILE_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::VEHCILE_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::VEHCILE_TICKS, ignored for wheel speed input. wheel_ticks_always_increase: bool = True WheelConfigConstruct = Struct( diff --git a/src/point_one/fusion_engine/messages/configuration.h b/src/point_one/fusion_engine/messages/configuration.h index 7c075442..82b0bd1c 100644 --- a/src/point_one/fusion_engine/messages/configuration.h +++ b/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::VEHCILE_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::VEHCILE_TICKS, ignored for wheel speed input. */ uint32_t wheel_tick_max_value = 0; @@ -1103,7 +1136,9 @@ 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::VEHCILE_TICKS, ignored for wheel speed input. See + * @ref wheel_tick_max_value for details. */ bool wheel_ticks_signed = false; @@ -1111,6 +1146,9 @@ struct P1_ALIGNAS(4) WheelConfig { * `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::VEHCILE_TICKS, ignored for wheel speed input. */ bool wheel_ticks_always_increase = true;