sensor.h revision 494ed550f5aea1332984fb9f0f11036fc58bd716
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 * @addtogroup Sensor
19 * @{
20 */
21
22/**
23 * @file sensor.h
24 */
25
26#ifndef ANDROID_SENSOR_H
27#define ANDROID_SENSOR_H
28
29/******************************************************************
30 *
31 * IMPORTANT NOTICE:
32 *
33 *   This file is part of Android's set of stable system headers
34 *   exposed by the Android NDK (Native Development Kit).
35 *
36 *   Third-party source AND binary code relies on the definitions
37 *   here to be FROZEN ON ALL UPCOMING PLATFORM RELEASES.
38 *
39 *   - DO NOT MODIFY ENUMS (EXCEPT IF YOU ADD NEW 32-BIT VALUES)
40 *   - DO NOT MODIFY CONSTANTS OR FUNCTIONAL MACROS
41 *   - DO NOT CHANGE THE SIGNATURE OF FUNCTIONS IN ANY WAY
42 *   - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES
43 */
44
45/**
46 * Structures and functions to receive and process sensor events in
47 * native code.
48 *
49 */
50
51#include <sys/types.h>
52
53#include <android/looper.h>
54
55#ifdef __cplusplus
56extern "C" {
57#endif
58
59
60/**
61 * Sensor types.
62 * (keep in sync with hardware/sensors.h)
63 */
64enum {
65    /**
66     * {@link ASENSOR_TYPE_ACCELEROMETER}
67     * reporting-mode: continuous
68     *
69     *  All values are in SI units (m/s^2) and measure the acceleration of the
70     *  device minus the force of gravity.
71     */
72    ASENSOR_TYPE_ACCELEROMETER       = 1,
73    /**
74     * {@link ASENSOR_TYPE_MAGNETIC_FIELD}
75     * reporting-mode: continuous
76     *
77     *  All values are in micro-Tesla (uT) and measure the geomagnetic
78     *  field in the X, Y and Z axis.
79     */
80    ASENSOR_TYPE_MAGNETIC_FIELD      = 2,
81    /**
82     * {@link ASENSOR_TYPE_GYROSCOPE}
83     * reporting-mode: continuous
84     *
85     *  All values are in radians/second and measure the rate of rotation
86     *  around the X, Y and Z axis.
87     */
88    ASENSOR_TYPE_GYROSCOPE           = 4,
89    /**
90     * {@link ASENSOR_TYPE_LIGHT}
91     * reporting-mode: on-change
92     *
93     * The light sensor value is returned in SI lux units.
94     */
95    ASENSOR_TYPE_LIGHT               = 5,
96    /**
97     * {@link ASENSOR_TYPE_PROXIMITY}
98     * reporting-mode: on-change
99     *
100     * The proximity sensor which turns the screen off and back on during calls is the
101     * wake-up proximity sensor. Implement wake-up proximity sensor before implementing
102     * a non wake-up proximity sensor. For the wake-up proximity sensor set the flag
103     * SENSOR_FLAG_WAKE_UP.
104     * The value corresponds to the distance to the nearest object in centimeters.
105     */
106    ASENSOR_TYPE_PROXIMITY           = 8,
107    /**
108     * {@link ASENSOR_TYPE_LINEAR_ACCELERATION}
109     * reporting-mode: continuous
110     *
111     *  All values are in SI units (m/s^2) and measure the acceleration of the
112     *  device not including the force of gravity.
113     */
114    ASENSOR_TYPE_LINEAR_ACCELERATION = 10
115};
116
117/**
118 * Sensor accuracy measure.
119 */
120enum {
121    /** no contact */
122    ASENSOR_STATUS_NO_CONTACT       = -1,
123    /** unreliable */
124    ASENSOR_STATUS_UNRELIABLE       = 0,
125    /** low accuracy */
126    ASENSOR_STATUS_ACCURACY_LOW     = 1,
127    /** medium accuracy */
128    ASENSOR_STATUS_ACCURACY_MEDIUM  = 2,
129    /** high accuracy */
130    ASENSOR_STATUS_ACCURACY_HIGH    = 3
131};
132
133/**
134 * Sensor Reporting Modes.
135 */
136enum {
137    /** continuous reporting */
138    AREPORTING_MODE_CONTINUOUS = 0,
139    /** reporting on change */
140    AREPORTING_MODE_ON_CHANGE = 1,
141    /** on shot reporting */
142    AREPORTING_MODE_ONE_SHOT = 2,
143    /** special trigger reporting */
144    AREPORTING_MODE_SPECIAL_TRIGGER = 3
145};
146
147/*
148 * A few useful constants
149 */
150
151/** Earth's gravity in m/s^2 */
152#define ASENSOR_STANDARD_GRAVITY            (9.80665f)
153/** Maximum magnetic field on Earth's surface in uT */
154#define ASENSOR_MAGNETIC_FIELD_EARTH_MAX    (60.0f)
155/** Minimum magnetic field on Earth's surface in uT*/
156#define ASENSOR_MAGNETIC_FIELD_EARTH_MIN    (30.0f)
157
158/**
159 * A sensor event.
160 */
161
162/* NOTE: Must match hardware/sensors.h */
163typedef struct ASensorVector {
164    union {
165        float v[3];
166        struct {
167            float x;
168            float y;
169            float z;
170        };
171        struct {
172            float azimuth;
173            float pitch;
174            float roll;
175        };
176    };
177    int8_t status;
178    uint8_t reserved[3];
179} ASensorVector;
180
181typedef struct AMetaDataEvent {
182    int32_t what;
183    int32_t sensor;
184} AMetaDataEvent;
185
186typedef struct AUncalibratedEvent {
187    union {
188        float uncalib[3];
189        struct {
190            float x_uncalib;
191            float y_uncalib;
192            float z_uncalib;
193        };
194    };
195    union {
196        float bias[3];
197        struct {
198            float x_bias;
199            float y_bias;
200            float z_bias;
201        };
202    };
203} AUncalibratedEvent;
204
205typedef struct AHeartRateEvent {
206    float bpm;
207    int8_t status;
208} AHeartRateEvent;
209
210typedef struct ADynamicSensorEvent {
211    int32_t  connected;
212    int32_t  handle;
213} ADynamicSensorEvent;
214
215typedef struct {
216    int32_t type;
217    int32_t serial;
218    union {
219        int32_t data_int32[14];
220        float   data_float[14];
221    };
222} AAdditionalInfoEvent;
223
224/* NOTE: Must match hardware/sensors.h */
225typedef struct ASensorEvent {
226    int32_t version; /* sizeof(struct ASensorEvent) */
227    int32_t sensor;
228    int32_t type;
229    int32_t reserved0;
230    int64_t timestamp;
231    union {
232        union {
233            float           data[16];
234            ASensorVector   vector;
235            ASensorVector   acceleration;
236            ASensorVector   magnetic;
237            float           temperature;
238            float           distance;
239            float           light;
240            float           pressure;
241            float           relative_humidity;
242            AUncalibratedEvent uncalibrated_gyro;
243            AUncalibratedEvent uncalibrated_magnetic;
244            AMetaDataEvent meta_data;
245            AHeartRateEvent heart_rate;
246            ADynamicSensorEvent dynamic_sensor_meta;
247            AAdditionalInfoEvent additional_info;
248        };
249        union {
250            uint64_t        data[8];
251            uint64_t        step_counter;
252        } u64;
253    };
254
255    uint32_t flags;
256    int32_t reserved1[3];
257} ASensorEvent;
258
259struct ASensorManager;
260/**
261 * {@link ASensorManager} is an opaque type to manage sensors and
262 * events queues.
263 *
264 * {@link ASensorManager} is a singleton that can be obtained using
265 * ASensorManager_getInstance().
266 *
267 * This file provides a set of functions that uses {@link
268 * ASensorManager} to access and list hardware sensors, and
269 * create and destroy event queues:
270 * - ASensorManager_getSensorList()
271 * - ASensorManager_getDefaultSensor()
272 * - ASensorManager_getDefaultSensorEx()
273 * - ASensorManager_createEventQueue()
274 * - ASensorManager_destroyEventQueue()
275 */
276typedef struct ASensorManager ASensorManager;
277
278
279struct ASensorEventQueue;
280/**
281 * {@link ASensorEventQueue} is an opaque type that provides access to
282 * {@link ASensorEvent} from hardware sensors.
283 *
284 * A new {@link ASensorEventQueue} can be obtained using ASensorManager_createEventQueue().
285 *
286 * This file provides a set of functions to enable and disable
287 * sensors, check and get events, and set event rates on a {@link
288 * ASensorEventQueue}.
289 * - ASensorEventQueue_enableSensor()
290 * - ASensorEventQueue_disableSensor()
291 * - ASensorEventQueue_hasEvents()
292 * - ASensorEventQueue_getEvents()
293 * - ASensorEventQueue_setEventRate()
294 */
295typedef struct ASensorEventQueue ASensorEventQueue;
296
297struct ASensor;
298/**
299 * {@link ASensor} is an opaque type that provides information about
300 * an hardware sensors.
301 *
302 * A {@link ASensor} pointer can be obtained using
303 * ASensorManager_getDefaultSensor(),
304 * ASensorManager_getDefaultSensorEx() or from a {@link ASensorList}.
305 *
306 * This file provides a set of functions to access properties of a
307 * {@link ASensor}:
308 * - ASensor_getName()
309 * - ASensor_getVendor()
310 * - ASensor_getType()
311 * - ASensor_getResolution()
312 * - ASensor_getMinDelay()
313 * - ASensor_getFifoMaxEventCount()
314 * - ASensor_getFifoReservedEventCount()
315 * - ASensor_getStringType()
316 * - ASensor_getReportingMode()
317 * - ASensor_isWakeUpSensor()
318 */
319typedef struct ASensor ASensor;
320/**
321 * {@link ASensorRef} is a type for constant pointers to {@link ASensor}.
322 *
323 * This is used to define entry in {@link ASensorList} arrays.
324 */
325typedef ASensor const* ASensorRef;
326/**
327 * {@link ASensorList} is an array of reference to {@link ASensor}.
328 *
329 * A {@link ASensorList} can be initialized using ASensorManager_getSensorList().
330 */
331typedef ASensorRef const* ASensorList;
332
333/*****************************************************************************/
334
335/**
336 * Get a reference to the sensor manager. ASensorManager is a singleton
337 * per package as different packages may have access to different sensors.
338 *
339 * Deprecated: Use ASensorManager_getInstanceForPackage(const char*) instead.
340 *
341 * Example:
342 *
343 *     ASensorManager* sensorManager = ASensorManager_getInstance();
344 *
345 */
346__attribute__ ((deprecated)) ASensorManager* ASensorManager_getInstance();
347
348/*
349 * Get a reference to the sensor manager. ASensorManager is a singleton
350 * per package as different packages may have access to different sensors.
351 *
352 * Example:
353 *
354 *    ASensorManager* sensorManager = ASensorManager_getInstanceForPackage("foo.bar.baz");
355 *
356 */
357ASensorManager* ASensorManager_getInstanceForPackage(const char* packageName);
358
359/**
360 * Returns the list of available sensors.
361 */
362int ASensorManager_getSensorList(ASensorManager* manager, ASensorList* list);
363
364/**
365 * Returns the default sensor for the given type, or NULL if no sensor
366 * of that type exists.
367 */
368ASensor const* ASensorManager_getDefaultSensor(ASensorManager* manager, int type);
369
370#if __ANDROID_API__ >= 21
371/**
372 * Returns the default sensor with the given type and wakeUp properties or NULL if no sensor
373 * of this type and wakeUp properties exists.
374 */
375ASensor const* ASensorManager_getDefaultSensorEx(ASensorManager* manager, int type,
376        bool wakeUp);
377#endif
378
379/**
380 * Creates a new sensor event queue and associate it with a looper.
381 *
382 * "ident" is a identifier for the events that will be returned when
383 * calling ALooper_pollOnce(). The identifier must be >= 0, or
384 * ALOOPER_POLL_CALLBACK if providing a non-NULL callback.
385 */
386ASensorEventQueue* ASensorManager_createEventQueue(ASensorManager* manager,
387        ALooper* looper, int ident, ALooper_callbackFunc callback, void* data);
388
389/**
390 * Destroys the event queue and free all resources associated to it.
391 */
392int ASensorManager_destroyEventQueue(ASensorManager* manager, ASensorEventQueue* queue);
393
394
395/*****************************************************************************/
396
397/**
398 * Enable the selected sensor with a specified sampling period and max batch report latency.
399 * Returns a negative error code on failure.
400 */
401int ASensorEventQueue_registerSensor(ASensorEventQueue* queue, ASensor const* sensor,
402        int32_t samplingPeriodUs, int maxBatchReportLatencyUs);
403
404/**
405 * Enable the selected sensor. Returns a negative error code on failure.
406 */
407int ASensorEventQueue_enableSensor(ASensorEventQueue* queue, ASensor const* sensor);
408
409/**
410 * Disable the selected sensor. Returns a negative error code on failure.
411 */
412int ASensorEventQueue_disableSensor(ASensorEventQueue* queue, ASensor const* sensor);
413
414/**
415 * Sets the delivery rate of events in microseconds for the given sensor.
416 * Note that this is a hint only, generally event will arrive at a higher
417 * rate. It is an error to set a rate inferior to the value returned by
418 * ASensor_getMinDelay().
419 * Returns a negative error code on failure.
420 */
421int ASensorEventQueue_setEventRate(ASensorEventQueue* queue, ASensor const* sensor, int32_t usec);
422
423/**
424 * Returns true if there are one or more events available in the
425 * sensor queue.  Returns 1 if the queue has events; 0 if
426 * it does not have events; and a negative value if there is an error.
427 */
428int ASensorEventQueue_hasEvents(ASensorEventQueue* queue);
429
430/**
431 * Returns the next available events from the queue.  Returns a negative
432 * value if no events are available or an error has occurred, otherwise
433 * the number of events returned.
434 *
435 * Examples:
436 *   ASensorEvent event;
437 *   ssize_t numEvent = ASensorEventQueue_getEvents(queue, &event, 1);
438 *
439 *   ASensorEvent eventBuffer[8];
440 *   ssize_t numEvent = ASensorEventQueue_getEvents(queue, eventBuffer, 8);
441 *
442 */
443ssize_t ASensorEventQueue_getEvents(ASensorEventQueue* queue,
444                ASensorEvent* events, size_t count);
445
446
447/*****************************************************************************/
448
449/**
450 * Returns this sensor's name (non localized)
451 */
452const char* ASensor_getName(ASensor const* sensor);
453
454/**
455 * Returns this sensor's vendor's name (non localized)
456 */
457const char* ASensor_getVendor(ASensor const* sensor);
458
459/**
460 * Return this sensor's type
461 */
462int ASensor_getType(ASensor const* sensor);
463
464/**
465 * Returns this sensors's resolution
466 */
467float ASensor_getResolution(ASensor const* sensor);
468
469/**
470 * Returns the minimum delay allowed between events in microseconds.
471 * A value of zero means that this sensor doesn't report events at a
472 * constant rate, but rather only when a new data is available.
473 */
474int ASensor_getMinDelay(ASensor const* sensor);
475
476#if __ANDROID_API__ >= 21
477/**
478 * Returns the maximum size of batches for this sensor. Batches will often be
479 * smaller, as the hardware fifo might be used for other sensors.
480 */
481int ASensor_getFifoMaxEventCount(ASensor const* sensor);
482
483/**
484 * Returns the hardware batch fifo size reserved to this sensor.
485 */
486int ASensor_getFifoReservedEventCount(ASensor const* sensor);
487
488/**
489 * Returns this sensor's string type.
490 */
491const char* ASensor_getStringType(ASensor const* sensor);
492
493/**
494 * Returns the reporting mode for this sensor. One of AREPORTING_MODE_* constants.
495 */
496int ASensor_getReportingMode(ASensor const* sensor);
497
498/**
499 * Returns true if this is a wake up sensor, false otherwise.
500 */
501bool ASensor_isWakeUpSensor(ASensor const* sensor);
502#endif /* __ANDROID_API__ >= 21 */
503
504#ifdef __cplusplus
505};
506#endif
507
508#endif // ANDROID_SENSOR_H
509
510/** @} */
511