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 AWAY from the z-axis.
 142  *
 143  * Note: This definition is different from yaw, pitch and roll used in aviation
 144  *  where the X axis is along the long side of the plane (tail to nose).
 145  *
 146  *
 147  * Acceleration
 148  * ------------
 149  *
 150  *  All values are in SI units (m/s^2) and measure the acceleration of the
 151  *  device minus the force of gravity.
 152  *
 153  *  x: Acceleration minus Gx on the x-axis
 154  *  y: Acceleration minus Gy on the y-axis
 155  *  z: Acceleration minus Gz on the z-axis
 156  *
 157  *  Examples:
 158  *    When the device lies flat on a table and is pushed on its left side
 159  *    toward the right, the x acceleration value is positive.
 160  *
 161  *    When the device lies flat on a table, the acceleration value is +9.81,
 162  *    which correspond to the acceleration of the device (0 m/s^2) minus the
 163  *    force of gravity (-9.81 m/s^2).
 164  *
 165  *    When the device lies flat on a table and is pushed toward the sky, the
 166  *    acceleration value is greater than +9.81, which correspond to the
 167  *    acceleration of the device (+A m/s^2) minus the force of
 168  *    gravity (-9.81 m/s^2).
 169  *
 170  *
 171  * Magnetic Field
 172  * --------------
 173  *
 174  *  All values are in micro-Tesla (uT) and measure the ambient magnetic
 175  *  field in the X, Y and Z axis.
 176  *
 177  */
 178 typedef struct {
 179     union {
 180         float v[3];
 181         struct {
 182             float x;
 183             float y;
 184             float z;
 185         };
 186         struct {
 187             float azimuth;
 188             float pitch;
 189             float roll;
 190         };
 191     };
 192     int8_t status;
 193     uint8_t reserved[3];
 194 } sensors_vec_t;
 195
 196 /**
 197  * Union of the various types of sensor data
 198  * that can be returned.
 199  */
 200 typedef struct {
 201     /* sensor identifier */
 202     int             sensor;
 203
 204     union {
 205         /* x,y,z values of the given sensor */
 206         sensors_vec_t   vector;
 207
 208         /* orientation values are in degrees */
 209         sensors_vec_t   orientation;
 210
 211         /* acceleration values are in meter per second per second (m/s^2) */
 212         sensors_vec_t   acceleration;
 213
 214         /* magnetic vector values are in micro-Tesla (uT) */
 215         sensors_vec_t   magnetic;
 216
 217         /* temperature is in degrees centigrade (Celsius) */
 218         float           temperature;
 219     };
 220
 221     /* time is in nanosecond */
 222     int64_t         time;
 223
 224     uint32_t        reserved;
 225 } sensors_data_t;
 226
 227
 228 struct sensor_t;
 229
 230 /**
 231  * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
 232  * and the fields of this data structure must begin with hw_module_t
 233  * followed by module specific information.
 234  */
 235 struct sensors_module_t {
 236     struct hw_module_t common;
 237
 238     /**
 239      * Enumerate all available sensors. The list is returned in "list".
 240      * @return number of sensors in the list
 241      */
 242     int (*get_sensors_list)(struct sensors_module_t* module,
 243             struct sensor_t const** list);
 244 };
 245
 246 struct sensor_t {
 247     /* name of this sensors */
 248     const char*     name;
 249     /* vendor of the hardware part */
 250     const char*     vendor;
 251     /* version of the hardware part + driver. The value of this field is
 252      * left to the implementation and doesn't have to be monotonicaly
 253      * increasing.
 254      */
 255     int             version;
 256     /* handle that identifies this sensors. This handle is used to activate
 257      * and deactivate this sensor. The value of the handle must be 8 bits
 258      * in this version of the API.
 259      */
 260     int             handle;
 261     /* this sensor's type. */
 262     int             type;
 263     /* maximaum range of this sensor's value in SI units */
 264     float           maxRange;
 265     /* smallest difference between two values reported by this sensor */
 266     float           resolution;
 267     /* rough estimate of this sensor's power consumption in mA */
 268     float           power;
 269     /* reserved fields, must be zero */
 270     void*           reserved[9];
 271 };
 272
 273
 274 /**
 275  * Every device data structure must begin with hw_device_t
 276  * followed by module specific public methods and attributes.
 277  */
 278 struct sensors_control_device_t {
 279     struct hw_device_t common;
 280
 281     /**
 282      * Returns a native_handle_t, which will be the parameter to
 283      * sensors_data_device_t::open_data().
 284      * The caller takes ownership of this handle. This is intended to be
 285      * passed cross processes.
 286      *
 287      * @return a native_handle_t if successful, < 0 on error
 288      */
 289     native_handle_t* (*open_data_source)(struct sensors_control_device_t *dev);
 290
 291     /** Activate/deactivate one sensor.
 292      *
 293      * @param handle is the handle of the sensor to change.
 294      * @param enabled set to 1 to enable, or 0 to disable the sensor.
 295      *
 296      * @return 0 on success, negative errno code otherwise
 297      */
 298     int (*activate)(struct sensors_control_device_t *dev,
 299             int handle, int enabled);
 300
 301     /**
 302      * Set the delay between sensor events in ms
 303      *
 304      * @return 0 if successful, < 0 on error
 305      */
 306     int (*set_delay)(struct sensors_control_device_t *dev, int32_t ms);
 307
 308     /**
 309      * Causes sensors_data_device_t.poll() to return -EWOULDBLOCK immediately.
 310      */
 311     int (*wake)(struct sensors_control_device_t *dev);
 312 };
 313
 314 struct sensors_data_device_t {
 315     struct hw_device_t common;
 316
 317     /**
 318      * Prepare to read sensor data.
 319      *
 320      * This routine does NOT take ownership of the handle
 321      * and must not close it. Typically this routine would
 322      * use a duplicate of the nh parameter.
 323      *
 324      * @param nh from sensors_control_open.
 325      *
 326      * @return 0 if successful, < 0 on error
 327      */
 328     int (*data_open)(struct sensors_data_device_t *dev, native_handle_t* nh);
 329
 330     /**
 331      * Caller has completed using the sensor data.
 332      * The caller will not be blocked in sensors_data_poll
 333      * when this routine is called.
 334      *
 335      * @return 0 if successful, < 0 on error
 336      */
 337     int (*data_close)(struct sensors_data_device_t *dev);
 338
 339     /**
 340      * Return sensor data for one of the enabled sensors.
 341      *
 342      * @return sensor handle for the returned data, 0x7FFFFFFF when
 343      * sensors_control_device_t.wake() is called and -errno on error
 344      *
 345      */
 346     int (*poll)(struct sensors_data_device_t *dev,
 347             sensors_data_t* data);
 348 };
 349
 350
 351 /** convenience API for opening and closing a device */
 352
 353 static inline int sensors_control_open(const struct hw_module_t* module,
 354         struct sensors_control_device_t** device) {
 355     return module->methods->open(module,
 356             SENSORS_HARDWARE_CONTROL, (struct hw_device_t**)device);
 357 }
 358
 359 static inline int sensors_control_close(struct sensors_control_device_t* device) {
 360     return device->common.close(&device->common);
 361 }
 362
 363 static inline int sensors_data_open(const struct hw_module_t* module,
 364         struct sensors_data_device_t** device) {
 365     return module->methods->open(module,
 366             SENSORS_HARDWARE_DATA, (struct hw_device_t**)device);
 367 }
 368
 369 static inline int sensors_data_close(struct sensors_data_device_t* device) {
 370     return device->common.close(&device->common);
 371 }
 372
 373
 374 __END_DECLS
 375
 376 #endif  // ANDROID_SENSORS_INTERFACE_H