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_CONTROL    "control"
  38 #define SENSORS_HARDWARE_DATA       "data"
  39
  40 /**
  41  * Handles must be higher than SENSORS_HANDLE_BASE and must be unique.
  42  * A Handle identifies a given sensors. The handle is used to activate
  43  * and/or deactivate sensors.
  44  * In this version of the API there can only be 256 handles.
  45  */
  46 #define SENSORS_HANDLE_BASE             0
  47 #define SENSORS_HANDLE_BITS             8
  48 #define SENSORS_HANDLE_COUNT            (1<<SENSORS_HANDLE_BITS)
  49
  50
  51 /**
  52  * Sensor types
  53  */
  54 #define SENSOR_TYPE_ACCELEROMETER       1
  55 #define SENSOR_TYPE_MAGNETIC_FIELD      2
  56 #define SENSOR_TYPE_ORIENTATION         3
  57 #define SENSOR_TYPE_GYROSCOPE           4
  58 #define SENSOR_TYPE_LIGHT               5
  59 #define SENSOR_TYPE_PRESSURE            6
  60 #define SENSOR_TYPE_TEMPERATURE         7
  61 #define SENSOR_TYPE_PROXIMITY           8
  62
  63 /**
  64  * Values returned by the accelerometer in various locations in the universe.
  65  * all values are in SI units (m/s^2)
  66  */
  67
  68 #define GRAVITY_SUN             (275.0f)
  69 #define GRAVITY_MERCURY         (3.70f)
  70 #define GRAVITY_VENUS           (8.87f)
  71 #define GRAVITY_EARTH           (9.80665f)
  72 #define GRAVITY_MOON            (1.6f)
  73 #define GRAVITY_MARS            (3.71f)
  74 #define GRAVITY_JUPITER         (23.12f)
  75 #define GRAVITY_SATURN          (8.96f)
  76 #define GRAVITY_URANUS          (8.69f)
  77 #define GRAVITY_NEPTUNE         (11.0f)
  78 #define GRAVITY_PLUTO           (0.6f)
  79 #define GRAVITY_DEATH_STAR_I    (0.000000353036145f)
  80 #define GRAVITY_THE_ISLAND      (4.815162342f)
  81
  82 /** Maximum magnetic field on Earth's surface */
  83 #define MAGNETIC_FIELD_EARTH_MAX    (60.0f)
  84
  85 /** Minimum magnetic field on Earth's surface */
  86 #define MAGNETIC_FIELD_EARTH_MIN    (30.0f)
  87
  88
  89 /**
  90  * status of each sensor
  91  */
  92
  93 #define SENSOR_STATUS_UNRELIABLE        0
  94 #define SENSOR_STATUS_ACCURACY_LOW      1
  95 #define SENSOR_STATUS_ACCURACY_MEDIUM   2
  96 #define SENSOR_STATUS_ACCURACY_HIGH     3
  97
  98 /**
  99  * Definition of the axis
 100  * ----------------------
 101  *
 102  * This API is relative to the screen of the device in its default orientation,
 103  * that is, if the device can be used in portrait or landscape, this API
 104  * is only relative to the NATURAL orientation of the screen. In other words,
 105  * the axis are not swapped when the device's screen orientation changes.
 106  * Higher level services /may/ perform this transformation.
 107  *
 108  *   x<0         x>0
 109  *                ^
 110  *                |
 111  *    +-----------+-->  y>0
 112  *    |           |
 113  *    |           |
 114  *    |           |
 115  *    |           |   / z<0
 116  *    |           |  /
 117  *    |           | /
 118  *    O-----------+/
 119  *    |[]  [ ]  []/
 120  *    +----------/+     y<0
 121  *              /
 122  *             /
 123  *           |/ z>0 (toward the sky)
 124  *
 125  *    O: Origin (x=0,y=0,z=0)
 126  *
 127  *
 128  * Orientation
 129  * -----------
 130  *
 131  * All values are angles in degrees.
 132  *
 133  * azimuth: angle between the magnetic north direction and the Y axis, around
 134  *  the Z axis (0<=azimuth<360).
 135  *      0=North, 90=East, 180=South, 270=West
 136  *
 137  * pitch: Rotation around X axis (-180<=pitch<=180), with positive values when
 138  *  the z-axis moves toward the y-axis.
 139  *
 140  * roll: Rotation around Y axis (-90<=roll<=90), with positive values when
 141  *  the x-axis moves towards the z-axis.
 142  *
 143  * Note: For historical reasons the roll angle is positive in the clockwise
 144  *  direction (mathematically speaking, it should be positive in the
 145  *  counter-clockwise direction):
 146  *
 147  *                Z
 148  *                ^
 149  *  (+roll)  .--> |
 150  *          /     |
 151  *         |      |  roll: rotation around Y axis
 152  *     X <-------(.)
 153  *                 Y
 154  *       note that +Y == -roll
 155  *
 156  *
 157  *
 158  * Note: This definition is different from yaw, pitch and roll used in aviation
 159  *  where the X axis is along the long side of the plane (tail to nose).
 160  *
 161  *
 162  * Acceleration
 163  * ------------
 164  *
 165  *  All values are in SI units (m/s^2) and measure the acceleration of the
 166  *  device minus the force of gravity.
 167  *
 168  *  x: Acceleration minus Gx on the x-axis
 169  *  y: Acceleration minus Gy on the y-axis
 170  *  z: Acceleration minus Gz on the z-axis
 171  *
 172  *  Examples:
 173  *    When the device lies flat on a table and is pushed on its left side
 174  *    toward the right, the x acceleration value is positive.
 175  *
 176  *    When the device lies flat on a table, the acceleration value is +9.81,
 177  *    which correspond to the acceleration of the device (0 m/s^2) minus the
 178  *    force of gravity (-9.81 m/s^2).
 179  *
 180  *    When the device lies flat on a table and is pushed toward the sky, the
 181  *    acceleration value is greater than +9.81, which correspond to the
 182  *    acceleration of the device (+A m/s^2) minus the force of
 183  *    gravity (-9.81 m/s^2).
 184  *
 185  *
 186  * Magnetic Field
 187  * --------------
 188  *
 189  *  All values are in micro-Tesla (uT) and measure the ambient magnetic
 190  *  field in the X, Y and Z axis.
 191  *
 192  * Proximity
 193  * ---------
 194  *
 195  * The distance value is measured in centimeters.  Note that some proximity
 196  * sensors only support a binary "close" or "far" measurement.  In this case,
 197  * the sensor should report its maxRange value in the "far" state and a value
 198  * less than maxRange in the "near" state.
 199  *
 200  * Light
 201  * -----
 202  *
 203  * The light sensor value is returned in SI lux units.
 204  *
 205  */
 206 typedef struct {
 207     union {
 208         float v[3];
 209         struct {
 210             float x;
 211             float y;
 212             float z;
 213         };
 214         struct {
 215             float azimuth;
 216             float pitch;
 217             float roll;
 218         };
 219     };
 220     int8_t status;
 221     uint8_t reserved[3];
 222 } sensors_vec_t;
 223
 224 /**
 225  * Union of the various types of sensor data
 226  * that can be returned.
 227  */
 228 typedef struct {
 229     /* sensor identifier */
 230     int             sensor;
 231
 232     union {
 233         /* x,y,z values of the given sensor */
 234         sensors_vec_t   vector;
 235
 236         /* orientation values are in degrees */
 237         sensors_vec_t   orientation;
 238
 239         /* acceleration values are in meter per second per second (m/s^2) */
 240         sensors_vec_t   acceleration;
 241
 242         /* magnetic vector values are in micro-Tesla (uT) */
 243         sensors_vec_t   magnetic;
 244
 245         /* temperature is in degrees centigrade (Celsius) */
 246         float           temperature;
 247
 248         /* distance in centimeters */
 249         float           distance;
 250
 251         /* light in SI lux units */
 252         float           light;
 253     };
 254
 255     /* time is in nanosecond */
 256     int64_t         time;
 257
 258     uint32_t        reserved;
 259 } sensors_data_t;
 260
 261
 262 struct sensor_t;
 263
 264 /**
 265  * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
 266  * and the fields of this data structure must begin with hw_module_t
 267  * followed by module specific information.
 268  */
 269 struct sensors_module_t {
 270     struct hw_module_t common;
 271
 272     /**
 273      * Enumerate all available sensors. The list is returned in "list".
 274      * @return number of sensors in the list
 275      */
 276     int (*get_sensors_list)(struct sensors_module_t* module,
 277             struct sensor_t const** list);
 278 };
 279
 280 struct sensor_t {
 281     /* name of this sensors */
 282     const char*     name;
 283     /* vendor of the hardware part */
 284     const char*     vendor;
 285     /* version of the hardware part + driver. The value of this field is
 286      * left to the implementation and doesn't have to be monotonicaly
 287      * increasing.
 288      */
 289     int             version;
 290     /* handle that identifies this sensors. This handle is used to activate
 291      * and deactivate this sensor. The value of the handle must be 8 bits
 292      * in this version of the API.
 293      */
 294     int             handle;
 295     /* this sensor's type. */
 296     int             type;
 297     /* maximaum range of this sensor's value in SI units */
 298     float           maxRange;
 299     /* smallest difference between two values reported by this sensor */
 300     float           resolution;
 301     /* rough estimate of this sensor's power consumption in mA */
 302     float           power;
 303     /* reserved fields, must be zero */
 304     void*           reserved[9];
 305 };
 306
 307
 308 /**
 309  * Every device data structure must begin with hw_device_t
 310  * followed by module specific public methods and attributes.
 311  */
 312 struct sensors_control_device_t {
 313     struct hw_device_t common;
 314
 315     /**
 316      * Returns a native_handle_t, which will be the parameter to
 317      * sensors_data_device_t::open_data().
 318      * The caller takes ownership of this handle. This is intended to be
 319      * passed cross processes.
 320      *
 321      * @return a native_handle_t if successful, NULL on error
 322      */
 323     native_handle_t* (*open_data_source)(struct sensors_control_device_t *dev);
 324
 325     /**
 326      * Releases any resources that were created by open_data_source.
 327      * This call is optional and can be NULL if not implemented
 328      * by the sensor HAL.
 329      *
 330      * @return 0 if successful, < 0 on error
 331      */
 332     int (*close_data_source)(struct sensors_control_device_t *dev);
 333
 334     /** Activate/deactivate one sensor.
 335      *
 336      * @param handle is the handle of the sensor to change.
 337      * @param enabled set to 1 to enable, or 0 to disable the sensor.
 338      *
 339      * @return 0 on success, negative errno code otherwise
 340      */
 341     int (*activate)(struct sensors_control_device_t *dev,
 342             int handle, int enabled);
 343
 344     /**
 345      * Set the delay between sensor events in ms
 346      *
 347      * @return 0 if successful, < 0 on error
 348      */
 349     int (*set_delay)(struct sensors_control_device_t *dev, int32_t ms);
 350
 351     /**
 352      * Causes sensors_data_device_t.poll() to return -EWOULDBLOCK immediately.
 353      */
 354     int (*wake)(struct sensors_control_device_t *dev);
 355 };
 356
 357 struct sensors_data_device_t {
 358     struct hw_device_t common;
 359
 360     /**
 361      * Prepare to read sensor data.
 362      *
 363      * This routine does NOT take ownership of the handle
 364      * and must not close it. Typically this routine would
 365      * use a duplicate of the nh parameter.
 366      *
 367      * @param nh from sensors_control_open.
 368      *
 369      * @return 0 if successful, < 0 on error
 370      */
 371     int (*data_open)(struct sensors_data_device_t *dev, native_handle_t* nh);
 372
 373     /**
 374      * Caller has completed using the sensor data.
 375      * The caller will not be blocked in sensors_data_poll
 376      * when this routine is called.
 377      *
 378      * @return 0 if successful, < 0 on error
 379      */
 380     int (*data_close)(struct sensors_data_device_t *dev);
 381
 382     /**
 383      * Return sensor data for one of the enabled sensors.
 384      *
 385      * @return sensor handle for the returned data, 0x7FFFFFFF when
 386      * sensors_control_device_t.wake() is called and -errno on error
 387      *
 388      */
 389     int (*poll)(struct sensors_data_device_t *dev,
 390             sensors_data_t* data);
 391 };
 392
 393
 394 /** convenience API for opening and closing a device */
 395
 396 static inline int sensors_control_open(const struct hw_module_t* module,
 397         struct sensors_control_device_t** device) {
 398     return module->methods->open(module,
 399             SENSORS_HARDWARE_CONTROL, (struct hw_device_t**)device);
 400 }
 401
 402 static inline int sensors_control_close(struct sensors_control_device_t* device) {
 403     return device->common.close(&device->common);
 404 }
 405
 406 static inline int sensors_data_open(const struct hw_module_t* module,
 407         struct sensors_data_device_t** device) {
 408     return module->methods->open(module,
 409             SENSORS_HARDWARE_DATA, (struct hw_device_t**)device);
 410 }
 411
 412 static inline int sensors_data_close(struct sensors_data_device_t* device) {
 413     return device->common.close(&device->common);
 414 }
 415
 416
 417 __END_DECLS
 418
 419 #endif  // ANDROID_SENSORS_INTERFACE_H