sensors.h revision 1832f55760fff86d00b5d808b3da8f1e55a889e5
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 */ 216typedef struct { 217 union { 218 float v[3]; 219 struct { 220 float x; 221 float y; 222 float z; 223 }; 224 struct { 225 float azimuth; 226 float pitch; 227 float roll; 228 }; 229 }; 230 int8_t status; 231 uint8_t reserved[3]; 232} sensors_vec_t; 233 234/** 235 * Union of the various types of sensor data 236 * that can be returned. 237 */ 238typedef struct sensors_event_t { 239 /* must be sizeof(struct sensors_event_t) */ 240 int32_t version; 241 242 /* sensor identifier */ 243 int32_t sensor; 244 245 /* sensor type */ 246 int32_t type; 247 248 /* reserved */ 249 int32_t reserved0; 250 251 /* time is in nanosecond */ 252 int64_t timestamp; 253 254 union { 255 float data[16]; 256 257 /* acceleration values are in meter per second per second (m/s^2) */ 258 sensors_vec_t acceleration; 259 260 /* magnetic vector values are in micro-Tesla (uT) */ 261 sensors_vec_t magnetic; 262 263 /* orientation values are in degrees */ 264 sensors_vec_t orientation; 265 266 /* temperature is in degrees centigrade (Celsius) */ 267 float temperature; 268 269 /* distance in centimeters */ 270 float distance; 271 272 /* light in SI lux units */ 273 float light; 274 275 /* pressure in hectopascal (hPa) */ 276 float pressure; 277 }; 278 uint32_t reserved1[4]; 279} sensors_event_t; 280 281 282 283struct sensor_t; 284 285/** 286 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM 287 * and the fields of this data structure must begin with hw_module_t 288 * followed by module specific information. 289 */ 290struct sensors_module_t { 291 struct hw_module_t common; 292 293 /** 294 * Enumerate all available sensors. The list is returned in "list". 295 * @return number of sensors in the list 296 */ 297 int (*get_sensors_list)(struct sensors_module_t* module, 298 struct sensor_t const** list); 299}; 300 301struct sensor_t { 302 /* name of this sensors */ 303 const char* name; 304 /* vendor of the hardware part */ 305 const char* vendor; 306 /* version of the hardware part + driver. The value of this field is 307 * left to the implementation and doesn't have to be monotonically 308 * increasing. 309 */ 310 int version; 311 /* handle that identifies this sensors. This handle is used to activate 312 * and deactivate this sensor. The value of the handle must be 8 bits 313 * in this version of the API. 314 */ 315 int handle; 316 /* this sensor's type. */ 317 int type; 318 /* maximaum range of this sensor's value in SI units */ 319 float maxRange; 320 /* smallest difference between two values reported by this sensor */ 321 float resolution; 322 /* rough estimate of this sensor's power consumption in mA */ 323 float power; 324 /* reserved fields, must be zero */ 325 void* reserved[9]; 326}; 327 328 329/** 330 * Every device data structure must begin with hw_device_t 331 * followed by module specific public methods and attributes. 332 */ 333struct sensors_poll_device_t { 334 struct hw_device_t common; 335 336 /** Activate/deactivate one sensor. 337 * 338 * @param handle is the handle of the sensor to change. 339 * @param enabled set to 1 to enable, or 0 to disable the sensor. 340 * 341 * @return 0 on success, negative errno code otherwise 342 */ 343 int (*activate)(struct sensors_poll_device_t *dev, 344 int handle, int enabled); 345 346 /** 347 * Set the delay between sensor events in nanoseconds for a given sensor 348 * 349 * @return 0 if successful, < 0 on error 350 */ 351 int (*setDelay)(struct sensors_poll_device_t *dev, 352 int handle, int64_t ns); 353 354 /** 355 * Returns an array of sensor data. 356 * 357 * @return the number of events read on success, or -errno in case of an error. 358 * 359 */ 360 int (*poll)(struct sensors_poll_device_t *dev, 361 sensors_event_t* data, int count); 362}; 363 364/** convenience API for opening and closing a device */ 365 366static inline int sensors_open(const struct hw_module_t* module, 367 struct sensors_poll_device_t** device) { 368 return module->methods->open(module, 369 SENSORS_HARDWARE_POLL, (struct hw_device_t**)device); 370} 371 372static inline int sensors_close(struct sensors_poll_device_t* device) { 373 return device->common.close(&device->common); 374} 375 376__END_DECLS 377 378#include <hardware/sensors_deprecated.h> 379 380#endif // ANDROID_SENSORS_INTERFACE_H 381