sensor.h revision 43dcd0eaf0d0ce3bbf696cdfb9d4c6b76d882251
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 <stdbool.h> 52#include <sys/types.h> 53 54#include <android/looper.h> 55 56#ifdef __cplusplus 57extern "C" { 58#endif 59 60 61/** 62 * Sensor types. 63 * (keep in sync with hardware/sensors.h) 64 */ 65enum { 66 /** 67 * {@link ASENSOR_TYPE_ACCELEROMETER} 68 * reporting-mode: continuous 69 * 70 * All values are in SI units (m/s^2) and measure the acceleration of the 71 * device minus the force of gravity. 72 */ 73 ASENSOR_TYPE_ACCELEROMETER = 1, 74 /** 75 * {@link ASENSOR_TYPE_MAGNETIC_FIELD} 76 * reporting-mode: continuous 77 * 78 * All values are in micro-Tesla (uT) and measure the geomagnetic 79 * field in the X, Y and Z axis. 80 */ 81 ASENSOR_TYPE_MAGNETIC_FIELD = 2, 82 /** 83 * {@link ASENSOR_TYPE_GYROSCOPE} 84 * reporting-mode: continuous 85 * 86 * All values are in radians/second and measure the rate of rotation 87 * around the X, Y and Z axis. 88 */ 89 ASENSOR_TYPE_GYROSCOPE = 4, 90 /** 91 * {@link ASENSOR_TYPE_LIGHT} 92 * reporting-mode: on-change 93 * 94 * The light sensor value is returned in SI lux units. 95 */ 96 ASENSOR_TYPE_LIGHT = 5, 97 /** 98 * {@link ASENSOR_TYPE_PROXIMITY} 99 * reporting-mode: on-change 100 * 101 * The proximity sensor which turns the screen off and back on during calls is the 102 * wake-up proximity sensor. Implement wake-up proximity sensor before implementing 103 * a non wake-up proximity sensor. For the wake-up proximity sensor set the flag 104 * SENSOR_FLAG_WAKE_UP. 105 * The value corresponds to the distance to the nearest object in centimeters. 106 */ 107 ASENSOR_TYPE_PROXIMITY = 8, 108 /** 109 * {@link ASENSOR_TYPE_LINEAR_ACCELERATION} 110 * reporting-mode: continuous 111 * 112 * All values are in SI units (m/s^2) and measure the acceleration of the 113 * device not including the force of gravity. 114 */ 115 ASENSOR_TYPE_LINEAR_ACCELERATION = 10 116}; 117 118/** 119 * Sensor accuracy measure. 120 */ 121enum { 122 /** no contact */ 123 ASENSOR_STATUS_NO_CONTACT = -1, 124 /** unreliable */ 125 ASENSOR_STATUS_UNRELIABLE = 0, 126 /** low accuracy */ 127 ASENSOR_STATUS_ACCURACY_LOW = 1, 128 /** medium accuracy */ 129 ASENSOR_STATUS_ACCURACY_MEDIUM = 2, 130 /** high accuracy */ 131 ASENSOR_STATUS_ACCURACY_HIGH = 3 132}; 133 134/** 135 * Sensor Reporting Modes. 136 */ 137enum { 138 /** continuous reporting */ 139 AREPORTING_MODE_CONTINUOUS = 0, 140 /** reporting on change */ 141 AREPORTING_MODE_ON_CHANGE = 1, 142 /** on shot reporting */ 143 AREPORTING_MODE_ONE_SHOT = 2, 144 /** special trigger reporting */ 145 AREPORTING_MODE_SPECIAL_TRIGGER = 3 146}; 147 148/* 149 * A few useful constants 150 */ 151 152/** Earth's gravity in m/s^2 */ 153#define ASENSOR_STANDARD_GRAVITY (9.80665f) 154/** Maximum magnetic field on Earth's surface in uT */ 155#define ASENSOR_MAGNETIC_FIELD_EARTH_MAX (60.0f) 156/** Minimum magnetic field on Earth's surface in uT*/ 157#define ASENSOR_MAGNETIC_FIELD_EARTH_MIN (30.0f) 158 159/** 160 * A sensor event. 161 */ 162 163/* NOTE: Must match hardware/sensors.h */ 164typedef struct ASensorVector { 165 union { 166 float v[3]; 167 struct { 168 float x; 169 float y; 170 float z; 171 }; 172 struct { 173 float azimuth; 174 float pitch; 175 float roll; 176 }; 177 }; 178 int8_t status; 179 uint8_t reserved[3]; 180} ASensorVector; 181 182typedef struct AMetaDataEvent { 183 int32_t what; 184 int32_t sensor; 185} AMetaDataEvent; 186 187typedef struct AUncalibratedEvent { 188 union { 189 float uncalib[3]; 190 struct { 191 float x_uncalib; 192 float y_uncalib; 193 float z_uncalib; 194 }; 195 }; 196 union { 197 float bias[3]; 198 struct { 199 float x_bias; 200 float y_bias; 201 float z_bias; 202 }; 203 }; 204} AUncalibratedEvent; 205 206typedef struct AHeartRateEvent { 207 float bpm; 208 int8_t status; 209} AHeartRateEvent; 210 211typedef struct ADynamicSensorEvent { 212 int32_t connected; 213 int32_t handle; 214} ADynamicSensorEvent; 215 216typedef struct { 217 int32_t type; 218 int32_t serial; 219 union { 220 int32_t data_int32[14]; 221 float data_float[14]; 222 }; 223} AAdditionalInfoEvent; 224 225/* NOTE: Must match hardware/sensors.h */ 226typedef struct ASensorEvent { 227 int32_t version; /* sizeof(struct ASensorEvent) */ 228 int32_t sensor; 229 int32_t type; 230 int32_t reserved0; 231 int64_t timestamp; 232 union { 233 union { 234 float data[16]; 235 ASensorVector vector; 236 ASensorVector acceleration; 237 ASensorVector magnetic; 238 float temperature; 239 float distance; 240 float light; 241 float pressure; 242 float relative_humidity; 243 AUncalibratedEvent uncalibrated_gyro; 244 AUncalibratedEvent uncalibrated_magnetic; 245 AMetaDataEvent meta_data; 246 AHeartRateEvent heart_rate; 247 ADynamicSensorEvent dynamic_sensor_meta; 248 AAdditionalInfoEvent additional_info; 249 }; 250 union { 251 uint64_t data[8]; 252 uint64_t step_counter; 253 } u64; 254 }; 255 256 uint32_t flags; 257 int32_t reserved1[3]; 258} ASensorEvent; 259 260struct ASensorManager; 261/** 262 * {@link ASensorManager} is an opaque type to manage sensors and 263 * events queues. 264 * 265 * {@link ASensorManager} is a singleton that can be obtained using 266 * ASensorManager_getInstance(). 267 * 268 * This file provides a set of functions that uses {@link 269 * ASensorManager} to access and list hardware sensors, and 270 * create and destroy event queues: 271 * - ASensorManager_getSensorList() 272 * - ASensorManager_getDefaultSensor() 273 * - ASensorManager_getDefaultSensorEx() 274 * - ASensorManager_createEventQueue() 275 * - ASensorManager_destroyEventQueue() 276 */ 277typedef struct ASensorManager ASensorManager; 278 279 280struct ASensorEventQueue; 281/** 282 * {@link ASensorEventQueue} is an opaque type that provides access to 283 * {@link ASensorEvent} from hardware sensors. 284 * 285 * A new {@link ASensorEventQueue} can be obtained using ASensorManager_createEventQueue(). 286 * 287 * This file provides a set of functions to enable and disable 288 * sensors, check and get events, and set event rates on a {@link 289 * ASensorEventQueue}. 290 * - ASensorEventQueue_enableSensor() 291 * - ASensorEventQueue_disableSensor() 292 * - ASensorEventQueue_hasEvents() 293 * - ASensorEventQueue_getEvents() 294 * - ASensorEventQueue_setEventRate() 295 */ 296typedef struct ASensorEventQueue ASensorEventQueue; 297 298struct ASensor; 299/** 300 * {@link ASensor} is an opaque type that provides information about 301 * an hardware sensors. 302 * 303 * A {@link ASensor} pointer can be obtained using 304 * ASensorManager_getDefaultSensor(), 305 * ASensorManager_getDefaultSensorEx() or from a {@link ASensorList}. 306 * 307 * This file provides a set of functions to access properties of a 308 * {@link ASensor}: 309 * - ASensor_getName() 310 * - ASensor_getVendor() 311 * - ASensor_getType() 312 * - ASensor_getResolution() 313 * - ASensor_getMinDelay() 314 * - ASensor_getFifoMaxEventCount() 315 * - ASensor_getFifoReservedEventCount() 316 * - ASensor_getStringType() 317 * - ASensor_getReportingMode() 318 * - ASensor_isWakeUpSensor() 319 */ 320typedef struct ASensor ASensor; 321/** 322 * {@link ASensorRef} is a type for constant pointers to {@link ASensor}. 323 * 324 * This is used to define entry in {@link ASensorList} arrays. 325 */ 326typedef ASensor const* ASensorRef; 327/** 328 * {@link ASensorList} is an array of reference to {@link ASensor}. 329 * 330 * A {@link ASensorList} can be initialized using ASensorManager_getSensorList(). 331 */ 332typedef ASensorRef const* ASensorList; 333 334/*****************************************************************************/ 335 336/** 337 * Get a reference to the sensor manager. ASensorManager is a singleton 338 * per package as different packages may have access to different sensors. 339 * 340 * Deprecated: Use ASensorManager_getInstanceForPackage(const char*) instead. 341 * 342 * Example: 343 * 344 * ASensorManager* sensorManager = ASensorManager_getInstance(); 345 * 346 */ 347__attribute__ ((deprecated)) ASensorManager* ASensorManager_getInstance(); 348 349/* 350 * Get a reference to the sensor manager. ASensorManager is a singleton 351 * per package as different packages may have access to different sensors. 352 * 353 * Example: 354 * 355 * ASensorManager* sensorManager = ASensorManager_getInstanceForPackage("foo.bar.baz"); 356 * 357 */ 358ASensorManager* ASensorManager_getInstanceForPackage(const char* packageName); 359 360/** 361 * Returns the list of available sensors. 362 */ 363int ASensorManager_getSensorList(ASensorManager* manager, ASensorList* list); 364 365/** 366 * Returns the default sensor for the given type, or NULL if no sensor 367 * of that type exists. 368 */ 369ASensor const* ASensorManager_getDefaultSensor(ASensorManager* manager, int type); 370 371#if __ANDROID_API__ >= 21 372/** 373 * Returns the default sensor with the given type and wakeUp properties or NULL if no sensor 374 * of this type and wakeUp properties exists. 375 */ 376ASensor const* ASensorManager_getDefaultSensorEx(ASensorManager* manager, int type, 377 bool wakeUp); 378#endif 379 380/** 381 * Creates a new sensor event queue and associate it with a looper. 382 * 383 * "ident" is a identifier for the events that will be returned when 384 * calling ALooper_pollOnce(). The identifier must be >= 0, or 385 * ALOOPER_POLL_CALLBACK if providing a non-NULL callback. 386 */ 387ASensorEventQueue* ASensorManager_createEventQueue(ASensorManager* manager, 388 ALooper* looper, int ident, ALooper_callbackFunc callback, void* data); 389 390/** 391 * Destroys the event queue and free all resources associated to it. 392 */ 393int ASensorManager_destroyEventQueue(ASensorManager* manager, ASensorEventQueue* queue); 394 395 396/*****************************************************************************/ 397 398/** 399 * Enable the selected sensor with a specified sampling period and max batch report latency. 400 * Returns a negative error code on failure. 401 * Note: To disable the selected sensor, use ASensorEventQueue_disableSensor() same as before. 402 */ 403int ASensorEventQueue_registerSensor(ASensorEventQueue* queue, ASensor const* sensor, 404 int32_t samplingPeriodUs, int maxBatchReportLatencyUs); 405 406/** 407 * Enable the selected sensor. Returns a negative error code on failure. 408 */ 409int ASensorEventQueue_enableSensor(ASensorEventQueue* queue, ASensor const* sensor); 410 411/** 412 * Disable the selected sensor. Returns a negative error code on failure. 413 */ 414int ASensorEventQueue_disableSensor(ASensorEventQueue* queue, ASensor const* sensor); 415 416/** 417 * Sets the delivery rate of events in microseconds for the given sensor. 418 * Note that this is a hint only, generally event will arrive at a higher 419 * rate. It is an error to set a rate inferior to the value returned by 420 * ASensor_getMinDelay(). 421 * Returns a negative error code on failure. 422 */ 423int ASensorEventQueue_setEventRate(ASensorEventQueue* queue, ASensor const* sensor, int32_t usec); 424 425/** 426 * Returns true if there are one or more events available in the 427 * sensor queue. Returns 1 if the queue has events; 0 if 428 * it does not have events; and a negative value if there is an error. 429 */ 430int ASensorEventQueue_hasEvents(ASensorEventQueue* queue); 431 432/** 433 * Returns the next available events from the queue. Returns a negative 434 * value if no events are available or an error has occurred, otherwise 435 * the number of events returned. 436 * 437 * Examples: 438 * ASensorEvent event; 439 * ssize_t numEvent = ASensorEventQueue_getEvents(queue, &event, 1); 440 * 441 * ASensorEvent eventBuffer[8]; 442 * ssize_t numEvent = ASensorEventQueue_getEvents(queue, eventBuffer, 8); 443 * 444 */ 445ssize_t ASensorEventQueue_getEvents(ASensorEventQueue* queue, 446 ASensorEvent* events, size_t count); 447 448 449/*****************************************************************************/ 450 451/** 452 * Returns this sensor's name (non localized) 453 */ 454const char* ASensor_getName(ASensor const* sensor); 455 456/** 457 * Returns this sensor's vendor's name (non localized) 458 */ 459const char* ASensor_getVendor(ASensor const* sensor); 460 461/** 462 * Return this sensor's type 463 */ 464int ASensor_getType(ASensor const* sensor); 465 466/** 467 * Returns this sensors's resolution 468 */ 469float ASensor_getResolution(ASensor const* sensor); 470 471/** 472 * Returns the minimum delay allowed between events in microseconds. 473 * A value of zero means that this sensor doesn't report events at a 474 * constant rate, but rather only when a new data is available. 475 */ 476int ASensor_getMinDelay(ASensor const* sensor); 477 478#if __ANDROID_API__ >= 21 479/** 480 * Returns the maximum size of batches for this sensor. Batches will often be 481 * smaller, as the hardware fifo might be used for other sensors. 482 */ 483int ASensor_getFifoMaxEventCount(ASensor const* sensor); 484 485/** 486 * Returns the hardware batch fifo size reserved to this sensor. 487 */ 488int ASensor_getFifoReservedEventCount(ASensor const* sensor); 489 490/** 491 * Returns this sensor's string type. 492 */ 493const char* ASensor_getStringType(ASensor const* sensor); 494 495/** 496 * Returns the reporting mode for this sensor. One of AREPORTING_MODE_* constants. 497 */ 498int ASensor_getReportingMode(ASensor const* sensor); 499 500/** 501 * Returns true if this is a wake up sensor, false otherwise. 502 */ 503bool ASensor_isWakeUpSensor(ASensor const* sensor); 504#endif /* __ANDROID_API__ >= 21 */ 505 506#ifdef __cplusplus 507}; 508#endif 509 510#endif // ANDROID_SENSOR_H 511 512/** @} */ 513