sensors.h revision fbe985ca9c8cd502ce9b8b0332dbdd639e9b723e
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: a single event is reported and the sensor returns to the 185 * disabled state, no further events are reported. setDelay() is 186 * ignored. 187 * eg: significant motion sensor 188 * special: see details in the sensor type specification below 189 * 190 */ 191 192/* 193 * SENSOR_TYPE_ACCELEROMETER 194 * trigger-mode: continuous 195 * wake-up sensor: no 196 * 197 * All values are in SI units (m/s^2) and measure the acceleration of the 198 * device minus the force of gravity. 199 * 200 * Acceleration sensors return sensor events for all 3 axes at a constant 201 * rate defined by setDelay(). 202 * 203 * x: Acceleration on the x-axis 204 * y: Acceleration on the y-axis 205 * z: Acceleration on the z-axis 206 * 207 * Note that the readings from the accelerometer include the acceleration 208 * due to gravity (which is opposite to the direction of the gravity vector). 209 * 210 * Examples: 211 * The norm of <x, y, z> should be close to 0 when in free fall. 212 * 213 * When the device lies flat on a table and is pushed on its left side 214 * toward the right, the x acceleration value is positive. 215 * 216 * When the device lies flat on a table, the acceleration value is +9.81, 217 * which correspond to the acceleration of the device (0 m/s^2) minus the 218 * force of gravity (-9.81 m/s^2). 219 * 220 * When the device lies flat on a table and is pushed toward the sky, the 221 * acceleration value is greater than +9.81, which correspond to the 222 * acceleration of the device (+A m/s^2) minus the force of 223 * gravity (-9.81 m/s^2). 224 */ 225#define SENSOR_TYPE_ACCELEROMETER (1) 226 227/* 228 * SENSOR_TYPE_GEOMAGNETIC_FIELD 229 * trigger-mode: continuous 230 * wake-up sensor: no 231 * 232 * All values are in micro-Tesla (uT) and measure the geomagnetic 233 * field in the X, Y and Z axis. 234 * 235 * Returned values include calibration mechanisms such that the vector is 236 * aligned with the magnetic declination and heading of the earth's 237 * geomagnetic field. 238 * 239 * Magnetic Field sensors return sensor events for all 3 axes at a constant 240 * rate defined by setDelay(). 241 */ 242#define SENSOR_TYPE_GEOMAGNETIC_FIELD (2) 243#define SENSOR_TYPE_MAGNETIC_FIELD SENSOR_TYPE_GEOMAGNETIC_FIELD 244 245/* 246 * SENSOR_TYPE_ORIENTATION 247 * trigger-mode: continuous 248 * wake-up sensor: no 249 * 250 * All values are angles in degrees. 251 * 252 * Orientation sensors return sensor events for all 3 axes at a constant 253 * rate defined by setDelay(). 254 * 255 * azimuth: angle between the magnetic north direction and the Y axis, around 256 * the Z axis (0<=azimuth<360). 257 * 0=North, 90=East, 180=South, 270=West 258 * 259 * pitch: Rotation around X axis (-180<=pitch<=180), with positive values when 260 * the z-axis moves toward the y-axis. 261 * 262 * roll: Rotation around Y axis (-90<=roll<=90), with positive values when 263 * the x-axis moves towards the z-axis. 264 * 265 * Note: For historical reasons the roll angle is positive in the clockwise 266 * direction (mathematically speaking, it should be positive in the 267 * counter-clockwise direction): 268 * 269 * Z 270 * ^ 271 * (+roll) .--> | 272 * / | 273 * | | roll: rotation around Y axis 274 * X <-------(.) 275 * Y 276 * note that +Y == -roll 277 * 278 * 279 * 280 * Note: This definition is different from yaw, pitch and roll used in aviation 281 * where the X axis is along the long side of the plane (tail to nose). 282 */ 283#define SENSOR_TYPE_ORIENTATION (3) 284 285/* 286 * SENSOR_TYPE_GYROSCOPE 287 * trigger-mode: continuous 288 * wake-up sensor: no 289 * 290 * All values are in radians/second and measure the rate of rotation 291 * around the X, Y and Z axis. The coordinate system is the same as is 292 * used for the acceleration sensor. Rotation is positive in the 293 * counter-clockwise direction (right-hand rule). That is, an observer 294 * looking from some positive location on the x, y or z axis at a device 295 * positioned on the origin would report positive rotation if the device 296 * appeared to be rotating counter clockwise. Note that this is the 297 * standard mathematical definition of positive rotation and does not agree 298 * with the definition of roll given earlier. 299 * The range should at least be 17.45 rad/s (ie: ~1000 deg/s). 300 * 301 * automatic gyro-drift compensation is allowed but not required. 302 */ 303#define SENSOR_TYPE_GYROSCOPE (4) 304 305/* 306 * SENSOR_TYPE_LIGHT 307 * trigger-mode: on-change 308 * wake-up sensor: no 309 * 310 * The light sensor value is returned in SI lux units. 311 */ 312#define SENSOR_TYPE_LIGHT (5) 313 314/* 315 * SENSOR_TYPE_PRESSURE 316 * trigger-mode: continuous 317 * wake-up sensor: no 318 * 319 * The pressure sensor return the athmospheric pressure in hectopascal (hPa) 320 */ 321#define SENSOR_TYPE_PRESSURE (6) 322 323/* SENSOR_TYPE_TEMPERATURE is deprecated in the HAL */ 324#define SENSOR_TYPE_TEMPERATURE (7) 325 326/* 327 * SENSOR_TYPE_PROXIMITY 328 * trigger-mode: on-change 329 * wake-up sensor: yes 330 * 331 * The distance value is measured in centimeters. Note that some proximity 332 * sensors only support a binary "close" or "far" measurement. In this case, 333 * the sensor should report its maxRange value in the "far" state and a value 334 * less than maxRange in the "near" state. 335 */ 336#define SENSOR_TYPE_PROXIMITY (8) 337 338/* 339 * SENSOR_TYPE_GRAVITY 340 * trigger-mode: continuous 341 * wake-up sensor: no 342 * 343 * A gravity output indicates the direction of and magnitude of gravity in 344 * the devices's coordinates. On Earth, the magnitude is 9.8 m/s^2. 345 * Units are m/s^2. The coordinate system is the same as is used for the 346 * acceleration sensor. When the device is at rest, the output of the 347 * gravity sensor should be identical to that of the accelerometer. 348 */ 349#define SENSOR_TYPE_GRAVITY (9) 350 351/* 352 * SENSOR_TYPE_LINEAR_ACCELERATION 353 * trigger-mode: continuous 354 * wake-up sensor: no 355 * 356 * Indicates the linear acceleration of the device in device coordinates, 357 * not including gravity. 358 * 359 * The output is conceptually: 360 * output of TYPE_ACCELERATION - output of TYPE_GRAVITY 361 * 362 * Readings on all axes should be close to 0 when device lies on a table. 363 * Units are m/s^2. 364 * The coordinate system is the same as is used for the acceleration sensor. 365 */ 366#define SENSOR_TYPE_LINEAR_ACCELERATION (10) 367 368 369/* 370 * SENSOR_TYPE_ROTATION_VECTOR 371 * trigger-mode: continuous 372 * wake-up sensor: no 373 * 374 * A rotation vector represents the orientation of the device as a combination 375 * of an angle and an axis, in which the device has rotated through an angle 376 * theta around an axis <x, y, z>. The three elements of the rotation vector 377 * are <x*sin(theta/2), y*sin(theta/2), z*sin(theta/2)>, such that the magnitude 378 * of the rotation vector is equal to sin(theta/2), and the direction of the 379 * rotation vector is equal to the direction of the axis of rotation. The three 380 * elements of the rotation vector are equal to the last three components of a 381 * unit quaternion <cos(theta/2), x*sin(theta/2), y*sin(theta/2), z*sin(theta/2)>. 382 * Elements of the rotation vector are unitless. The x, y, and z axis are defined 383 * in the same was as for the acceleration sensor. 384 * 385 * The reference coordinate system is defined as a direct orthonormal basis, 386 * where: 387 * 388 * - X is defined as the vector product Y.Z (It is tangential to 389 * the ground at the device's current location and roughly points East). 390 * 391 * - Y is tangential to the ground at the device's current location and 392 * points towards the magnetic North Pole. 393 * 394 * - Z points towards the sky and is perpendicular to the ground. 395 * 396 * 397 * The rotation-vector is stored as: 398 * 399 * sensors_event_t.data[0] = x*sin(theta/2) 400 * sensors_event_t.data[1] = y*sin(theta/2) 401 * sensors_event_t.data[2] = z*sin(theta/2) 402 * sensors_event_t.data[3] = cos(theta/2) 403 */ 404#define SENSOR_TYPE_ROTATION_VECTOR (11) 405 406/* 407 * SENSOR_TYPE_RELATIVE_HUMIDITY 408 * trigger-mode: on-change 409 * wake-up sensor: no 410 * 411 * A relative humidity sensor measures relative ambient air humidity and 412 * returns a value in percent. 413 */ 414#define SENSOR_TYPE_RELATIVE_HUMIDITY (12) 415 416/* 417 * SENSOR_TYPE_AMBIENT_TEMPERATURE 418 * trigger-mode: on-change 419 * wake-up sensor: no 420 * 421 * The ambient (room) temperature in degree Celsius. 422 */ 423#define SENSOR_TYPE_AMBIENT_TEMPERATURE (13) 424 425/* 426 * SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED 427 * trigger-mode: continuous 428 * wake-up sensor: no 429 * 430 * All values are in micro-Tesla (uT) and measure the ambient magnetic 431 * field in the X, Y and Z axis. 432 * 433 * No periodic calibration is performed (ie: there are no discontinuities 434 * in the data stream while using this sensor). Assumptions that the the 435 * magnetic field is due to the Earth's poles should be avoided. 436 * 437 * Factory calibration and temperature compensation should still be applied. 438 * 439 * If this sensor is present, then the corresponding 440 * SENSOR_TYPE_MAGNETIC_FIELD must be present and both must return the 441 * same sensor_t::name and sensor_t::vendor. 442 */ 443#define SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED (14) 444 445/* 446 * SENSOR_TYPE_GAME_ROTATION_VECTOR 447 * trigger-mode: continuous 448 * wake-up sensor: no 449 * 450 * SENSOR_TYPE_GAME_ROTATION_VECTOR is identical to SENSOR_TYPE_ROTATION_VECTOR, 451 * except that it doesn't use the geomagnetic field. Therefore the Y axis doesn't 452 * point north, but instead to some other reference, that reference is allowed 453 * to drift by the same order of magnitude than the gyroscope drift around 454 * the Z axis. 455 * 456 * In the ideal case, a phone rotated and returning to the same real-world 457 * orientation should report the same game rotation vector 458 * (without using the earth's geomagnetic field). 459 * 460 * see SENSOR_TYPE_ROTATION_VECTOR for more details 461 */ 462#define SENSOR_TYPE_GAME_ROTATION_VECTOR (15) 463 464/* 465 * SENSOR_TYPE_GYROSCOPE_UNCALIBRATED 466 * trigger-mode: continuous 467 * wake-up sensor: no 468 * 469 * All values are in radians/second and measure the rate of rotation 470 * around the X, Y and Z axis. An estimation of the drift on each axis is 471 * reported as well. 472 * 473 * No gyro-drift compensation shall be performed. 474 * Factory calibration and temperature compensation should still be applied 475 * to the rate of rotation (angular speeds). 476 * 477 * The coordinate system is the same as is 478 * used for the acceleration sensor. Rotation is positive in the 479 * counter-clockwise direction (right-hand rule). That is, an observer 480 * looking from some positive location on the x, y or z axis at a device 481 * positioned on the origin would report positive rotation if the device 482 * appeared to be rotating counter clockwise. Note that this is the 483 * standard mathematical definition of positive rotation and does not agree 484 * with the definition of roll given earlier. 485 * The range should at least be 17.45 rad/s (ie: ~1000 deg/s). 486 * 487 * sensors_event_t:: 488 * data[0] : angular speed (w/o drift compensation) around the X axis in rad/s 489 * data[1] : angular speed (w/o drift compensation) around the Y axis in rad/s 490 * data[2] : angular speed (w/o drift compensation) around the Z axis in rad/s 491 * data[3] : estimated drift around X axis in rad/s 492 * data[4] : estimated drift around Y axis in rad/s 493 * data[5] : estimated drift around Z axis in rad/s 494 * 495 * IMPLEMENTATION NOTES: 496 * 497 * If the implementation is not able to estimate the drift, then this 498 * sensor MUST NOT be reported by this HAL. Instead, the regular 499 * SENSOR_TYPE_GYROSCOPE is used without drift compensation. 500 * 501 * If this sensor is present, then the corresponding 502 * SENSOR_TYPE_GYROSCOPE must be present and both must return the 503 * same sensor_t::name and sensor_t::vendor. 504 */ 505#define SENSOR_TYPE_GYROSCOPE_UNCALIBRATED (16) 506 507 508/* 509 * SENSOR_TYPE_SIGNIFICANT_MOTION 510 * trigger-mode: one-shot 511 * wake-up sensor: yes 512 * 513 * A sensor of this type triggers an event each time significant motion 514 * is detected and automatically disables itself. 515 * The only allowed value to return is 1.0. 516 * 517 * 518 * TODO: give more details about what constitute significant motion 519 * and/or what algorithm is to be used 520 * 521 * 522 * IMPORTANT NOTE: this sensor type is very different from other types 523 * in that it must work when the screen is off without the need of 524 * holding a partial wake-lock and MUST allow the SoC to go into suspend. 525 * When significant motion is detected, the sensor must awaken the SoC and 526 * the event be reported. 527 * 528 * If a particular hardware cannot support this mode of operation then this 529 * sensor type MUST NOT be reported by the HAL. ie: it is not acceptable 530 * to "emulate" this sensor in the HAL. 531 * 532 * The whole point of this sensor type is to save power by keeping the 533 * SoC in suspend mode when the device is at rest. 534 * 535 * When the sensor is not activated, it must also be deactivated in the 536 * hardware: it must not wake up the SoC anymore, even in case of 537 * significant motion. 538 * 539 * setDelay() has no effect and is ignored. 540 * Once a "significant motion" event is returned, a sensor of this type 541 * must disables itself automatically, as if activate(..., 0) had been called. 542 */ 543 544#define SENSOR_TYPE_SIGNIFICANT_MOTION (17) 545 546 547/* 548 * SENSOR_TYPE_STEP_DETECTOR 549 * trigger-mode: special 550 * wake-up sensor: no 551 * 552 * A sensor of this type triggers an event each time a step is taken 553 * by the user. The only allowed value to return is 1.0 and an event is 554 * generated for each step. Like with any other event, the timestamp 555 * indicates when the event (here the step) occurred, this corresponds to when 556 * the foot hit the ground, generating a high variation in acceleration. 557 * 558 * While this sensor operates, it shall not disrupt any other sensors, in 559 * particular, but not limited to, the accelerometer; which might very well 560 * be in use as well. 561 * 562 * This sensor must be low power. That is, if the step detection cannot be 563 * done in hardware, this sensor should not be defined. Also, when the 564 * step detector is activated and the accelerometer is not, only steps should 565 * trigger interrupts (not accelerometer data). 566 * 567 * setDelay() has no impact on this sensor type 568 */ 569 570#define SENSOR_TYPE_STEP_DETECTOR (18) 571 572 573/* 574 * SENSOR_TYPE_STEP_COUNTER 575 * trigger-mode: on-change 576 * wake-up sensor: no 577 * 578 * A sensor of this type returns the number of steps taken by the user since 579 * the last reboot while activated. The value is returned as a uint64_t and is 580 * reset to zero only on a system reboot. 581 * 582 * The timestamp of the event is set to the time when the first step 583 * for that event was taken. 584 * See SENSOR_TYPE_STEP_DETECTOR for the signification of the time of a step. 585 * 586 * The minimum size of the hardware's internal counter shall be 16 bits 587 * (this restriction is here to avoid too frequent wake-ups when the 588 * delay is very large). 589 * 590 * IMPORTANT NOTE: this sensor type is different from other types 591 * in that it must work when the screen is off without the need of 592 * holding a partial wake-lock and MUST allow the SoC to go into suspend. 593 * Unlike other sensors, while in suspend mode this sensor must stay active, 594 * no events are reported during that time but, steps continue to be 595 * accounted for; an event will be reported as soon as the SoC resumes if 596 * the timeout has expired. 597 * 598 * In other words, when the screen is off and the device allowed to 599 * go into suspend mode, we don't want to be woken up, regardless of the 600 * setDelay() value, but the steps shall continue to be counted. 601 * 602 * The driver must however ensure that the internal step count never 603 * overflows. It is allowed in this situation to wake the SoC up so the 604 * driver can do the counter maintenance. 605 * 606 * While this sensor operates, it shall not disrupt any other sensors, in 607 * particular, but not limited to, the accelerometer; which might very well 608 * be in use as well. 609 * 610 * If a particular hardware cannot support these modes of operation then this 611 * sensor type MUST NOT be reported by the HAL. ie: it is not acceptable 612 * to "emulate" this sensor in the HAL. 613 * 614 * This sensor must be low power. That is, if the step detection cannot be 615 * done in hardware, this sensor should not be defined. Also, when the 616 * step counter is activated and the accelerometer is not, only steps should 617 * trigger interrupts (not accelerometer data). 618 * 619 * The whole point of this sensor type is to save power by keeping the 620 * SoC in suspend mode when the device is at rest. 621 */ 622 623#define SENSOR_TYPE_STEP_COUNTER (19) 624 625 626/** 627 * Values returned by the accelerometer in various locations in the universe. 628 * all values are in SI units (m/s^2) 629 */ 630#define GRAVITY_SUN (275.0f) 631#define GRAVITY_EARTH (9.80665f) 632 633/** Maximum magnetic field on Earth's surface */ 634#define MAGNETIC_FIELD_EARTH_MAX (60.0f) 635 636/** Minimum magnetic field on Earth's surface */ 637#define MAGNETIC_FIELD_EARTH_MIN (30.0f) 638 639 640/** 641 * status of orientation sensor 642 */ 643 644#define SENSOR_STATUS_UNRELIABLE 0 645#define SENSOR_STATUS_ACCURACY_LOW 1 646#define SENSOR_STATUS_ACCURACY_MEDIUM 2 647#define SENSOR_STATUS_ACCURACY_HIGH 3 648 649 650/** 651 * sensor event data 652 */ 653typedef struct { 654 union { 655 float v[3]; 656 struct { 657 float x; 658 float y; 659 float z; 660 }; 661 struct { 662 float azimuth; 663 float pitch; 664 float roll; 665 }; 666 }; 667} sensors_data_t; 668 669typedef struct { 670 union { 671 float v[3]; 672 struct { 673 float x; 674 float y; 675 float z; 676 }; 677 struct { 678 float azimuth; 679 float pitch; 680 float roll; 681 }; 682 }; 683 int8_t status; 684 uint8_t reserved[3]; 685} sensors_vec_t; 686 687/** 688 * Union of the various types of sensor data 689 * that can be returned. 690 */ 691typedef struct sensors_event_t { 692 /* must be sizeof(struct sensors_event_t) */ 693 int32_t version; 694 695 /* sensor identifier */ 696 int32_t sensor; 697 698 /* sensor type */ 699 int32_t type; 700 701 /* reserved */ 702 int32_t reserved0; 703 704 /* time is in nanosecond */ 705 int64_t timestamp; 706 707 union { 708 float data[16]; 709 710 /* acceleration values are in meter per second per second (m/s^2) */ 711 sensors_data_t acceleration; 712 713 /* magnetic vector values are in micro-Tesla (uT) */ 714 sensors_vec_t magnetic; 715 716 /* orientation values are in degrees */ 717 sensors_vec_t orientation; 718 719 /* gyroscope values are in rad/s */ 720 sensors_data_t gyro; 721 722 /* temperature is in degrees centigrade (Celsius) */ 723 float temperature; 724 725 /* distance in centimeters */ 726 float distance; 727 728 /* light in SI lux units */ 729 float light; 730 731 /* pressure in hectopascal (hPa) */ 732 float pressure; 733 734 /* relative humidity in percent */ 735 float relative_humidity; 736 737 /* step-counter */ 738 uint64_t step_counter; 739 }; 740 uint32_t reserved1[4]; 741} sensors_event_t; 742 743 744 745struct sensor_t; 746 747/** 748 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM 749 * and the fields of this data structure must begin with hw_module_t 750 * followed by module specific information. 751 */ 752struct sensors_module_t { 753 struct hw_module_t common; 754 755 /** 756 * Enumerate all available sensors. The list is returned in "list". 757 * @return number of sensors in the list 758 */ 759 int (*get_sensors_list)(struct sensors_module_t* module, 760 struct sensor_t const** list); 761}; 762 763struct sensor_t { 764 765 /* Name of this sensor. 766 * All sensors of the same "type" must have a different "name". 767 */ 768 const char* name; 769 770 /* vendor of the hardware part */ 771 const char* vendor; 772 773 /* version of the hardware part + driver. The value of this field 774 * must increase when the driver is updated in a way that changes the 775 * output of this sensor. This is important for fused sensors when the 776 * fusion algorithm is updated. 777 */ 778 int version; 779 780 /* handle that identifies this sensors. This handle is used to reference 781 * this sensor throughout the HAL API. 782 */ 783 int handle; 784 785 /* this sensor's type. */ 786 int type; 787 788 /* maximum range of this sensor's value in SI units */ 789 float maxRange; 790 791 /* smallest difference between two values reported by this sensor */ 792 float resolution; 793 794 /* rough estimate of this sensor's power consumption in mA */ 795 float power; 796 797 /* this value depends on the trigger mode: 798 * 799 * continuous: minimum sample period allowed in microseconds 800 * on-change : 0 801 * one-shot :-1 802 * special : 0, unless otherwise noted 803 */ 804 int32_t minDelay; 805 806 /* reserved fields, must be zero */ 807 void* reserved[8]; 808}; 809 810 811/* 812 * sensors_poll_device_t is used with SENSORS_DEVICE_API_VERSION_0_1 813 * and is present for backward binary and source compatibility. 814 * (see documentation of the hooks in struct sensors_poll_device_1 below) 815 */ 816struct sensors_poll_device_t { 817 struct hw_device_t common; 818 int (*activate)(struct sensors_poll_device_t *dev, 819 int handle, int enabled); 820 int (*setDelay)(struct sensors_poll_device_t *dev, 821 int handle, int64_t ns); 822 int (*poll)(struct sensors_poll_device_t *dev, 823 sensors_event_t* data, int count); 824}; 825 826/* 827 * struct sensors_poll_device_1 is used with SENSORS_DEVICE_API_VERSION_1_0 828 */ 829typedef struct sensors_poll_device_1 { 830 union { 831 /* sensors_poll_device_1 is compatible with sensors_poll_device_t, 832 * and can be down-cast to it 833 */ 834 struct sensors_poll_device_t v0; 835 836 struct { 837 struct hw_device_t common; 838 839 /* Activate/de-activate one sensor. 840 * 841 * handle is the handle of the sensor to change. 842 * enabled set to 1 to enable, or 0 to disable the sensor. 843 * 844 * unless otherwise noted in the sensor types definitions, an 845 * activated sensor never prevents the SoC to go into suspend 846 * mode; that is, the HAL shall not hold a partial wake-lock on 847 * behalf of applications. 848 * 849 * one-shot sensors de-activate themselves automatically upon 850 * receiving an event and they must still accept to be deactivated 851 * through a call to activate(..., ..., 0). 852 * 853 * if "enabled" is true and the sensor is already activated, this 854 * function is a no-op and succeeds. 855 * 856 * if "enabled" is false and the sensor is already de-activated, 857 * this function is a no-op and succeeds. 858 * 859 * return 0 on success, negative errno code otherwise 860 */ 861 int (*activate)(struct sensors_poll_device_t *dev, 862 int handle, int enabled); 863 864 /** 865 * Set the events's period in nanoseconds for a given sensor. 866 * 867 * What the period_ns parameter means depends on the specified 868 * sensor's trigger mode: 869 * 870 * continuous: setDelay() sets the sampling rate. 871 * on-change: setDelay() limits the delivery rate of events 872 * one-shot: setDelay() is ignored. it has no effect. 873 * special: see specific sensor type definitions 874 * 875 * For continuous and on-change sensors, if the requested value is 876 * less than sensor_t::minDelay, then it's silently clamped to 877 * sensor_t::minDelay unless sensor_t::minDelay is 0, in which 878 * case it is clamped to >= 1ms. 879 * 880 * @return 0 if successful, < 0 on error 881 */ 882 int (*setDelay)(struct sensors_poll_device_t *dev, 883 int handle, int64_t period_ns); 884 885 /** 886 * Returns an array of sensor data. 887 * This function must block until events are available. 888 * 889 * return the number of events read on success, or -errno in case 890 * of an error. 891 * 892 * The number of events returned in data must be less or equal 893 * to SENSORS_QUERY_MAX_EVENTS_BATCH_COUNT. 894 * 895 * This function shall never return 0 (no event). 896 */ 897 int (*poll)(struct sensors_poll_device_t *dev, 898 sensors_event_t* data, int count); 899 }; 900 }; 901 902 /* 903 * Used to retrieve information about the sensor HAL 904 * 905 * Returns 0 on success or -errno on error. 906 */ 907 int (*query)(struct sensors_poll_device_1* dev, int what, int* value); 908 909 910 /* 911 * Enables batch mode for the given sensor and sets the delay between events 912 * 913 * A timeout value of zero disables batch mode for the given sensor. 914 * 915 * The period_ns parameter is equivalent to calling setDelay() -- this 916 * function both enables or disables the batch mode AND sets the events's 917 * period in nanosecond. See setDelay() above for a detailed explanation of 918 * the period_ns parameter. 919 * 920 * While in batch mode sensor events are reported in batches at least 921 * every "timeout" nanosecond; that is all events since the previous batch 922 * are recorded and returned all at once. Batches can be interleaved and 923 * split, and as usual events of the same sensor type are time-ordered. 924 * 925 * setDelay() is not affected and it behaves as usual. 926 * 927 * Each event has a timestamp associated with it, the timestamp 928 * must be accurate and correspond to the time at which the event 929 * physically happened. 930 * 931 * If internal h/w FIFOs fill-up before the timeout, then events are 932 * reported at that point. No event shall be dropped or lost. 933 * 934 * 935 * INTERACTION WITH SUSPEND MODE: 936 * ------------------------------ 937 * 938 * By default batch mode doesn't significantly change the interaction with 939 * suspend mode, that is, sensors must continue to allow the SoC to 940 * go into suspend mode and sensors must stay active to fill their 941 * internal FIFO, in this mode, when the FIFO fills-up, it shall wrap 942 * around (basically behave like a circular buffer, overwriting events). 943 * As soon as the SoC comes out of suspend mode, a batch is produced with 944 * as much as the recent history as possible, and batch operation 945 * resumes as usual. 946 * 947 * The behavior described above allows applications to record the recent 948 * history of a set of sensor while keeping the SoC into suspend. It 949 * also allows the hardware to not have to rely on a wake-up interrupt line. 950 * 951 * There are cases however where an application cannot afford to lose 952 * any events, even when the device goes into suspend mode. The behavior 953 * specified above can be altered by setting the 954 * SENSORS_BATCH_WAKE_UPON_FIFO_FULL flag. If this flag is set, the SoC 955 * must be woken up from suspend and a batch must be returned before 956 * the FIFO fills-up. Enough head room must be allocated in the FIFO to allow 957 * the device to entirely come out of suspend (which might take a while and 958 * is device dependent) such that no event are lost. 959 * 960 * If the hardware cannot support this mode, or, if the physical 961 * FIFO is so small that the device would never be allowed to go into 962 * suspend for at least 10 seconds, then this function MUST fail when 963 * the flag SENSORS_BATCH_WAKE_UPON_FIFO_FULL is set, regardless of 964 * the value of the timeout parameter. 965 * 966 * DRY RUN: 967 * -------- 968 * 969 * If the flag SENSORS_BATCH_DRY_RUN is set, this function returns 970 * without modifying the batch mode or the event period and has no side 971 * effects, but returns errors as usual (as it would if this flag was 972 * not set). This flag is used to check if batch mode is available for a 973 * given configuration -- in particular for a given sensor at a given rate. 974 * 975 * 976 * Return values: 977 * -------------- 978 * 979 * Because sensors must be independent, the return value must not depend 980 * on the state of the system (whether another sensor is on or not), 981 * nor on whether the flag SENSORS_BATCH_DRY_RUN is set (in other words, 982 * if a batch call with SENSORS_BATCH_DRY_RUN is successful, 983 * the same call without SENSORS_BATCH_DRY_RUN must succeed as well). 984 * 985 * If successful, 0 is returned. 986 * If the specified sensor doesn't support batch mode, -EINVAL is returned. 987 * If the specified sensor's trigger-mode is one-shot, -EINVAL is returned. 988 * If any of the constraint above cannot be satisfied, -EINVAL is returned. 989 * 990 * Note: the timeout parameter, when > 0, has no impact on whether this 991 * function succeeds or fails. 992 * 993 * If timeout is set to 0, this function must succeed. 994 * 995 * 996 * IMPLEMENTATION NOTES: 997 * --------------------- 998 * 999 * batch mode, if supported, should happen at the hardware level, 1000 * typically using hardware FIFOs. In particular, it SHALL NOT be 1001 * implemented in the HAL, as this would be counter productive. 1002 * The goal here is to save significant amounts of power. 1003 * 1004 * batch mode can be enabled or disabled at any time, in particular 1005 * while the specified sensor is already enabled and this shall not 1006 * result in the loss of events. 1007 * 1008 */ 1009 int (*batch)(struct sensors_poll_device_1* dev, 1010 int handle, int flags, int64_t period_ns, int64_t timeout); 1011 1012 void (*reserved_procs[8])(void); 1013 1014} sensors_poll_device_1_t; 1015 1016 1017 1018/** convenience API for opening and closing a device */ 1019 1020static inline int sensors_open(const struct hw_module_t* module, 1021 struct sensors_poll_device_t** device) { 1022 return module->methods->open(module, 1023 SENSORS_HARDWARE_POLL, (struct hw_device_t**)device); 1024} 1025 1026static inline int sensors_close(struct sensors_poll_device_t* device) { 1027 return device->common.close(&device->common); 1028} 1029 1030static inline int sensors_open_1(const struct hw_module_t* module, 1031 sensors_poll_device_1_t** device) { 1032 return module->methods->open(module, 1033 SENSORS_HARDWARE_POLL, (struct hw_device_t**)device); 1034} 1035 1036static inline int sensors_close_1(sensors_poll_device_1_t* device) { 1037 return device->common.close(&device->common); 1038} 1039 1040__END_DECLS 1041 1042#endif // ANDROID_SENSORS_INTERFACE_H 1043