sensor.h revision 8afbe27f81d35686e40e4e6d76af0c9118782754
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 * @addtogroup Sensor 19 * @{ 20 */ 21 22/** 23 * @file sensor.h 24 */ 25 26#ifndef ANDROID_SENSOR_H 27#define ANDROID_SENSOR_H 28 29/****************************************************************** 30 * 31 * IMPORTANT NOTICE: 32 * 33 * This file is part of Android's set of stable system headers 34 * exposed by the Android NDK (Native Development Kit). 35 * 36 * Third-party source AND binary code relies on the definitions 37 * here to be FROZEN ON ALL UPCOMING PLATFORM RELEASES. 38 * 39 * - DO NOT MODIFY ENUMS (EXCEPT IF YOU ADD NEW 32-BIT VALUES) 40 * - DO NOT MODIFY CONSTANTS OR FUNCTIONAL MACROS 41 * - DO NOT CHANGE THE SIGNATURE OF FUNCTIONS IN ANY WAY 42 * - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES 43 */ 44 45/** 46 * Structures and functions to receive and process sensor events in 47 * native code. 48 * 49 */ 50 51#include <android/looper.h> 52 53#include <stdbool.h> 54#include <sys/types.h> 55#include <math.h> 56#include <stdint.h> 57 58#ifdef __cplusplus 59extern "C" { 60#endif 61 62typedef struct AHardwareBuffer AHardwareBuffer; 63 64#define ASENSOR_RESOLUTION_INVALID (nanf("")) 65#define ASENSOR_FIFO_COUNT_INVALID (-1) 66#define ASENSOR_DELAY_INVALID INT32_MIN 67 68/** 69 * Sensor types. 70 * (keep in sync with hardware/sensors.h) 71 */ 72enum { 73 /** 74 * Invalid sensor type. Returned by {@link ASensor_getType} as error value. 75 */ 76 ASENSOR_TYPE_INVALID = -1, 77 /** 78 * {@link ASENSOR_TYPE_ACCELEROMETER} 79 * reporting-mode: continuous 80 * 81 * All values are in SI units (m/s^2) and measure the acceleration of the 82 * device minus the force of gravity. 83 */ 84 ASENSOR_TYPE_ACCELEROMETER = 1, 85 /** 86 * {@link ASENSOR_TYPE_MAGNETIC_FIELD} 87 * reporting-mode: continuous 88 * 89 * All values are in micro-Tesla (uT) and measure the geomagnetic 90 * field in the X, Y and Z axis. 91 */ 92 ASENSOR_TYPE_MAGNETIC_FIELD = 2, 93 /** 94 * {@link ASENSOR_TYPE_GYROSCOPE} 95 * reporting-mode: continuous 96 * 97 * All values are in radians/second and measure the rate of rotation 98 * around the X, Y and Z axis. 99 */ 100 ASENSOR_TYPE_GYROSCOPE = 4, 101 /** 102 * {@link ASENSOR_TYPE_LIGHT} 103 * reporting-mode: on-change 104 * 105 * The light sensor value is returned in SI lux units. 106 */ 107 ASENSOR_TYPE_LIGHT = 5, 108 /** 109 * {@link ASENSOR_TYPE_PROXIMITY} 110 * reporting-mode: on-change 111 * 112 * The proximity sensor which turns the screen off and back on during calls is the 113 * wake-up proximity sensor. Implement wake-up proximity sensor before implementing 114 * a non wake-up proximity sensor. For the wake-up proximity sensor set the flag 115 * SENSOR_FLAG_WAKE_UP. 116 * The value corresponds to the distance to the nearest object in centimeters. 117 */ 118 ASENSOR_TYPE_PROXIMITY = 8, 119 /** 120 * {@link ASENSOR_TYPE_LINEAR_ACCELERATION} 121 * reporting-mode: continuous 122 * 123 * All values are in SI units (m/s^2) and measure the acceleration of the 124 * device not including the force of gravity. 125 */ 126 ASENSOR_TYPE_LINEAR_ACCELERATION = 10 127}; 128 129/** 130 * Sensor accuracy measure. 131 */ 132enum { 133 /** no contact */ 134 ASENSOR_STATUS_NO_CONTACT = -1, 135 /** unreliable */ 136 ASENSOR_STATUS_UNRELIABLE = 0, 137 /** low accuracy */ 138 ASENSOR_STATUS_ACCURACY_LOW = 1, 139 /** medium accuracy */ 140 ASENSOR_STATUS_ACCURACY_MEDIUM = 2, 141 /** high accuracy */ 142 ASENSOR_STATUS_ACCURACY_HIGH = 3 143}; 144 145/** 146 * Sensor Reporting Modes. 147 */ 148enum { 149 /** invalid reporting mode */ 150 AREPORTING_MODE_INVALID = -1, 151 /** continuous reporting */ 152 AREPORTING_MODE_CONTINUOUS = 0, 153 /** reporting on change */ 154 AREPORTING_MODE_ON_CHANGE = 1, 155 /** on shot reporting */ 156 AREPORTING_MODE_ONE_SHOT = 2, 157 /** special trigger reporting */ 158 AREPORTING_MODE_SPECIAL_TRIGGER = 3 159}; 160 161/** 162 * Sensor Direct Report Rates. 163 */ 164enum { 165 /** stopped */ 166 ASENSOR_DIRECT_RATE_STOP = 0, 167 /** nominal 50Hz */ 168 ASENSOR_DIRECT_RATE_NORMAL = 1, 169 /** nominal 200Hz */ 170 ASENSOR_DIRECT_RATE_FAST = 2, 171 /** nominal 800Hz */ 172 ASENSOR_DIRECT_RATE_VERY_FAST = 3 173}; 174 175/** 176 * Sensor Direct Channel Type. 177 */ 178enum { 179 /** shared memory created by ASharedMemory_create */ 180 ASENSOR_DIRECT_CHANNEL_TYPE_SHARED_MEMORY = 1, 181 /** AHardwareBuffer */ 182 ASENSOR_DIRECT_CHANNEL_TYPE_HARDWARE_BUFFER = 2 183}; 184 185/* 186 * A few useful constants 187 */ 188 189/** Earth's gravity in m/s^2 */ 190#define ASENSOR_STANDARD_GRAVITY (9.80665f) 191/** Maximum magnetic field on Earth's surface in uT */ 192#define ASENSOR_MAGNETIC_FIELD_EARTH_MAX (60.0f) 193/** Minimum magnetic field on Earth's surface in uT*/ 194#define ASENSOR_MAGNETIC_FIELD_EARTH_MIN (30.0f) 195 196/** 197 * A sensor event. 198 */ 199 200/* NOTE: Must match hardware/sensors.h */ 201typedef struct ASensorVector { 202 union { 203 float v[3]; 204 struct { 205 float x; 206 float y; 207 float z; 208 }; 209 struct { 210 float azimuth; 211 float pitch; 212 float roll; 213 }; 214 }; 215 int8_t status; 216 uint8_t reserved[3]; 217} ASensorVector; 218 219typedef struct AMetaDataEvent { 220 int32_t what; 221 int32_t sensor; 222} AMetaDataEvent; 223 224typedef struct AUncalibratedEvent { 225 union { 226 float uncalib[3]; 227 struct { 228 float x_uncalib; 229 float y_uncalib; 230 float z_uncalib; 231 }; 232 }; 233 union { 234 float bias[3]; 235 struct { 236 float x_bias; 237 float y_bias; 238 float z_bias; 239 }; 240 }; 241} AUncalibratedEvent; 242 243typedef struct AHeartRateEvent { 244 float bpm; 245 int8_t status; 246} AHeartRateEvent; 247 248typedef struct ADynamicSensorEvent { 249 int32_t connected; 250 int32_t handle; 251} ADynamicSensorEvent; 252 253typedef struct { 254 int32_t type; 255 int32_t serial; 256 union { 257 int32_t data_int32[14]; 258 float data_float[14]; 259 }; 260} AAdditionalInfoEvent; 261 262/* NOTE: Must match hardware/sensors.h */ 263typedef struct ASensorEvent { 264 int32_t version; /* sizeof(struct ASensorEvent) */ 265 int32_t sensor; 266 int32_t type; 267 int32_t reserved0; 268 int64_t timestamp; 269 union { 270 union { 271 float data[16]; 272 ASensorVector vector; 273 ASensorVector acceleration; 274 ASensorVector magnetic; 275 float temperature; 276 float distance; 277 float light; 278 float pressure; 279 float relative_humidity; 280 AUncalibratedEvent uncalibrated_gyro; 281 AUncalibratedEvent uncalibrated_magnetic; 282 AMetaDataEvent meta_data; 283 AHeartRateEvent heart_rate; 284 ADynamicSensorEvent dynamic_sensor_meta; 285 AAdditionalInfoEvent additional_info; 286 }; 287 union { 288 uint64_t data[8]; 289 uint64_t step_counter; 290 } u64; 291 }; 292 293 uint32_t flags; 294 int32_t reserved1[3]; 295} ASensorEvent; 296 297struct ASensorManager; 298/** 299 * {@link ASensorManager} is an opaque type to manage sensors and 300 * events queues. 301 * 302 * {@link ASensorManager} is a singleton that can be obtained using 303 * ASensorManager_getInstance(). 304 * 305 * This file provides a set of functions that uses {@link 306 * ASensorManager} to access and list hardware sensors, and 307 * create and destroy event queues: 308 * - ASensorManager_getSensorList() 309 * - ASensorManager_getDefaultSensor() 310 * - ASensorManager_getDefaultSensorEx() 311 * - ASensorManager_createEventQueue() 312 * - ASensorManager_destroyEventQueue() 313 */ 314typedef struct ASensorManager ASensorManager; 315 316 317struct ASensorEventQueue; 318/** 319 * {@link ASensorEventQueue} is an opaque type that provides access to 320 * {@link ASensorEvent} from hardware sensors. 321 * 322 * A new {@link ASensorEventQueue} can be obtained using ASensorManager_createEventQueue(). 323 * 324 * This file provides a set of functions to enable and disable 325 * sensors, check and get events, and set event rates on a {@link 326 * ASensorEventQueue}. 327 * - ASensorEventQueue_enableSensor() 328 * - ASensorEventQueue_disableSensor() 329 * - ASensorEventQueue_hasEvents() 330 * - ASensorEventQueue_getEvents() 331 * - ASensorEventQueue_setEventRate() 332 */ 333typedef struct ASensorEventQueue ASensorEventQueue; 334 335struct ASensor; 336/** 337 * {@link ASensor} is an opaque type that provides information about 338 * an hardware sensors. 339 * 340 * A {@link ASensor} pointer can be obtained using 341 * ASensorManager_getDefaultSensor(), 342 * ASensorManager_getDefaultSensorEx() or from a {@link ASensorList}. 343 * 344 * This file provides a set of functions to access properties of a 345 * {@link ASensor}: 346 * - ASensor_getName() 347 * - ASensor_getVendor() 348 * - ASensor_getType() 349 * - ASensor_getResolution() 350 * - ASensor_getMinDelay() 351 * - ASensor_getFifoMaxEventCount() 352 * - ASensor_getFifoReservedEventCount() 353 * - ASensor_getStringType() 354 * - ASensor_getReportingMode() 355 * - ASensor_isWakeUpSensor() 356 */ 357typedef struct ASensor ASensor; 358/** 359 * {@link ASensorRef} is a type for constant pointers to {@link ASensor}. 360 * 361 * This is used to define entry in {@link ASensorList} arrays. 362 */ 363typedef ASensor const* ASensorRef; 364/** 365 * {@link ASensorList} is an array of reference to {@link ASensor}. 366 * 367 * A {@link ASensorList} can be initialized using ASensorManager_getSensorList(). 368 */ 369typedef ASensorRef const* ASensorList; 370 371/*****************************************************************************/ 372 373/** 374 * Get a reference to the sensor manager. ASensorManager is a singleton 375 * per package as different packages may have access to different sensors. 376 * 377 * Deprecated: Use ASensorManager_getInstanceForPackage(const char*) instead. 378 * 379 * Example: 380 * 381 * ASensorManager* sensorManager = ASensorManager_getInstance(); 382 * 383 */ 384__attribute__ ((deprecated)) ASensorManager* ASensorManager_getInstance(); 385 386/* 387 * Get a reference to the sensor manager. ASensorManager is a singleton 388 * per package as different packages may have access to different sensors. 389 * 390 * Example: 391 * 392 * ASensorManager* sensorManager = ASensorManager_getInstanceForPackage("foo.bar.baz"); 393 * 394 */ 395ASensorManager* ASensorManager_getInstanceForPackage(const char* packageName); 396 397/** 398 * Returns the list of available sensors. 399 */ 400int ASensorManager_getSensorList(ASensorManager* manager, ASensorList* list); 401 402/** 403 * Returns the default sensor for the given type, or NULL if no sensor 404 * of that type exists. 405 */ 406ASensor const* ASensorManager_getDefaultSensor(ASensorManager* manager, int type); 407 408#if __ANDROID_API__ >= 21 409/** 410 * Returns the default sensor with the given type and wakeUp properties or NULL if no sensor 411 * of this type and wakeUp properties exists. 412 */ 413ASensor const* ASensorManager_getDefaultSensorEx(ASensorManager* manager, int type, bool wakeUp); 414#endif 415 416/** 417 * Creates a new sensor event queue and associate it with a looper. 418 * 419 * "ident" is a identifier for the events that will be returned when 420 * calling ALooper_pollOnce(). The identifier must be >= 0, or 421 * ALOOPER_POLL_CALLBACK if providing a non-NULL callback. 422 */ 423ASensorEventQueue* ASensorManager_createEventQueue(ASensorManager* manager, 424 ALooper* looper, int ident, ALooper_callbackFunc callback, void* data); 425 426/** 427 * Destroys the event queue and free all resources associated to it. 428 */ 429int ASensorManager_destroyEventQueue(ASensorManager* manager, ASensorEventQueue* queue); 430 431#if __ANDROID_API__ >= __ANDROID_API_O__ 432/** 433 * Create direct channel based on shared memory 434 * 435 * Create a direct channel of {@link ASENSOR_DIRECT_CHANNEL_TYPE_SHARED_MEMORY} to be used 436 * for configuring sensor direct report. 437 * 438 * \param manager the {@link ASensorManager} instance obtained from 439 * {@link ASensorManager_getInstanceForPackage}. 440 * \param fd file descriptor representing a shared memory created by 441 * {@link ASharedMemory_create} 442 * \param size size to be used, must be less or equal to size of shared memory. 443 * 444 * \return a positive integer as a channel id to be used in 445 * {@link ASensorManager_destroyDirectChannel} and 446 * {@link ASensorManager_configureDirectReport}, or value less or equal to 0 for failures. 447 */ 448int ASensorManager_createSharedMemoryDirectChannel(ASensorManager* manager, int fd, size_t size); 449 450/** 451 * Create direct channel based on AHardwareBuffer 452 * 453 * Create a direct channel of {@link ASENSOR_DIRECT_CHANNEL_TYPE_HARDWARE_BUFFER} type to be used 454 * for configuring sensor direct report. 455 * 456 * \param manager the {@link ASensorManager} instance obtained from 457 * {@link ASensorManager_getInstanceForPackage}. 458 * \param buffer {@link AHardwareBuffer} instance created by {@link AHardwareBuffer_allocate}. 459 * \param size the intended size to be used, must be less or equal to size of buffer. 460 * 461 * \return a positive integer as a channel id to be used in 462 * {@link ASensorManager_destroyDirectChannel} and 463 * {@link ASensorManager_configureDirectReport}, or value less or equal to 0 for failures. 464 */ 465int ASensorManager_createHardwareBufferDirectChannel( 466 ASensorManager* manager, AHardwareBuffer const * buffer, size_t size); 467 468/** 469 * Destroy a direct channel 470 * 471 * Destroy a direct channel previously created using {@link ASensorManager_createDirectChannel}. 472 * The buffer used for creating direct channel does not get destroyed with 473 * {@link ASensorManager_destroy} and has to be close or released separately. 474 * 475 * \param manager the {@link ASensorManager} instance obtained from 476 * {@link ASensorManager_getInstanceForPackage}. 477 * \param channelId channel id (a positive integer) returned from 478 * {@link ASensorManager_createSharedMemoryDirectChannel} or 479 * {@link ASensorManager_createHardwareBufferDirectChannel}. 480 */ 481void ASensorManager_destroyDirectChannel(ASensorManager* manager, int channelId); 482 483/** 484 * Configure direct report on channel 485 * 486 * Configure sensor direct report on a direct channel: set rate to value other than 487 * {@link ASENSOR_DIRECT_RATE_STOP} so that sensor event can be directly 488 * written into the shared memory region used for creating the buffer. It returns a positive token 489 * which can be used for identify sensor events from different sensors on success. Calling with rate 490 * {@link ASENSOR_DIRECT_RATE_STOP} will stop direct report of the sensor specified in the channel. 491 * 492 * To stop all active sensor direct report configured to a channel, set sensor to NULL and rate to 493 * {@link ASENSOR_DIRECT_RATE_STOP}. 494 * 495 * In order to successfully configure a direct report, the sensor has to support the specified rate 496 * and the channel type, which can be checked by {@link ASensor_getHighestDirectReportRateLevel} and 497 * {@link ASensor_isDirectChannelTypeSupported}, respectively. 498 * 499 * Example: 500 * \code{.cpp} 501 * ASensorManager *manager = ...; 502 * ASensor *sensor = ...; 503 * int channelId = ...; 504 * 505 * ASensorManager_configureDirectReport( 506 * manager, sensor, channel_id, ASENSOR_DIRECT_RATE_FAST); 507 * \endcode 508 * 509 * \param manager the {@link ASensorManager} instance obtained from 510 * {@link ASensorManager_getInstanceForPackage}. 511 * \param sensor a {@link ASensor} to denote which sensor to be operate. It can be NULL if rate 512 * is {@link ASENSOR_DIRECT_RATE_STOP}, denoting stopping of all active sensor 513 * direct report. 514 * \param channelId channel id (a positive integer) returned from 515 * {@link ASensorManager_createSharedMemoryDirectChannel} or 516 * {@link ASensorManager_createHardwareBufferDirectChannel}. 517 * 518 * \return positive token for success or negative error code. 519 */ 520int ASensorManager_configureDirectReport( 521 ASensorManager* manager, ASensor const* sensor, int channelId, int rate); 522#endif 523 524/*****************************************************************************/ 525 526/** 527 * Enable the selected sensor with a specified sampling period and max batch report latency. 528 * Returns a negative error code on failure. 529 * Note: To disable the selected sensor, use ASensorEventQueue_disableSensor() same as before. 530 */ 531int ASensorEventQueue_registerSensor(ASensorEventQueue* queue, ASensor const* sensor, 532 int32_t samplingPeriodUs, int64_t maxBatchReportLatencyUs); 533 534/** 535 * Enable the selected sensor. Returns a negative error code on failure. 536 */ 537int ASensorEventQueue_enableSensor(ASensorEventQueue* queue, ASensor const* sensor); 538 539/** 540 * Disable the selected sensor. Returns a negative error code on failure. 541 */ 542int ASensorEventQueue_disableSensor(ASensorEventQueue* queue, ASensor const* sensor); 543 544/** 545 * Sets the delivery rate of events in microseconds for the given sensor. 546 * Note that this is a hint only, generally event will arrive at a higher 547 * rate. It is an error to set a rate inferior to the value returned by 548 * ASensor_getMinDelay(). 549 * Returns a negative error code on failure. 550 */ 551int ASensorEventQueue_setEventRate(ASensorEventQueue* queue, ASensor const* sensor, int32_t usec); 552 553/** 554 * Returns true if there are one or more events available in the 555 * sensor queue. Returns 1 if the queue has events; 0 if 556 * it does not have events; and a negative value if there is an error. 557 */ 558int ASensorEventQueue_hasEvents(ASensorEventQueue* queue); 559 560/** 561 * Returns the next available events from the queue. Returns a negative 562 * value if no events are available or an error has occurred, otherwise 563 * the number of events returned. 564 * 565 * Examples: 566 * ASensorEvent event; 567 * ssize_t numEvent = ASensorEventQueue_getEvents(queue, &event, 1); 568 * 569 * ASensorEvent eventBuffer[8]; 570 * ssize_t numEvent = ASensorEventQueue_getEvents(queue, eventBuffer, 8); 571 * 572 */ 573ssize_t ASensorEventQueue_getEvents(ASensorEventQueue* queue, ASensorEvent* events, size_t count); 574 575 576/*****************************************************************************/ 577 578/** 579 * Returns this sensor's name (non localized) 580 */ 581const char* ASensor_getName(ASensor const* sensor); 582 583/** 584 * Returns this sensor's vendor's name (non localized) 585 */ 586const char* ASensor_getVendor(ASensor const* sensor); 587 588/** 589 * Return this sensor's type 590 */ 591int ASensor_getType(ASensor const* sensor); 592 593/** 594 * Returns this sensors's resolution 595 */ 596float ASensor_getResolution(ASensor const* sensor); 597 598/** 599 * Returns the minimum delay allowed between events in microseconds. 600 * A value of zero means that this sensor doesn't report events at a 601 * constant rate, but rather only when a new data is available. 602 */ 603int ASensor_getMinDelay(ASensor const* sensor); 604 605#if __ANDROID_API__ >= 21 606/** 607 * Returns the maximum size of batches for this sensor. Batches will often be 608 * smaller, as the hardware fifo might be used for other sensors. 609 */ 610int ASensor_getFifoMaxEventCount(ASensor const* sensor); 611 612/** 613 * Returns the hardware batch fifo size reserved to this sensor. 614 */ 615int ASensor_getFifoReservedEventCount(ASensor const* sensor); 616 617/** 618 * Returns this sensor's string type. 619 */ 620const char* ASensor_getStringType(ASensor const* sensor); 621 622/** 623 * Returns the reporting mode for this sensor. One of AREPORTING_MODE_* constants. 624 */ 625int ASensor_getReportingMode(ASensor const* sensor); 626 627/** 628 * Returns true if this is a wake up sensor, false otherwise. 629 */ 630bool ASensor_isWakeUpSensor(ASensor const* sensor); 631#endif /* __ANDROID_API__ >= 21 */ 632 633#if __ANDROID_API__ >= __ANDROID_API_O__ 634/** 635 * Test if sensor supports a certain type of direct channel. 636 * 637 * \param sensor a {@link ASensor} to denote the sensor to be checked. 638 * \param channelType Channel type constant, either 639 * {@ASENSOR_DIRECT_CHANNEL_TYPE_SHARED_MEMORY} 640 * or {@link ASENSOR_DIRECT_CHANNEL_TYPE_HARDWARE_BUFFER}. 641 * \returns true if sensor supports the specified direct channel type. 642 */ 643bool ASensor_isDirectChannelTypeSupported(ASensor const* sensor, int channelType); 644/** 645 * Get the highest direct rate level that a sensor support. 646 * 647 * \param sensor a {@link ASensor} to denote the sensor to be checked. 648 * 649 * \return a ASENSOR_DIRECT_RATE_... enum denoting the highest rate level supported by the sensor. 650 * If return value is {@link ASENSOR_DIRECT_RATE_STOP}, it means the sensor 651 * does not support direct report. 652 */ 653int ASensor_getHighestDirectReportRateLevel(ASensor const* sensor); 654#endif 655 656#ifdef __cplusplus 657}; 658#endif 659 660#endif // ANDROID_SENSOR_H 661 662/** @} */ 663