sensors.h revision 1461f28f503d75c6eda29ec9bbd5db33b44f65fe
1/* 2 * Copyright (C) 2012 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#ifndef ANDROID_SENSORS_INTERFACE_H 18#define ANDROID_SENSORS_INTERFACE_H 19 20#include <stdint.h> 21#include <sys/cdefs.h> 22#include <sys/types.h> 23 24#include <hardware/hardware.h> 25#include <cutils/native_handle.h> 26 27__BEGIN_DECLS 28 29/*****************************************************************************/ 30 31#define SENSORS_HEADER_VERSION 1 32#define SENSORS_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) 33#define SENSORS_DEVICE_API_VERSION_0_1 HARDWARE_DEVICE_API_VERSION_2(0, 1, SENSORS_HEADER_VERSION) 34#define SENSORS_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION_2(1, 0, SENSORS_HEADER_VERSION) 35 36/** 37 * The id of this module 38 */ 39#define SENSORS_HARDWARE_MODULE_ID "sensors" 40 41/** 42 * Name of the sensors device to open 43 */ 44#define SENSORS_HARDWARE_POLL "poll" 45 46/** 47 * Handles must be higher than SENSORS_HANDLE_BASE and must be unique. 48 * A Handle identifies a given sensors. The handle is used to activate 49 * and/or deactivate sensors. 50 * In this version of the API there can only be 256 handles. 51 */ 52#define SENSORS_HANDLE_BASE 0 53#define SENSORS_HANDLE_BITS 8 54#define SENSORS_HANDLE_COUNT (1<<SENSORS_HANDLE_BITS) 55 56 57/* attributes queriable with query() */ 58enum { 59 /* 60 * Availability: SENSORS_DEVICE_API_VERSION_1_0 61 * return the maximum number of events that can be returned 62 * in a single call to (*poll)(). This value is used by the 63 * framework to adequately dimension the buffer passed to 64 * (*poll)(), note that (*poll)() still needs to pay attention to 65 * the count parameter passed to it, it cannot blindly expect that 66 * this value will be used for all calls to (*poll)(). 67 * 68 * Generally this value should be set to match the sum of the internal 69 * FIFOs of all available sensors. 70 */ 71 SENSORS_QUERY_MAX_EVENTS_BATCH_COUNT = 0 72}; 73 74/* 75 * flags for (*batch)() 76 * Availability: SENSORS_DEVICE_API_VERSION_1_0 77 * see (*batch)() documentation for details 78 */ 79enum { 80 SENSORS_BATCH_DRY_RUN = 0x00000001, 81 SENSORS_BATCH_WAKE_UPON_FIFO_FULL = 0x00000002 82}; 83 84/** 85 * Definition of the axis used by the sensor HAL API 86 * 87 * This API is relative to the screen of the device in its default orientation, 88 * that is, if the device can be used in portrait or landscape, this API 89 * is only relative to the NATURAL orientation of the screen. In other words, 90 * the axis are not swapped when the device's screen orientation changes. 91 * Higher level services /may/ perform this transformation. 92 * 93 * x<0 x>0 94 * ^ 95 * | 96 * +-----------+--> y>0 97 * | | 98 * | | 99 * | | 100 * | | / z<0 101 * | | / 102 * | | / 103 * O-----------+/ 104 * |[] [ ] []/ 105 * +----------/+ y<0 106 * / 107 * / 108 * |/ z>0 (toward the sky) 109 * 110 * O: Origin (x=0,y=0,z=0) 111 * 112 */ 113 114/* 115 * Interaction with suspend mode 116 * 117 * Unless otherwise noted, an enabled sensor shall not prevent the 118 * SoC to go into suspend mode. It is the responsibility of applications 119 * to keep a partial wake-lock should they wish to receive sensor 120 * events while the screen is off. While in suspend mode, and unless 121 * otherwise noted, enabled sensors' events are lost. 122 * 123 * Note that conceptually, the sensor itself is not de-activated while in 124 * suspend mode -- it's just that the data it returns are lost. As soon as 125 * the SoC gets out of suspend mode, operations resume as usual. Of course, 126 * in practice sensors shall be disabled while in suspend mode to 127 * save power, unless batch mode is active, in which case they must 128 * continue fill their internal FIFO (see the documentation of batch() to 129 * learn how suspend interacts with batch mode). 130 * 131 * In batch mode and only when the flag SENSORS_BATCH_WAKE_UPON_FIFO_FULL is 132 * set and supported, the specified sensor must be able to wake-up the SoC and 133 * be able to buffer at least 10 seconds worth of the requested sensor events. 134 * 135 * There are notable exceptions to this behavior, which are sensor-dependent 136 * (see sensor types definitions below) 137 * 138 * 139 * The sensor type documentation below specifies the wake-up behavior of 140 * each sensor: 141 * wake-up: yes this sensor must wake-up the SoC to deliver events 142 * wake-up: no this sensor shall not wake-up the SoC, events are dropped 143 * 144 */ 145 146/* 147 * Sensor type 148 * 149 * Each sensor has a type which defines what this sensor measures and how 150 * measures are reported. All types are defined below. 151 */ 152 153/* 154 * Sensor fusion and virtual sensors 155 * 156 * Many sensor types are or can be implemented as virtual sensors from 157 * physical sensors on the device. For instance the rotation vector sensor, 158 * orientation sensor, step-detector, step-counter, etc... 159 * 160 * From the point of view of this API these virtual sensors MUST appear as 161 * real, individual sensors. It is the responsibility of the driver and HAL 162 * to make sure this is the case. 163 * 164 * In particular, all sensors must be able to function concurrently. 165 * For example, if defining both an accelerometer and a step counter, 166 * then both must be able to work concurrently. 167 */ 168 169/* 170 * Trigger modes 171 * 172 * Sensors can report events in different ways called trigger modes, 173 * each sensor type has one and only one trigger mode associated to it. 174 * Currently there are four trigger modes defined: 175 * 176 * continuous: events are reported at a constant rate defined by setDelay(). 177 * eg: accelerometers, gyroscopes. 178 * on-change: events are reported only if the sensor's value has changed. 179 * setDelay() is used to set a lower limit to the reporting 180 * period (minimum time between two events). 181 * The HAL must return an event immediately when an on-change 182 * sensor is activated. 183 * eg: proximity, light sensors 184 * one-shot: upon detection of an event, the sensor deactivates itself and 185 * then sends a single event. Order matters to avoid race 186 * conditions. No other event is sent until the sensor get 187 * reactivated. setDelay() is ignored. 188 * eg: significant motion sensor 189 * special: see details in the sensor type specification below 190 * 191 */ 192 193/* 194 * SENSOR_TYPE_ACCELEROMETER 195 * trigger-mode: continuous 196 * wake-up sensor: no 197 * 198 * All values are in SI units (m/s^2) and measure the acceleration of the 199 * device minus the force of gravity. 200 * 201 * Acceleration sensors return sensor events for all 3 axes at a constant 202 * rate defined by setDelay(). 203 * 204 * x: Acceleration on the x-axis 205 * y: Acceleration on the y-axis 206 * z: Acceleration on the z-axis 207 * 208 * Note that the readings from the accelerometer include the acceleration 209 * due to gravity (which is opposite to the direction of the gravity vector). 210 * 211 * Examples: 212 * The norm of <x, y, z> should be close to 0 when in free fall. 213 * 214 * When the device lies flat on a table and is pushed on its left side 215 * toward the right, the x acceleration value is positive. 216 * 217 * When the device lies flat on a table, the acceleration value is +9.81, 218 * which correspond to the acceleration of the device (0 m/s^2) minus the 219 * force of gravity (-9.81 m/s^2). 220 * 221 * When the device lies flat on a table and is pushed toward the sky, the 222 * acceleration value is greater than +9.81, which correspond to the 223 * acceleration of the device (+A m/s^2) minus the force of 224 * gravity (-9.81 m/s^2). 225 */ 226#define SENSOR_TYPE_ACCELEROMETER (1) 227 228/* 229 * SENSOR_TYPE_GEOMAGNETIC_FIELD 230 * trigger-mode: continuous 231 * wake-up sensor: no 232 * 233 * All values are in micro-Tesla (uT) and measure the geomagnetic 234 * field in the X, Y and Z axis. 235 * 236 * Returned values include calibration mechanisms such that the vector is 237 * aligned with the magnetic declination and heading of the earth's 238 * geomagnetic field. 239 * 240 * Magnetic Field sensors return sensor events for all 3 axes at a constant 241 * rate defined by setDelay(). 242 */ 243#define SENSOR_TYPE_GEOMAGNETIC_FIELD (2) 244#define SENSOR_TYPE_MAGNETIC_FIELD SENSOR_TYPE_GEOMAGNETIC_FIELD 245 246/* 247 * SENSOR_TYPE_ORIENTATION 248 * trigger-mode: continuous 249 * wake-up sensor: no 250 * 251 * All values are angles in degrees. 252 * 253 * Orientation sensors return sensor events for all 3 axes at a constant 254 * rate defined by setDelay(). 255 * 256 * azimuth: angle between the magnetic north direction and the Y axis, around 257 * the Z axis (0<=azimuth<360). 258 * 0=North, 90=East, 180=South, 270=West 259 * 260 * pitch: Rotation around X axis (-180<=pitch<=180), with positive values when 261 * the z-axis moves toward the y-axis. 262 * 263 * roll: Rotation around Y axis (-90<=roll<=90), with positive values when 264 * the x-axis moves towards the z-axis. 265 * 266 * Note: For historical reasons the roll angle is positive in the clockwise 267 * direction (mathematically speaking, it should be positive in the 268 * counter-clockwise direction): 269 * 270 * Z 271 * ^ 272 * (+roll) .--> | 273 * / | 274 * | | roll: rotation around Y axis 275 * X <-------(.) 276 * Y 277 * note that +Y == -roll 278 * 279 * 280 * 281 * Note: This definition is different from yaw, pitch and roll used in aviation 282 * where the X axis is along the long side of the plane (tail to nose). 283 */ 284#define SENSOR_TYPE_ORIENTATION (3) 285 286/* 287 * SENSOR_TYPE_GYROSCOPE 288 * trigger-mode: continuous 289 * wake-up sensor: no 290 * 291 * All values are in radians/second and measure the rate of rotation 292 * around the X, Y and Z axis. The coordinate system is the same as is 293 * used for the acceleration sensor. Rotation is positive in the 294 * counter-clockwise direction (right-hand rule). That is, an observer 295 * looking from some positive location on the x, y or z axis at a device 296 * positioned on the origin would report positive rotation if the device 297 * appeared to be rotating counter clockwise. Note that this is the 298 * standard mathematical definition of positive rotation and does not agree 299 * with the definition of roll given earlier. 300 * The range should at least be 17.45 rad/s (ie: ~1000 deg/s). 301 * 302 * automatic gyro-drift compensation is allowed but not required. 303 */ 304#define SENSOR_TYPE_GYROSCOPE (4) 305 306/* 307 * SENSOR_TYPE_LIGHT 308 * trigger-mode: on-change 309 * wake-up sensor: no 310 * 311 * The light sensor value is returned in SI lux units. 312 */ 313#define SENSOR_TYPE_LIGHT (5) 314 315/* 316 * SENSOR_TYPE_PRESSURE 317 * trigger-mode: continuous 318 * wake-up sensor: no 319 * 320 * The pressure sensor return the athmospheric pressure in hectopascal (hPa) 321 */ 322#define SENSOR_TYPE_PRESSURE (6) 323 324/* SENSOR_TYPE_TEMPERATURE is deprecated in the HAL */ 325#define SENSOR_TYPE_TEMPERATURE (7) 326 327/* 328 * SENSOR_TYPE_PROXIMITY 329 * trigger-mode: on-change 330 * wake-up sensor: yes 331 * 332 * The distance value is measured in centimeters. Note that some proximity 333 * sensors only support a binary "close" or "far" measurement. In this case, 334 * the sensor should report its maxRange value in the "far" state and a value 335 * less than maxRange in the "near" state. 336 */ 337#define SENSOR_TYPE_PROXIMITY (8) 338 339/* 340 * SENSOR_TYPE_GRAVITY 341 * trigger-mode: continuous 342 * wake-up sensor: no 343 * 344 * A gravity output indicates the direction of and magnitude of gravity in 345 * the devices's coordinates. On Earth, the magnitude is 9.8 m/s^2. 346 * Units are m/s^2. The coordinate system is the same as is used for the 347 * acceleration sensor. When the device is at rest, the output of the 348 * gravity sensor should be identical to that of the accelerometer. 349 */ 350#define SENSOR_TYPE_GRAVITY (9) 351 352/* 353 * SENSOR_TYPE_LINEAR_ACCELERATION 354 * trigger-mode: continuous 355 * wake-up sensor: no 356 * 357 * Indicates the linear acceleration of the device in device coordinates, 358 * not including gravity. 359 * 360 * The output is conceptually: 361 * output of TYPE_ACCELERATION - output of TYPE_GRAVITY 362 * 363 * Readings on all axes should be close to 0 when device lies on a table. 364 * Units are m/s^2. 365 * The coordinate system is the same as is used for the acceleration sensor. 366 */ 367#define SENSOR_TYPE_LINEAR_ACCELERATION (10) 368 369 370/* 371 * SENSOR_TYPE_ROTATION_VECTOR 372 * trigger-mode: continuous 373 * wake-up sensor: no 374 * 375 * A rotation vector represents the orientation of the device as a combination 376 * of an angle and an axis, in which the device has rotated through an angle 377 * theta around an axis <x, y, z>. The three elements of the rotation vector 378 * are <x*sin(theta/2), y*sin(theta/2), z*sin(theta/2)>, such that the magnitude 379 * of the rotation vector is equal to sin(theta/2), and the direction of the 380 * rotation vector is equal to the direction of the axis of rotation. The three 381 * elements of the rotation vector are equal to the last three components of a 382 * unit quaternion 383 * <cos(theta/2), x*sin(theta/2), y*sin(theta/2), z*sin(theta/2)>. 384 * Elements of the rotation vector are unitless. The x, y, and z axis are 385 * defined in the same way as for the acceleration sensor. 386 * 387 * The reference coordinate system is defined as a direct orthonormal basis, 388 * where: 389 * 390 * - X is defined as the vector product Y.Z (It is tangential to 391 * the ground at the device's current location and roughly points East). 392 * 393 * - Y is tangential to the ground at the device's current location and 394 * points towards the magnetic North Pole. 395 * 396 * - Z points towards the sky and is perpendicular to the ground. 397 * 398 * 399 * The rotation-vector is stored as: 400 * 401 * sensors_event_t.data[0] = x*sin(theta/2) 402 * sensors_event_t.data[1] = y*sin(theta/2) 403 * sensors_event_t.data[2] = z*sin(theta/2) 404 * 405 * In addition, this sensor reports an estimated heading accuracy. 406 * sensors_event_t.data[3] = estimated_accuracy (in radians) 407 * The heading error must be less than estimated_accuracy 95% of the time 408 * 409 * This sensor must use a gyroscope and an accelerometer as main orientation 410 * change input. 411 * 412 * This sensor can also include magnetometer input to make up for gyro drift, 413 * but it cannot be implemented using only a magnetometer. 414 */ 415#define SENSOR_TYPE_ROTATION_VECTOR (11) 416 417/* 418 * SENSOR_TYPE_RELATIVE_HUMIDITY 419 * trigger-mode: on-change 420 * wake-up sensor: no 421 * 422 * A relative humidity sensor measures relative ambient air humidity and 423 * returns a value in percent. 424 */ 425#define SENSOR_TYPE_RELATIVE_HUMIDITY (12) 426 427/* 428 * SENSOR_TYPE_AMBIENT_TEMPERATURE 429 * trigger-mode: on-change 430 * wake-up sensor: no 431 * 432 * The ambient (room) temperature in degree Celsius. 433 */ 434#define SENSOR_TYPE_AMBIENT_TEMPERATURE (13) 435 436/* 437 * SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED 438 * trigger-mode: continuous 439 * wake-up sensor: no 440 * 441 * Similar to SENSOR_TYPE_MAGNETIC_FIELD, but the hard iron calibration is 442 * reported separately instead of being included in the measurement. 443 * Factory calibration and temperature compensation should still be applied to 444 * the "uncalibrated" measurement. 445 * Separating away the hard iron calibration estimation allows the system to 446 * better recover from bad hard iron estimation. 447 * 448 * All values are in micro-Tesla (uT) and measure the ambient magnetic 449 * field in the X, Y and Z axis. Assumptions that the the magnetic field 450 * is due to the Earth's poles should be avoided. 451 * 452 * The uncalibrated_magnetic event contains 453 * - 3 fields for uncalibrated measurement: x_uncalib, y_uncalib, z_uncalib. 454 * Each is a component of the measured magnetic field, with soft iron 455 * and temperature compensation applied, but not hard iron calibration. 456 * These values should be continuous (no re-calibration should cause a jump). 457 * - 3 fields for hard iron bias estimates: x_bias, y_bias, z_bias. 458 * Each field is a component of the estimated hard iron calibration. 459 * They represent the offsets to apply to the uncalibrated readings to obtain 460 * calibrated readings (x_calibrated = x_uncalib + x_bias) 461 * These values are expected to jump as soon as the estimate of the hard iron 462 * changes. 463 * 464 * If this sensor is present, then the corresponding 465 * SENSOR_TYPE_MAGNETIC_FIELD must be present and both must return the 466 * same sensor_t::name and sensor_t::vendor. 467 * 468 * See SENSOR_TYPE_MAGNETIC_FIELD for more information 469 */ 470#define SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED (14) 471 472/* 473 * SENSOR_TYPE_GAME_ROTATION_VECTOR 474 * trigger-mode: continuous 475 * wake-up sensor: no 476 * 477 * Similar to SENSOR_TYPE_ROTATION_VECTOR, but not using the geomagnetic 478 * field. Therefore the Y axis doesn't point north, but instead to some other 479 * reference. That reference is allowed to drift by the same order of 480 * magnitude than the gyroscope drift around the Z axis. 481 * 482 * This sensor does not report an estimated heading accuracy: 483 * sensors_event_t.data[3] is reserved and should be set to 0 484 * 485 * In the ideal case, a phone rotated and returning to the same real-world 486 * orientation should report the same game rotation vector 487 * (without using the earth's geomagnetic field). 488 * 489 * This sensor must be based on a gyroscope. It cannot be implemented using 490 * a magnetometer. 491 * 492 * see SENSOR_TYPE_ROTATION_VECTOR for more details 493 */ 494#define SENSOR_TYPE_GAME_ROTATION_VECTOR (15) 495 496/* 497 * SENSOR_TYPE_GYROSCOPE_UNCALIBRATED 498 * trigger-mode: continuous 499 * wake-up sensor: no 500 * 501 * All values are in radians/second and measure the rate of rotation 502 * around the X, Y and Z axis. An estimation of the drift on each axis is 503 * reported as well. 504 * 505 * No gyro-drift compensation shall be performed. 506 * Factory calibration and temperature compensation should still be applied 507 * to the rate of rotation (angular speeds). 508 * 509 * The coordinate system is the same as is 510 * used for the acceleration sensor. Rotation is positive in the 511 * counter-clockwise direction (right-hand rule). That is, an observer 512 * looking from some positive location on the x, y or z axis at a device 513 * positioned on the origin would report positive rotation if the device 514 * appeared to be rotating counter clockwise. Note that this is the 515 * standard mathematical definition of positive rotation and does not agree 516 * with the definition of roll given earlier. 517 * The range should at least be 17.45 rad/s (ie: ~1000 deg/s). 518 * 519 * Content of an uncalibrated_gyro event: (units are rad/sec) 520 * x_uncalib : angular speed (w/o drift compensation) around the X axis 521 * y_uncalib : angular speed (w/o drift compensation) around the Y axis 522 * z_uncalib : angular speed (w/o drift compensation) around the Z axis 523 * x_bias : estimated drift around X axis in rad/s 524 * y_bias : estimated drift around Y axis in rad/s 525 * z_bias : estimated drift around Z axis in rad/s 526 * 527 * IMPLEMENTATION NOTES: 528 * 529 * If the implementation is not able to estimate the drift, then this 530 * sensor MUST NOT be reported by this HAL. Instead, the regular 531 * SENSOR_TYPE_GYROSCOPE is used without drift compensation. 532 * 533 * If this sensor is present, then the corresponding 534 * SENSOR_TYPE_GYROSCOPE must be present and both must return the 535 * same sensor_t::name and sensor_t::vendor. 536 */ 537#define SENSOR_TYPE_GYROSCOPE_UNCALIBRATED (16) 538 539 540/* 541 * SENSOR_TYPE_SIGNIFICANT_MOTION 542 * trigger-mode: one-shot 543 * wake-up sensor: yes 544 * 545 * A sensor of this type triggers an event each time significant motion 546 * is detected and automatically disables itself. 547 * The only allowed value to return is 1.0. 548 * 549 * A significant motion is a motion that might lead to a change in the user 550 * location. 551 * Examples of such motions are: 552 * walking, biking, sitting in a moving car, coach or train. 553 * Examples of situations that should not trigger significant motion: 554 * - phone in pocket and person is not moving 555 * - phone is on a table, even if the table shakes a bit due to nearby traffic 556 * or washing machine 557 * 558 * A note on false positive / false negative / power consumption tradeoff 559 * - The goal of this sensor is to save power. 560 * - Triggering an event when the user is not moving (false positive) is costly 561 * in terms of power, so it should be avoided. 562 * - Not triggering an event when the user is moving (false negative) is 563 * - acceptable as long as it is not done repeatedly. If the user has been 564 * walking for 10 seconds, not triggering an event within those 10 seconds 565 * is not acceptable. 566 * 567 * IMPORTANT NOTE: this sensor type is very different from other types 568 * in that it must work when the screen is off without the need of 569 * holding a partial wake-lock and MUST allow the SoC to go into suspend. 570 * When significant motion is detected, the sensor must awaken the SoC and 571 * the event be reported. 572 * 573 * If a particular hardware cannot support this mode of operation then this 574 * sensor type MUST NOT be reported by the HAL. ie: it is not acceptable 575 * to "emulate" this sensor in the HAL. 576 * 577 * The whole point of this sensor type is to save power by keeping the 578 * SoC in suspend mode when the device is at rest. 579 * 580 * When the sensor is not activated, it must also be deactivated in the 581 * hardware: it must not wake up the SoC anymore, even in case of 582 * significant motion. 583 * 584 * setDelay() has no effect and is ignored. 585 * Once a "significant motion" event is returned, a sensor of this type 586 * must disables itself automatically, as if activate(..., 0) had been called. 587 */ 588 589#define SENSOR_TYPE_SIGNIFICANT_MOTION (17) 590 591 592/* 593 * SENSOR_TYPE_STEP_DETECTOR 594 * trigger-mode: special 595 * wake-up sensor: no 596 * 597 * A sensor of this type triggers an event each time a step is taken 598 * by the user. The only allowed value to return is 1.0 and an event is 599 * generated for each step. Like with any other event, the timestamp 600 * indicates when the event (here the step) occurred, this corresponds to when 601 * the foot hit the ground, generating a high variation in acceleration. 602 * 603 * While this sensor operates, it shall not disrupt any other sensors, in 604 * particular, but not limited to, the accelerometer; which might very well 605 * be in use as well. 606 * 607 * This sensor must be low power. That is, if the step detection cannot be 608 * done in hardware, this sensor should not be defined. Also, when the 609 * step detector is activated and the accelerometer is not, only steps should 610 * trigger interrupts (not accelerometer data). 611 * 612 * setDelay() has no impact on this sensor type 613 */ 614 615#define SENSOR_TYPE_STEP_DETECTOR (18) 616 617 618/* 619 * SENSOR_TYPE_STEP_COUNTER 620 * trigger-mode: on-change 621 * wake-up sensor: no 622 * 623 * A sensor of this type returns the number of steps taken by the user since 624 * the last reboot while activated. The value is returned as a uint64_t and is 625 * reset to zero only on a system reboot. 626 * 627 * The timestamp of the event is set to the time when the first step 628 * for that event was taken. 629 * See SENSOR_TYPE_STEP_DETECTOR for the signification of the time of a step. 630 * 631 * The minimum size of the hardware's internal counter shall be 16 bits 632 * (this restriction is here to avoid too frequent wake-ups when the 633 * delay is very large). 634 * 635 * IMPORTANT NOTE: this sensor type is different from other types 636 * in that it must work when the screen is off without the need of 637 * holding a partial wake-lock and MUST allow the SoC to go into suspend. 638 * Unlike other sensors, while in suspend mode this sensor must stay active, 639 * no events are reported during that time but, steps continue to be 640 * accounted for; an event will be reported as soon as the SoC resumes if 641 * the timeout has expired. 642 * 643 * In other words, when the screen is off and the device allowed to 644 * go into suspend mode, we don't want to be woken up, regardless of the 645 * setDelay() value, but the steps shall continue to be counted. 646 * 647 * The driver must however ensure that the internal step count never 648 * overflows. It is allowed in this situation to wake the SoC up so the 649 * driver can do the counter maintenance. 650 * 651 * While this sensor operates, it shall not disrupt any other sensors, in 652 * particular, but not limited to, the accelerometer; which might very well 653 * be in use as well. 654 * 655 * If a particular hardware cannot support these modes of operation then this 656 * sensor type MUST NOT be reported by the HAL. ie: it is not acceptable 657 * to "emulate" this sensor in the HAL. 658 * 659 * This sensor must be low power. That is, if the step detection cannot be 660 * done in hardware, this sensor should not be defined. Also, when the 661 * step counter is activated and the accelerometer is not, only steps should 662 * trigger interrupts (not accelerometer data). 663 * 664 * The whole point of this sensor type is to save power by keeping the 665 * SoC in suspend mode when the device is at rest. 666 */ 667 668#define SENSOR_TYPE_STEP_COUNTER (19) 669 670/* 671 * SENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR 672 * trigger-mode: continuous 673 * wake-up sensor: no 674 * 675 * Similar to SENSOR_TYPE_ROTATION_VECTOR, but using a magnetometer instead 676 * of using a gyroscope. 677 * 678 * This sensor must be based on a magnetometer. It cannot be implemented using 679 * a gyroscope, and gyroscope input cannot be used by this sensor. 680 * 681 * Just like SENSOR_TYPE_ROTATION_VECTOR, this sensor reports an estimated 682 * heading accuracy: 683 * sensors_event_t.data[3] = estimated_accuracy (in radians) 684 * The heading error must be less than estimated_accuracy 95% of the time 685 * 686 * see SENSOR_TYPE_ROTATION_VECTOR for more details 687 */ 688#define SENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR (20) 689 690/** 691 * Values returned by the accelerometer in various locations in the universe. 692 * all values are in SI units (m/s^2) 693 */ 694#define GRAVITY_SUN (275.0f) 695#define GRAVITY_EARTH (9.80665f) 696 697/** Maximum magnetic field on Earth's surface */ 698#define MAGNETIC_FIELD_EARTH_MAX (60.0f) 699 700/** Minimum magnetic field on Earth's surface */ 701#define MAGNETIC_FIELD_EARTH_MIN (30.0f) 702 703 704/** 705 * status of orientation sensor 706 */ 707 708#define SENSOR_STATUS_UNRELIABLE 0 709#define SENSOR_STATUS_ACCURACY_LOW 1 710#define SENSOR_STATUS_ACCURACY_MEDIUM 2 711#define SENSOR_STATUS_ACCURACY_HIGH 3 712 713 714/** 715 * sensor event data 716 */ 717typedef struct { 718 union { 719 float v[3]; 720 struct { 721 float x; 722 float y; 723 float z; 724 }; 725 struct { 726 float azimuth; 727 float pitch; 728 float roll; 729 }; 730 }; 731 int8_t status; 732 uint8_t reserved[3]; 733} sensors_vec_t; 734 735/** 736 * uncalibrated gyroscope and magnetometer event data 737 */ 738typedef struct { 739 float x_uncalib; 740 float y_uncalib; 741 float z_uncalib; 742 float x_bias; 743 float y_bias; 744 float z_bias; 745} uncalibrated_event_t; 746 747/** 748 * Union of the various types of sensor data 749 * that can be returned. 750 */ 751typedef struct sensors_event_t { 752 /* must be sizeof(struct sensors_event_t) */ 753 int32_t version; 754 755 /* sensor identifier */ 756 int32_t sensor; 757 758 /* sensor type */ 759 int32_t type; 760 761 /* reserved */ 762 int32_t reserved0; 763 764 /* time is in nanosecond */ 765 int64_t timestamp; 766 767 union { 768 float data[16]; 769 770 /* acceleration values are in meter per second per second (m/s^2) */ 771 sensors_vec_t acceleration; 772 773 /* magnetic vector values are in micro-Tesla (uT) */ 774 sensors_vec_t magnetic; 775 776 /* orientation values are in degrees */ 777 sensors_vec_t orientation; 778 779 /* gyroscope values are in rad/s */ 780 sensors_vec_t gyro; 781 782 /* temperature is in degrees centigrade (Celsius) */ 783 float temperature; 784 785 /* distance in centimeters */ 786 float distance; 787 788 /* light in SI lux units */ 789 float light; 790 791 /* pressure in hectopascal (hPa) */ 792 float pressure; 793 794 /* relative humidity in percent */ 795 float relative_humidity; 796 797 /* step-counter */ 798 uint64_t step_counter; 799 800 /* uncalibrated gyroscope values are in rad/s */ 801 uncalibrated_event_t uncalibrated_gyro; 802 803 /* uncalibrated magnetometer values are in micro-Teslas */ 804 uncalibrated_event_t uncalibrated_magnetic; 805 }; 806 uint32_t reserved1[4]; 807} sensors_event_t; 808 809 810 811struct sensor_t; 812 813/** 814 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM 815 * and the fields of this data structure must begin with hw_module_t 816 * followed by module specific information. 817 */ 818struct sensors_module_t { 819 struct hw_module_t common; 820 821 /** 822 * Enumerate all available sensors. The list is returned in "list". 823 * @return number of sensors in the list 824 */ 825 int (*get_sensors_list)(struct sensors_module_t* module, 826 struct sensor_t const** list); 827}; 828 829struct sensor_t { 830 831 /* Name of this sensor. 832 * All sensors of the same "type" must have a different "name". 833 */ 834 const char* name; 835 836 /* vendor of the hardware part */ 837 const char* vendor; 838 839 /* version of the hardware part + driver. The value of this field 840 * must increase when the driver is updated in a way that changes the 841 * output of this sensor. This is important for fused sensors when the 842 * fusion algorithm is updated. 843 */ 844 int version; 845 846 /* handle that identifies this sensors. This handle is used to reference 847 * this sensor throughout the HAL API. 848 */ 849 int handle; 850 851 /* this sensor's type. */ 852 int type; 853 854 /* maximum range of this sensor's value in SI units */ 855 float maxRange; 856 857 /* smallest difference between two values reported by this sensor */ 858 float resolution; 859 860 /* rough estimate of this sensor's power consumption in mA */ 861 float power; 862 863 /* this value depends on the trigger mode: 864 * 865 * continuous: minimum sample period allowed in microseconds 866 * on-change : 0 867 * one-shot :-1 868 * special : 0, unless otherwise noted 869 */ 870 int32_t minDelay; 871 872 /* reserved fields, must be zero */ 873 void* reserved[8]; 874}; 875 876 877/* 878 * sensors_poll_device_t is used with SENSORS_DEVICE_API_VERSION_0_1 879 * and is present for backward binary and source compatibility. 880 * (see documentation of the hooks in struct sensors_poll_device_1 below) 881 */ 882struct sensors_poll_device_t { 883 struct hw_device_t common; 884 int (*activate)(struct sensors_poll_device_t *dev, 885 int handle, int enabled); 886 int (*setDelay)(struct sensors_poll_device_t *dev, 887 int handle, int64_t ns); 888 int (*poll)(struct sensors_poll_device_t *dev, 889 sensors_event_t* data, int count); 890}; 891 892/* 893 * struct sensors_poll_device_1 is used with SENSORS_DEVICE_API_VERSION_1_0 894 */ 895typedef struct sensors_poll_device_1 { 896 union { 897 /* sensors_poll_device_1 is compatible with sensors_poll_device_t, 898 * and can be down-cast to it 899 */ 900 struct sensors_poll_device_t v0; 901 902 struct { 903 struct hw_device_t common; 904 905 /* Activate/de-activate one sensor. 906 * 907 * handle is the handle of the sensor to change. 908 * enabled set to 1 to enable, or 0 to disable the sensor. 909 * 910 * unless otherwise noted in the sensor types definitions, an 911 * activated sensor never prevents the SoC to go into suspend 912 * mode; that is, the HAL shall not hold a partial wake-lock on 913 * behalf of applications. 914 * 915 * one-shot sensors de-activate themselves automatically upon 916 * receiving an event and they must still accept to be deactivated 917 * through a call to activate(..., ..., 0). 918 * 919 * if "enabled" is true and the sensor is already activated, this 920 * function is a no-op and succeeds. 921 * 922 * if "enabled" is false and the sensor is already de-activated, 923 * this function is a no-op and succeeds. 924 * 925 * return 0 on success, negative errno code otherwise 926 */ 927 int (*activate)(struct sensors_poll_device_t *dev, 928 int handle, int enabled); 929 930 /** 931 * Set the events's period in nanoseconds for a given sensor. 932 * 933 * What the period_ns parameter means depends on the specified 934 * sensor's trigger mode: 935 * 936 * continuous: setDelay() sets the sampling rate. 937 * on-change: setDelay() limits the delivery rate of events 938 * one-shot: setDelay() is ignored. it has no effect. 939 * special: see specific sensor type definitions 940 * 941 * For continuous and on-change sensors, if the requested value is 942 * less than sensor_t::minDelay, then it's silently clamped to 943 * sensor_t::minDelay unless sensor_t::minDelay is 0, in which 944 * case it is clamped to >= 1ms. 945 * 946 * @return 0 if successful, < 0 on error 947 */ 948 int (*setDelay)(struct sensors_poll_device_t *dev, 949 int handle, int64_t period_ns); 950 951 /** 952 * Returns an array of sensor data. 953 * This function must block until events are available. 954 * 955 * return the number of events read on success, or -errno in case 956 * of an error. 957 * 958 * The number of events returned in data must be less or equal 959 * to SENSORS_QUERY_MAX_EVENTS_BATCH_COUNT. 960 * 961 * This function shall never return 0 (no event). 962 */ 963 int (*poll)(struct sensors_poll_device_t *dev, 964 sensors_event_t* data, int count); 965 }; 966 }; 967 968 /* 969 * Used to retrieve information about the sensor HAL 970 * 971 * Returns 0 on success or -errno on error. 972 */ 973 int (*query)(struct sensors_poll_device_1* dev, int what, int* value); 974 975 976 /* 977 * Enables batch mode for the given sensor and sets the delay between events 978 * 979 * A timeout value of zero disables batch mode for the given sensor. 980 * 981 * The period_ns parameter is equivalent to calling setDelay() -- this 982 * function both enables or disables the batch mode AND sets the events's 983 * period in nanosecond. See setDelay() above for a detailed explanation of 984 * the period_ns parameter. 985 * 986 * While in batch mode sensor events are reported in batches at least 987 * every "timeout" nanosecond; that is all events since the previous batch 988 * are recorded and returned all at once. Batches can be interleaved and 989 * split, and as usual events of the same sensor type are time-ordered. 990 * 991 * setDelay() is not affected and it behaves as usual. 992 * 993 * Each event has a timestamp associated with it, the timestamp 994 * must be accurate and correspond to the time at which the event 995 * physically happened. 996 * 997 * If internal h/w FIFOs fill-up before the timeout, then events are 998 * reported at that point. No event shall be dropped or lost. 999 * 1000 * 1001 * INTERACTION WITH SUSPEND MODE: 1002 * ------------------------------ 1003 * 1004 * By default batch mode doesn't significantly change the interaction with 1005 * suspend mode, that is, sensors must continue to allow the SoC to 1006 * go into suspend mode and sensors must stay active to fill their 1007 * internal FIFO, in this mode, when the FIFO fills-up, it shall wrap 1008 * around (basically behave like a circular buffer, overwriting events). 1009 * As soon as the SoC comes out of suspend mode, a batch is produced with 1010 * as much as the recent history as possible, and batch operation 1011 * resumes as usual. 1012 * 1013 * The behavior described above allows applications to record the recent 1014 * history of a set of sensor while keeping the SoC into suspend. It 1015 * also allows the hardware to not have to rely on a wake-up interrupt line. 1016 * 1017 * There are cases however where an application cannot afford to lose 1018 * any events, even when the device goes into suspend mode. The behavior 1019 * specified above can be altered by setting the 1020 * SENSORS_BATCH_WAKE_UPON_FIFO_FULL flag. If this flag is set, the SoC 1021 * must be woken up from suspend and a batch must be returned before 1022 * the FIFO fills-up. Enough head room must be allocated in the FIFO to allow 1023 * the device to entirely come out of suspend (which might take a while and 1024 * is device dependent) such that no event are lost. 1025 * 1026 * If the hardware cannot support this mode, or, if the physical 1027 * FIFO is so small that the device would never be allowed to go into 1028 * suspend for at least 10 seconds, then this function MUST fail when 1029 * the flag SENSORS_BATCH_WAKE_UPON_FIFO_FULL is set, regardless of 1030 * the value of the timeout parameter. 1031 * 1032 * DRY RUN: 1033 * -------- 1034 * 1035 * If the flag SENSORS_BATCH_DRY_RUN is set, this function returns 1036 * without modifying the batch mode or the event period and has no side 1037 * effects, but returns errors as usual (as it would if this flag was 1038 * not set). This flag is used to check if batch mode is available for a 1039 * given configuration -- in particular for a given sensor at a given rate. 1040 * 1041 * 1042 * Return values: 1043 * -------------- 1044 * 1045 * Because sensors must be independent, the return value must not depend 1046 * on the state of the system (whether another sensor is on or not), 1047 * nor on whether the flag SENSORS_BATCH_DRY_RUN is set (in other words, 1048 * if a batch call with SENSORS_BATCH_DRY_RUN is successful, 1049 * the same call without SENSORS_BATCH_DRY_RUN must succeed as well). 1050 * 1051 * If successful, 0 is returned. 1052 * If the specified sensor doesn't support batch mode, -EINVAL is returned. 1053 * If the specified sensor's trigger-mode is one-shot, -EINVAL is returned. 1054 * If any of the constraint above cannot be satisfied, -EINVAL is returned. 1055 * 1056 * Note: the timeout parameter, when > 0, has no impact on whether this 1057 * function succeeds or fails. 1058 * 1059 * If timeout is set to 0, this function must succeed. 1060 * 1061 * 1062 * IMPLEMENTATION NOTES: 1063 * --------------------- 1064 * 1065 * batch mode, if supported, should happen at the hardware level, 1066 * typically using hardware FIFOs. In particular, it SHALL NOT be 1067 * implemented in the HAL, as this would be counter productive. 1068 * The goal here is to save significant amounts of power. 1069 * 1070 * batch mode can be enabled or disabled at any time, in particular 1071 * while the specified sensor is already enabled and this shall not 1072 * result in the loss of events. 1073 * 1074 * COMPARATIVE IMPORTANCE OF BATCHING FOR DIFFERENT SENSORS: 1075 * --------------------------------------------------------- 1076 * 1077 * On platforms on which hardware fifo size is limited, the system designers 1078 * might have to choose how much fifo to reserve for each sensor. To help 1079 * with this choice, Here is a list of applications made possible when 1080 * batching is implemented on the different sensors. 1081 * 1082 * High value: Low power pedestrian dead reckoning 1083 * Target batching time: 20 seconds to 1 minute 1084 * Sensors to batch: 1085 * - Step detector 1086 * - Rotation vector or game rotation vector at 5Hz 1087 * Gives us step and heading while letting the AP go to Suspend. 1088 * 1089 * High value: Medium power activity/gesture recognition 1090 * Target batching time: 3 seconds 1091 * Sensors to batch: accelerometer between 20Hz and 50Hz 1092 * Allows recognizing arbitrary activities and gestures without having 1093 * to keep the AP fully awake while the data is collected. 1094 * 1095 * Medium-high value: Interrupt load reduction 1096 * Target batching time: < 1 second 1097 * Sensors to batch: any high frequency sensor. 1098 * If the gyroscope is set at 800Hz, even batching just 10 gyro events can 1099 * reduce the number of interrupts from 800/second to 80/second. 1100 * 1101 * Medium value: Continuous low frequency data collection 1102 * Target batching time: > 1 minute 1103 * Sensors to batch: barometer, humidity sensor, other low frequency 1104 * sensors. 1105 * Allows creating monitoring applications at low power. 1106 * 1107 * Medium value: Continuous full-sensors collection 1108 * Target batching time: > 1 minute 1109 * Sensors to batch: all, at high frequencies 1110 * Allows full collection of sensor data while leaving the AP in 1111 * suspend mode. Only to consider if fifo space is not an issue. 1112 */ 1113 int (*batch)(struct sensors_poll_device_1* dev, 1114 int handle, int flags, int64_t period_ns, int64_t timeout); 1115 1116 void (*reserved_procs[8])(void); 1117 1118} sensors_poll_device_1_t; 1119 1120 1121 1122/** convenience API for opening and closing a device */ 1123 1124static inline int sensors_open(const struct hw_module_t* module, 1125 struct sensors_poll_device_t** device) { 1126 return module->methods->open(module, 1127 SENSORS_HARDWARE_POLL, (struct hw_device_t**)device); 1128} 1129 1130static inline int sensors_close(struct sensors_poll_device_t* device) { 1131 return device->common.close(&device->common); 1132} 1133 1134static inline int sensors_open_1(const struct hw_module_t* module, 1135 sensors_poll_device_1_t** device) { 1136 return module->methods->open(module, 1137 SENSORS_HARDWARE_POLL, (struct hw_device_t**)device); 1138} 1139 1140static inline int sensors_close_1(sensors_poll_device_1_t* device) { 1141 return device->common.close(&device->common); 1142} 1143 1144__END_DECLS 1145 1146#endif // ANDROID_SENSORS_INTERFACE_H 1147