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