sensors.h revision 1144bea332fb24789712062bb35fe762f2f17505
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 int8_t status; 668 uint8_t reserved[3]; 669} sensors_vec_t; 670 671/** 672 * Union of the various types of sensor data 673 * that can be returned. 674 */ 675typedef struct sensors_event_t { 676 /* must be sizeof(struct sensors_event_t) */ 677 int32_t version; 678 679 /* sensor identifier */ 680 int32_t sensor; 681 682 /* sensor type */ 683 int32_t type; 684 685 /* reserved */ 686 int32_t reserved0; 687 688 /* time is in nanosecond */ 689 int64_t timestamp; 690 691 union { 692 float data[16]; 693 694 /* acceleration values are in meter per second per second (m/s^2) */ 695 sensors_vec_t acceleration; 696 697 /* magnetic vector values are in micro-Tesla (uT) */ 698 sensors_vec_t magnetic; 699 700 /* orientation values are in degrees */ 701 sensors_vec_t orientation; 702 703 /* gyroscope values are in rad/s */ 704 sensors_vec_t gyro; 705 706 /* temperature is in degrees centigrade (Celsius) */ 707 float temperature; 708 709 /* distance in centimeters */ 710 float distance; 711 712 /* light in SI lux units */ 713 float light; 714 715 /* pressure in hectopascal (hPa) */ 716 float pressure; 717 718 /* relative humidity in percent */ 719 float relative_humidity; 720 721 /* step-counter */ 722 uint64_t step_counter; 723 }; 724 uint32_t reserved1[4]; 725} sensors_event_t; 726 727 728 729struct sensor_t; 730 731/** 732 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM 733 * and the fields of this data structure must begin with hw_module_t 734 * followed by module specific information. 735 */ 736struct sensors_module_t { 737 struct hw_module_t common; 738 739 /** 740 * Enumerate all available sensors. The list is returned in "list". 741 * @return number of sensors in the list 742 */ 743 int (*get_sensors_list)(struct sensors_module_t* module, 744 struct sensor_t const** list); 745}; 746 747struct sensor_t { 748 749 /* Name of this sensor. 750 * All sensors of the same "type" must have a different "name". 751 */ 752 const char* name; 753 754 /* vendor of the hardware part */ 755 const char* vendor; 756 757 /* version of the hardware part + driver. The value of this field 758 * must increase when the driver is updated in a way that changes the 759 * output of this sensor. This is important for fused sensors when the 760 * fusion algorithm is updated. 761 */ 762 int version; 763 764 /* handle that identifies this sensors. This handle is used to reference 765 * this sensor throughout the HAL API. 766 */ 767 int handle; 768 769 /* this sensor's type. */ 770 int type; 771 772 /* maximum range of this sensor's value in SI units */ 773 float maxRange; 774 775 /* smallest difference between two values reported by this sensor */ 776 float resolution; 777 778 /* rough estimate of this sensor's power consumption in mA */ 779 float power; 780 781 /* this value depends on the trigger mode: 782 * 783 * continuous: minimum sample period allowed in microseconds 784 * on-change : 0 785 * one-shot :-1 786 * special : 0, unless otherwise noted 787 */ 788 int32_t minDelay; 789 790 /* reserved fields, must be zero */ 791 void* reserved[8]; 792}; 793 794 795/* 796 * sensors_poll_device_t is used with SENSORS_DEVICE_API_VERSION_0_1 797 * and is present for backward binary and source compatibility. 798 * (see documentation of the hooks in struct sensors_poll_device_1 below) 799 */ 800struct sensors_poll_device_t { 801 struct hw_device_t common; 802 int (*activate)(struct sensors_poll_device_t *dev, 803 int handle, int enabled); 804 int (*setDelay)(struct sensors_poll_device_t *dev, 805 int handle, int64_t ns); 806 int (*poll)(struct sensors_poll_device_t *dev, 807 sensors_event_t* data, int count); 808}; 809 810/* 811 * struct sensors_poll_device_1 is used with SENSORS_DEVICE_API_VERSION_1_0 812 */ 813typedef struct sensors_poll_device_1 { 814 union { 815 /* sensors_poll_device_1 is compatible with sensors_poll_device_t, 816 * and can be down-cast to it 817 */ 818 struct sensors_poll_device_t v0; 819 820 struct { 821 struct hw_device_t common; 822 823 /* Activate/de-activate one sensor. 824 * 825 * handle is the handle of the sensor to change. 826 * enabled set to 1 to enable, or 0 to disable the sensor. 827 * 828 * unless otherwise noted in the sensor types definitions, an 829 * activated sensor never prevents the SoC to go into suspend 830 * mode; that is, the HAL shall not hold a partial wake-lock on 831 * behalf of applications. 832 * 833 * one-shot sensors de-activate themselves automatically upon 834 * receiving an event and they must still accept to be deactivated 835 * through a call to activate(..., ..., 0). 836 * 837 * if "enabled" is true and the sensor is already activated, this 838 * function is a no-op and succeeds. 839 * 840 * if "enabled" is false and the sensor is already de-activated, 841 * this function is a no-op and succeeds. 842 * 843 * return 0 on success, negative errno code otherwise 844 */ 845 int (*activate)(struct sensors_poll_device_t *dev, 846 int handle, int enabled); 847 848 /** 849 * Set the events's period in nanoseconds for a given sensor. 850 * 851 * What the period_ns parameter means depends on the specified 852 * sensor's trigger mode: 853 * 854 * continuous: setDelay() sets the sampling rate. 855 * on-change: setDelay() limits the delivery rate of events 856 * one-shot: setDelay() is ignored. it has no effect. 857 * special: see specific sensor type definitions 858 * 859 * For continuous and on-change sensors, if the requested value is 860 * less than sensor_t::minDelay, then it's silently clamped to 861 * sensor_t::minDelay unless sensor_t::minDelay is 0, in which 862 * case it is clamped to >= 1ms. 863 * 864 * @return 0 if successful, < 0 on error 865 */ 866 int (*setDelay)(struct sensors_poll_device_t *dev, 867 int handle, int64_t period_ns); 868 869 /** 870 * Returns an array of sensor data. 871 * This function must block until events are available. 872 * 873 * return the number of events read on success, or -errno in case 874 * of an error. 875 * 876 * The number of events returned in data must be less or equal 877 * to SENSORS_QUERY_MAX_EVENTS_BATCH_COUNT. 878 * 879 * This function shall never return 0 (no event). 880 */ 881 int (*poll)(struct sensors_poll_device_t *dev, 882 sensors_event_t* data, int count); 883 }; 884 }; 885 886 /* 887 * Used to retrieve information about the sensor HAL 888 * 889 * Returns 0 on success or -errno on error. 890 */ 891 int (*query)(struct sensors_poll_device_1* dev, int what, int* value); 892 893 894 /* 895 * Enables batch mode for the given sensor and sets the delay between events 896 * 897 * A timeout value of zero disables batch mode for the given sensor. 898 * 899 * The period_ns parameter is equivalent to calling setDelay() -- this 900 * function both enables or disables the batch mode AND sets the events's 901 * period in nanosecond. See setDelay() above for a detailed explanation of 902 * the period_ns parameter. 903 * 904 * While in batch mode sensor events are reported in batches at least 905 * every "timeout" nanosecond; that is all events since the previous batch 906 * are recorded and returned all at once. Batches can be interleaved and 907 * split, and as usual events of the same sensor type are time-ordered. 908 * 909 * setDelay() is not affected and it behaves as usual. 910 * 911 * Each event has a timestamp associated with it, the timestamp 912 * must be accurate and correspond to the time at which the event 913 * physically happened. 914 * 915 * If internal h/w FIFOs fill-up before the timeout, then events are 916 * reported at that point. No event shall be dropped or lost. 917 * 918 * 919 * INTERACTION WITH SUSPEND MODE: 920 * ------------------------------ 921 * 922 * By default batch mode doesn't significantly change the interaction with 923 * suspend mode, that is, sensors must continue to allow the SoC to 924 * go into suspend mode and sensors must stay active to fill their 925 * internal FIFO, in this mode, when the FIFO fills-up, it shall wrap 926 * around (basically behave like a circular buffer, overwriting events). 927 * As soon as the SoC comes out of suspend mode, a batch is produced with 928 * as much as the recent history as possible, and batch operation 929 * resumes as usual. 930 * 931 * The behavior described above allows applications to record the recent 932 * history of a set of sensor while keeping the SoC into suspend. It 933 * also allows the hardware to not have to rely on a wake-up interrupt line. 934 * 935 * There are cases however where an application cannot afford to lose 936 * any events, even when the device goes into suspend mode. The behavior 937 * specified above can be altered by setting the 938 * SENSORS_BATCH_WAKE_UPON_FIFO_FULL flag. If this flag is set, the SoC 939 * must be woken up from suspend and a batch must be returned before 940 * the FIFO fills-up. Enough head room must be allocated in the FIFO to allow 941 * the device to entirely come out of suspend (which might take a while and 942 * is device dependent) such that no event are lost. 943 * 944 * If the hardware cannot support this mode, or, if the physical 945 * FIFO is so small that the device would never be allowed to go into 946 * suspend for at least 10 seconds, then this function MUST fail when 947 * the flag SENSORS_BATCH_WAKE_UPON_FIFO_FULL is set, regardless of 948 * the value of the timeout parameter. 949 * 950 * DRY RUN: 951 * -------- 952 * 953 * If the flag SENSORS_BATCH_DRY_RUN is set, this function returns 954 * without modifying the batch mode or the event period and has no side 955 * effects, but returns errors as usual (as it would if this flag was 956 * not set). This flag is used to check if batch mode is available for a 957 * given configuration -- in particular for a given sensor at a given rate. 958 * 959 * 960 * Return values: 961 * -------------- 962 * 963 * Because sensors must be independent, the return value must not depend 964 * on the state of the system (whether another sensor is on or not), 965 * nor on whether the flag SENSORS_BATCH_DRY_RUN is set (in other words, 966 * if a batch call with SENSORS_BATCH_DRY_RUN is successful, 967 * the same call without SENSORS_BATCH_DRY_RUN must succeed as well). 968 * 969 * If successful, 0 is returned. 970 * If the specified sensor doesn't support batch mode, -EINVAL is returned. 971 * If the specified sensor's trigger-mode is one-shot, -EINVAL is returned. 972 * If any of the constraint above cannot be satisfied, -EINVAL is returned. 973 * 974 * Note: the timeout parameter, when > 0, has no impact on whether this 975 * function succeeds or fails. 976 * 977 * If timeout is set to 0, this function must succeed. 978 * 979 * 980 * IMPLEMENTATION NOTES: 981 * --------------------- 982 * 983 * batch mode, if supported, should happen at the hardware level, 984 * typically using hardware FIFOs. In particular, it SHALL NOT be 985 * implemented in the HAL, as this would be counter productive. 986 * The goal here is to save significant amounts of power. 987 * 988 * batch mode can be enabled or disabled at any time, in particular 989 * while the specified sensor is already enabled and this shall not 990 * result in the loss of events. 991 * 992 */ 993 int (*batch)(struct sensors_poll_device_1* dev, 994 int handle, int flags, int64_t period_ns, int64_t timeout); 995 996 void (*reserved_procs[8])(void); 997 998} sensors_poll_device_1_t; 999 1000 1001 1002/** convenience API for opening and closing a device */ 1003 1004static inline int sensors_open(const struct hw_module_t* module, 1005 struct sensors_poll_device_t** device) { 1006 return module->methods->open(module, 1007 SENSORS_HARDWARE_POLL, (struct hw_device_t**)device); 1008} 1009 1010static inline int sensors_close(struct sensors_poll_device_t* device) { 1011 return device->common.close(&device->common); 1012} 1013 1014static inline int sensors_open_1(const struct hw_module_t* module, 1015 sensors_poll_device_1_t** device) { 1016 return module->methods->open(module, 1017 SENSORS_HARDWARE_POLL, (struct hw_device_t**)device); 1018} 1019 1020static inline int sensors_close_1(sensors_poll_device_1_t* device) { 1021 return device->common.close(&device->common); 1022} 1023 1024__END_DECLS 1025 1026#endif // ANDROID_SENSORS_INTERFACE_H 1027