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