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