1 /* 2 * Copyright (C) 2017 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef _CHRE_SENSOR_TYPES_H_ 18 #define _CHRE_SENSOR_TYPES_H_ 19 20 /** 21 * @file 22 * Standalone definition of sensor types, and the data structures of the sample 23 * events they emit. 24 */ 25 26 #include <stdint.h> 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif 31 32 /** 33 * @file 34 * The CHRE_SENSOR_TYPE_* defines are the sensor types supported. 35 * 36 * Unless otherwise noted, each of these sensor types is based off of a 37 * corresponding sensor type in the Android API's sensors.h interface. 38 * For a given CHRE_SENSOR_TYPE_FOO, it corresponds to the SENSOR_TYPE_FOO in 39 * hardware/libhardware/include/hardware/sensors.h of the Android code base. 40 * 41 * Unless otherwise noted below, a CHRE_SENSOR_TYPE_FOO should be assumed 42 * to work the same as the Android SENSOR_TYPE_FOO, as documented in the 43 * sensors.h documentation and as detailed within the Android Compatibility 44 * Definition Document. 45 * 46 * Note that every sensor will generate CHRE_EVENT_SENSOR_SAMPLING_CHANGE 47 * events, so it is not listed with each individual sensor. 48 */ 49 50 /** 51 * Start value for all of the vendor-defined private sensors. 52 * 53 * @since v1.2 54 */ 55 #define CHRE_SENSOR_TYPE_VENDOR_START UINT8_C(192) 56 57 /** 58 * Accelerometer. 59 * 60 * Generates: CHRE_EVENT_SENSOR_ACCELEROMETER_DATA and 61 * optionally CHRE_EVENT_SENSOR_ACCELEROMETER_BIAS_INFO 62 * 63 * Note that the ACCELEROMETER_DATA is always the fully calibrated data, 64 * including factory calibration and runtime calibration if available. 65 * 66 * @see chreConfigureSensorBiasEvents 67 */ 68 #define CHRE_SENSOR_TYPE_ACCELEROMETER UINT8_C(1) 69 70 /** 71 * Instantaneous motion detection. 72 * 73 * Generates: CHRE_EVENT_SENSOR_INSTANT_MOTION_DETECT_DATA 74 * 75 * This is a one-shot sensor. 76 * 77 * This does not have a direct analogy within sensors.h. This is similar 78 * to SENSOR_TYPE_MOTION_DETECT, but this triggers instantly upon any 79 * motion, instead of waiting for a period of continuous motion. 80 */ 81 #define CHRE_SENSOR_TYPE_INSTANT_MOTION_DETECT UINT8_C(2) 82 83 /** 84 * Stationary detection. 85 * 86 * Generates: CHRE_EVENT_SENSOR_STATIONARY_DETECT_DATA 87 * 88 * This is a one-shot sensor. 89 */ 90 #define CHRE_SENSOR_TYPE_STATIONARY_DETECT UINT8_C(3) 91 92 /** 93 * Gyroscope. 94 * 95 * Generates: CHRE_EVENT_SENSOR_GYROSCOPE_DATA and 96 * optionally CHRE_EVENT_SENSOR_GYROSCOPE_BIAS_INFO 97 * 98 * Note that the GYROSCOPE_DATA is always the fully calibrated data, including 99 * factory calibration and runtime calibration if available. 100 * 101 * @see chreConfigureSensorBiasEvents 102 */ 103 #define CHRE_SENSOR_TYPE_GYROSCOPE UINT8_C(6) 104 105 /** 106 * Uncalibrated gyroscope. 107 * 108 * Generates: CHRE_EVENT_SENSOR_UNCALIBRATED_GYROSCOPE_DATA 109 * 110 * Note that the UNCALIBRATED_GYROSCOPE_DATA must be factory calibrated data, 111 * but not runtime calibrated. 112 */ 113 #define CHRE_SENSOR_TYPE_UNCALIBRATED_GYROSCOPE UINT8_C(7) 114 115 /** 116 * Magnetometer. 117 * 118 * Generates: CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_DATA and 119 * optionally CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_BIAS_INFO 120 * 121 * Note that the GEOMAGNETIC_FIELD_DATA is always the fully calibrated data, 122 * including factory calibration and runtime calibration if available. 123 * 124 * @see chreConfigureSensorBiasEvents 125 */ 126 #define CHRE_SENSOR_TYPE_GEOMAGNETIC_FIELD UINT8_C(8) 127 128 /** 129 * Uncalibrated magnetometer. 130 * 131 * Generates: CHRE_EVENT_SENSOR_UNCALIBRATED_GEOMAGNETIC_FIELD_DATA 132 * 133 * Note that the UNCALIBRATED_GEOMAGNETIC_FIELD_DATA must be factory calibrated 134 * data, but not runtime calibrated. 135 */ 136 #define CHRE_SENSOR_TYPE_UNCALIBRATED_GEOMAGNETIC_FIELD UINT8_C(9) 137 138 /** 139 * Barometric pressure sensor. 140 * 141 * Generates: CHRE_EVENT_SENSOR_PRESSURE_DATA 142 */ 143 #define CHRE_SENSOR_TYPE_PRESSURE UINT8_C(10) 144 145 /** 146 * Ambient light sensor. 147 * 148 * Generates: CHRE_EVENT_SENSOR_LIGHT_DATA 149 * 150 * This is an on-change sensor. 151 */ 152 #define CHRE_SENSOR_TYPE_LIGHT UINT8_C(12) 153 154 /** 155 * Proximity detection. 156 * 157 * Generates: CHRE_EVENT_SENSOR_PROXIMITY_DATA 158 * 159 * This is an on-change sensor. 160 */ 161 #define CHRE_SENSOR_TYPE_PROXIMITY UINT8_C(13) 162 163 /** 164 * Step detection. 165 * 166 * Generates: CHRE_EVENT_SENSOR_STEP_DETECT_DATA 167 * 168 * @since v1.3 169 */ 170 #define CHRE_SENSOR_TYPE_STEP_DETECT UINT8_C(23) 171 172 /** 173 * Uncalibrated accelerometer. 174 * 175 * Generates: CHRE_EVENT_SENSOR_UNCALIBRATED_ACCELEROMETER_DATA 176 * 177 * Note that the UNCALIBRATED_ACCELEROMETER_DATA must be factory calibrated 178 * data, but not runtime calibrated. 179 */ 180 #define CHRE_SENSOR_TYPE_UNCALIBRATED_ACCELEROMETER UINT8_C(55) 181 182 /** 183 * Accelerometer temperature. 184 * 185 * Generates: CHRE_EVENT_SENSOR_ACCELEROMETER_TEMPERATURE_DATA 186 */ 187 #define CHRE_SENSOR_TYPE_ACCELEROMETER_TEMPERATURE UINT8_C(56) 188 189 /** 190 * Gyroscope temperature. 191 * 192 * Generates: CHRE_EVENT_SENSOR_GYROSCOPE_TEMPERATURE_DATA 193 */ 194 #define CHRE_SENSOR_TYPE_GYROSCOPE_TEMPERATURE UINT8_C(57) 195 196 /** 197 * Magnetometer temperature. 198 * 199 * Generates: CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_TEMPERATURE_DATA 200 */ 201 #define CHRE_SENSOR_TYPE_GEOMAGNETIC_FIELD_TEMPERATURE UINT8_C(58) 202 203 #if CHRE_SENSOR_TYPE_GEOMAGNETIC_FIELD_TEMPERATURE >= CHRE_SENSOR_TYPE_VENDOR_START 204 #error Too many sensor types 205 #endif 206 207 /** 208 * Values that can be stored in the accuracy field of chreSensorDataHeader. 209 * If CHRE_SENSOR_ACCURACY_UNKNOWN is returned, then the driver did not provide 210 * accuracy information with the data. Values in the range 211 * [CHRE_SENSOR_ACCURACY_VENDOR_START, CHRE_SENSOR_ACCURACY_VENDOR_END] are 212 * reserved for vendor-specific values for vendor sensor types, and are not used 213 * by CHRE for standard sensor types. 214 * 215 * Otherwise, the values have the same meaning as defined in the Android 216 * Sensors definition: 217 * https://developer.android.com/reference/android/hardware/SensorManager 218 * 219 * @since v1.3 220 * 221 * @defgroup CHRE_SENSOR_ACCURACY 222 * @{ 223 */ 224 225 #define CHRE_SENSOR_ACCURACY_UNKNOWN UINT8_C(0) 226 #define CHRE_SENSOR_ACCURACY_UNRELIABLE UINT8_C(1) 227 #define CHRE_SENSOR_ACCURACY_LOW UINT8_C(2) 228 #define CHRE_SENSOR_ACCURACY_MEDIUM UINT8_C(3) 229 #define CHRE_SENSOR_ACCURACY_HIGH UINT8_C(4) 230 #define CHRE_SENSOR_ACCURACY_VENDOR_START UINT8_C(192) 231 #define CHRE_SENSOR_ACCURACY_VENDOR_END UINT8_MAX 232 233 /** @} */ 234 235 /** 236 * Header used in every structure containing batchable data from a sensor. 237 * 238 * The typical structure for sensor data looks like: 239 * 240 * struct chreSensorTypeData { 241 * struct chreSensorDataHeader header; 242 * struct chreSensorTypeSampleData { 243 * uint32_t timestampDelta; 244 * union { 245 * <type> value; 246 * <type> interpretation0; 247 * <type> interpretation1; 248 * }; 249 * } readings[1]; 250 * }; 251 * 252 * Despite 'readings' being declared as an array of 1 element, 253 * an instance of the struct will actually have 'readings' as 254 * an array of header.readingCount elements (which may be 1). 255 * The 'timestampDelta' is in relation to the previous 'readings' (or 256 * the baseTimestamp for readings[0]. So, 257 * Timestamp for readings[0] == header.baseTimestamp + 258 * readings[0].timestampDelta. 259 * Timestamp for readings[1] == timestamp for readings[0] + 260 * readings[1].timestampDelta. 261 * And thus, in order to determine the timestamp for readings[N], it's 262 * necessary to process through all of the N-1 readings. The advantage, 263 * though, is that our entire readings can span an arbitrary length of time, 264 * just as long as any two consecutive readings differ by no more than 265 * 4.295 seconds (timestampDelta, like all time in the CHRE, is in 266 * nanoseconds). 267 * 268 * If a sensor has batched readings where two consecutive readings differ by 269 * more than 4.295 seconds, the CHRE will split them across multiple 270 * instances of the struct, and send multiple events. 271 * 272 * The value from the sensor is typically expressed in a union, 273 * allowing a generic access to the data ('value'), along with 274 * differently named access giving a more natural interpretation 275 * of the data for the specific sensor types which use this 276 * structure. This allows, for example, barometer code to 277 * reference readings[N].pressure, and an ambient light sensor 278 * to reference readings[N].light, while both use the same 279 * structure. 280 */ 281 struct chreSensorDataHeader { 282 /** 283 * The base timestamp, in nanoseconds. 284 */ 285 uint64_t baseTimestamp; 286 287 /** 288 * The handle of the sensor producing this event. 289 */ 290 uint32_t sensorHandle; 291 292 /** 293 * The number elements in the 'readings' array. 294 * 295 * This must be at least 1. 296 */ 297 uint16_t readingCount; 298 299 /** 300 * The accuracy of the sensor data. 301 * 302 * @ref CHRE_SENSOR_ACCURACY 303 * 304 * @since v1.3 305 */ 306 uint8_t accuracy; 307 308 /** 309 * Reserved bytes. 310 * 311 * This must be 0. 312 */ 313 uint8_t reserved; 314 }; 315 316 /** 317 * Data for a sensor which reports on three axes. 318 * 319 * This is used by CHRE_EVENT_SENSOR_ACCELEROMETER_DATA, 320 * CHRE_EVENT_SENSOR_ACCELEROMETER_BIAS_INFO, 321 * CHRE_EVENT_SENSOR_UNCALIBRATED_ACCELEROMETER_DATA, 322 * CHRE_EVENT_SENSOR_GYROSCOPE_DATA, 323 * CHRE_EVENT_SENSOR_GYROSCOPE_BIAS_INFO, 324 * CHRE_EVENT_SENSOR_UNCALIBRATED_GYROSCOPE_DATA, 325 * CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_DATA, 326 * CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_BIAS_INFO, and 327 * CHRE_EVENT_SENSOR_UNCALIBRATED_GEOMAGNETIC_FIELD_DATA. 328 */ 329 struct chreSensorThreeAxisData { 330 /** 331 * @see chreSensorDataHeader 332 */ 333 struct chreSensorDataHeader header; 334 struct chreSensorThreeAxisSampleData { 335 /** 336 * @see chreSensorDataHeader 337 */ 338 uint32_t timestampDelta; 339 union { 340 float values[3]; 341 float v[3]; 342 struct { 343 float x; 344 float y; 345 float z; 346 }; 347 float bias[3]; 348 struct { 349 float x_bias; 350 float y_bias; 351 float z_bias; 352 }; 353 }; 354 } readings[1]; 355 }; 356 357 /** 358 * Data from a sensor where we only care about a event occurring. 359 * 360 * This is a bit unusual in that our readings have no data in addition 361 * to the timestamp. But since we only care about the occurrence, we 362 * don't need to know anything else. 363 * 364 * Used by: CHRE_EVENT_SENSOR_INSTANT_MOTION_DETECT_DATA, 365 * CHRE_EVENT_SENSOR_STATIONARY_DETECT_DATA, and 366 * CHRE_EVENT_SENSOR_STEP_DETECT_DATA. 367 */ 368 struct chreSensorOccurrenceData { 369 struct chreSensorDataHeader header; 370 struct chreSensorOccurrenceSampleData { 371 uint32_t timestampDelta; 372 // This space intentionally left blank. 373 // Only the timestamp is meaningful here, there 374 // is no additional data. 375 } readings[1]; 376 }; 377 378 /** 379 * This is used by CHRE_EVENT_SENSOR_LIGHT_DATA, 380 * CHRE_EVENT_SENSOR_PRESSURE_DATA, 381 * CHRE_EVENT_SENSOR_ACCELEROMETER_TEMPERATURE_DATA, 382 * CHRE_EVENT_SENSOR_GYROSCOPE_TEMPERATURE_DATA, and 383 * CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_TEMPERATURE_DATA. 384 */ 385 struct chreSensorFloatData { 386 struct chreSensorDataHeader header; 387 struct chreSensorFloatSampleData { 388 uint32_t timestampDelta; 389 union { 390 float value; 391 float light; //!< Unit: lux 392 float pressure; //!< Unit: hectopascals (hPa) 393 float temperature; //!< Unit: degrees Celsius 394 }; 395 } readings[1]; 396 }; 397 398 /** 399 * CHRE_EVENT_SENSOR_PROXIMITY_DATA. 400 */ 401 struct chreSensorByteData { 402 struct chreSensorDataHeader header; 403 struct chreSensorByteSampleData { 404 uint32_t timestampDelta; 405 union { 406 uint8_t value; 407 struct { 408 uint8_t isNear : 1; 409 //! @deprecated As of v1.2, this field is deprecated and must 410 //! always be set to 0 411 uint8_t invalid : 1; 412 uint8_t padding0 : 6; 413 }; 414 }; 415 } readings[1]; 416 }; 417 418 419 #ifdef __cplusplus 420 } 421 #endif 422 423 #endif /* _CHRE_SENSOR_TYPES_H_ */ 424