1 /* 2 * Copyright (C) 2010 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 /** 18 * Structures and functions to receive and process sensor events in 19 * native code. 20 * 21 * @addtogroup Sensor 22 * @{ 23 */ 24 25 /** 26 * @file sensor.h 27 */ 28 29 #ifndef ANDROID_SENSOR_H 30 #define ANDROID_SENSOR_H 31 32 #include <sys/cdefs.h> 33 34 /****************************************************************** 35 * 36 * IMPORTANT NOTICE: 37 * 38 * This file is part of Android's set of stable system headers 39 * exposed by the Android NDK (Native Development Kit). 40 * 41 * Third-party source AND binary code relies on the definitions 42 * here to be FROZEN ON ALL UPCOMING PLATFORM RELEASES. 43 * 44 * - DO NOT MODIFY ENUMS (EXCEPT IF YOU ADD NEW 32-BIT VALUES) 45 * - DO NOT MODIFY CONSTANTS OR FUNCTIONAL MACROS 46 * - DO NOT CHANGE THE SIGNATURE OF FUNCTIONS IN ANY WAY 47 * - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES 48 */ 49 50 #include <android/looper.h> 51 52 #include <stdbool.h> 53 #include <sys/types.h> 54 #include <math.h> 55 #include <stdint.h> 56 57 // This file may also be built on glibc or on Windows/MacOS libc's, so no-op 58 // and deprecated definitions are provided. 59 #if !defined(__INTRODUCED_IN) 60 #define __INTRODUCED_IN(__api_level) /* nothing */ 61 #endif 62 #if !defined(__DEPRECATED_IN) 63 #define __DEPRECATED_IN(__api_level, msg) __attribute__((__deprecated__(msg))) 64 #endif 65 66 #ifdef __cplusplus 67 extern "C" { 68 #endif 69 70 typedef struct AHardwareBuffer AHardwareBuffer; 71 72 #define ASENSOR_RESOLUTION_INVALID (nanf("")) 73 #define ASENSOR_FIFO_COUNT_INVALID (-1) 74 #define ASENSOR_DELAY_INVALID INT32_MIN 75 #define ASENSOR_INVALID (-1) 76 77 /* (Keep in sync with hardware/sensors-base.h and Sensor.java.) */ 78 79 /** 80 * Sensor types. 81 * 82 * See 83 * [android.hardware.SensorEvent#values](https://developer.android.com/reference/android/hardware/SensorEvent.html#values) 84 * for detailed explanations of the data returned for each of these types. 85 */ 86 enum { 87 /** 88 * Invalid sensor type. Returned by {@link ASensor_getType} as error value. 89 */ 90 ASENSOR_TYPE_INVALID = -1, 91 /** 92 * {@link ASENSOR_TYPE_ACCELEROMETER} 93 * reporting-mode: continuous 94 * 95 * All values are in SI units (m/s^2) and measure the acceleration of the 96 * device minus the force of gravity. 97 */ 98 ASENSOR_TYPE_ACCELEROMETER = 1, 99 /** 100 * {@link ASENSOR_TYPE_MAGNETIC_FIELD} 101 * reporting-mode: continuous 102 * 103 * All values are in micro-Tesla (uT) and measure the geomagnetic 104 * field in the X, Y and Z axis. 105 */ 106 ASENSOR_TYPE_MAGNETIC_FIELD = 2, 107 /** 108 * {@link ASENSOR_TYPE_GYROSCOPE} 109 * reporting-mode: continuous 110 * 111 * All values are in radians/second and measure the rate of rotation 112 * around the X, Y and Z axis. 113 */ 114 ASENSOR_TYPE_GYROSCOPE = 4, 115 /** 116 * {@link ASENSOR_TYPE_LIGHT} 117 * reporting-mode: on-change 118 * 119 * The light sensor value is returned in SI lux units. 120 */ 121 ASENSOR_TYPE_LIGHT = 5, 122 /** 123 * {@link ASENSOR_TYPE_PRESSURE} 124 * 125 * The pressure sensor value is returned in hPa (millibar). 126 */ 127 ASENSOR_TYPE_PRESSURE = 6, 128 /** 129 * {@link ASENSOR_TYPE_PROXIMITY} 130 * reporting-mode: on-change 131 * 132 * The proximity sensor which turns the screen off and back on during calls is the 133 * wake-up proximity sensor. Implement wake-up proximity sensor before implementing 134 * a non wake-up proximity sensor. For the wake-up proximity sensor set the flag 135 * SENSOR_FLAG_WAKE_UP. 136 * The value corresponds to the distance to the nearest object in centimeters. 137 */ 138 ASENSOR_TYPE_PROXIMITY = 8, 139 /** 140 * {@link ASENSOR_TYPE_GRAVITY} 141 * 142 * All values are in SI units (m/s^2) and measure the direction and 143 * magnitude of gravity. When the device is at rest, the output of 144 * the gravity sensor should be identical to that of the accelerometer. 145 */ 146 ASENSOR_TYPE_GRAVITY = 9, 147 /** 148 * {@link ASENSOR_TYPE_LINEAR_ACCELERATION} 149 * reporting-mode: continuous 150 * 151 * All values are in SI units (m/s^2) and measure the acceleration of the 152 * device not including the force of gravity. 153 */ 154 ASENSOR_TYPE_LINEAR_ACCELERATION = 10, 155 /** 156 * {@link ASENSOR_TYPE_ROTATION_VECTOR} 157 */ 158 ASENSOR_TYPE_ROTATION_VECTOR = 11, 159 /** 160 * {@link ASENSOR_TYPE_RELATIVE_HUMIDITY} 161 * 162 * The relative humidity sensor value is returned in percent. 163 */ 164 ASENSOR_TYPE_RELATIVE_HUMIDITY = 12, 165 /** 166 * {@link ASENSOR_TYPE_AMBIENT_TEMPERATURE} 167 * 168 * The ambient temperature sensor value is returned in Celcius. 169 */ 170 ASENSOR_TYPE_AMBIENT_TEMPERATURE = 13, 171 /** 172 * {@link ASENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED} 173 */ 174 ASENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED = 14, 175 /** 176 * {@link ASENSOR_TYPE_GAME_ROTATION_VECTOR} 177 */ 178 ASENSOR_TYPE_GAME_ROTATION_VECTOR = 15, 179 /** 180 * {@link ASENSOR_TYPE_GYROSCOPE_UNCALIBRATED} 181 */ 182 ASENSOR_TYPE_GYROSCOPE_UNCALIBRATED = 16, 183 /** 184 * {@link ASENSOR_TYPE_SIGNIFICANT_MOTION} 185 */ 186 ASENSOR_TYPE_SIGNIFICANT_MOTION = 17, 187 /** 188 * {@link ASENSOR_TYPE_STEP_DETECTOR} 189 */ 190 ASENSOR_TYPE_STEP_DETECTOR = 18, 191 /** 192 * {@link ASENSOR_TYPE_STEP_COUNTER} 193 */ 194 ASENSOR_TYPE_STEP_COUNTER = 19, 195 /** 196 * {@link ASENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR} 197 */ 198 ASENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR = 20, 199 /** 200 * {@link ASENSOR_TYPE_HEART_RATE} 201 */ 202 ASENSOR_TYPE_HEART_RATE = 21, 203 /** 204 * {@link ASENSOR_TYPE_POSE_6DOF} 205 */ 206 ASENSOR_TYPE_POSE_6DOF = 28, 207 /** 208 * {@link ASENSOR_TYPE_STATIONARY_DETECT} 209 */ 210 ASENSOR_TYPE_STATIONARY_DETECT = 29, 211 /** 212 * {@link ASENSOR_TYPE_MOTION_DETECT} 213 */ 214 ASENSOR_TYPE_MOTION_DETECT = 30, 215 /** 216 * {@link ASENSOR_TYPE_HEART_BEAT} 217 */ 218 ASENSOR_TYPE_HEART_BEAT = 31, 219 /** 220 * A constant describing a dynamic sensor meta event sensor. 221 * 222 * A sensor event of this type is received when a dynamic sensor is added to or removed from 223 * the system. This sensor type should always use special trigger report mode. 224 */ 225 ASENSOR_TYPE_DYNAMIC_SENSOR_META = 32, 226 /** 227 * This sensor type is for delivering additional sensor information aside 228 * from sensor event data. 229 * 230 * Additional information may include: 231 * - {@link ASENSOR_ADDITIONAL_INFO_INTERNAL_TEMPERATURE} 232 * - {@link ASENSOR_ADDITIONAL_INFO_SAMPLING} 233 * - {@link ASENSOR_ADDITIONAL_INFO_SENSOR_PLACEMENT} 234 * - {@link ASENSOR_ADDITIONAL_INFO_UNTRACKED_DELAY} 235 * - {@link ASENSOR_ADDITIONAL_INFO_VEC3_CALIBRATION} 236 * 237 * This type will never bind to a sensor. In other words, no sensor in the 238 * sensor list can have the type {@link ASENSOR_TYPE_ADDITIONAL_INFO}. 239 * 240 * If a device supports the sensor additional information feature, it will 241 * report additional information events via {@link ASensorEvent} and will 242 * have the type of {@link ASensorEvent} set to 243 * {@link ASENSOR_TYPE_ADDITIONAL_INFO} and the sensor of {@link ASensorEvent} set 244 * to the handle of the reporting sensor. 245 * 246 * Additional information reports consist of multiple frames ordered by 247 * {@link ASensorEvent#timestamp}. The first frame in the report will have 248 * a {@link AAdditionalInfoEvent#type} of 249 * {@link ASENSOR_ADDITIONAL_INFO_BEGIN}, and the last frame in the report 250 * will have a {@link AAdditionalInfoEvent#type} of 251 * {@link ASENSOR_ADDITIONAL_INFO_END}. 252 * 253 */ 254 ASENSOR_TYPE_ADDITIONAL_INFO = 33, 255 /** 256 * {@link ASENSOR_TYPE_LOW_LATENCY_OFFBODY_DETECT} 257 */ 258 ASENSOR_TYPE_LOW_LATENCY_OFFBODY_DETECT = 34, 259 /** 260 * {@link ASENSOR_TYPE_ACCELEROMETER_UNCALIBRATED} 261 */ 262 ASENSOR_TYPE_ACCELEROMETER_UNCALIBRATED = 35, 263 /** 264 * {@link ASENSOR_TYPE_HINGE_ANGLE} 265 * reporting-mode: on-change 266 * 267 * The hinge angle sensor value is returned in degrees. 268 */ 269 ASENSOR_TYPE_HINGE_ANGLE = 36, 270 /** 271 * {@link ASENSOR_TYPE_HEAD_TRACKER} 272 * reporting-mode: continuous 273 * 274 * Measures the orientation and rotational velocity of a user's head. Only for internal use 275 * within the Android system. 276 */ 277 ASENSOR_TYPE_HEAD_TRACKER = 37, 278 /** 279 * {@link ASENSOR_TYPE_ACCELEROMETER_LIMITED_AXES} 280 * reporting-mode: continuous 281 * 282 * The first three values are in SI units (m/s^2) and measure the acceleration of the device 283 * minus the force of gravity. The last three values indicate which acceleration axes are 284 * supported. A value of 1.0 means supported and a value of 0 means not supported. 285 */ 286 ASENSOR_TYPE_ACCELEROMETER_LIMITED_AXES = 38, 287 /** 288 * {@link ASENSOR_TYPE_GYROSCOPE_LIMITED_AXES} 289 * reporting-mode: continuous 290 * 291 * The first three values are in radians/second and measure the rate of rotation around the X, 292 * Y and Z axis. The last three values indicate which rotation axes are supported. A value of 293 * 1.0 means supported and a value of 0 means not supported. 294 */ 295 ASENSOR_TYPE_GYROSCOPE_LIMITED_AXES = 39, 296 /** 297 * {@link ASENSOR_TYPE_ACCELEROMETER_LIMITED_AXES_UNCALIBRATED} 298 * reporting-mode: continuous 299 * 300 * The first three values are in SI units (m/s^2) and measure the acceleration of the device 301 * minus the force of gravity. The middle three values represent the estimated bias for each 302 * axis. The last three values indicate which acceleration axes are supported. A value of 1.0 303 * means supported and a value of 0 means not supported. 304 */ 305 ASENSOR_TYPE_ACCELEROMETER_LIMITED_AXES_UNCALIBRATED = 40, 306 /** 307 * {@link ASENSOR_TYPE_GYROSCOPE_LIMITED_AXES_UNCALIBRATED} 308 * reporting-mode: continuous 309 * 310 * The first three values are in radians/second and measure the rate of rotation around the X, 311 * Y and Z axis. The middle three values represent the estimated drift around each axis in 312 * rad/s. The last three values indicate which rotation axes are supported. A value of 1.0 means 313 * supported and a value of 0 means not supported. 314 */ 315 ASENSOR_TYPE_GYROSCOPE_LIMITED_AXES_UNCALIBRATED = 41, 316 /** 317 * {@link ASENSOR_TYPE_HEADING} 318 * reporting-mode: continuous 319 * 320 * A heading sensor measures the direction in which the device is pointing 321 * relative to true north in degrees. 322 */ 323 ASENSOR_TYPE_HEADING = 42, 324 }; 325 326 /** 327 * Sensor accuracy measure. 328 */ 329 enum { 330 /** no contact */ 331 ASENSOR_STATUS_NO_CONTACT = -1, 332 /** unreliable */ 333 ASENSOR_STATUS_UNRELIABLE = 0, 334 /** low accuracy */ 335 ASENSOR_STATUS_ACCURACY_LOW = 1, 336 /** medium accuracy */ 337 ASENSOR_STATUS_ACCURACY_MEDIUM = 2, 338 /** high accuracy */ 339 ASENSOR_STATUS_ACCURACY_HIGH = 3 340 }; 341 342 /** 343 * Sensor Reporting Modes. 344 */ 345 enum { 346 /** invalid reporting mode */ 347 AREPORTING_MODE_INVALID = -1, 348 /** continuous reporting */ 349 AREPORTING_MODE_CONTINUOUS = 0, 350 /** reporting on change */ 351 AREPORTING_MODE_ON_CHANGE = 1, 352 /** on shot reporting */ 353 AREPORTING_MODE_ONE_SHOT = 2, 354 /** special trigger reporting */ 355 AREPORTING_MODE_SPECIAL_TRIGGER = 3 356 }; 357 358 /** 359 * Sensor Direct Report Rates. 360 */ 361 enum { 362 /** stopped */ 363 ASENSOR_DIRECT_RATE_STOP = 0, 364 /** nominal 50Hz */ 365 ASENSOR_DIRECT_RATE_NORMAL = 1, 366 /** nominal 200Hz */ 367 ASENSOR_DIRECT_RATE_FAST = 2, 368 /** nominal 800Hz */ 369 ASENSOR_DIRECT_RATE_VERY_FAST = 3 370 }; 371 372 /** 373 * Sensor Direct Channel Type. 374 */ 375 enum { 376 /** shared memory created by ASharedMemory_create */ 377 ASENSOR_DIRECT_CHANNEL_TYPE_SHARED_MEMORY = 1, 378 /** AHardwareBuffer */ 379 ASENSOR_DIRECT_CHANNEL_TYPE_HARDWARE_BUFFER = 2 380 }; 381 382 /** 383 * Sensor Additional Info Types. 384 * 385 * Used to populate {@link AAdditionalInfoEvent#type}. 386 */ 387 enum { 388 /** Marks the beginning of additional information frames */ 389 ASENSOR_ADDITIONAL_INFO_BEGIN = 0, 390 391 /** Marks the end of additional information frames */ 392 ASENSOR_ADDITIONAL_INFO_END = 1, 393 394 /** 395 * Estimation of the delay that is not tracked by sensor timestamps. This 396 * includes delay introduced by sensor front-end filtering, data transport, 397 * etc. 398 * float[2]: delay in seconds, standard deviation of estimated value 399 */ 400 ASENSOR_ADDITIONAL_INFO_UNTRACKED_DELAY = 0x10000, 401 402 /** float: Celsius temperature */ 403 ASENSOR_ADDITIONAL_INFO_INTERNAL_TEMPERATURE, 404 405 /** 406 * First three rows of a homogeneous matrix, which represents calibration to 407 * a three-element vector raw sensor reading. 408 * float[12]: 3x4 matrix in row major order 409 */ 410 ASENSOR_ADDITIONAL_INFO_VEC3_CALIBRATION, 411 412 /** 413 * Location and orientation of sensor element in the device frame: origin is 414 * the geometric center of the mobile device screen surface; the axis 415 * definition corresponds to Android sensor definitions. 416 * float[12]: 3x4 matrix in row major order 417 */ 418 ASENSOR_ADDITIONAL_INFO_SENSOR_PLACEMENT, 419 420 /** 421 * float[2]: raw sample period in seconds, 422 * standard deviation of sampling period 423 */ 424 ASENSOR_ADDITIONAL_INFO_SAMPLING, 425 }; 426 427 /* 428 * A few useful constants 429 */ 430 431 /** Earth's gravity in m/s^2 */ 432 #define ASENSOR_STANDARD_GRAVITY (9.80665f) 433 /** Maximum magnetic field on Earth's surface in uT */ 434 #define ASENSOR_MAGNETIC_FIELD_EARTH_MAX (60.0f) 435 /** Minimum magnetic field on Earth's surface in uT*/ 436 #define ASENSOR_MAGNETIC_FIELD_EARTH_MIN (30.0f) 437 438 /** 439 * A sensor event. 440 */ 441 442 /* NOTE: changes to these structs have to be backward compatible */ 443 typedef struct ASensorVector { 444 union { 445 float v[3]; 446 struct { 447 float x; 448 float y; 449 float z; 450 }; 451 struct { 452 float azimuth; 453 float pitch; 454 float roll; 455 }; 456 }; 457 int8_t status; 458 uint8_t reserved[3]; 459 } ASensorVector; 460 461 typedef struct AMetaDataEvent { 462 int32_t what; 463 int32_t sensor; 464 } AMetaDataEvent; 465 466 typedef struct AUncalibratedEvent { 467 union { 468 float uncalib[3]; 469 struct { 470 float x_uncalib; 471 float y_uncalib; 472 float z_uncalib; 473 }; 474 }; 475 union { 476 float bias[3]; 477 struct { 478 float x_bias; 479 float y_bias; 480 float z_bias; 481 }; 482 }; 483 } AUncalibratedEvent; 484 485 typedef struct AHeartRateEvent { 486 float bpm; 487 int8_t status; 488 } AHeartRateEvent; 489 490 typedef struct ADynamicSensorEvent { 491 int32_t connected; 492 int32_t handle; 493 } ADynamicSensorEvent; 494 495 typedef struct AAdditionalInfoEvent { 496 /** 497 * Event type, such as ASENSOR_ADDITIONAL_INFO_BEGIN, ASENSOR_ADDITIONAL_INFO_END and others. 498 * Refer to {@link ASENSOR_TYPE_ADDITIONAL_INFO} for the expected reporting behavior. 499 */ 500 int32_t type; 501 int32_t serial; 502 union { 503 int32_t data_int32[14]; 504 float data_float[14]; 505 }; 506 } AAdditionalInfoEvent; 507 508 typedef struct AHeadTrackerEvent { 509 /** 510 * The fields rx, ry, rz are an Euler vector (rotation vector, i.e. a vector 511 * whose direction indicates the axis of rotation and magnitude indicates 512 * the angle to rotate around that axis) representing the transform from 513 * the (arbitrary, possibly slowly drifting) reference frame to the 514 * head frame. Expressed in radians. Magnitude of the vector must be 515 * in the range [0, pi], while the value of individual axes are 516 * in the range [-pi, pi]. 517 */ 518 float rx; 519 float ry; 520 float rz; 521 522 /** 523 * The fields vx, vy, vz are an Euler vector (rotation vector) representing 524 * the angular velocity of the head (relative to itself), in radians per 525 * second. The direction of this vector indicates the axis of rotation, and 526 * the magnitude indicates the rate of rotation. 527 */ 528 float vx; 529 float vy; 530 float vz; 531 532 /** 533 * This value changes each time the reference frame is suddenly and 534 * significantly changed, for example if an orientation filter algorithm 535 * used for determining the orientation has had its state reset. 536 */ 537 int32_t discontinuity_count; 538 } AHeadTrackerEvent; 539 540 typedef struct ALimitedAxesImuEvent { 541 union { 542 float calib[3]; 543 struct { 544 float x; 545 float y; 546 float z; 547 }; 548 }; 549 union { 550 float supported[3]; 551 struct { 552 float x_supported; 553 float y_supported; 554 float z_supported; 555 }; 556 }; 557 } ALimitedAxesImuEvent; 558 559 typedef struct ALimitedAxesImuUncalibratedEvent { 560 union { 561 float uncalib[3]; 562 struct { 563 float x_uncalib; 564 float y_uncalib; 565 float z_uncalib; 566 }; 567 }; 568 union { 569 float bias[3]; 570 struct { 571 float x_bias; 572 float y_bias; 573 float z_bias; 574 }; 575 }; 576 union { 577 float supported[3]; 578 struct { 579 float x_supported; 580 float y_supported; 581 float z_supported; 582 }; 583 }; 584 } ALimitedAxesImuUncalibratedEvent; 585 586 typedef struct AHeadingEvent { 587 /** 588 * The direction in which the device is pointing relative to true north in 589 * degrees. The value must be between 0.0 (inclusive) and 360.0 (exclusive), 590 * with 0 indicating north, 90 east, 180 south, and 270 west. 591 */ 592 float heading; 593 /** 594 * Accuracy is defined at 68% confidence. In the case where the underlying 595 * distribution is assumed Gaussian normal, this would be considered one 596 * standard deviation. For example, if the heading returns 60 degrees, and 597 * accuracy returns 10 degrees, then there is a 68 percent probability of 598 * the true heading being between 50 degrees and 70 degrees. 599 */ 600 float accuracy; 601 } AHeadingEvent; 602 603 // LINT.IfChange 604 /** 605 * Information that describes a sensor event, refer to 606 * <a href="/reference/android/hardware/SensorEvent">SensorEvent</a> for additional 607 * documentation. 608 * 609 * NOTE: changes to this struct has to be backward compatible and reflected in 610 * sensors_event_t 611 */ 612 typedef struct ASensorEvent { 613 /* sizeof(struct ASensorEvent) */ 614 int32_t version; 615 /** The sensor that generates this event */ 616 int32_t sensor; 617 /** Sensor type for the event, such as {@link ASENSOR_TYPE_ACCELEROMETER} */ 618 int32_t type; 619 /** do not use */ 620 int32_t reserved0; 621 /** 622 * The time in nanoseconds at which the event happened, and its behavior 623 * is identical to <a href="/reference/android/hardware/SensorEvent#timestamp"> 624 * SensorEvent::timestamp</a> in Java API. 625 */ 626 int64_t timestamp; 627 union { 628 union { 629 float data[16]; 630 ASensorVector vector; 631 ASensorVector acceleration; 632 ASensorVector gyro; 633 ASensorVector magnetic; 634 float temperature; 635 float distance; 636 float light; 637 float pressure; 638 float relative_humidity; 639 AUncalibratedEvent uncalibrated_acceleration; 640 AUncalibratedEvent uncalibrated_gyro; 641 AUncalibratedEvent uncalibrated_magnetic; 642 AMetaDataEvent meta_data; 643 AHeartRateEvent heart_rate; 644 ADynamicSensorEvent dynamic_sensor_meta; 645 AAdditionalInfoEvent additional_info; 646 AHeadTrackerEvent head_tracker; 647 ALimitedAxesImuEvent limited_axes_imu; 648 ALimitedAxesImuUncalibratedEvent limited_axes_imu_uncalibrated; 649 AHeadingEvent heading; 650 }; 651 union { 652 uint64_t data[8]; 653 uint64_t step_counter; 654 } u64; 655 }; 656 657 uint32_t flags; 658 int32_t reserved1[3]; 659 } ASensorEvent; 660 // LINT.ThenChange(hardware/libhardware/include/hardware/sensors.h) 661 662 struct ASensorManager; 663 /** 664 * {@link ASensorManager} is an opaque type to manage sensors and 665 * events queues. 666 * 667 * {@link ASensorManager} is a singleton that can be obtained using 668 * ASensorManager_getInstance(). 669 * 670 * This file provides a set of functions that uses {@link 671 * ASensorManager} to access and list hardware sensors, and 672 * create and destroy event queues: 673 * - ASensorManager_getSensorList() 674 * - ASensorManager_getDefaultSensor() 675 * - ASensorManager_getDefaultSensorEx() 676 * - ASensorManager_createEventQueue() 677 * - ASensorManager_destroyEventQueue() 678 */ 679 typedef struct ASensorManager ASensorManager; 680 681 682 struct ASensorEventQueue; 683 /** 684 * {@link ASensorEventQueue} is an opaque type that provides access to 685 * {@link ASensorEvent} from hardware sensors. 686 * 687 * A new {@link ASensorEventQueue} can be obtained using ASensorManager_createEventQueue(). 688 * 689 * This file provides a set of functions to enable and disable 690 * sensors, check and get events, and set event rates on a {@link 691 * ASensorEventQueue}. 692 * - ASensorEventQueue_enableSensor() 693 * - ASensorEventQueue_disableSensor() 694 * - ASensorEventQueue_hasEvents() 695 * - ASensorEventQueue_getEvents() 696 * - ASensorEventQueue_setEventRate() 697 * - ASensorEventQueue_requestAdditionalInfoEvents() 698 */ 699 typedef struct ASensorEventQueue ASensorEventQueue; 700 701 struct ASensor; 702 /** 703 * {@link ASensor} is an opaque type that provides information about 704 * an hardware sensors. 705 * 706 * A {@link ASensor} pointer can be obtained using 707 * ASensorManager_getDefaultSensor(), 708 * ASensorManager_getDefaultSensorEx() or from a {@link ASensorList}. 709 * 710 * This file provides a set of functions to access properties of a 711 * {@link ASensor}: 712 * - ASensor_getName() 713 * - ASensor_getVendor() 714 * - ASensor_getType() 715 * - ASensor_getResolution() 716 * - ASensor_getMinDelay() 717 * - ASensor_getFifoMaxEventCount() 718 * - ASensor_getFifoReservedEventCount() 719 * - ASensor_getStringType() 720 * - ASensor_getReportingMode() 721 * - ASensor_isWakeUpSensor() 722 * - ASensor_getHandle() 723 */ 724 typedef struct ASensor ASensor; 725 /** 726 * {@link ASensorRef} is a type for constant pointers to {@link ASensor}. 727 * 728 * This is used to define entry in {@link ASensorList} arrays. 729 */ 730 typedef ASensor const* ASensorRef; 731 /** 732 * {@link ASensorList} is an array of reference to {@link ASensor}. 733 * 734 * A {@link ASensorList} can be initialized using ASensorManager_getSensorList(). 735 */ 736 typedef ASensorRef const* ASensorList; 737 738 /*****************************************************************************/ 739 740 /** 741 * Get a reference to the sensor manager. ASensorManager is a singleton 742 * per package as different packages may have access to different sensors. 743 * 744 * Deprecated: Use ASensorManager_getInstanceForPackage(const char*) instead. 745 * 746 * Example: 747 * 748 * ASensorManager* sensorManager = ASensorManager_getInstance(); 749 * 750 */ 751 ASensorManager* ASensorManager_getInstance() 752 __DEPRECATED_IN(26, "Use ASensorManager_getInstanceForPackage instead"); 753 754 /** 755 * Get a reference to the sensor manager. ASensorManager is a singleton 756 * per package as different packages may have access to different sensors. 757 * 758 * Example: 759 * 760 * ASensorManager* sensorManager = ASensorManager_getInstanceForPackage("foo.bar.baz"); 761 * 762 * Available since API level 26. 763 */ 764 ASensorManager* ASensorManager_getInstanceForPackage(const char* packageName) __INTRODUCED_IN(26); 765 766 /** 767 * Returns the list of available sensors. The returned list is owned by the 768 * sensor manager and will not change between calls to this function. 769 * 770 * \param manager the {@link ASensorManager} instance obtained from 771 * {@link ASensorManager_getInstanceForPackage}. 772 * \param list the returned list of sensors. 773 * \return positive number of returned sensors or negative error code. 774 * BAD_VALUE: manager is NULL. 775 */ 776 int ASensorManager_getSensorList(ASensorManager* manager, ASensorList* list); 777 778 /** 779 * Returns the list of available dynamic sensors. If there are no dynamic 780 * sensors available, returns nullptr in list. 781 * 782 * Each time this is called, the previously returned list is deallocated and 783 * must no longer be used. 784 * 785 * Clients should call this if they receive a sensor update from 786 * {@link ASENSOR_TYPE_DYNAMIC_SENSOR_META} indicating the sensors have changed. 787 * If this happens, previously received lists from this method will be stale. 788 * 789 * Available since API level 33. 790 * 791 * \param manager the {@link ASensorManager} instance obtained from 792 * {@link ASensorManager_getInstanceForPackage}. 793 * \param list the returned list of dynamic sensors. 794 * \return positive number of returned sensors or negative error code. 795 * BAD_VALUE: manager is NULL. 796 */ 797 ssize_t ASensorManager_getDynamicSensorList( 798 ASensorManager* manager, ASensorList* list) __INTRODUCED_IN(33); 799 800 /** 801 * Returns the default sensor for the given type, or NULL if no sensor 802 * of that type exists. 803 */ 804 ASensor const* ASensorManager_getDefaultSensor(ASensorManager* manager, int type); 805 806 /** 807 * Returns the default sensor with the given type and wakeUp properties or NULL if no sensor 808 * of this type and wakeUp properties exists. 809 * 810 * Available since API level 21. 811 */ 812 ASensor const* ASensorManager_getDefaultSensorEx(ASensorManager* manager, int type, bool wakeUp) __INTRODUCED_IN(21); 813 814 /** 815 * Creates a new sensor event queue and associate it with a looper. 816 * 817 * "ident" is a identifier for the events that will be returned when 818 * calling ALooper_pollOnce(). The identifier must be >= 0, or 819 * ALOOPER_POLL_CALLBACK if providing a non-NULL callback. 820 */ 821 ASensorEventQueue* ASensorManager_createEventQueue(ASensorManager* manager, 822 ALooper* looper, int ident, ALooper_callbackFunc callback, void* data); 823 824 /** 825 * Destroys the event queue and free all resources associated to it. 826 */ 827 int ASensorManager_destroyEventQueue(ASensorManager* manager, ASensorEventQueue* queue); 828 829 /** 830 * Create direct channel based on shared memory 831 * 832 * Create a direct channel of {@link ASENSOR_DIRECT_CHANNEL_TYPE_SHARED_MEMORY} to be used 833 * for configuring sensor direct report. 834 * 835 * Available since API level 26. 836 * 837 * \param manager the {@link ASensorManager} instance obtained from 838 * {@link ASensorManager_getInstanceForPackage}. 839 * \param fd file descriptor representing a shared memory created by 840 * {@link ASharedMemory_create} 841 * \param size size to be used, must be less or equal to size of shared memory. 842 * 843 * \return a positive integer as a channel id to be used in 844 * {@link ASensorManager_destroyDirectChannel} and 845 * {@link ASensorManager_configureDirectReport}, or value less or equal to 0 for failures. 846 */ 847 int ASensorManager_createSharedMemoryDirectChannel(ASensorManager* manager, int fd, size_t size) __INTRODUCED_IN(26); 848 849 /** 850 * Create direct channel based on AHardwareBuffer 851 * 852 * Create a direct channel of {@link ASENSOR_DIRECT_CHANNEL_TYPE_HARDWARE_BUFFER} type to be used 853 * for configuring sensor direct report. 854 * 855 * Available since API level 26. 856 * 857 * \param manager the {@link ASensorManager} instance obtained from 858 * {@link ASensorManager_getInstanceForPackage}. 859 * \param buffer {@link AHardwareBuffer} instance created by {@link AHardwareBuffer_allocate}. 860 * \param size the intended size to be used, must be less or equal to size of buffer. 861 * 862 * \return a positive integer as a channel id to be used in 863 * {@link ASensorManager_destroyDirectChannel} and 864 * {@link ASensorManager_configureDirectReport}, or value less or equal to 0 for failures. 865 */ 866 int ASensorManager_createHardwareBufferDirectChannel( 867 ASensorManager* manager, AHardwareBuffer const * buffer, size_t size) __INTRODUCED_IN(26); 868 869 /** 870 * Destroy a direct channel 871 * 872 * Destroy a direct channel previously created by using one of 873 * ASensorManager_create*DirectChannel() derivative functions. 874 * Note that the buffer used for creating the direct channel does not get destroyed with 875 * ASensorManager_destroyDirectChannel and has to be closed or released separately. 876 * 877 * Available since API level 26. 878 * 879 * \param manager the {@link ASensorManager} instance obtained from 880 * {@link ASensorManager_getInstanceForPackage}. 881 * \param channelId channel id (a positive integer) returned from 882 * {@link ASensorManager_createSharedMemoryDirectChannel} or 883 * {@link ASensorManager_createHardwareBufferDirectChannel}. 884 */ 885 void ASensorManager_destroyDirectChannel(ASensorManager* manager, int channelId) __INTRODUCED_IN(26); 886 887 /** 888 * Configure direct report on channel 889 * 890 * Configure sensor direct report on a direct channel: set rate to value other than 891 * {@link ASENSOR_DIRECT_RATE_STOP} so that sensor event can be directly 892 * written into the shared memory region used for creating the buffer. It returns a positive token 893 * which can be used for identify sensor events from different sensors on success. Calling with rate 894 * {@link ASENSOR_DIRECT_RATE_STOP} will stop direct report of the sensor specified in the channel. 895 * 896 * To stop all active sensor direct report configured to a channel, set sensor to NULL and rate to 897 * {@link ASENSOR_DIRECT_RATE_STOP}. 898 * 899 * In order to successfully configure a direct report, the sensor has to support the specified rate 900 * and the channel type, which can be checked by {@link ASensor_getHighestDirectReportRateLevel} and 901 * {@link ASensor_isDirectChannelTypeSupported}, respectively. 902 * 903 * Example: 904 * 905 * ASensorManager *manager = ...; 906 * ASensor *sensor = ...; 907 * int channelId = ...; 908 * 909 * ASensorManager_configureDirectReport(manager, sensor, channel_id, ASENSOR_DIRECT_RATE_FAST); 910 * 911 * Available since API level 26. 912 * 913 * \param manager the {@link ASensorManager} instance obtained from 914 * {@link ASensorManager_getInstanceForPackage}. 915 * \param sensor a {@link ASensor} to denote which sensor to be operate. It can be NULL if rate 916 * is {@link ASENSOR_DIRECT_RATE_STOP}, denoting stopping of all active sensor 917 * direct report. 918 * \param channelId channel id (a positive integer) returned from 919 * {@link ASensorManager_createSharedMemoryDirectChannel} or 920 * {@link ASensorManager_createHardwareBufferDirectChannel}. 921 * \param rate one of predefined ASENSOR_DIRECT_RATE_... that is supported by the sensor. 922 * \return positive token for success or negative error code. 923 */ 924 int ASensorManager_configureDirectReport(ASensorManager* manager, 925 ASensor const* sensor, int channelId, int rate) __INTRODUCED_IN(26); 926 927 /*****************************************************************************/ 928 929 /** 930 * Enable the selected sensor with sampling and report parameters 931 * 932 * Enable the selected sensor at a specified sampling period and max batch report latency. 933 * To disable sensor, use {@link ASensorEventQueue_disableSensor}. 934 * 935 * \param queue {@link ASensorEventQueue} for sensor event to be report to. 936 * \param sensor {@link ASensor} to be enabled. 937 * \param samplingPeriodUs sampling period of sensor in microseconds. 938 * \param maxBatchReportLatencyUs maximum time interval between two batches of sensor events are 939 * delievered in microseconds. For sensor streaming, set to 0. 940 * \return 0 on success or a negative error code on failure. 941 */ 942 int ASensorEventQueue_registerSensor(ASensorEventQueue* queue, ASensor const* sensor, 943 int32_t samplingPeriodUs, int64_t maxBatchReportLatencyUs); 944 945 /** 946 * Enable the selected sensor at default sampling rate. 947 * 948 * Start event reports of a sensor to specified sensor event queue at a default rate. 949 * 950 * \param queue {@link ASensorEventQueue} for sensor event to be report to. 951 * \param sensor {@link ASensor} to be enabled. 952 * 953 * \return 0 on success or a negative error code on failure. 954 */ 955 int ASensorEventQueue_enableSensor(ASensorEventQueue* queue, ASensor const* sensor); 956 957 /** 958 * Disable the selected sensor. 959 * 960 * Stop event reports from the sensor to specified sensor event queue. 961 * 962 * \param queue {@link ASensorEventQueue} to be changed 963 * \param sensor {@link ASensor} to be disabled 964 * \return 0 on success or a negative error code on failure. 965 */ 966 int ASensorEventQueue_disableSensor(ASensorEventQueue* queue, ASensor const* sensor); 967 968 /** 969 * Sets the delivery rate of events in microseconds for the given sensor. 970 * 971 * This function has to be called after {@link ASensorEventQueue_enableSensor}. 972 * Note that this is a hint only, generally event will arrive at a higher 973 * rate. It is an error to set a rate inferior to the value returned by 974 * ASensor_getMinDelay(). 975 * 976 * \param queue {@link ASensorEventQueue} to which sensor event is delivered. 977 * \param sensor {@link ASensor} of which sampling rate to be updated. 978 * \param usec sensor sampling period (1/sampling rate) in microseconds 979 * \return 0 on sucess or a negative error code on failure. 980 */ 981 int ASensorEventQueue_setEventRate(ASensorEventQueue* queue, ASensor const* sensor, int32_t usec); 982 983 /** 984 * Determine if a sensor event queue has pending event to be processed. 985 * 986 * \param queue {@link ASensorEventQueue} to be queried 987 * \return 1 if the queue has events; 0 if it does not have events; 988 * or a negative value if there is an error. 989 */ 990 int ASensorEventQueue_hasEvents(ASensorEventQueue* queue); 991 992 /** 993 * Retrieve pending events in sensor event queue 994 * 995 * Retrieve next available events from the queue to a specified event array. 996 * 997 * \param queue {@link ASensorEventQueue} to get events from 998 * \param events pointer to an array of {@link ASensorEvent}. 999 * \param count max number of event that can be filled into array event. 1000 * \return number of events returned on success; negative error code when 1001 * no events are pending or an error has occurred. 1002 * 1003 * Examples: 1004 * 1005 * ASensorEvent event; 1006 * ssize_t numEvent = ASensorEventQueue_getEvents(queue, &event, 1); 1007 * 1008 * ASensorEvent eventBuffer[8]; 1009 * ssize_t numEvent = ASensorEventQueue_getEvents(queue, eventBuffer, 8); 1010 * 1011 */ 1012 ssize_t ASensorEventQueue_getEvents(ASensorEventQueue* queue, ASensorEvent* events, size_t count); 1013 1014 /** 1015 * Request that {@link ASENSOR_TYPE_ADDITIONAL_INFO} events to be delivered on 1016 * the given {@link ASensorEventQueue}. 1017 * 1018 * Sensor data events are always delivered to the {@link ASensorEventQueue}. 1019 * 1020 * The {@link ASENSOR_TYPE_ADDITIONAL_INFO} events will be returned through 1021 * {@link ASensorEventQueue_getEvents}. The client is responsible for checking 1022 * {@link ASensorEvent#type} to determine the event type prior to handling of 1023 * the event. 1024 * 1025 * The client must be tolerant of any value for 1026 * {@link AAdditionalInfoEvent#type}, as new values may be defined in the future 1027 * and may delivered to the client. 1028 * 1029 * Available since API level 29. 1030 * 1031 * \param queue {@link ASensorEventQueue} to configure 1032 * \param enable true to request {@link ASENSOR_TYPE_ADDITIONAL_INFO} events, 1033 * false to stop receiving events 1034 * \return 0 on success or a negative error code on failure 1035 */ 1036 int ASensorEventQueue_requestAdditionalInfoEvents(ASensorEventQueue* queue, bool enable) __INTRODUCED_IN(29); 1037 1038 /*****************************************************************************/ 1039 1040 /** 1041 * Returns this sensor's name (non localized) 1042 */ 1043 const char* ASensor_getName(ASensor const* sensor); 1044 1045 /** 1046 * Returns this sensor's vendor's name (non localized) 1047 */ 1048 const char* ASensor_getVendor(ASensor const* sensor); 1049 1050 /** 1051 * Return this sensor's type 1052 */ 1053 int ASensor_getType(ASensor const* sensor); 1054 1055 /** 1056 * Returns this sensors's resolution 1057 */ 1058 float ASensor_getResolution(ASensor const* sensor); 1059 1060 /** 1061 * Returns the minimum delay allowed between events in microseconds. 1062 * A value of zero means that this sensor doesn't report events at a 1063 * constant rate, but rather only when a new data is available. 1064 */ 1065 int ASensor_getMinDelay(ASensor const* sensor); 1066 1067 /** 1068 * Returns the maximum size of batches for this sensor. Batches will often be 1069 * smaller, as the hardware fifo might be used for other sensors. 1070 * 1071 * Available since API level 21. 1072 */ 1073 int ASensor_getFifoMaxEventCount(ASensor const* sensor) __INTRODUCED_IN(21); 1074 1075 /** 1076 * Returns the hardware batch fifo size reserved to this sensor. 1077 * 1078 * Available since API level 21. 1079 */ 1080 int ASensor_getFifoReservedEventCount(ASensor const* sensor) __INTRODUCED_IN(21); 1081 1082 /** 1083 * Returns this sensor's string type. 1084 * 1085 * Available since API level 21. 1086 */ 1087 const char* ASensor_getStringType(ASensor const* sensor) __INTRODUCED_IN(21); 1088 1089 /** 1090 * Returns the reporting mode for this sensor. One of AREPORTING_MODE_* constants. 1091 * 1092 * Available since API level 21. 1093 */ 1094 int ASensor_getReportingMode(ASensor const* sensor) __INTRODUCED_IN(21); 1095 1096 /** 1097 * Returns true if this is a wake up sensor, false otherwise. 1098 * 1099 * Available since API level 21. 1100 */ 1101 bool ASensor_isWakeUpSensor(ASensor const* sensor) __INTRODUCED_IN(21); 1102 1103 /** 1104 * Test if sensor supports a certain type of direct channel. 1105 * 1106 * Available since API level 26. 1107 * 1108 * \param sensor a {@link ASensor} to denote the sensor to be checked. 1109 * \param channelType Channel type constant, either 1110 * {@link ASENSOR_DIRECT_CHANNEL_TYPE_SHARED_MEMORY} 1111 * or {@link ASENSOR_DIRECT_CHANNEL_TYPE_HARDWARE_BUFFER}. 1112 * \returns true if sensor supports the specified direct channel type. 1113 */ 1114 bool ASensor_isDirectChannelTypeSupported(ASensor const* sensor, int channelType) __INTRODUCED_IN(26); 1115 1116 /** 1117 * Get the highest direct rate level that a sensor supports. 1118 * 1119 * Available since API level 26. 1120 * 1121 * \param sensor a {@link ASensor} to denote the sensor to be checked. 1122 * 1123 * \return a ASENSOR_DIRECT_RATE_... enum denoting the highest rate level supported by the sensor. 1124 * If return value is {@link ASENSOR_DIRECT_RATE_STOP}, it means the sensor 1125 * does not support direct report. 1126 */ 1127 int ASensor_getHighestDirectReportRateLevel(ASensor const* sensor) __INTRODUCED_IN(26); 1128 1129 /** 1130 * Returns the sensor's handle. 1131 * 1132 * The handle identifies the sensor within the system and is included in the 1133 * sensor field of {@link ASensorEvent}, including those sent with type 1134 * {@link ASENSOR_TYPE_ADDITIONAL_INFO}. 1135 * 1136 * A sensor's handle is able to be used to map {@link ASENSOR_TYPE_ADDITIONAL_INFO} events to the 1137 * sensor that generated the event. 1138 * 1139 * It is important to note that the value returned by {@link ASensor_getHandle} is not the same as 1140 * the value returned by the Java API <a href="/reference/android/hardware/Sensor#getId()"> 1141 * android.hardware.Sensor's getId()</a> and no mapping exists between the values. 1142 * 1143 * Available since API level 29. 1144 */ 1145 int ASensor_getHandle(ASensor const* sensor) __INTRODUCED_IN(29); 1146 1147 #ifdef __cplusplus 1148 }; 1149 #endif 1150 1151 #endif // ANDROID_SENSOR_H 1152 1153 /** @} */ 1154