hardware/sensors.h

   1 /*
   2  * Copyright (C) 2008 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  * The id of this module
  31  */
  32 #define SENSORS_HARDWARE_MODULE_ID "sensors"
  33
  34 /**
  35  * Name of the sensors device to open
  36  */
  37 #define SENSORS_HARDWARE_POLL       "poll"
  38
  39 /**
  40  * Handles must be higher than SENSORS_HANDLE_BASE and must be unique.
  41  * A Handle identifies a given sensors. The handle is used to activate
  42  * and/or deactivate sensors.
  43  * In this version of the API there can only be 256 handles.
  44  */
  45 #define SENSORS_HANDLE_BASE             0
  46 #define SENSORS_HANDLE_BITS             8
  47 #define SENSORS_HANDLE_COUNT            (1<<SENSORS_HANDLE_BITS)
  48
  49
  50 /**
  51  * Sensor types
  52  */
  53 #define SENSOR_TYPE_ACCELEROMETER       1
  54 #define SENSOR_TYPE_MAGNETIC_FIELD      2
  55 #define SENSOR_TYPE_ORIENTATION         3
  56 #define SENSOR_TYPE_GYROSCOPE           4
  57 #define SENSOR_TYPE_LIGHT               5
  58 #define SENSOR_TYPE_PRESSURE            6
  59 #define SENSOR_TYPE_TEMPERATURE         7   // deprecated
  60 #define SENSOR_TYPE_PROXIMITY           8
  61 #define SENSOR_TYPE_GRAVITY             9
  62 #define SENSOR_TYPE_LINEAR_ACCELERATION 10
  63 #define SENSOR_TYPE_ROTATION_VECTOR     11
  64 #define SENSOR_TYPE_RELATIVE_HUMIDITY   12
  65 #define SENSOR_TYPE_AMBIENT_TEMPERATURE 13
  66
  67 /**
  68  * Values returned by the accelerometer in various locations in the universe.
  69  * all values are in SI units (m/s^2)
  70  */
  71
  72 #define GRAVITY_SUN             (275.0f)
  73 #define GRAVITY_EARTH           (9.80665f)
  74
  75 /** Maximum magnetic field on Earth's surface */
  76 #define MAGNETIC_FIELD_EARTH_MAX    (60.0f)
  77
  78 /** Minimum magnetic field on Earth's surface */
  79 #define MAGNETIC_FIELD_EARTH_MIN    (30.0f)
  80
  81
  82 /**
  83  * status of each sensor
  84  */
  85
  86 #define SENSOR_STATUS_UNRELIABLE        0
  87 #define SENSOR_STATUS_ACCURACY_LOW      1
  88 #define SENSOR_STATUS_ACCURACY_MEDIUM   2
  89 #define SENSOR_STATUS_ACCURACY_HIGH     3
  90
  91 /**
  92  * Definition of the axis
  93  * ----------------------
  94  *
  95  * This API is relative to the screen of the device in its default orientation,
  96  * that is, if the device can be used in portrait or landscape, this API
  97  * is only relative to the NATURAL orientation of the screen. In other words,
  98  * the axis are not swapped when the device's screen orientation changes.
  99  * Higher level services /may/ perform this transformation.
 100  *
 101  *   x<0         x>0
 102  *                ^
 103  *                |
 104  *    +-----------+-->  y>0
 105  *    |           |
 106  *    |           |
 107  *    |           |
 108  *    |           |   / z<0
 109  *    |           |  /
 110  *    |           | /
 111  *    O-----------+/
 112  *    |[]  [ ]  []/
 113  *    +----------/+     y<0
 114  *              /
 115  *             /
 116  *           |/ z>0 (toward the sky)
 117  *
 118  *    O: Origin (x=0,y=0,z=0)
 119  *
 120  *
 121  * SENSOR_TYPE_ORIENTATION
 122  * -----------------------
 123  *
 124  * All values are angles in degrees.
 125  *
 126  * Orientation sensors return sensor events for all 3 axes at a constant
 127  * rate defined by setDelay().
 128  *
 129  * azimuth: angle between the magnetic north direction and the Y axis, around
 130  *  the Z axis (0<=azimuth<360).
 131  *      0=North, 90=East, 180=South, 270=West
 132  *
 133  * pitch: Rotation around X axis (-180<=pitch<=180), with positive values when
 134  *  the z-axis moves toward the y-axis.
 135  *
 136  * roll: Rotation around Y axis (-90<=roll<=90), with positive values when
 137  *  the x-axis moves towards the z-axis.
 138  *
 139  * Note: For historical reasons the roll angle is positive in the clockwise
 140  *  direction (mathematically speaking, it should be positive in the
 141  *  counter-clockwise direction):
 142  *
 143  *                Z
 144  *                ^
 145  *  (+roll)  .--> |
 146  *          /     |
 147  *         |      |  roll: rotation around Y axis
 148  *     X <-------(.)
 149  *                 Y
 150  *       note that +Y == -roll
 151  *
 152  *
 153  *
 154  * Note: This definition is different from yaw, pitch and roll used in aviation
 155  *  where the X axis is along the long side of the plane (tail to nose).
 156  *
 157  *
 158  * SENSOR_TYPE_ACCELEROMETER
 159  * -------------------------
 160  *
 161  *  All values are in SI units (m/s^2) and measure the acceleration of the
 162  *  device minus the force of gravity.
 163  *
 164  *  Acceleration sensors return sensor events for all 3 axes at a constant
 165  *  rate defined by setDelay().
 166  *
 167  *  x: Acceleration minus Gx on the x-axis
 168  *  y: Acceleration minus Gy on the y-axis
 169  *  z: Acceleration minus Gz on the z-axis
 170  *
 171  *  Examples:
 172  *    When the device lies flat on a table and is pushed on its left side
 173  *    toward the right, the x acceleration value is positive.
 174  *
 175  *    When the device lies flat on a table, the acceleration value is +9.81,
 176  *    which correspond to the acceleration of the device (0 m/s^2) minus the
 177  *    force of gravity (-9.81 m/s^2).
 178  *
 179  *    When the device lies flat on a table and is pushed toward the sky, the
 180  *    acceleration value is greater than +9.81, which correspond to the
 181  *    acceleration of the device (+A m/s^2) minus the force of
 182  *    gravity (-9.81 m/s^2).
 183  *
 184  *
 185  * SENSOR_TYPE_MAGNETIC_FIELD
 186  * --------------------------
 187  *
 188  *  All values are in micro-Tesla (uT) and measure the ambient magnetic
 189  *  field in the X, Y and Z axis.
 190  *
 191  *  Magnetic Field sensors return sensor events for all 3 axes at a constant
 192  *  rate defined by setDelay().
 193  *
 194  * SENSOR_TYPE_GYROSCOPE
 195  * ---------------------
 196  *
 197  *  All values are in radians/second and measure the rate of rotation
 198  *  around the X, Y and Z axis.  The coordinate system is the same as is
 199  *  used for the acceleration sensor. Rotation is positive in the
 200  *  counter-clockwise direction (right-hand rule). That is, an observer
 201  *  looking from some positive location on the x, y or z axis at a device
 202  *  positioned on the origin would report positive rotation if the device
 203  *  appeared to be rotating counter clockwise. Note that this is the
 204  *  standard mathematical definition of positive rotation and does not agree
 205  *  with the definition of roll given earlier.
 206  *  The range should at least be 17.45 rad/s (ie: ~1000 deg/s).
 207  *
 208  * SENSOR_TYPE_PROXIMITY
 209  * ----------------------
 210  *
 211  * The distance value is measured in centimeters.  Note that some proximity
 212  * sensors only support a binary "close" or "far" measurement.  In this case,
 213  * the sensor should report its maxRange value in the "far" state and a value
 214  * less than maxRange in the "near" state.
 215  *
 216  * Proximity sensors report a value only when it changes and each time the
 217  * sensor is enabled.
 218  *
 219  * SENSOR_TYPE_LIGHT
 220  * -----------------
 221  *
 222  * The light sensor value is returned in SI lux units.
 223  *
 224  * Light sensors report a value only when it changes and each time the
 225  * sensor is enabled.
 226  *
 227  * SENSOR_TYPE_PRESSURE
 228  * --------------------
 229  *
 230  * The pressure sensor return the athmospheric pressure in hectopascal (hPa)
 231  *
 232  * Pressure sensors report events at a constant rate defined by setDelay().
 233  *
 234  * SENSOR_TYPE_GRAVITY
 235  * -------------------
 236  *
 237  * A gravity output indicates the direction of and magnitude of gravity in
 238  * the devices's coordinates.  On Earth, the magnitude is 9.8 m/s^2.
 239  * Units are m/s^2.  The coordinate system is the same as is used for the
 240  * acceleration sensor. When the device is at rest, the output of the
 241  * gravity sensor should be identical to that of the accelerometer.
 242  *
 243  * SENSOR_TYPE_LINEAR_ACCELERATION
 244  * --------------------------------
 245  *
 246  * Indicates the linear acceleration of the device in device coordinates,
 247  * not including gravity.
 248  * This output is essentially Acceleration - Gravity.  Units are m/s^2.
 249  * The coordinate system is the same as is used for the acceleration sensor.
 250  *
 251  *
 252  * SENSOR_TYPE_ROTATION_VECTOR
 253  * ---------------------------
 254  *
 255  * A rotation vector represents the orientation of the device as a combination
 256  * of an angle and an axis, in which the device has rotated through an angle
 257  * theta around an axis <x, y, z>. The three elements of the rotation vector
 258  * are <x*sin(theta/2), y*sin(theta/2), z*sin(theta/2)>, such that the magnitude
 259  * of the rotation vector is equal to sin(theta/2), and the direction of the
 260  * rotation vector is equal to the direction of the axis of rotation. The three
 261  * elements of the rotation vector are equal to the last three components of a
 262  * unit quaternion <cos(theta/2), x*sin(theta/2), y*sin(theta/2), z*sin(theta/2)>.
 263  * Elements of the rotation vector are unitless.  The x, y, and z axis are defined
 264  * in the same was as for the acceleration sensor.
 265  *
 266  * The reference coordinate system is defined as a direct orthonormal basis,
 267  * where:
 268  *
 269  * - X is defined as the vector product Y.Z (It is tangential to
 270  * the ground at the device's current location and roughly points East).
 271  *
 272  * - Y is tangential to the ground at the device's current location and
 273  * points towards the magnetic North Pole.
 274  *
 275  * - Z points towards the sky and is perpendicular to the ground.
 276  *
 277  *
 278  * The rotation-vector is stored as:
 279  *
 280  *   sensors_event_t.data[0] = x*sin(theta/2)
 281  *   sensors_event_t.data[1] = y*sin(theta/2)
 282  *   sensors_event_t.data[2] = z*sin(theta/2)
 283  *   sensors_event_t.data[3] =   cos(theta/2)
 284  *
 285  *
 286  * SENSOR_TYPE_RELATIVE_HUMIDITY
 287  * ------------------------------
 288  *
 289  * A relative humidity sensor measures relative ambient air humidity and
 290  * returns a value in percent.
 291  *
 292  * Relative humidity sensors report a value only when it changes and each
 293  * time the sensor is enabled.
 294  *
 295  *
 296  * SENSOR_TYPE_AMBIENT_TEMPERATURE
 297  * -------------------------------
 298  *
 299  * The ambient (room) temperature in degree Celsius.
 300  *
 301  * Temperature sensors report a value only when it changes and each time the
 302  * sensor is enabled.
 303  *
 304  */
 305
 306 typedef struct {
 307     union {
 308         float v[3];
 309         struct {
 310             float x;
 311             float y;
 312             float z;
 313         };
 314         struct {
 315             float azimuth;
 316             float pitch;
 317             float roll;
 318         };
 319     };
 320     int8_t status;
 321     uint8_t reserved[3];
 322 } sensors_vec_t;
 323
 324 /**
 325  * Union of the various types of sensor data
 326  * that can be returned.
 327  */
 328 typedef struct sensors_event_t {
 329     /* must be sizeof(struct sensors_event_t) */
 330     int32_t version;
 331
 332     /* sensor identifier */
 333     int32_t sensor;
 334
 335     /* sensor type */
 336     int32_t type;
 337
 338     /* reserved */
 339     int32_t reserved0;
 340
 341     /* time is in nanosecond */
 342     int64_t timestamp;
 343
 344     union {
 345         float           data[16];
 346
 347         /* acceleration values are in meter per second per second (m/s^2) */
 348         sensors_vec_t   acceleration;
 349
 350         /* magnetic vector values are in micro-Tesla (uT) */
 351         sensors_vec_t   magnetic;
 352
 353         /* orientation values are in degrees */
 354         sensors_vec_t   orientation;
 355
 356         /* gyroscope values are in rad/s */
 357         sensors_vec_t   gyro;
 358
 359         /* temperature is in degrees centigrade (Celsius) */
 360         float           temperature;
 361
 362         /* distance in centimeters */
 363         float           distance;
 364
 365         /* light in SI lux units */
 366         float           light;
 367
 368         /* pressure in hectopascal (hPa) */
 369         float           pressure;
 370
 371         /* relative humidity in percent */
 372         float           relative_humidity;
 373     };
 374     uint32_t        reserved1[4];
 375 } sensors_event_t;
 376
 377
 378
 379 struct sensor_t;
 380
 381 /**
 382  * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
 383  * and the fields of this data structure must begin with hw_module_t
 384  * followed by module specific information.
 385  */
 386 struct sensors_module_t {
 387     struct hw_module_t common;
 388
 389     /**
 390      * Enumerate all available sensors. The list is returned in "list".
 391      * @return number of sensors in the list
 392      */
 393     int (*get_sensors_list)(struct sensors_module_t* module,
 394             struct sensor_t const** list);
 395 };
 396
 397 struct sensor_t {
 398     /* name of this sensors */
 399     const char*     name;
 400     /* vendor of the hardware part */
 401     const char*     vendor;
 402     /* version of the hardware part + driver. The value of this field
 403      * must increase when the driver is updated in a way that changes the
 404      * output of this sensor. This is important for fused sensors when the
 405      * fusion algorithm is updated.
 406      */
 407     int             version;
 408     /* handle that identifies this sensors. This handle is used to activate
 409      * and deactivate this sensor. The value of the handle must be 8 bits
 410      * in this version of the API.
 411      */
 412     int             handle;
 413     /* this sensor's type. */
 414     int             type;
 415     /* maximaum range of this sensor's value in SI units */
 416     float           maxRange;
 417     /* smallest difference between two values reported by this sensor */
 418     float           resolution;
 419     /* rough estimate of this sensor's power consumption in mA */
 420     float           power;
 421     /* minimum delay allowed between events in microseconds. A value of zero
 422      * means that this sensor doesn't report events at a constant rate, but
 423      * rather only when a new data is available */
 424     int32_t         minDelay;
 425     /* reserved fields, must be zero */
 426     void*           reserved[8];
 427 };
 428
 429
 430 /**
 431  * Every device data structure must begin with hw_device_t
 432  * followed by module specific public methods and attributes.
 433  */
 434 struct sensors_poll_device_t {
 435     struct hw_device_t common;
 436
 437     /** Activate/deactivate one sensor.
 438      *
 439      * @param handle is the handle of the sensor to change.
 440      * @param enabled set to 1 to enable, or 0 to disable the sensor.
 441      *
 442      * @return 0 on success, negative errno code otherwise
 443      */
 444     int (*activate)(struct sensors_poll_device_t *dev,
 445             int handle, int enabled);
 446
 447     /**
 448      * Set the delay between sensor events in nanoseconds for a given sensor.
 449      *
 450      * If the requested value is less than sensor_t::minDelay, then it's
 451      * silently clamped to sensor_t::minDelay unless sensor_t::minDelay is
 452      * 0, in which case it is clamped to >= 1ms.
 453      *
 454      * @return 0 if successful, < 0 on error
 455      */
 456     int (*setDelay)(struct sensors_poll_device_t *dev,
 457             int handle, int64_t ns);
 458
 459     /**
 460      * Returns an array of sensor data.
 461      * This function must block until events are available.
 462      *
 463      * @return the number of events read on success, or -errno in case of an error.
 464      * This function should never return 0 (no event).
 465      *
 466      */
 467     int (*poll)(struct sensors_poll_device_t *dev,
 468             sensors_event_t* data, int count);
 469 };
 470
 471 /** convenience API for opening and closing a device */
 472
 473 static inline int sensors_open(const struct hw_module_t* module,
 474         struct sensors_poll_device_t** device) {
 475     return module->methods->open(module,
 476             SENSORS_HARDWARE_POLL, (struct hw_device_t**)device);
 477 }
 478
 479 static inline int sensors_close(struct sensors_poll_device_t* device) {
 480     return device->common.close(&device->common);
 481 }
 482
 483 __END_DECLS
 484
 485 #endif  // ANDROID_SENSORS_INTERFACE_H