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/sensors.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 * {@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 */ 120 enum { 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 */ 136 enum { 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 */ 163 typedef 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 181 typedef struct AMetaDataEvent { 182 int32_t what; 183 int32_t sensor; 184 } AMetaDataEvent; 185 186 typedef 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 205 typedef struct AHeartRateEvent { 206 float bpm; 207 int8_t status; 208 } AHeartRateEvent; 209 210 typedef struct ADynamicSensorEvent { 211 int32_t connected; 212 int32_t handle; 213 } ADynamicSensorEvent; 214 215 typedef struct { 216 int32_t type; 217 int32_t serial; 218 union { 219 int32_t data_int32[14]; 220 float data_float[14]; 221 }; 222 } AAdditionalInfoEvent; 223 224 /* NOTE: Must match hardware/sensors.h */ 225 typedef struct ASensorEvent { 226 int32_t version; /* sizeof(struct ASensorEvent) */ 227 int32_t sensor; 228 int32_t type; 229 int32_t reserved0; 230 int64_t timestamp; 231 union { 232 union { 233 float data[16]; 234 ASensorVector vector; 235 ASensorVector acceleration; 236 ASensorVector magnetic; 237 float temperature; 238 float distance; 239 float light; 240 float pressure; 241 float relative_humidity; 242 AUncalibratedEvent uncalibrated_gyro; 243 AUncalibratedEvent uncalibrated_magnetic; 244 AMetaDataEvent meta_data; 245 AHeartRateEvent heart_rate; 246 ADynamicSensorEvent dynamic_sensor_meta; 247 AAdditionalInfoEvent additional_info; 248 }; 249 union { 250 uint64_t data[8]; 251 uint64_t step_counter; 252 } u64; 253 }; 254 255 uint32_t flags; 256 int32_t reserved1[3]; 257 } ASensorEvent; 258 259 struct ASensorManager; 260 /** 261 * {@link ASensorManager} is an opaque type to manage sensors and 262 * events queues. 263 * 264 * {@link ASensorManager} is a singleton that can be obtained using 265 * ASensorManager_getInstance(). 266 * 267 * This file provides a set of functions that uses {@link 268 * ASensorManager} to access and list hardware sensors, and 269 * create and destroy event queues: 270 * - ASensorManager_getSensorList() 271 * - ASensorManager_getDefaultSensor() 272 * - ASensorManager_getDefaultSensorEx() 273 * - ASensorManager_createEventQueue() 274 * - ASensorManager_destroyEventQueue() 275 */ 276 typedef struct ASensorManager ASensorManager; 277 278 279 struct ASensorEventQueue; 280 /** 281 * {@link ASensorEventQueue} is an opaque type that provides access to 282 * {@link ASensorEvent} from hardware sensors. 283 * 284 * A new {@link ASensorEventQueue} can be obtained using ASensorManager_createEventQueue(). 285 * 286 * This file provides a set of functions to enable and disable 287 * sensors, check and get events, and set event rates on a {@link 288 * ASensorEventQueue}. 289 * - ASensorEventQueue_enableSensor() 290 * - ASensorEventQueue_disableSensor() 291 * - ASensorEventQueue_hasEvents() 292 * - ASensorEventQueue_getEvents() 293 * - ASensorEventQueue_setEventRate() 294 */ 295 typedef struct ASensorEventQueue ASensorEventQueue; 296 297 struct ASensor; 298 /** 299 * {@link ASensor} is an opaque type that provides information about 300 * an hardware sensors. 301 * 302 * A {@link ASensor} pointer can be obtained using 303 * ASensorManager_getDefaultSensor(), 304 * ASensorManager_getDefaultSensorEx() or from a {@link ASensorList}. 305 * 306 * This file provides a set of functions to access properties of a 307 * {@link ASensor}: 308 * - ASensor_getName() 309 * - ASensor_getVendor() 310 * - ASensor_getType() 311 * - ASensor_getResolution() 312 * - ASensor_getMinDelay() 313 * - ASensor_getFifoMaxEventCount() 314 * - ASensor_getFifoReservedEventCount() 315 * - ASensor_getStringType() 316 * - ASensor_getReportingMode() 317 * - ASensor_isWakeUpSensor() 318 */ 319 typedef struct ASensor ASensor; 320 /** 321 * {@link ASensorRef} is a type for constant pointers to {@link ASensor}. 322 * 323 * This is used to define entry in {@link ASensorList} arrays. 324 */ 325 typedef ASensor const* ASensorRef; 326 /** 327 * {@link ASensorList} is an array of reference to {@link ASensor}. 328 * 329 * A {@link ASensorList} can be initialized using ASensorManager_getSensorList(). 330 */ 331 typedef ASensorRef const* ASensorList; 332 333 /*****************************************************************************/ 334 335 /** 336 * Get a reference to the sensor manager. ASensorManager is a singleton 337 * per package as different packages may have access to different sensors. 338 * 339 * Deprecated: Use ASensorManager_getInstanceForPackage(const char*) instead. 340 * 341 * Example: 342 * 343 * ASensorManager* sensorManager = ASensorManager_getInstance(); 344 * 345 */ 346 __attribute__ ((deprecated)) ASensorManager* ASensorManager_getInstance(); 347 348 /* 349 * Get a reference to the sensor manager. ASensorManager is a singleton 350 * per package as different packages may have access to different sensors. 351 * 352 * Example: 353 * 354 * ASensorManager* sensorManager = ASensorManager_getInstanceForPackage("foo.bar.baz"); 355 * 356 */ 357 ASensorManager* ASensorManager_getInstanceForPackage(const char* packageName); 358 359 /** 360 * Returns the list of available sensors. 361 */ 362 int ASensorManager_getSensorList(ASensorManager* manager, ASensorList* list); 363 364 /** 365 * Returns the default sensor for the given type, or NULL if no sensor 366 * of that type exists. 367 */ 368 ASensor const* ASensorManager_getDefaultSensor(ASensorManager* manager, int type); 369 370 /** 371 * Returns the default sensor with the given type and wakeUp properties or NULL if no sensor 372 * of this type and wakeUp properties exists. 373 */ 374 ASensor const* ASensorManager_getDefaultSensorEx(ASensorManager* manager, int type, 375 bool wakeUp); 376 377 /** 378 * Creates a new sensor event queue and associate it with a looper. 379 * 380 * "ident" is a identifier for the events that will be returned when 381 * calling ALooper_pollOnce(). The identifier must be >= 0, or 382 * ALOOPER_POLL_CALLBACK if providing a non-NULL callback. 383 */ 384 ASensorEventQueue* ASensorManager_createEventQueue(ASensorManager* manager, 385 ALooper* looper, int ident, ALooper_callbackFunc callback, void* data); 386 387 /** 388 * Destroys the event queue and free all resources associated to it. 389 */ 390 int ASensorManager_destroyEventQueue(ASensorManager* manager, ASensorEventQueue* queue); 391 392 393 /*****************************************************************************/ 394 395 /** 396 * Enable the selected sensor with a specified sampling period and max batch report latency. 397 * Returns a negative error code on failure. 398 */ 399 int ASensorEventQueue_registerSensor(ASensorEventQueue* queue, ASensor const* sensor, 400 int32_t samplingPeriodUs, int maxBatchReportLatencyUs); 401 402 /** 403 * Enable the selected sensor. Returns a negative error code on failure. 404 */ 405 int ASensorEventQueue_enableSensor(ASensorEventQueue* queue, ASensor const* sensor); 406 407 /** 408 * Disable the selected sensor. Returns a negative error code on failure. 409 */ 410 int ASensorEventQueue_disableSensor(ASensorEventQueue* queue, ASensor const* sensor); 411 412 /** 413 * Sets the delivery rate of events in microseconds for the given sensor. 414 * Note that this is a hint only, generally event will arrive at a higher 415 * rate. It is an error to set a rate inferior to the value returned by 416 * ASensor_getMinDelay(). 417 * Returns a negative error code on failure. 418 */ 419 int ASensorEventQueue_setEventRate(ASensorEventQueue* queue, ASensor const* sensor, int32_t usec); 420 421 /** 422 * Returns true if there are one or more events available in the 423 * sensor queue. Returns 1 if the queue has events; 0 if 424 * it does not have events; and a negative value if there is an error. 425 */ 426 int ASensorEventQueue_hasEvents(ASensorEventQueue* queue); 427 428 /** 429 * Returns the next available events from the queue. Returns a negative 430 * value if no events are available or an error has occurred, otherwise 431 * the number of events returned. 432 * 433 * Examples: 434 * ASensorEvent event; 435 * ssize_t numEvent = ASensorEventQueue_getEvents(queue, &event, 1); 436 * 437 * ASensorEvent eventBuffer[8]; 438 * ssize_t numEvent = ASensorEventQueue_getEvents(queue, eventBuffer, 8); 439 * 440 */ 441 ssize_t ASensorEventQueue_getEvents(ASensorEventQueue* queue, 442 ASensorEvent* events, size_t count); 443 444 445 /*****************************************************************************/ 446 447 /** 448 * Returns this sensor's name (non localized) 449 */ 450 const char* ASensor_getName(ASensor const* sensor); 451 452 /** 453 * Returns this sensor's vendor's name (non localized) 454 */ 455 const char* ASensor_getVendor(ASensor const* sensor); 456 457 /** 458 * Return this sensor's type 459 */ 460 int ASensor_getType(ASensor const* sensor); 461 462 /** 463 * Returns this sensors's resolution 464 */ 465 float ASensor_getResolution(ASensor const* sensor); 466 467 /** 468 * Returns the minimum delay allowed between events in microseconds. 469 * A value of zero means that this sensor doesn't report events at a 470 * constant rate, but rather only when a new data is available. 471 */ 472 int ASensor_getMinDelay(ASensor const* sensor); 473 474 /** 475 * Returns the maximum size of batches for this sensor. Batches will often be 476 * smaller, as the hardware fifo might be used for other sensors. 477 */ 478 int ASensor_getFifoMaxEventCount(ASensor const* sensor); 479 480 /** 481 * Returns the hardware batch fifo size reserved to this sensor. 482 */ 483 int ASensor_getFifoReservedEventCount(ASensor const* sensor); 484 485 /** 486 * Returns this sensor's string type. 487 */ 488 const char* ASensor_getStringType(ASensor const* sensor); 489 490 /** 491 * Returns the reporting mode for this sensor. One of AREPORTING_MODE_* constants. 492 */ 493 int ASensor_getReportingMode(ASensor const* sensor); 494 495 /** 496 * Returns true if this is a wake up sensor, false otherwise. 497 */ 498 bool ASensor_isWakeUpSensor(ASensor const* sensor); 499 500 #ifdef __cplusplus 501 }; 502 #endif 503 504 #endif // ANDROID_SENSOR_H 505 506 /** @} */ 507