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