sensor.h revision bf6d5e012cd9b15568c2351831f3349cf564bf18 
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/sensor.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
109/**
110 * Sensor accuracy measure.
111 */
112enum {
113    /** no contact */
114    ASENSOR_STATUS_NO_CONTACT       = -1,
115    /** unreliable */
116    ASENSOR_STATUS_UNRELIABLE       = 0,
117    /** low accuracy */
118    ASENSOR_STATUS_ACCURACY_LOW     = 1,
119    /** medium accuracy */
120    ASENSOR_STATUS_ACCURACY_MEDIUM  = 2,
121    /** high accuracy */
122    ASENSOR_STATUS_ACCURACY_HIGH    = 3
123};
124
125/**
126 * Sensor Reporting Modes.
127 */
128enum {
129    /** continuous reporting */
130    AREPORTING_MODE_CONTINUOUS = 0,
131    /** reporting on change */
132    AREPORTING_MODE_ON_CHANGE = 1,
133    /** on shot reporting */
134    AREPORTING_MODE_ONE_SHOT = 2,
135    /** special trigger reporting */
136    AREPORTING_MODE_SPECIAL_TRIGGER = 3
137};
138
139/*
140 * A few useful constants
141 */
142
143/** Earth's gravity in m/s^2 */
144#define ASENSOR_STANDARD_GRAVITY            (9.80665f)
145/** Maximum magnetic field on Earth's surface in uT */
146#define ASENSOR_MAGNETIC_FIELD_EARTH_MAX    (60.0f)
147/** Minimum magnetic field on Earth's surface in uT*/
148#define ASENSOR_MAGNETIC_FIELD_EARTH_MIN    (30.0f)
149
150/**
151 * A sensor event.
152 */
153
154/* NOTE: Must match hardware/sensors.h */
155typedef struct ASensorVector {
156    union {
157        float v[3];
158        struct {
159            float x;
160            float y;
161            float z;
162        };
163        struct {
164            float azimuth;
165            float pitch;
166            float roll;
167        };
168    };
169    int8_t status;
170    uint8_t reserved[3];
171} ASensorVector;
172
173typedef struct AMetaDataEvent {
174    int32_t what;
175    int32_t sensor;
176} AMetaDataEvent;
177
178typedef struct AUncalibratedEvent {
179  union {
180    float uncalib[3];
181    struct {
182      float x_uncalib;
183      float y_uncalib;
184      float z_uncalib;
185    };
186  };
187  union {
188    float bias[3];
189    struct {
190      float x_bias;
191      float y_bias;
192      float z_bias;
193    };
194  };
195} AUncalibratedEvent;
196
197typedef struct AHeartRateEvent {
198  float bpm;
199  int8_t status;
200} AHeartRateEvent;
201
202/* NOTE: Must match hardware/sensors.h */
203typedef struct ASensorEvent {
204    int32_t version; /* sizeof(struct ASensorEvent) */
205    int32_t sensor;
206    int32_t type;
207    int32_t reserved0;
208    int64_t timestamp;
209    union {
210        union {
211            float           data[16];
212            ASensorVector   vector;
213            ASensorVector   acceleration;
214            ASensorVector   magnetic;
215            float           temperature;
216            float           distance;
217            float           light;
218            float           pressure;
219            float           relative_humidity;
220            AUncalibratedEvent uncalibrated_gyro;
221            AUncalibratedEvent uncalibrated_magnetic;
222            AMetaDataEvent meta_data;
223            AHeartRateEvent heart_rate;
224        };
225        union {
226            uint64_t        data[8];
227            uint64_t        step_counter;
228        } u64;
229    };
230
231    uint32_t flags;
232    int32_t reserved1[3];
233} ASensorEvent;
234
235struct ASensorManager;
236/**
237 * {@link ASensorManager} is an opaque type to manage sensors and
238 * events queues.
239 *
240 * {@link ASensorManager} is a singleton that can be obtained using
241 * ASensorManager_getInstance().
242 *
243 * This file provides a set of functions that uses {@link
244 * ASensorManager} to access and list hardware sensors, and
245 * create and destroy event queues:
246 * - ASensorManager_getSensorList()
247 * - ASensorManager_getDefaultSensor()
248 * - ASensorManager_getDefaultSensorEx()
249 * - ASensorManager_createEventQueue()
250 * - ASensorManager_destroyEventQueue()
251 */
252typedef struct ASensorManager ASensorManager;
253
254
255struct ASensorEventQueue;
256/**
257 * {@link ASensorEventQueue} is an opaque type that provides access to
258 * {@link ASensorEvent} from hardware sensors.
259 *
260 * A new {@link ASensorEventQueue} can be obtained using ASensorManager_createEventQueue().
261 *
262 * This file provides a set of functions to enable and disable
263 * sensors, check and get events, and set event rates on a {@link
264 * ASensorEventQueue}.
265 * - ASensorEventQueue_enableSensor()
266 * - ASensorEventQueue_disableSensor()
267 * - ASensorEventQueue_hasEvents()
268 * - ASensorEventQueue_getEvents()
269 * - ASensorEventQueue_setEventRate()
270 */
271typedef struct ASensorEventQueue ASensorEventQueue;
272
273struct ASensor;
274/**
275 * {@link ASensor} is an opaque type that provides information about
276 * an hardware sensors.
277 *
278 * A {@link ASensor} pointer can be obtained using
279 * ASensorManager_getDefaultSensor(),
280 * ASensorManager_getDefaultSensorEx() or from a {@link ASensorList}.
281 *
282 * This file provides a set of functions to access properties of a
283 * {@link ASensor}:
284 * - ASensor_getName()
285 * - ASensor_getVendor()
286 * - ASensor_getType()
287 * - ASensor_getResolution()
288 * - ASensor_getMinDelay()
289 * - ASensor_getFifoMaxEventCount()
290 * - ASensor_getFifoReservedEventCount()
291 * - ASensor_getStringType()
292 * - ASensor_getReportingMode()
293 * - ASensor_isWakeUpSensor()
294 */
295typedef struct ASensor ASensor;
296/**
297 * {@link ASensorRef} is a type for constant pointers to {@link ASensor}.
298 *
299 * This is used to define entry in {@link ASensorList} arrays.
300 */
301typedef ASensor const* ASensorRef;
302/**
303 * {@link ASensorList} is an array of reference to {@link ASensor}.
304 *
305 * A {@link ASensorList} can be initialized using ASensorManager_getSensorList().
306 */
307typedef ASensorRef const* ASensorList;
308
309/*****************************************************************************/
310
311/**
312 * Get a reference to the sensor manager. ASensorManager is a singleton.
313 *
314 * Example:
315 *
316 *     ASensorManager* sensorManager = ASensorManager_getInstance();
317 *
318 */
319ASensorManager* ASensorManager_getInstance();
320
321
322/**
323 * Returns the list of available sensors.
324 */
325int ASensorManager_getSensorList(ASensorManager* manager, ASensorList* list);
326
327/**
328 * Returns the default sensor for the given type, or NULL if no sensor
329 * of that type exists.
330 */
331ASensor const* ASensorManager_getDefaultSensor(ASensorManager* manager, int type);
332
333/**
334 * Returns the default sensor with the given type and wakeUp properties or NULL if no sensor
335 * of this type and wakeUp properties exists.
336 */
337ASensor const* ASensorManager_getDefaultSensorEx(ASensorManager* manager, int type,
338        bool wakeUp);
339
340/**
341 * Creates a new sensor event queue and associate it with a looper.
342 *
343 * "ident" is a identifier for the events that will be returned when
344 * calling ALooper_pollOnce(). The identifier must be >= 0, or
345 * ALOOPER_POLL_CALLBACK if providing a non-NULL callback.
346 */
347ASensorEventQueue* ASensorManager_createEventQueue(ASensorManager* manager,
348        ALooper* looper, int ident, ALooper_callbackFunc callback, void* data);
349
350/**
351 * Destroys the event queue and free all resources associated to it.
352 */
353int ASensorManager_destroyEventQueue(ASensorManager* manager, ASensorEventQueue* queue);
354
355
356/*****************************************************************************/
357
358/**
359 * Enable the selected sensor. Returns a negative error code on failure.
360 */
361int ASensorEventQueue_enableSensor(ASensorEventQueue* queue, ASensor const* sensor);
362
363/**
364 * Disable the selected sensor. Returns a negative error code on failure.
365 */
366int ASensorEventQueue_disableSensor(ASensorEventQueue* queue, ASensor const* sensor);
367
368/**
369 * Sets the delivery rate of events in microseconds for the given sensor.
370 * Note that this is a hint only, generally event will arrive at a higher
371 * rate. It is an error to set a rate inferior to the value returned by
372 * ASensor_getMinDelay().
373 * Returns a negative error code on failure.
374 */
375int ASensorEventQueue_setEventRate(ASensorEventQueue* queue, ASensor const* sensor, int32_t usec);
376
377/**
378 * Returns true if there are one or more events available in the
379 * sensor queue.  Returns 1 if the queue has events; 0 if
380 * it does not have events; and a negative value if there is an error.
381 */
382int ASensorEventQueue_hasEvents(ASensorEventQueue* queue);
383
384/**
385 * Returns the next available events from the queue.  Returns a negative
386 * value if no events are available or an error has occurred, otherwise
387 * the number of events returned.
388 *
389 * Examples:
390 *   ASensorEvent event;
391 *   ssize_t numEvent = ASensorEventQueue_getEvents(queue, &event, 1);
392 *
393 *   ASensorEvent eventBuffer[8];
394 *   ssize_t numEvent = ASensorEventQueue_getEvents(queue, eventBuffer, 8);
395 *
396 */
397ssize_t ASensorEventQueue_getEvents(ASensorEventQueue* queue,
398                ASensorEvent* events, size_t count);
399
400
401/*****************************************************************************/
402
403/**
404 * Returns this sensor's name (non localized)
405 */
406const char* ASensor_getName(ASensor const* sensor);
407
408/**
409 * Returns this sensor's vendor's name (non localized)
410 */
411const char* ASensor_getVendor(ASensor const* sensor);
412
413/**
414 * Return this sensor's type
415 */
416int ASensor_getType(ASensor const* sensor);
417
418/**
419 * Returns this sensors's resolution
420 */
421float ASensor_getResolution(ASensor const* sensor);
422
423/**
424 * Returns the minimum delay allowed between events in microseconds.
425 * A value of zero means that this sensor doesn't report events at a
426 * constant rate, but rather only when a new data is available.
427 */
428int ASensor_getMinDelay(ASensor const* sensor);
429
430/**
431 * Returns the maximum size of batches for this sensor. Batches will often be
432 * smaller, as the hardware fifo might be used for other sensors.
433 */
434int ASensor_getFifoMaxEventCount(ASensor const* sensor);
435
436/**
437 * Returns the hardware batch fifo size reserved to this sensor.
438 */
439int ASensor_getFifoReservedEventCount(ASensor const* sensor);
440
441/**
442 * Returns this sensor's string type.
443 */
444const char* ASensor_getStringType(ASensor const* sensor);
445
446/**
447 * Returns the reporting mode for this sensor. One of AREPORTING_MODE_* constants.
448 */
449int ASensor_getReportingMode(ASensor const* sensor);
450
451/**
452 * Returns true if this is a wake up sensor, false otherwise.
453 */
454bool ASensor_isWakeUpSensor(ASensor const* sensor);
455
456#ifdef __cplusplus
457};
458#endif
459
460#endif // ANDROID_SENSOR_H
461
462/** @} */
463