From 4c1d07eef5d69354dfe089de3307dc2fe00ef56a Mon Sep 17 00:00:00 2001 From: Helmut Schmidt Date: Fri, 4 Nov 2016 10:39:16 +0100 Subject: GT-3402 "Positioning SensorsService API: Add sampling interval field to gyroscope, accelerometer etc data structures" step 4: Wheel API --- sensors-service/api/wheel.h | 253 ++++++++++++++++++++++++++++++-------------- 1 file changed, 173 insertions(+), 80 deletions(-) diff --git a/sensors-service/api/wheel.h b/sensors-service/api/wheel.h index a6865d3..da3e931 100644 --- a/sensors-service/api/wheel.h +++ b/sensors-service/api/wheel.h @@ -101,14 +101,18 @@ extern "C" { * */ typedef enum { - WHEEL_STATUS_GAP = 0x00000001, /**< There has been a gap in data collection, - i.e. an unknown number of wheel revolutions has been lost. - The reason for such a gap can be for example - - wheel tick data on the vehicle bus explicitly tagged as invalid - - interrupted reception of vehicle bus messages. - This flag will only be set if the detected gap may affect the application. */ - WHEEL_STATUS_INIT = 0x00000002 /**< This is the first wheel data of a bus or ignition lifecycle, - i.e. the wheel tick difference calculation may be less reliable. */ + /** There has been a gap in data collection, + * i.e. an unknown number of wheel revolutions has been lost. + * The reason for such a gap can be for example + * - wheel tick data on the vehicle bus explicitly tagged as invalid + * - interrupted reception of vehicle bus messages. + * This flag will only be set if the detected gap may affect the application. + */ + WHEEL_STATUS_GAP = 0x00000001, + /** This is the first wheel data of a bus or ignition lifecycle, + * i.e. the wheel tick difference calculation may be less reliable. + */ + WHEEL_STATUS_INIT = 0x00000002 } EWheelStatusBits; /** @@ -117,14 +121,33 @@ typedef enum { * Note: The assignment of the fields to the wheels of the vehicle is provided by the function snsWheelGetConfiguration(). */ typedef enum { - WHEEL0_VALID = 0x00000001, /**< Validity bit for field TWheelData::data[0]. */ - WHEEL1_VALID = 0x00000002, /**< Validity bit for field TWheelData::data[1]. */ - WHEEL2_VALID = 0x00000004, /**< Validity bit for field TWheelData::data[2]. */ - WHEEL3_VALID = 0x00000008, /**< Validity bit for field TWheelData::data[3]. */ - WHEEL4_VALID = 0x00000010, /**< Validity bit for field TWheelData::data[4]. */ - WHEEL5_VALID = 0x00000020, /**< Validity bit for field TWheelData::data[5]. */ - WHEEL6_VALID = 0x00000040, /**< Validity bit for field TWheelData::data[6]. */ - WHEEL7_VALID = 0x00000080 /**< Validity bit for field TWheelData::data[7]. */ + /** Validity bit for field TWheelData::data[0]. + */ + WHEEL0_VALID = 0x00000001, + /** Validity bit for field TWheelData::data[1]. + */ + WHEEL1_VALID = 0x00000002, + /** Validity bit for field TWheelData::data[2]. + */ + WHEEL2_VALID = 0x00000004, + /** Validity bit for field TWheelData::data[3]. + */ + WHEEL3_VALID = 0x00000008, + /** Validity bit for field TWheelData::data[4]. + */ + WHEEL4_VALID = 0x00000010, + /** Validity bit for field TWheelData::data[5]. + */ + WHEEL5_VALID = 0x00000020, + /** Validity bit for field TWheelData::data[6]. + */ + WHEEL6_VALID = 0x00000040, + /** Validity bit for field TWheelData::data[7]. + */ + WHEEL7_VALID = 0x00000080, + /** Validity bit for field TWheelData::measurementInterval. + */ + WHEEL_MEASINT_VALID = 0x00000100 } EWheelValidityBits; /** @@ -136,43 +159,74 @@ typedef enum { */ typedef enum { - WHEEL_UNIT_NONE = 0, /**< Wheel does not provide any data. */ - WHEEL_UNIT_TICKS = 1, /**< Wheel rotation data is provided as number of wheel ticks accumulated within measurement interval. - Note 1: Therefore, if the wheel ticks on the vehicle bus are represented as rolling counters, - this is the difference between two subsequent rolling counter values - taking the vehicle specific roll-over boundary into account. - Note 2: It is safe to store integer values such as for wheel ticks - without precision loss in float variables for values up to 2^23. */ - WHEEL_UNIT_SPEED = 2, /**< Wheel rotation data is provided as speed in [m/s]. */ - WHEEL_UNIT_ANGULAR_SPEED = 3, /**< Wheel rotation data is provided as angular speed in [1/s] rotation per seconds. */ + /** Wheel does not provide any data. + */ + WHEEL_UNIT_NONE = 0, + /** Wheel rotation data is provided as number of wheel ticks accumulated within measurement interval. + * Note 1: Therefore, if the wheel ticks on the vehicle bus are represented as rolling counters, + * this is the difference between two subsequent rolling counter values + * taking the vehicle specific roll-over boundary into account. + * Note 2: It is safe to store integer values such as for wheel ticks + * without precision loss in float variables for values up to 2^23. + */ + WHEEL_UNIT_TICKS = 1, + /** Wheel rotation data is provided as speed in [m/s]. + */ + WHEEL_UNIT_SPEED = 2, + /** Wheel rotation data is provided as angular speed in [1/s] rotation per seconds. + */ + WHEEL_UNIT_ANGULAR_SPEED = 3, } EWheelUnit; /** * Wheel configuration status bits */ typedef enum { - WHEEL_CONFIG_DRIVEN = 0x00000001, /**< The wheel is driven by the powertrain. - It may thus be affected by additional wheel slip. */ - WHEEL_CONFIG_STEERED = 0x00000002, /**< The wheel may be turned by the steering. - This is typically the case only for wheels on the front axle. - But for some vehicles also wheels on other axles are permanently or temporarily steered. */ - WHEEL_CONFIG_DIFF_LOCK = 0x00000004 /**< The differential lock for this wheel is activated. */ + /** The wheel is driven by the powertrain. + * It may thus be affected by additional wheel slip. + */ + WHEEL_CONFIG_DRIVEN = 0x00000001, + /** The wheel may be turned by the steering. + * This is typically the case only for wheels on the front axle. + * But for some vehicles also wheels on other axles are permanently or temporarily steered. + */ + WHEEL_CONFIG_STEERED = 0x00000002, + /** The differential lock for this wheel is activated. + */ + WHEEL_CONFIG_DIFF_LOCK = 0x00000004 } EWheelConfigStatusBits; /** - * TWheelConfiguration::validityBits provides information about the currently valid signals of the wheel configuration data. + * TWheelConfiguration::validityBits provides information about the currently + * valid signals of the wheel configuration data. * It is a or'ed bitmask of the EWheelConfigValidityBits values. */ typedef enum { - WHEEL_CONFIG_TICKS_PER_REV_VALID = 0x00000001, /**< Validity bit for field TWheelConfiguration::wheelticksPerRevolution. */ - WHEEL_CONFIG_TIRE_CIRC_VALID = 0x00000002, /**< Validity bit for field TWheelConfiguration::tireRollingCircumference. */ - WHEEL_CONFIG_DISTX_VALID = 0x00000004, /**< Validity bit for field TWheelConfiguration::dist2RefPointX. */ - WHEEL_CONFIG_DISTY_VALID = 0x00000008, /**< Validity bit for field TWheelConfiguration::dist2RefPointY. */ - WHEEL_CONFIG_DISTZ_VALID = 0x00000010, /**< Validity bit for field TWheelConfiguration::dist2RefPointZ. */ - WHEEL_CONFIG_DRIVEN_VALID = 0x00000020, /**< Validity bit for field TWheelConfiguration::EWheelConfigStatusBits::WHEEL_CONFIG_DRIVEN. */ - WHEEL_CONFIG_STEERED_VALID = 0x00000040, /**< Validity bit for field TWheelConfiguration::EWheelConfigStatusBits::WHEEL_CONFIG_STEERED. */ - WHEEL_CONFIG_DIFF_LOCK_VALID = 0x00000080, /**< Validity bit for field TWheelConfiguration::EWheelConfigStatusBits::WHEEL_CONFIG_DIFF_LOCK. */ + /** Validity bit for field TWheelConfiguration::wheelticksPerRevolution. + */ + WHEEL_CONFIG_TICKS_PER_REV_VALID = 0x00000001, + /** Validity bit for field TWheelConfiguration::tireRollingCircumference. + */ + WHEEL_CONFIG_TIRE_CIRC_VALID = 0x00000002, + /** Validity bit for field TWheelConfiguration::dist2RefPointX. + */ + WHEEL_CONFIG_DISTX_VALID = 0x00000004, + /** Validity bit for field TWheelConfiguration::dist2RefPointY. + */ + WHEEL_CONFIG_DISTY_VALID = 0x00000008, + /** Validity bit for field TWheelConfiguration::dist2RefPointZ. + */ + WHEEL_CONFIG_DISTZ_VALID = 0x00000010, + /** Validity bit for field TWheelConfiguration::EWheelConfigStatusBits::WHEEL_CONFIG_DRIVEN. + */ + WHEEL_CONFIG_DRIVEN_VALID = 0x00000020, + /** Validity bit for field TWheelConfiguration::EWheelConfigStatusBits::WHEEL_CONFIG_STEERED. + */ + WHEEL_CONFIG_STEERED_VALID = 0x00000040, + /** Validity bit for field TWheelConfiguration::EWheelConfigStatusBits::WHEEL_CONFIG_DIFF_LOCK. + */ + WHEEL_CONFIG_DIFF_LOCK_VALID = 0x00000080, } EWheelConfigValidityBits; @@ -192,35 +246,59 @@ typedef enum { * */ typedef struct { - EWheelUnit wheelUnit; /**< [Static] Measurement unit in which the wheel rotation data is provided. - WHEEL_UNIT_NONE, if no wheel rotation data is provided (and thus the rest of the structure can be ignored. */ - uint8_t axleIndex; /**< [Static] Identification of the axle on which the wheel is mounted - Axles are numbered consecutively from front to rear. - 0: unknown/unspecified - 1: front axle - 2: 2nd axle (rear axle on a typical 2-axle vehicle) - 3: 3rd axle - ... */ - uint8_t wheelIndex; /**< [Static] Identification of the location of the wheel on the axle - Wheels are numbered consecutively from left to right - 0: unknown/unspecified - 1: left-most wheel (also used when there is only one wheel per axle, e.g. for a trike) - 2: right wheel #1 (right wheel on a typical passenger car with 2 wheels per axle) - 3: right wheel #2 - ... */ - uint16_t wheelticksPerRevolution; /**< [Static] Number of ticks for a single revolution of one wheel. - Typically only available when wheelUnit is WHEEL_UNIT_TICKS. */ - float tireRollingCircumference; /**< [Static] Distance travelled on the ground per a single revolution of the wheel. Unit: [m]. */ - float dist2RefPointX; /**< [Static] Distance of the wheel center from the vehicle reference point (x-coordinate) [m]. */ - float dist2RefPointY; /**< [Static] Distance of the wheel center from the vehicle reference point (y-coordinate) [m]. */ - float dist2RefPointZ; /**< [Static] Distance of the wheel center from the vehicle reference point (z-coordinate) [m]. */ - uint32_t statusBits; /**< Bit mask providing additional status information. - [bitwise or'ed @ref EWheelConfigStatusBits values]. */ - - uint32_t validityBits; /**< Bit mask indicating the validity of each corresponding value. - [bitwise or'ed @ref EWheelConfigValidityBits values]. - Must be checked before usage. - Note: wheelUnit, axleIndex and wheelIndex must always be valid. Therefore no dedicated validityBits are required.*/ + /** [Static] Measurement unit in which the wheel rotation data is provided. + * WHEEL_UNIT_NONE, if no wheel rotation data is provided (and thus the rest of the structure can be ignored. + */ + EWheelUnit wheelUnit; + /** [Static] Identification of the axle on which the wheel is mounted + * Axles are numbered consecutively from front to rear. + * 0: unknown/unspecified + * 1: front axle + * 2: 2nd axle (rear axle on a typical 2-axle vehicle) + * 3: 3rd axle + * ... + */ + uint8_t axleIndex; + /** [Static] Identification of the location of the wheel on the axle + * Wheels are numbered consecutively from left to right + * 0: unknown/unspecified + * 1: left-most wheel (also used when there is only one wheel per axle, e.g. for a trike) + * 2: right wheel #1 (right wheel on a typical passenger car with 2 wheels per axle) + * 3: right wheel #2 + * ... + */ + uint8_t wheelIndex; + /** [Static] Number of ticks for a single revolution of one wheel. + * Typically only available when wheelUnit is WHEEL_UNIT_TICKS. + */ + uint16_t wheelticksPerRevolution; + /** [Static] Distance travelled on the ground + * per a single revolution of the wheel. Unit: [m]. + */ + float tireRollingCircumference; + /** [Static] Distance of the wheel center from + * the vehicle reference point (x-coordinate) [m]. + */ + float dist2RefPointX; + /** [Static] Distance of the wheel center from + * the vehicle reference point (y-coordinate) [m]. + */ + float dist2RefPointY; + /** [Static] Distance of the wheel center from + * the vehicle reference point (z-coordinate) [m]. + */ + float dist2RefPointZ; + /** Bit mask providing additional status information. + * [bitwise or'ed @ref EWheelConfigStatusBits values]. + */ + uint32_t statusBits; + /** Bit mask indicating the validity of each corresponding value. + * [bitwise or'ed @ref EWheelConfigValidityBits values]. + * Must be checked before usage. + * Note: wheelUnit, axleIndex and wheelIndex must always be valid. + * Therefore no dedicated validityBits are required. + */ + uint32_t validityBits; } TWheelConfiguration; /** @@ -241,17 +319,32 @@ typedef TWheelConfiguration TWheelConfigurationArray[WHEEL_MAX]; * The index used for an individual wheel in the data[] array is the same as in the TWheelConfigurationArray. */ typedef struct { - uint64_t timestamp; /**< Timestamp of the acquisition of this wheel tick signal [ms]. - All sensor/GNSS timestamps must be based on the same time source. */ - - float data[WHEEL_MAX]; /**< Wheel rotation data for the wheel identified by TWheelConfiguration::wheel1 in measurement unit identified by TWheelConfiguration::wheelUnit. */ - - uint32_t statusBits; /**< Bit mask providing additional status information. - [bitwise or'ed @ref EWheelStatusBits values]. */ - - uint32_t validityBits; /**< Bit mask indicating the validity of each corresponding value. - [bitwise or'ed @ref EWheelValidityBits values]. - Must be checked before usage. */ + /** Timestamp of the acquisition of this wheel tick signal [ms]. + * All sensor/GNSS timestamps must be based on the same time source. + */ + uint64_t timestamp; + /** Wheel rotation data for the wheel identified by TWheelConfiguration::wheel[i] + * in measurement unit identified by TWheelConfiguration::wheelUnit. + */ + float data[WHEEL_MAX]; + /** Bit mask providing additional status information. + * [bitwise or'ed @ref EWheelStatusBits values]. + */ + uint32_t statusBits; + /** Measurement interval over which the wheel data have been acquired [ms]. + * This may slightly differ from the timestamp difference, + * e.g. in case of transmission jitter before timestamping. + * Providing the measurement interval allows thus + * - a more accurate integration of wheel data measurements. + * - correct usage of the first sample + * - adding consistency checks + */ + uint16_t measurementInterval; + /** Bit mask indicating the validity of each corresponding value. + * [bitwise or'ed @ref EWheelValidityBits values]. + * Must be checked before usage. + */ + uint32_t validityBits; } TWheelData; /** -- cgit v1.2.1