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