1/* 2 * Copyright (C) 2016 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_H_ 18#define _CHRE_SENSOR_H_ 19 20/** 21 * @file 22 * API dealing with sensor interaction in the Context Hub Runtime 23 * Environment. 24 * 25 * This includes the definition of our sensor types and the ability to 26 * configure them for receiving events. 27 */ 28 29#include <stdbool.h> 30#include <stdint.h> 31 32#include <chre/event.h> 33 34#ifdef __cplusplus 35extern "C" { 36#endif 37 38/** 39 * The CHRE_SENSOR_TYPE_* defines are the sensor types supported. 40 * 41 * Unless otherwise noted, each of these sensor types is based off of a 42 * corresponding sensor type in the Android API's sensors.h interface. 43 * For a given CHRE_SENSOR_TYPE_FOO, it corresponds to the SENSOR_TYPE_FOO in 44 * hardware/libhardware/include/hardware/sensors.h of the Android code base. 45 * 46 * Unless otherwise noted below, a CHRE_SENSOR_TYPE_FOO should be assumed 47 * to work the same as the Android SENSOR_TYPE_FOO, as documented in the 48 * sensors.h documentation and as detailed within the Android Compatibility 49 * Definition Document. 50 * 51 * Note that every sensor will generate CHRE_EVENT_SENSOR_SAMPLING_CHANGE 52 * events, so it is not listed with each individual sensor. 53 */ 54 55/** 56 * Accelerometer. 57 * 58 * Generates: CHRE_EVENT_SENSOR_ACCELEROMETER_DATA 59 * 60 * Note that the ACCELEROMETER_DATA is always the fully calibrated data, 61 * including factory calibration and runtime calibration if available. 62 */ 63#define CHRE_SENSOR_TYPE_ACCELEROMETER UINT8_C(1) 64 65/** 66 * Instantaneous motion detection. 67 * 68 * Generates: CHRE_EVENT_SENSOR_INSTANT_MOTION_DETECT_DATA 69 * 70 * This is a one-shot sensor. 71 * 72 * This does not have a direct analogy within sensors.h. This is similar 73 * to SENSOR_TYPE_MOTION_DETECT, but this triggers instantly upon any 74 * motion, instead of waiting for a period of continuous motion. 75 */ 76#define CHRE_SENSOR_TYPE_INSTANT_MOTION_DETECT UINT8_C(2) 77 78/** 79 * Stationary detection. 80 * 81 * Generates: CHRE_EVENT_SENSOR_STATIONARY_DETECT_DATA 82 * 83 * This is a one-shot sensor. 84 */ 85#define CHRE_SENSOR_TYPE_STATIONARY_DETECT UINT8_C(3) 86 87/** 88 * Gyroscope. 89 * 90 * Generates: CHRE_EVENT_SENSOR_GYROSCOPE_DATA and 91 * optionally CHRE_EVENT_SENSOR_GYROSCOPE_BIAS_INFO 92 * 93 * Note that the GYROSCOPE_DATA is always the fully calibrated data, including 94 * factory calibration and runtime calibration if available. 95 */ 96#define CHRE_SENSOR_TYPE_GYROSCOPE UINT8_C(6) 97 98/** 99 * Uncalibrated gyroscope. 100 * 101 * Generates: CHRE_EVENT_SENSOR_UNCALIBRATED_GYROSCOPE_DATA 102 * 103 * Note that the UNCALIBRATED_GYROSCOPE_DATA must be factory calibrated data, 104 * but not runtime calibrated. 105 */ 106#define CHRE_SENSOR_TYPE_UNCALIBRATED_GYROSCOPE UINT8_C(7) 107 108/** 109 * Magnetometer. 110 * 111 * Generates: CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_DATA and 112 * optionally CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_BIAS_INFO 113 * 114 * Note that the GEOMAGNETIC_FIELD_DATA is always the fully calibrated data, 115 * including factory calibration and runtime calibration if available. 116 */ 117#define CHRE_SENSOR_TYPE_GEOMAGNETIC_FIELD UINT8_C(8) 118 119/** 120 * Uncalibrated magnetometer. 121 * 122 * Generates: CHRE_EVENT_SENSOR_UNCALIBRATED_GEOMAGNETIC_FIELD_DATA 123 * 124 * Note that the UNCALIBRATED_GEOMAGNETIC_FIELD_DATA must be factory calibrated 125 * data, but not runtime calibrated. 126 */ 127#define CHRE_SENSOR_TYPE_UNCALIBRATED_GEOMAGNETIC_FIELD UINT8_C(9) 128 129/** 130 * Barometric pressure sensor. 131 * 132 * Generates: CHRE_EVENT_SENSOR_PRESSURE_DATA 133 */ 134#define CHRE_SENSOR_TYPE_PRESSURE UINT8_C(10) 135 136/** 137 * Ambient light sensor. 138 * 139 * Generates: CHRE_EVENT_SENSOR_LIGHT_DATA 140 * 141 * This is an on-change sensor. 142 */ 143#define CHRE_SENSOR_TYPE_LIGHT UINT8_C(12) 144 145/** 146 * Proximity detection. 147 * 148 * Generates: CHRE_EVENT_SENSOR_PROXIMITY_DATA 149 * 150 * This is an on-change sensor. 151 */ 152#define CHRE_SENSOR_TYPE_PROXIMITY UINT8_C(13) 153 154/** 155 * Uncalibrated accelerometer. 156 * 157 * Generates: CHRE_EVENT_SENSOR_UNCALIBRATED_ACCELEROMETER_DATA 158 * 159 * Note that the UNCALIBRATED_ACCELEROMETER_DATA must be factory calibrated 160 * data, but not runtime calibrated. 161 */ 162#define CHRE_SENSOR_TYPE_UNCALIBRATED_ACCELEROMETER UINT8_C(55) 163 164/** 165 * Accelerometer temperature. 166 * 167 * Generates: CHRE_EVENT_SENSOR_ACCELEROMETER_TEMPERATURE_DATA 168 */ 169#define CHRE_SENSOR_TYPE_ACCELEROMETER_TEMPERATURE UINT8_C(56) 170 171/** 172 * Gyroscope temperature. 173 * 174 * Generates: CHRE_EVENT_SENSOR_GYROSCOPE_TEMPERATURE_DATA 175 */ 176#define CHRE_SENSOR_TYPE_GYROSCOPE_TEMPERATURE UINT8_C(57) 177 178/** 179 * Magnetometer temperature. 180 * 181 * Generates: CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_TEMPERATURE_DATA 182 */ 183#define CHRE_SENSOR_TYPE_GEOMAGNETIC_FIELD_TEMPERATURE UINT8_C(58) 184 185/** 186 * Base value for all of the data events for sensors. 187 * 188 * The value for a data event FOO is 189 * CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_FOO 190 * 191 * This allows for easy mapping, and also explains why there are gaps 192 * in our values since we don't have all possible sensor types assigned. 193 */ 194#define CHRE_EVENT_SENSOR_DATA_EVENT_BASE CHRE_EVENT_SENSOR_FIRST_EVENT 195 196/** 197 * nanoappHandleEvent argument: struct chreSensorThreeAxisData 198 * 199 * The data can be interpreted using the 'x', 'y', and 'z' fields within 200 * 'readings', or by the 3D array 'v' (v[0] == x; v[1] == y; v[2] == z). 201 * 202 * All values are in SI units (m/s^2) and measure the acceleration applied to 203 * the device. 204 */ 205#define CHRE_EVENT_SENSOR_ACCELEROMETER_DATA \ 206 (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_ACCELEROMETER) 207 208/** 209 * nanoappHandleEvent argument: struct chreSensorOccurrenceData 210 * 211 * Since this is a one-shot sensor, after this event is delivered to the 212 * nanoapp, the sensor automatically goes into DONE mode. Sensors of this 213 * type must be configured with a ONE_SHOT mode. 214 */ 215#define CHRE_EVENT_SENSOR_INSTANT_MOTION_DETECT_DATA \ 216 (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_INSTANT_MOTION_DETECT) 217 218/** 219 * nanoappHandleEvent argument: struct chreSensorOccurrenceData 220 * 221 * Since this is a one-shot sensor, after this event is delivered to the 222 * nanoapp, the sensor automatically goes into DONE mode. Sensors of this 223 * type must be configured with a ONE_SHOT mode. 224 */ 225#define CHRE_EVENT_SENSOR_STATIONARY_DETECT_DATA \ 226 (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_STATIONARY_DETECT) 227 228/** 229 * nanoappHandleEvent argument: struct chreSensorThreeAxisData 230 * 231 * The data can be interpreted using the 'x', 'y', and 'z' fields within 232 * 'readings', or by the 3D array 'v' (v[0] == x; v[1] == y; v[2] == z). 233 * 234 * All values are in radians/second and measure the rate of rotation 235 * around the X, Y and Z axis. 236 */ 237#define CHRE_EVENT_SENSOR_GYROSCOPE_DATA \ 238 (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_GYROSCOPE) 239 240/** 241 * nanoappHandleEvent argument: struct chreSensorThreeAxisData 242 * 243 * The data can be interpreted using the 'x', 'y', and 'z' fields within 244 * 'readings', or by the 3D array 'v' (v[0] == x; v[1] == y; v[2] == z). 245 * 246 * All values are in micro-Tesla (uT) and measure the geomagnetic 247 * field in the X, Y and Z axis. 248 */ 249#define CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_DATA \ 250 (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_GEOMAGNETIC_FIELD) 251 252/** 253 * nanoappHandleEvent argument: struct chreSensorFloatData 254 * 255 * The data can be interpreted using the 'pressure' field within 'readings'. 256 * This value is in hectopascals (hPa). 257 */ 258#define CHRE_EVENT_SENSOR_PRESSURE_DATA \ 259 (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_PRESSURE) 260 261/** 262 * nanoappHandleEvent argument: struct chreSensorFloatData 263 * 264 * The data can be interpreted using the 'light' field within 'readings'. 265 * This value is in SI lux units. 266 */ 267#define CHRE_EVENT_SENSOR_LIGHT_DATA \ 268 (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_LIGHT) 269 270/** 271 * nanoappHandleEvent argument: struct chreSensorByteData 272 * 273 * The data is interpreted from the following fields in 'readings': 274 * o 'isNear': If set to 1, we are nearby (on the order of centimeters); 275 * if set to 0, we are far. 276 * o 'invalid': If set to 1, this is not a valid reading of this data. 277 * 278 * As an on-change sensor, there can be an event generated upon configuring 279 * this sensor. This is when we might get an 'invalid' reading. Thus, 280 * this field must be checked on the first event before interpreting 'isNear'. 281 */ 282#define CHRE_EVENT_SENSOR_PROXIMITY_DATA \ 283 (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_PROXIMITY) 284 285/** 286 * nanoappHandleEvent argument: struct chreSensorThreeAxisData 287 * 288 * The data can be interpreted using the 'x', 'y', and 'z' fields within 289 * 'readings', or by the 3D array 'v' (v[0] == x; v[1] == y; v[2] == z). 290 * 291 * All values are in SI units (m/s^2) and measure the acceleration applied to 292 * the device. 293 */ 294#define CHRE_EVENT_SENSOR_UNCALIBRATED_ACCELEROMETER_DATA \ 295 (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_UNCALIBRATED_ACCELEROMETER) 296 297/** 298 * nanoappHandleEvent argument: struct chreSensorThreeAxisData 299 * 300 * The data can be interpreted using the 'x', 'y', and 'z' fields within 301 * 'readings', or by the 3D array 'v' (v[0] == x; v[1] == y; v[2] == z). 302 * 303 * All values are in radians/second and measure the rate of rotation 304 * around the X, Y and Z axis. 305 */ 306#define CHRE_EVENT_SENSOR_UNCALIBRATED_GYROSCOPE_DATA \ 307 (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_UNCALIBRATED_GYROSCOPE) 308 309/** 310 * nanoappHandleEvent argument: struct chreSensorThreeAxisData 311 * 312 * The data can be interpreted using the 'x', 'y', and 'z' fields within 313 * 'readings', or by the 3D array 'v' (v[0] == x; v[1] == y; v[2] == z). 314 * 315 * All values are in micro-Tesla (uT) and measure the geomagnetic 316 * field in the X, Y and Z axis. 317 */ 318#define CHRE_EVENT_SENSOR_UNCALIBRATED_GEOMAGNETIC_FIELD_DATA \ 319 (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_UNCALIBRATED_GEOMAGNETIC_FIELD) 320 321/** 322 * nanoappHandleEvent argument: struct chreSensorFloatData 323 * 324 * The data can be interpreted using the 'temperature' field within 'readings'. 325 * This value is in degrees Celsius. 326 */ 327#define CHRE_EVENT_SENSOR_ACCELEROMETER_TEMPERATURE_DATA \ 328 (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_ACCELEROMETER_TEMPERATURE) 329 330/** 331 * nanoappHandleEvent argument: struct chreSensorFloatData 332 * 333 * The data can be interpreted using the 'temperature' field within 'readings'. 334 * This value is in degrees Celsius. 335 */ 336#define CHRE_EVENT_SENSOR_GYROSCOPE_TEMPERATURE_DATA \ 337 (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_GYROSCOPE_TEMPERATURE) 338 339/** 340 * nanoappHandleEvent argument: struct chreSensorFloatData 341 * 342 * The data can be interpreted using the 'temperature' field within 'readings'. 343 * This value is in degrees Celsius. 344 */ 345#define CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_TEMPERATURE_DATA \ 346 (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_GEOMAGNETIC_FIELD_TEMPERATURE) 347 348/** 349 * First value for sensor events which are not data from the sensor. 350 * 351 * Unlike the data event values, these other event values don't have any 352 * mapping to sensor types. 353 */ 354#define CHRE_EVENT_SENSOR_OTHER_EVENTS_BASE \ 355 (CHRE_EVENT_SENSOR_FIRST_EVENT + 0x0100) 356 357/** 358 * nanoappHandleEvent argument: struct chreSensorSamplingStatusEvent 359 * 360 * Indicates that the interval and/or the latency which this sensor is 361 * sampling at has changed. 362 */ 363#define CHRE_EVENT_SENSOR_SAMPLING_CHANGE \ 364 (CHRE_EVENT_SENSOR_OTHER_EVENTS_BASE + 0) 365 366/** 367 * nanoappHandleEvent argument: struct chreSensorThreeAxisData 368 * 369 * The data can be interpreted using the 'x_bias', 'y_bias', and 'z_bias' 370 * field within 'readings', or by the 3D array 'bias' (bias[0] == x_bias; 371 * bias[1] == y_bias; bias[2] == z_bias). 372 * 373 * All values are in radians/second and measure the rate of rotation 374 * around the X, Y and Z axis. 375 */ 376#define CHRE_EVENT_SENSOR_GYROSCOPE_BIAS_INFO \ 377 (CHRE_EVENT_SENSOR_OTHER_EVENTS_BASE + 1) 378 379/** 380 * nanoappHandleEvent argument: struct chreSensorThreeAxisData 381 * 382 * The data can be interpreted using the 'x_bias', 'y_bias', and 'z_bias' 383 * field within 'readings', or by the 3D array 'bias' (bias[0] == x_bias; 384 * bias[1] == y_bias; bias[2] == z_bias). 385 * 386 * All values are in micro-Tesla (uT) and measure the geomagnetic 387 * field in the X, Y and Z axis. 388 */ 389#define CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_BIAS_INFO \ 390 (CHRE_EVENT_SENSOR_OTHER_EVENTS_BASE + 2) 391 392 393#if CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_BIAS_INFO > CHRE_EVENT_SENSOR_LAST_EVENT 394#error Too many sensor events. 395#endif 396 397 398/** 399 * Value indicating we want the smallest possible latency for a sensor. 400 * 401 * This literally translates to 0 nanoseconds for the chreSensorConfigure() 402 * argument. While we won't get exactly 0 nanoseconds, the CHRE will 403 * queue up this event As Soon As Possible. 404 */ 405#define CHRE_SENSOR_LATENCY_ASAP UINT64_C(0) 406 407/** 408 * Special value indicating non-importance, or non-applicability of the sampling 409 * interval. 410 * 411 * @see chreSensorConfigure 412 * @see chreSensorSamplingStatus 413 */ 414#define CHRE_SENSOR_INTERVAL_DEFAULT UINT64_C(-1) 415 416/** 417 * Special value indicating non-importance of the latency. 418 * 419 * @see chreSensorConfigure 420 * @see chreSensorSamplingStatus 421 */ 422#define CHRE_SENSOR_LATENCY_DEFAULT UINT64_C(-1) 423 424/** 425 * Special value indicating non-importance of the batch interval. 426 * 427 * @see chreSensorConfigureWithBatchInterval 428 */ 429#define CHRE_SENSOR_BATCH_INTERVAL_DEFAULT UINT64_C(-1) 430 431// This is used to define elements of enum chreSensorConfigureMode. 432#define CHRE_SENSOR_CONFIGURE_RAW_POWER_ON (1 << 0) 433 434// This is used to define elements of enum chreSensorConfigureMode. 435#define CHRE_SENSOR_CONFIGURE_RAW_REPORT_CONTINUOUS (1 << 1) 436 437// This is used to define elements of enum chreSensorConfigureMode. 438#define CHRE_SENSOR_CONFIGURE_RAW_REPORT_ONE_SHOT (2 << 1) 439 440 441/** 442 * Modes we can configure a sensor to use. 443 * 444 * Our mode will affect not only how/if we receive events, but 445 * also whether or not the sensor will be powered on our behalf. 446 * 447 * @see chreSensorConfigure 448 */ 449enum chreSensorConfigureMode { 450 /** 451 * Get events from the sensor. 452 * 453 * Power: Turn on if not already on. 454 * Reporting: Continuous. Send each new event as it comes (subject to 455 * batching and latency). 456 */ 457 CHRE_SENSOR_CONFIGURE_MODE_CONTINUOUS = 458 (CHRE_SENSOR_CONFIGURE_RAW_POWER_ON | 459 CHRE_SENSOR_CONFIGURE_RAW_REPORT_CONTINUOUS), 460 461 /** 462 * Get a single event from the sensor and then become DONE. 463 * 464 * Once the event is sent, the sensor automatically 465 * changes to CHRE_SENSOR_CONFIGURE_MODE_DONE mode. 466 * 467 * Power: Turn on if not already on. 468 * Reporting: One shot. Send the next event and then be DONE. 469 */ 470 CHRE_SENSOR_CONFIGURE_MODE_ONE_SHOT = 471 (CHRE_SENSOR_CONFIGURE_RAW_POWER_ON | 472 CHRE_SENSOR_CONFIGURE_RAW_REPORT_ONE_SHOT), 473 474 /** 475 * Get events from a sensor that are generated for other apps. 476 * 477 * This is considered passive because the sensor will not be powered 478 * on for the sake of our nanoapp. If and only if another app in 479 * the system has requested this sensor power on will we get events. 480 * 481 * This can be useful for something which is interested in seeing data, 482 * but not interested enough to be responsible for powering on the sensor. 483 * 484 * Power: Do not power the sensor on our behalf. 485 * Reporting: Continuous. Send each event as it comes. 486 */ 487 CHRE_SENSOR_CONFIGURE_MODE_PASSIVE_CONTINUOUS = 488 CHRE_SENSOR_CONFIGURE_RAW_REPORT_CONTINUOUS, 489 490 /** 491 * Get a single event from a sensor that is generated for other apps. 492 * 493 * See CHRE_SENSOR_CONFIGURE_MODE_PASSIVE_CONTINUOUS for more details 494 * on what be "passive" means. 495 * 496 * Power: Do not power the sensor on our behalf. 497 * Reporting: One shot. Send only the next event and then be DONE. 498 */ 499 CHRE_SENSOR_CONFIGURE_MODE_PASSIVE_ONE_SHOT = 500 CHRE_SENSOR_CONFIGURE_RAW_REPORT_ONE_SHOT, 501 502 /** 503 * Indicate we are done using this sensor and no longer interested in it. 504 * 505 * See chreSensorConfigure for more details on expressing interest or 506 * lack of interest in a sensor. 507 * 508 * Power: Do not power the sensor on our behalf. 509 * Reporting: None. 510 */ 511 CHRE_SENSOR_CONFIGURE_MODE_DONE = 0, 512}; 513 514/** 515 * A structure containing information about a Sensor. 516 * 517 * See documentation of individual fields below. 518 */ 519struct chreSensorInfo { 520 /** 521 * The name of the sensor. 522 * 523 * A text name, useful for logging/debugging, describing the Sensor. This 524 * is not assured to be unique (i.e. there could be multiple sensors with 525 * the name "Temperature"). 526 * 527 * CHRE implementations may not set this as NULL. An empty 528 * string, while discouraged, is legal. 529 */ 530 const char *sensorName; 531 532 /** 533 * One of the CHRE_SENSOR_TYPE_* defines above. 534 */ 535 uint8_t sensorType; 536 537 /** 538 * Flag indicating if this sensor is on-change. 539 * 540 * An on-change sensor only generates events when underlying state 541 * changes. This has the same meaning as on-change does in the Android 542 * Sensors HAL. See sensors.h for much more details. 543 * 544 * A value of 1 indicates this is on-change. 0 indicates this is not 545 * on-change. 546 */ 547 uint8_t isOnChange : 1; 548 549 /** 550 * Flag indicating if this sensor is one-shot. 551 * 552 * A one-shot sensor only triggers a single event, and then automatically 553 * disables itself. 554 * 555 * A value of 1 indicates this is one-shot. 0 indicates this is not 556 * on-change. 557 */ 558 uint8_t isOneShot : 1; 559 uint8_t unusedFlags : 6; 560 561 /** 562 * The minimum sampling interval supported by this sensor, in nanoseconds. 563 * 564 * Requests to chreSensorConfigure with a lower interval than this will 565 * fail. If the sampling interval is not applicable to this sensor, this 566 * will be set to CHRE_SENSOR_INTERVAL_DEFAULT. 567 * 568 * This field will be set to 0 when running on CHRE API versions prior to 569 * v1.1, indicating that the minimum interval is not known. 570 * 571 * @since v1.1 572 */ 573 uint64_t minInterval; 574}; 575 576/** 577 * Header used in every structure containing batchable data from a sensor. 578 * 579 * The typical structure for sensor data looks like: 580 * 581 * struct chreSensorTypeData { 582 * struct chreSensorDataHeader header; 583 * struct chreSensorTypeSampleData { 584 * uint32_t timestampDelta; 585 * union { 586 * <type> value; 587 * <type> interpretation0; 588 * <type> interpretation1; 589 * }; 590 * } readings[1]; 591 * }; 592 * 593 * Despite 'readings' being declared as an array of 1 element, 594 * an instance of the struct will actually have 'readings' as 595 * an array of header.readingCount elements (which may be 1). 596 * The 'timestampDelta' is in relation to the previous 'readings' (or 597 * the baseTimestamp for readings[0]. So, 598 * Timestamp for readings[0] == header.baseTimestamp + 599 * readings[0].timestampDelta. 600 * Timestamp for readings[1] == timestamp for readings[0] + 601 * readings[1].timestampDelta. 602 * And thus, in order to determine the timestamp for readings[N], it's 603 * necessary to process through all of the N-1 readings. The advantage, 604 * though, is that our entire readings can span an arbitrary length of time, 605 * just as long as any two consecutive readings differ by no more than 606 * 4.295 seconds (timestampDelta, like all time in the CHRE, is in 607 * nanoseconds). 608 * 609 * If a sensor has batched readings where two consecutive readings differ by 610 * more than 4.295 seconds, the CHRE will split them across multiple 611 * instances of the struct, and send multiple events. 612 * 613 * The value from the sensor is typically expressed in a union, 614 * allowing a generic access to the data ('value'), along with 615 * differently named access giving a more natural interpretation 616 * of the data for the specific sensor types which use this 617 * structure. This allows, for example, barometer code to 618 * reference readings[N].pressure, and an ambient light sensor 619 * to reference readings[N].light, while both use the same 620 * structure. 621 */ 622struct chreSensorDataHeader { 623 /** 624 * The base timestamp, in nanoseconds. 625 */ 626 uint64_t baseTimestamp; 627 628 /** 629 * The handle of the sensor producing this event. 630 */ 631 uint32_t sensorHandle; 632 633 /** 634 * The number elements in the 'readings' array. 635 * 636 * This must be at least 1. 637 */ 638 uint16_t readingCount; 639 640 /** 641 * Reserved bytes. 642 * 643 * These must be 0. 644 */ 645 uint8_t reserved[2]; 646}; 647 648/** 649 * Data for a sensor which reports on three axes. 650 * 651 * This is used by CHRE_EVENT_SENSOR_ACCELEROMETER_DATA, 652 * CHRE_EVENT_SENSOR_UNCALIBRATED_ACCELEROMETER_DATA, 653 * CHRE_EVENT_SENSOR_GYROSCOPE_DATA, 654 * CHRE_EVENT_SENSOR_GYROSCOPE_BIAS_INFO, 655 * CHRE_EVENT_SENSOR_UNCALIBRATED_GYROSCOPE_DATA, 656 * CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_DATA, 657 * CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_BIAS_INFO, and 658 * CHRE_EVENT_SENSOR_UNCALIBRATED_GEOMAGNETIC_FIELD_DATA. 659 */ 660struct chreSensorThreeAxisData { 661 /** 662 * @see chreSensorDataHeader 663 */ 664 struct chreSensorDataHeader header; 665 struct chreSensorThreeAxisSampleData { 666 /** 667 * @see chreSensorDataHeader 668 */ 669 uint32_t timestampDelta; 670 union { 671 float values[3]; 672 float v[3]; 673 struct { 674 float x; 675 float y; 676 float z; 677 }; 678 float bias[3]; 679 struct { 680 float x_bias; 681 float y_bias; 682 float z_bias; 683 }; 684 }; 685 } readings[1]; 686}; 687 688/** 689 * Data from a sensor where we only care about a event occurring. 690 * 691 * This is a bit unusual in that our readings have no data in addition 692 * to the timestamp. But since we only care about the occurrence, we 693 * don't need to know anything else. 694 * 695 * Used by: CHRE_EVENT_SENSOR_INSTANT_MOTION_DETECT_DATA and 696 * CHRE_EVENT_SENSOR_STATIONARY_DETECT_DATA. 697 */ 698struct chreSensorOccurrenceData { 699 struct chreSensorDataHeader header; 700 struct chreSensorOccurrenceSampleData { 701 uint32_t timestampDelta; 702 // This space intentionally left blank. 703 // Only the timestamp is meaningful here, there 704 // is no additional data. 705 } readings[1]; 706}; 707 708/** 709 * This is used by CHRE_EVENT_SENSOR_LIGHT_DATA, 710 * CHRE_EVENT_SENSOR_PRESSURE_DATA, 711 * CHRE_EVENT_SENSOR_ACCELEROMETER_TEMPERATURE_DATA, 712 * CHRE_EVENT_SENSOR_GYROSCOPE_TEMPERATURE_DATA, and 713 * CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_TEMPERATURE_DATA. 714 */ 715struct chreSensorFloatData { 716 struct chreSensorDataHeader header; 717 struct chreSensorFloatSampleData { 718 uint32_t timestampDelta; 719 union { 720 float value; 721 float light; //!< Unit: lux 722 float pressure; //!< Unit: hectopascals (hPa) 723 float temperature; //!< Unit: degrees Celsius 724 }; 725 } readings[1]; 726}; 727 728/** 729 * CHRE_EVENT_SENSOR_PROXIMITY_DATA. 730 */ 731struct chreSensorByteData { 732 struct chreSensorDataHeader header; 733 struct chreSensorByteSampleData { 734 uint32_t timestampDelta; 735 union { 736 uint8_t value; 737 struct { 738 uint8_t isNear : 1; 739 uint8_t invalid : 1; 740 uint8_t padding0 : 6; 741 }; 742 }; 743 } readings[1]; 744}; 745 746/** 747 * The status of a sensor's sampling configuration. 748 */ 749struct chreSensorSamplingStatus { 750 /** 751 * The interval, in nanoseconds, at which the sensor is now sampling. 752 * 753 * If this is CHRE_SENSOR_INTERVAL_DEFAULT, then a sampling interval 754 * isn't meaningful for this sensor. 755 * 756 * Note that if 'enabled' is false, this value is not meaningful. 757 */ 758 uint64_t interval; 759 760 /** 761 * The latency, in nanoseconds, at which the senor is now reporting. 762 * 763 * If this is CHRE_SENSOR_LATENCY_DEFAULT, then a latency 764 * isn't meaningful for this sensor. 765 * 766 * The effective batch interval can be derived from this value by 767 * adding the current sampling interval. 768 * 769 * Note that if 'enabled' is false, this value is not meaningful. 770 */ 771 uint64_t latency; 772 773 /** 774 * True if the sensor is actively powered and sampling; false otherwise. 775 */ 776 bool enabled; 777}; 778 779/** 780 * The nanoappHandleEvent argument for CHRE_EVENT_SENSOR_SAMPLING_CHANGE. 781 * 782 * Note that only at least one of 'interval' or 'latency' must be 783 * different than it was prior to this event. Thus, one of these 784 * fields may be (but doesn't need to be) the same as before. 785 */ 786struct chreSensorSamplingStatusEvent { 787 /** 788 * The handle of the sensor which has experienced a change in sampling. 789 */ 790 uint32_t sensorHandle; 791 792 /** 793 * The new sampling status. 794 * 795 * At least one of the field in this struct will be different from 796 * the previous sampling status event. 797 */ 798 struct chreSensorSamplingStatus status; 799}; 800 801 802/** 803 * Find the default sensor for a given sensor type. 804 * 805 * @param sensorType One of the CHRE_SENSOR_TYPE_* constants. 806 * @param handle If a sensor is found, then the memory will be filled with 807 * the value for the sensor's handle. This argument must be non-NULL. 808 * @returns true if a sensor was found, false otherwise. 809 */ 810bool chreSensorFindDefault(uint8_t sensorType, uint32_t *handle); 811 812/** 813 * Get the chreSensorInfo struct for a given sensor. 814 * 815 * @param sensorHandle The sensor handle, as obtained from 816 * chreSensorFindDefault() or passed to nanoappHandleEvent(). 817 * @param info If the sensor is valid, then this memory will be filled with 818 * the SensorInfo contents for this sensor. This argument must be 819 * non-NULL. 820 * @returns true if the senor handle is valid and 'info' was filled in; 821 * false otherwise. 822 */ 823bool chreGetSensorInfo(uint32_t sensorHandle, struct chreSensorInfo *info); 824 825/** 826 * Get the chreSensorSamplingStatus struct for a given sensor. 827 * 828 * Note that this may be different from what was requested in 829 * chreSensorConfigure(), for multiple reasons. It's possible that the sensor 830 * does not exactly support the interval requested in chreSensorConfigure(), so 831 * a faster one was chosen. 832 * 833 * It's also possible that there is another user of this sensor who has 834 * requested a faster interval and/or lower latency. This latter scenario 835 * should be noted, because it means the sensor rate can change due to no 836 * interaction from this nanoapp. Note that the 837 * CHRE_EVENT_SENSOR_SAMPLING_CHANGE event will trigger in this case, so it's 838 * not necessary to poll for such a change. 839 * 840 * @param sensorHandle The sensor handle, as obtained from 841 * chreSensorFindDefault() or passed to nanoappHandleEvent(). 842 * @param status If the sensor is valid, then this memory will be filled with 843 * the sampling status contents for this sensor. This argument must be 844 * non-NULL. 845 * @returns true if the senor handle is valid and 'status' was filled in; 846 * false otherwise. 847 */ 848bool chreGetSensorSamplingStatus(uint32_t sensorHandle, 849 struct chreSensorSamplingStatus *status); 850 851/** 852 * Configures a given sensor at a specific interval and latency and mode. 853 * 854 * If this sensor's chreSensorInfo has isOneShot set to 1, 855 * then the mode must be one of the ONE_SHOT modes, or this method will fail. 856 * 857 * The CHRE wants to power as few sensors as possible, in keeping with its 858 * low power design. As such, it only turns on sensors when there are clients 859 * actively interested in that sensor data, and turns off sensors as soon as 860 * there are no clients interested in them. Calling this method generally 861 * indicates an interest, and using CHRE_SENSOR_CONFIGURE_MODE_DONE shows 862 * when we are no longer interested. 863 * 864 * Thus, each initial Configure of a sensor (per nanoapp) needs to eventually 865 * have a DONE call made, either directly or on its behalf. Subsequent calls 866 * to a Configure method within the same nanoapp, when there has been no DONE 867 * in between, still only require a single DONE call. 868 * 869 * For example, the following is valid usage: 870 * <code> 871 * chreSensorConfigure(myHandle, mode, interval0, latency0); 872 * [...] 873 * chreSensorConfigure(myHandle, mode, interval1, latency0); 874 * [...] 875 * chreSensorConfigure(myHandle, mode, interval1, latency1); 876 * [...] 877 * chreSensorConfigureModeOnly(myHandle, CHRE_SENSOR_CONFIGURE_MODE_DONE); 878 * </code> 879 * 880 * The first call to Configure is the one which creates the requirement 881 * to eventually call with DONE. The subsequent calls are just changing the 882 * interval/latency. They have not changed the fact that this nanoapp is 883 * still interested in output from the sensor 'myHandle'. Thus, only one 884 * single call for DONE is needed. 885 * 886 * There is a special case. One-shot sensors, sensors which 887 * just trigger a single event and never trigger again, implicitly go into 888 * DONE mode after that single event triggers. Thus, the 889 * following are legitimate usages: 890 * <code> 891 * chreSensorConfigure(myHandle, MODE_ONE_SHOT, interval, latency); 892 * [...] 893 * [myHandle triggers an event] 894 * [no need to configure to DONE]. 895 * </code> 896 * 897 * And: 898 * <code> 899 * chreSensorConfigure(myHandle, MODE_ONE_SHOT, interval, latency); 900 * [...] 901 * chreSensorConfigureModeOnly(myHandle, MODE_DONE); 902 * [we cancelled myHandle before it ever triggered an event] 903 * </code> 904 * 905 * Note that while PASSIVE modes, by definition, don't express 906 * an interest in powering the sensor, DONE is still necessary 907 * to silence the event reporting. 908 * 909 * @param sensorHandle The handle to the sensor, as obtained from 910 * chreSensorFindDefault(). 911 * @param mode The mode to use. See descriptions within the 912 * chreSensorConfigureMode enum. 913 * @param interval The interval, in nanoseconds, at which we want events from 914 * the sensor. On success, the sensor will be set to 'interval', or a value 915 * less than 'interval'. There is a special value 916 * CHRE_SENSOR_INTERVAL_DEFAULT, in which we don't express a preference for 917 * the interval, and allow the sensor to chose what it wants. Note that 918 * due to batching, we may receive events less frequently than 919 * 'interval'. 920 * @param latency The maximum latency, in nanoseconds, allowed before the 921 * CHRE begins delivery of an event. This will control how many events 922 * can be queued by the sensor before requiring a delivery event. 923 * Latency is defined as the "timestamp when event is queued by the CHRE" 924 * minus "timestamp of oldest unsent data reading". 925 * There is a special value CHRE_SENSOR_LATENCY_DEFAULT, in which we don't 926 * express a preference for the latency, and allow the sensor to choose what 927 * it wants. 928 * Note that there is no assurance of how long it will take an event to 929 * get through a CHRE's queueing system, and thus there is no ability to 930 * request a minimum time from the occurrence of a phenomenon to when the 931 * nanoapp receives the information. The current CHRE API has no 932 * real-time elements, although future versions may introduce some to 933 * help with this issue. 934 * @returns true if the configuration succeeded, false otherwise. 935 * 936 * @see chreSensorConfigureMode 937 * @see chreSensorFindDefault 938 * @see chreSensorInfo 939 */ 940bool chreSensorConfigure(uint32_t sensorHandle, 941 enum chreSensorConfigureMode mode, 942 uint64_t interval, uint64_t latency); 943 944/** 945 * Short cut for chreSensorConfigure where we only want to configure the mode 946 * and do not care about interval/latency. 947 * 948 * @see chreSensorConfigure 949 */ 950static inline bool chreSensorConfigureModeOnly( 951 uint32_t sensorHandle, enum chreSensorConfigureMode mode) { 952 return chreSensorConfigure(sensorHandle, 953 mode, 954 CHRE_SENSOR_INTERVAL_DEFAULT, 955 CHRE_SENSOR_LATENCY_DEFAULT); 956} 957 958/** 959 * Convenience function that wraps chreSensorConfigure but enables batching to 960 * be controlled by specifying the desired maximum batch interval rather 961 * than maximum sample latency. Users may find the batch interval to be a more 962 * intuitive method of expressing the desired batching behavior. 963 * 964 * Batch interval is different from latency as the batch interval time is 965 * counted starting when the prior event containing a batch of sensor samples is 966 * delivered, while latency starts counting when the first sample is deferred to 967 * start collecting a batch. In other words, latency ignores the time between 968 * the last sample in a batch to the first sample of the next batch, while it's 969 * included in the batch interval, as illustrated below. 970 * 971 * Time 0 1 2 3 4 5 6 7 8 972 * Batch A B C 973 * Sample a1 a2 a3 b1 b2 b3 c1 c2 c3 974 * Latency [ ] [ ] [ ] 975 * BatchInt | | | 976 * 977 * In the diagram, the effective sample interval is 1 time unit, latency is 2 978 * time units, and batch interval is 3 time units. 979 * 980 * @param sensorHandle See chreSensorConfigure#sensorHandle 981 * @param mode See chreSensorConfigure#mode 982 * @param sampleInterval See chreSensorConfigure#interval, but note that 983 * CHRE_SENSOR_INTERVAL_DEFAULT is not a supported input to this method. 984 * @param batchInterval The desired maximum interval, in nanoseconds, between 985 * CHRE enqueuing each batch of sensor samples. 986 * @return Same as chreSensorConfigure 987 * 988 * @see chreSensorConfigure 989 * 990 * @since v1.1 991 */ 992static inline bool chreSensorConfigureWithBatchInterval( 993 uint32_t sensorHandle, enum chreSensorConfigureMode mode, 994 uint64_t sampleInterval, uint64_t batchInterval) { 995 bool result = false; 996 997 if (sampleInterval != CHRE_SENSOR_INTERVAL_DEFAULT) { 998 uint64_t latency; 999 if (batchInterval == CHRE_SENSOR_BATCH_INTERVAL_DEFAULT) { 1000 latency = CHRE_SENSOR_LATENCY_DEFAULT; 1001 } else if (batchInterval > sampleInterval) { 1002 latency = batchInterval - sampleInterval; 1003 } else { 1004 latency = CHRE_SENSOR_LATENCY_ASAP; 1005 } 1006 result = chreSensorConfigure(sensorHandle, mode, sampleInterval, 1007 latency); 1008 } 1009 1010 return result; 1011} 1012 1013#ifdef __cplusplus 1014} 1015#endif 1016 1017#endif /* _CHRE_SENSOR_H_ */ 1018