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