Line data    Source code

       1           0 : /*
       2             :  * Copyright (c) 2022-2023 Intel Corporation.
       3             :  *
       4             :  * SPDX-License-Identifier: Apache-2.0
       5             :  */
       6             : 
       7             : #ifndef ZEPHYR_INCLUDE_SENSING_DATATYPES_H_
       8             : #define ZEPHYR_INCLUDE_SENSING_DATATYPES_H_
       9             : 
      10             : #include <stdint.h>
      11             : #include <zephyr/dsp/types.h>
      12             : 
      13             : /**
      14             :  * @brief Data Types
      15             :  * @addtogroup sensing_datatypes
      16             :  * @{
      17             :  */
      18             : 
      19             : /**
      20             :  * @struct sensing_sensor_value_header
      21             :  * @brief sensor value header
      22             :  *
      23             :  * Each sensor value data structure should have this header
      24             :  *
      25             :  * Here use 'base_timestamp' (uint64_t) and 'timestamp_delta' (uint32_t) to
      26             :  * save memory usage in batching mode.
      27             :  *
      28             :  * The 'base_timestamp' is for readings[0], the 'timestamp_delta' is relation
      29             :  * to the previous 'readings'. So,
      30             :  * timestamp of readings[0] is
      31             :  *      header.base_timestamp + readings[0].timestamp_delta.
      32             :  * timestamp of readings[1] is
      33             :  *      timestamp of readings[0] + readings[1].timestamp_delta.
      34             :  *
      35             :  * Since timestamp unit is micro seconds, the max 'timestamp_delta' (uint32_t)
      36             :  * is 4295 seconds.
      37             :  *
      38             :  * If a sensor has batched data where two consecutive readings differ by
      39             :  * more than 4295 seconds, the sensor subsystem core will split them
      40             :  * across multiple instances of the readings structure, and send multiple
      41             :  * events.
      42             :  *
      43             :  * This concept is borrowed from CHRE:
      44             :  * https://cs.android.com/android/platform/superproject/+/master:\
      45             :  * system/chre/chre_api/include/chre_api/chre/sensor_types.h
      46             :  */
      47           1 : struct sensing_sensor_value_header {
      48             :         /** Base timestamp of this data readings, unit is micro seconds */
      49           1 :         uint64_t base_timestamp;
      50             :         /** Count of this data readings */
      51           1 :         uint16_t reading_count;
      52             : };
      53             : 
      54             : /**
      55             :  * @brief Sensor value data structure types based on common data types.
      56             :  * Suitable for common sensors, such as IMU, Light sensors and orientation sensors.
      57             :  */
      58             : 
      59             : /**
      60             :  * @brief Sensor value data structure for 3-axis sensors.
      61             :  * struct sensing_sensor_value_3d_q31 can be used by 3D IMU sensors like:
      62             :  * SENSING_SENSOR_TYPE_MOTION_ACCELEROMETER_3D,
      63             :  * SENSING_SENSOR_TYPE_MOTION_UNCALIB_ACCELEROMETER_3D,
      64             :  * SENSING_SENSOR_TYPE_MOTION_GYROMETER_3D,
      65             :  * q31 version
      66             :  */
      67           1 : struct sensing_sensor_value_3d_q31 {
      68             :         /** Header of the sensor value data structure. */
      69           1 :         struct sensing_sensor_value_header header;
      70           1 :         int8_t shift; /**< The shift value for the q31_t v[3] reading. */
      71             :         struct {
      72             :                 /** Timestamp delta of the reading. Unit is micro seconds. */
      73           1 :                 uint32_t timestamp_delta;
      74             :                 union {
      75             :                         /**
      76             :                          * 3D vector of the reading represented as an array.
      77             :                          * For SENSING_SENSOR_TYPE_MOTION_ACCELEROMETER_3D and
      78             :                          * SENSING_SENSOR_TYPE_MOTION_UNCALIB_ACCELEROMETER_3D,
      79             :                          * the unit is Gs (gravitational force).
      80             :                          * For SENSING_SENSOR_TYPE_MOTION_GYROMETER_3D, the unit is degrees.
      81             :                          */
      82           1 :                         q31_t v[3];
      83             :                         struct {
      84           1 :                                 q31_t x; /**< X value of the 3D vector. */
      85           1 :                                 q31_t y; /**< Y value of the 3D vector. */
      86           1 :                                 q31_t z; /**< Z value of the 3D vector. */
      87             :                         };
      88             :                 };
      89           1 :         } readings[1]; /**< Array of readings. */
      90             : };
      91             : 
      92             : /**
      93             :  * @brief Sensor value data structure for single 1-axis value.
      94             :  * struct sensing_sensor_value_uint32 can be used by SENSING_SENSOR_TYPE_LIGHT_AMBIENTLIGHT sensor
      95             :  * uint32_t version
      96             :  */
      97           1 : struct sensing_sensor_value_uint32 {
      98             :         /** Header of the sensor value data structure. */
      99           1 :         struct sensing_sensor_value_header header;
     100             :         struct {
     101             :                 /** Timestamp delta of the reading. Unit is micro seconds. */
     102           1 :                 uint32_t timestamp_delta;
     103             :                 /**
     104             :                  * Value of the reading.
     105             :                  * For SENSING_SENSOR_TYPE_LIGHT_AMBIENTLIGHT, the unit is luxs.
     106             :                  */
     107           1 :                 uint32_t v;
     108           1 :         } readings[1];      /**< Array of readings. */
     109             : };
     110             : 
     111             : /**
     112             :  * @brief Sensor value data structure for single 1-axis value.
     113             :  * struct sensing_sensor_value_q31 can be used by SENSING_SENSOR_TYPE_MOTION_HINGE_ANGLE sensor
     114             :  * q31 version
     115             :  */
     116           1 : struct sensing_sensor_value_q31 {
     117             :         /** Header of the sensor value data structure. */
     118           1 :         struct sensing_sensor_value_header header;
     119           1 :         int8_t shift; /**< The shift value for the q31_t v reading. */
     120             :         struct {
     121             :                 /** Timestamp delta of the reading. Unit is micro seconds. */
     122           1 :                 uint32_t timestamp_delta;
     123             :                 /**
     124             :                  * Value of the reading.
     125             :                  * For SENSING_SENSOR_TYPE_MOTION_HINGE_ANGLE, the unit is degrees.
     126             :                  */
     127           1 :                 q31_t v;
     128           1 :         } readings[1];   /**< Array of readings. */
     129             : };
     130             : 
     131             : /**
     132             :  * @}
     133             :  */
     134             : 
     135             : #endif /*ZEPHYR_INCLUDE_SENSING_DATATYPES_H_*/