Home | History | Annotate | Download | only in hardware
      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
    486