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