1 /* 2 * Copyright (C) 2010 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 18 #ifndef ANDROID_SENSOR_H 19 #define ANDROID_SENSOR_H 20 21 /****************************************************************** 22 * 23 * IMPORTANT NOTICE: 24 * 25 * This file is part of Android's set of stable system headers 26 * exposed by the Android NDK (Native Development Kit). 27 * 28 * Third-party source AND binary code relies on the definitions 29 * here to be FROZEN ON ALL UPCOMING PLATFORM RELEASES. 30 * 31 * - DO NOT MODIFY ENUMS (EXCEPT IF YOU ADD NEW 32-BIT VALUES) 32 * - DO NOT MODIFY CONSTANTS OR FUNCTIONAL MACROS 33 * - DO NOT CHANGE THE SIGNATURE OF FUNCTIONS IN ANY WAY 34 * - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES 35 */ 36 37 /* 38 * Structures and functions to receive and process sensor events in 39 * native code. 40 * 41 */ 42 43 #include <sys/types.h> 44 45 #include <android/looper.h> 46 47 #ifdef __cplusplus 48 extern "C" { 49 #endif 50 51 52 /* 53 * Sensor types 54 * (keep in sync with hardware/sensor.h) 55 */ 56 57 enum { 58 ASENSOR_TYPE_ACCELEROMETER = 1, 59 ASENSOR_TYPE_MAGNETIC_FIELD = 2, 60 ASENSOR_TYPE_GYROSCOPE = 4, 61 ASENSOR_TYPE_LIGHT = 5, 62 ASENSOR_TYPE_PROXIMITY = 8 63 }; 64 65 /* 66 * Sensor accuracy measure 67 */ 68 enum { 69 ASENSOR_STATUS_NO_CONTACT = -1, 70 ASENSOR_STATUS_UNRELIABLE = 0, 71 ASENSOR_STATUS_ACCURACY_LOW = 1, 72 ASENSOR_STATUS_ACCURACY_MEDIUM = 2, 73 ASENSOR_STATUS_ACCURACY_HIGH = 3 74 }; 75 76 /* 77 * Sensor Reporting Modes. 78 */ 79 enum { 80 AREPORTING_MODE_CONTINUOUS = 0, 81 AREPORTING_MODE_ON_CHANGE = 1, 82 AREPORTING_MODE_ONE_SHOT = 2, 83 AREPORTING_MODE_SPECIAL_TRIGGER = 3 84 }; 85 86 /* 87 * A few useful constants 88 */ 89 90 /* Earth's gravity in m/s^2 */ 91 #define ASENSOR_STANDARD_GRAVITY (9.80665f) 92 /* Maximum magnetic field on Earth's surface in uT */ 93 #define ASENSOR_MAGNETIC_FIELD_EARTH_MAX (60.0f) 94 /* Minimum magnetic field on Earth's surface in uT*/ 95 #define ASENSOR_MAGNETIC_FIELD_EARTH_MIN (30.0f) 96 97 /* 98 * A sensor event. 99 */ 100 101 /* NOTE: Must match hardware/sensors.h */ 102 typedef struct ASensorVector { 103 union { 104 float v[3]; 105 struct { 106 float x; 107 float y; 108 float z; 109 }; 110 struct { 111 float azimuth; 112 float pitch; 113 float roll; 114 }; 115 }; 116 int8_t status; 117 uint8_t reserved[3]; 118 } ASensorVector; 119 120 typedef struct AMetaDataEvent { 121 int32_t what; 122 int32_t sensor; 123 } AMetaDataEvent; 124 125 typedef struct AUncalibratedEvent { 126 union { 127 float uncalib[3]; 128 struct { 129 float x_uncalib; 130 float y_uncalib; 131 float z_uncalib; 132 }; 133 }; 134 union { 135 float bias[3]; 136 struct { 137 float x_bias; 138 float y_bias; 139 float z_bias; 140 }; 141 }; 142 } AUncalibratedEvent; 143 144 typedef struct AHeartRateEvent { 145 float bpm; 146 int8_t status; 147 } AHeartRateEvent; 148 149 /* NOTE: Must match hardware/sensors.h */ 150 typedef struct ASensorEvent { 151 int32_t version; /* sizeof(struct ASensorEvent) */ 152 int32_t sensor; 153 int32_t type; 154 int32_t reserved0; 155 int64_t timestamp; 156 union { 157 union { 158 float data[16]; 159 ASensorVector vector; 160 ASensorVector acceleration; 161 ASensorVector magnetic; 162 float temperature; 163 float distance; 164 float light; 165 float pressure; 166 float relative_humidity; 167 AUncalibratedEvent uncalibrated_gyro; 168 AUncalibratedEvent uncalibrated_magnetic; 169 AMetaDataEvent meta_data; 170 AHeartRateEvent heart_rate; 171 }; 172 union { 173 uint64_t data[8]; 174 uint64_t step_counter; 175 } u64; 176 }; 177 178 uint32_t flags; 179 int32_t reserved1[3]; 180 } ASensorEvent; 181 182 struct ASensorManager; 183 typedef struct ASensorManager ASensorManager; 184 185 struct ASensorEventQueue; 186 typedef struct ASensorEventQueue ASensorEventQueue; 187 188 struct ASensor; 189 typedef struct ASensor ASensor; 190 typedef ASensor const* ASensorRef; 191 typedef ASensorRef const* ASensorList; 192 193 /*****************************************************************************/ 194 195 /* 196 * Get a reference to the sensor manager. ASensorManager is a singleton 197 * per package as different packages may have access to different sensors. 198 * 199 * Deprecated: Use ASensorManager_getInstanceForPackage(const char*) instead. 200 * 201 * Example: 202 * 203 * ASensorManager* sensorManager = ASensorManager_getInstance(); 204 * 205 */ 206 __attribute__ ((deprecated)) ASensorManager* ASensorManager_getInstance(); 207 208 /* 209 * Get a reference to the sensor manager. ASensorManager is a singleton 210 * per package as different packages may have access to different sensors. 211 * 212 * Example: 213 * 214 * ASensorManager* sensorManager = ASensorManager_getInstanceForPackage("foo.bar.baz"); 215 * 216 */ 217 ASensorManager* ASensorManager_getInstanceForPackage(const char* packageName); 218 219 /* 220 * Returns the list of available sensors. 221 */ 222 int ASensorManager_getSensorList(ASensorManager* manager, ASensorList* list); 223 224 /* 225 * Returns the default sensor for the given type, or NULL if no sensor 226 * of that type exists. 227 */ 228 ASensor const* ASensorManager_getDefaultSensor(ASensorManager* manager, int type); 229 230 /* 231 * Returns the default sensor with the given type and wakeUp properties or NULL if no sensor 232 * of this type and wakeUp properties exists. 233 */ 234 ASensor const* ASensorManager_getDefaultSensorEx(ASensorManager* manager, int type, 235 bool wakeUp); 236 237 /* 238 * Creates a new sensor event queue and associate it with a looper. 239 */ 240 ASensorEventQueue* ASensorManager_createEventQueue(ASensorManager* manager, 241 ALooper* looper, int ident, ALooper_callbackFunc callback, void* data); 242 243 /* 244 * Destroys the event queue and free all resources associated to it. 245 */ 246 int ASensorManager_destroyEventQueue(ASensorManager* manager, ASensorEventQueue* queue); 247 248 249 /*****************************************************************************/ 250 251 /* 252 * Enable the selected sensor. Returns a negative error code on failure. 253 */ 254 int ASensorEventQueue_enableSensor(ASensorEventQueue* queue, ASensor const* sensor); 255 256 /* 257 * Disable the selected sensor. Returns a negative error code on failure. 258 */ 259 int ASensorEventQueue_disableSensor(ASensorEventQueue* queue, ASensor const* sensor); 260 261 /* 262 * Sets the delivery rate of events in microseconds for the given sensor. 263 * Note that this is a hint only, generally event will arrive at a higher 264 * rate. It is an error to set a rate inferior to the value returned by 265 * ASensor_getMinDelay(). 266 * Returns a negative error code on failure. 267 */ 268 int ASensorEventQueue_setEventRate(ASensorEventQueue* queue, ASensor const* sensor, int32_t usec); 269 270 /* 271 * Returns true if there are one or more events available in the 272 * sensor queue. Returns 1 if the queue has events; 0 if 273 * it does not have events; and a negative value if there is an error. 274 */ 275 int ASensorEventQueue_hasEvents(ASensorEventQueue* queue); 276 277 /* 278 * Returns the next available events from the queue. Returns a negative 279 * value if no events are available or an error has occurred, otherwise 280 * the number of events returned. 281 * 282 * Examples: 283 * ASensorEvent event; 284 * ssize_t numEvent = ASensorEventQueue_getEvents(queue, &event, 1); 285 * 286 * ASensorEvent eventBuffer[8]; 287 * ssize_t numEvent = ASensorEventQueue_getEvents(queue, eventBuffer, 8); 288 * 289 */ 290 ssize_t ASensorEventQueue_getEvents(ASensorEventQueue* queue, 291 ASensorEvent* events, size_t count); 292 293 294 /*****************************************************************************/ 295 296 /* 297 * Returns this sensor's name (non localized) 298 */ 299 const char* ASensor_getName(ASensor const* sensor); 300 301 /* 302 * Returns this sensor's vendor's name (non localized) 303 */ 304 const char* ASensor_getVendor(ASensor const* sensor); 305 306 /* 307 * Return this sensor's type 308 */ 309 int ASensor_getType(ASensor const* sensor); 310 311 /* 312 * Returns this sensors's resolution 313 */ 314 float ASensor_getResolution(ASensor const* sensor); 315 316 /* 317 * Returns the minimum delay allowed between events in microseconds. 318 * A value of zero means that this sensor doesn't report events at a 319 * constant rate, but rather only when a new data is available. 320 */ 321 int ASensor_getMinDelay(ASensor const* sensor); 322 323 /* 324 * Returns the maximum size of batches for this sensor. Batches will often be 325 * smaller, as the hardware fifo might be used for other sensors. 326 */ 327 int ASensor_getFifoMaxEventCount(ASensor const* sensor); 328 329 /* 330 * Returns the hardware batch fifo size reserved to this sensor. 331 */ 332 int ASensor_getFifoReservedEventCount(ASensor const* sensor); 333 334 /* 335 * Returns this sensor's string type. 336 */ 337 const char* ASensor_getStringType(ASensor const* sensor); 338 339 /* 340 * Returns the reporting mode for this sensor. One of AREPORTING_MODE_* constants. 341 */ 342 int ASensor_getReportingMode(ASensor const* sensor); 343 344 /* 345 * Returns true if this is a wake up sensor, false otherwise. 346 */ 347 bool ASensor_isWakeUpSensor(ASensor const* sensor); 348 349 #ifdef __cplusplus 350 }; 351 #endif 352 353 #endif // ANDROID_SENSOR_H 354