sensor.h revision ba02cd2f6cc3f59adf66cb2b9176bfe6c9e382d1
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 109/* NOTE: Must match hardware/sensors.h */ 110typedef struct ASensorEvent { 111 int32_t version; /* sizeof(struct ASensorEvent) */ 112 int32_t sensor; 113 int32_t type; 114 int32_t reserved0; 115 int64_t timestamp; 116 union { 117 union { 118 float data[16]; 119 ASensorVector vector; 120 ASensorVector acceleration; 121 ASensorVector magnetic; 122 float temperature; 123 float distance; 124 float light; 125 float pressure; 126 }; 127 union { 128 uint64_t data[8]; 129 uint64_t step_counter; 130 } u64; 131 }; 132 int32_t reserved1[4]; 133} ASensorEvent; 134 135 136struct ASensorManager; 137typedef struct ASensorManager ASensorManager; 138 139struct ASensorEventQueue; 140typedef struct ASensorEventQueue ASensorEventQueue; 141 142struct ASensor; 143typedef struct ASensor ASensor; 144typedef ASensor const* ASensorRef; 145typedef ASensorRef const* ASensorList; 146 147/*****************************************************************************/ 148 149/* 150 * Get a reference to the sensor manager. ASensorManager is a singleton. 151 * 152 * Example: 153 * 154 * ASensorManager* sensorManager = ASensorManager_getInstance(); 155 * 156 */ 157ASensorManager* ASensorManager_getInstance(); 158 159 160/* 161 * Returns the list of available sensors. 162 */ 163int ASensorManager_getSensorList(ASensorManager* manager, ASensorList* list); 164 165/* 166 * Returns the default sensor for the given type, or NULL if no sensor 167 * of that type exist. 168 */ 169ASensor const* ASensorManager_getDefaultSensor(ASensorManager* manager, int type); 170 171/* 172 * Creates a new sensor event queue and associate it with a looper. 173 */ 174ASensorEventQueue* ASensorManager_createEventQueue(ASensorManager* manager, 175 ALooper* looper, int ident, ALooper_callbackFunc callback, void* data); 176 177/* 178 * Destroys the event queue and free all resources associated to it. 179 */ 180int ASensorManager_destroyEventQueue(ASensorManager* manager, ASensorEventQueue* queue); 181 182 183/*****************************************************************************/ 184 185/* 186 * Enable the selected sensor. Returns a negative error code on failure. 187 */ 188int ASensorEventQueue_enableSensor(ASensorEventQueue* queue, ASensor const* sensor); 189 190/* 191 * Disable the selected sensor. Returns a negative error code on failure. 192 */ 193int ASensorEventQueue_disableSensor(ASensorEventQueue* queue, ASensor const* sensor); 194 195/* 196 * Sets the delivery rate of events in microseconds for the given sensor. 197 * Note that this is a hint only, generally event will arrive at a higher 198 * rate. It is an error to set a rate inferior to the value returned by 199 * ASensor_getMinDelay(). 200 * Returns a negative error code on failure. 201 */ 202int ASensorEventQueue_setEventRate(ASensorEventQueue* queue, ASensor const* sensor, int32_t usec); 203 204/* 205 * Returns true if there are one or more events available in the 206 * sensor queue. Returns 1 if the queue has events; 0 if 207 * it does not have events; and a negative value if there is an error. 208 */ 209int ASensorEventQueue_hasEvents(ASensorEventQueue* queue); 210 211/* 212 * Returns the next available events from the queue. Returns a negative 213 * value if no events are available or an error has occurred, otherwise 214 * the number of events returned. 215 * 216 * Examples: 217 * ASensorEvent event; 218 * ssize_t numEvent = ASensorEventQueue_getEvents(queue, &event, 1); 219 * 220 * ASensorEvent eventBuffer[8]; 221 * ssize_t numEvent = ASensorEventQueue_getEvents(queue, eventBuffer, 8); 222 * 223 */ 224ssize_t ASensorEventQueue_getEvents(ASensorEventQueue* queue, 225 ASensorEvent* events, size_t count); 226 227 228/*****************************************************************************/ 229 230/* 231 * Returns this sensor's name (non localized) 232 */ 233const char* ASensor_getName(ASensor const* sensor); 234 235/* 236 * Returns this sensor's vendor's name (non localized) 237 */ 238const char* ASensor_getVendor(ASensor const* sensor); 239 240/* 241 * Return this sensor's type 242 */ 243int ASensor_getType(ASensor const* sensor); 244 245/* 246 * Returns this sensors's resolution 247 */ 248float ASensor_getResolution(ASensor const* sensor); 249 250/* 251 * Returns the minimum delay allowed between events in microseconds. 252 * A value of zero means that this sensor doesn't report events at a 253 * constant rate, but rather only when a new data is available. 254 */ 255int ASensor_getMinDelay(ASensor const* sensor); 256 257 258#ifdef __cplusplus 259}; 260#endif 261 262#endif // ANDROID_SENSOR_H 263