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