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