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