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