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