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