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 49extern "C" { 50#endif 51 52 53/* 54 * Sensor types 55 * (keep in sync with hardware/sensor.h) 56 */ 57 58enum { 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 */ 69enum { 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 */ 80enum { 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 */ 103typedef 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 121typedef struct AMetaDataEvent { 122 int32_t what; 123 int32_t sensor; 124} AMetaDataEvent; 125 126typedef 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 145typedef struct AHeartRateEvent { 146 float bpm; 147 int8_t status; 148} AHeartRateEvent; 149 150/* NOTE: Must match hardware/sensors.h */ 151typedef 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 183struct ASensorManager; 184typedef struct ASensorManager ASensorManager; 185 186struct ASensorEventQueue; 187typedef struct ASensorEventQueue ASensorEventQueue; 188 189struct ASensor; 190typedef struct ASensor ASensor; 191typedef ASensor const* ASensorRef; 192typedef 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 */ 204ASensorManager* ASensorManager_getInstance(); 205 206 207/* 208 * Returns the list of available sensors. 209 */ 210int 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 */ 216ASensor 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 */ 222ASensor 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 */ 228ASensorEventQueue* 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 */ 234int ASensorManager_destroyEventQueue(ASensorManager* manager, ASensorEventQueue* queue); 235 236 237/*****************************************************************************/ 238 239/* 240 * Enable the selected sensor. Returns a negative error code on failure. 241 */ 242int ASensorEventQueue_enableSensor(ASensorEventQueue* queue, ASensor const* sensor); 243 244/* 245 * Disable the selected sensor. Returns a negative error code on failure. 246 */ 247int 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 */ 256int 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 */ 263int 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 */ 278ssize_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 */ 287const char* ASensor_getName(ASensor const* sensor); 288 289/* 290 * Returns this sensor's vendor's name (non localized) 291 */ 292const char* ASensor_getVendor(ASensor const* sensor); 293 294/* 295 * Return this sensor's type 296 */ 297int ASensor_getType(ASensor const* sensor); 298 299/* 300 * Returns this sensors's resolution 301 */ 302float 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 */ 309int 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 */ 315int ASensor_getFifoMaxEventCount(ASensor const* sensor); 316 317/* 318 * Returns the hardware batch fifo size reserved to this sensor. 319 */ 320int ASensor_getFifoReservedEventCount(ASensor const* sensor); 321 322/* 323 * Returns this sensor's string type. 324 */ 325const char* ASensor_getStringType(ASensor const* sensor); 326 327/* 328 * Returns the reporting mode for this sensor. One of AREPORTING_MODE_* constants. 329 */ 330int ASensor_getReportingMode(ASensor const* sensor); 331 332/* 333 * Returns true if this is a wake up sensor, false otherwise. 334 */ 335bool ASensor_isWakeUpSensor(ASensor const* sensor); 336 337#ifdef __cplusplus 338}; 339#endif 340 341#endif // ANDROID_SENSOR_H 342