sensor.h revision e75b7b491e9e345801c8f3cb72bca08b0f153abf 
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#ifdef __cplusplus
303};
304#endif
305
306#endif // ANDROID_SENSOR_H
307