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