blob: ca017a0f40abb244027f1cce2e45ff308cca7d99 [file] [log] [blame]
The Android Open Source Projectf53ebec2009-03-03 19:32:14 -08001/*
Mathias Agopiana4557722012-11-28 17:21:55 -08002 * Copyright (C) 2012 The Android Open Source Project
The Android Open Source Projectf53ebec2009-03-03 19:32:14 -08003 *
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#ifndef ANDROID_SENSORS_INTERFACE_H
18#define ANDROID_SENSORS_INTERFACE_H
19
20#include <stdint.h>
21#include <sys/cdefs.h>
22#include <sys/types.h>
23
24#include <hardware/hardware.h>
Mike Lockwood21b652f2009-05-22 10:05:48 -040025#include <cutils/native_handle.h>
The Android Open Source Projectf53ebec2009-03-03 19:32:14 -080026
27__BEGIN_DECLS
28
Mathias Agopian56f66cc2012-11-08 15:57:38 -080029/*****************************************************************************/
30
31#define SENSORS_HEADER_VERSION 1
32#define SENSORS_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1)
33#define SENSORS_DEVICE_API_VERSION_0_1 HARDWARE_DEVICE_API_VERSION_2(0, 1, SENSORS_HEADER_VERSION)
Mathias Agopiana4557722012-11-28 17:21:55 -080034#define SENSORS_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION_2(1, 0, SENSORS_HEADER_VERSION)
Mathias Agopian16671c52013-07-24 21:07:40 -070035#define SENSORS_DEVICE_API_VERSION_1_1 HARDWARE_DEVICE_API_VERSION_2(1, 1, SENSORS_HEADER_VERSION)
Aravind Akella477fbd52014-04-07 22:46:01 +000036#define SENSORS_DEVICE_API_VERSION_1_2 HARDWARE_DEVICE_API_VERSION_2(1, 2, SENSORS_HEADER_VERSION)
Mathias Agopian56f66cc2012-11-08 15:57:38 -080037
The Android Open Source Projectf53ebec2009-03-03 19:32:14 -080038/**
Clay Murphy8db1fb42013-12-19 09:58:28 -080039 * Please see the Sensors section of source.android.com for an
40 * introduction to and detailed descriptions of Android sensor types:
41 * http://source.android.com/devices/sensors/index.html
42 */
43
44/**
The Android Open Source Projectf53ebec2009-03-03 19:32:14 -080045 * The id of this module
46 */
47#define SENSORS_HARDWARE_MODULE_ID "sensors"
48
49/**
50 * Name of the sensors device to open
51 */
Mathias Agopianb1e212e2010-07-08 16:44:54 -070052#define SENSORS_HARDWARE_POLL "poll"
The Android Open Source Projectf53ebec2009-03-03 19:32:14 -080053
54/**
55 * Handles must be higher than SENSORS_HANDLE_BASE and must be unique.
56 * A Handle identifies a given sensors. The handle is used to activate
57 * and/or deactivate sensors.
58 * In this version of the API there can only be 256 handles.
59 */
60#define SENSORS_HANDLE_BASE 0
61#define SENSORS_HANDLE_BITS 8
62#define SENSORS_HANDLE_COUNT (1<<SENSORS_HANDLE_BITS)
63
64
Mathias Agopiana4557722012-11-28 17:21:55 -080065/*
66 * flags for (*batch)()
67 * Availability: SENSORS_DEVICE_API_VERSION_1_0
68 * see (*batch)() documentation for details
69 */
70enum {
71 SENSORS_BATCH_DRY_RUN = 0x00000001,
72 SENSORS_BATCH_WAKE_UPON_FIFO_FULL = 0x00000002
73};
74
Mathias Agopian16671c52013-07-24 21:07:40 -070075/*
76 * what field for meta_data_event_t
77 */
78enum {
79 /* a previous flush operation has completed */
Mathias Agopianaf32a8d2013-08-06 20:33:38 -070080 META_DATA_FLUSH_COMPLETE = 1,
81 META_DATA_VERSION /* always last, leave auto-assigned */
Mathias Agopian16671c52013-07-24 21:07:40 -070082};
83
Mathias Agopiana4557722012-11-28 17:21:55 -080084/*
Aravind Akella477fbd52014-04-07 22:46:01 +000085 * The permission to use for body sensors (like heart rate monitors).
86 * See sensor types for more details on what sensors should require this
87 * permission.
88 */
89#define SENSOR_PERMISSION_BODY_SENSORS "android.permission.BODY_SENSORS"
90
91/*
Mathias Agopiana4557722012-11-28 17:21:55 -080092 * Sensor type
93 *
94 * Each sensor has a type which defines what this sensor measures and how
Clay Murphy8db1fb42013-12-19 09:58:28 -080095 * measures are reported. See the Base sensors and Composite sensors lists
96 * for complete descriptions:
97 * http://source.android.com/devices/sensors/base_triggers.html
98 * http://source.android.com/devices/sensors/composite_sensors.html
Mathias Agopian1599ec62013-08-19 14:34:47 -070099 *
100 * Device manufacturers (OEMs) can define their own sensor types, for
101 * their private use by applications or services provided by them. Such
102 * sensor types are specific to an OEM and can't be exposed in the SDK.
103 * These types must start at SENSOR_TYPE_DEVICE_PRIVATE_BASE.
Aravind Akella477fbd52014-04-07 22:46:01 +0000104 *
105 * All sensors defined outside of the device private range must correspond to
106 * a type defined in this file, and must satisfy the characteristics listed in
107 * the description of the sensor type.
108 *
109 * Starting with version SENSORS_DEVICE_API_VERSION_1_2, each sensor also
110 * has a stringType.
111 * - StringType of sensors inside of the device private range MUST be prefixed
112 * by the sensor provider's or OEM reverse domain name. In particular, they
113 * cannot use the "android.sensor" prefix.
114 * - StringType of sensors outside of the device private range MUST correspond
115 * to the one defined in this file (starting with "android.sensor").
116 * For example, accelerometers must have
117 * type=SENSOR_TYPE_ACCELEROMETER and
118 * stringType=SENSOR_STRING_TYPE_ACCELEROMETER
119 *
120 * When android introduces a new sensor type that can replace an OEM-defined
121 * sensor type, the OEM must use the official sensor type and stringType on
122 * versions of the HAL that support this new official sensor type.
123 *
124 * Example (made up): Suppose Google's Glass team wants to surface a sensor
125 * detecting that Glass is on a head.
126 * - Such a sensor is not officially supported in android KitKat
127 * - Glass devices launching on KitKat can implement a sensor with
128 * type = 0x10001 and stringType = "com.google.glass.onheaddetector"
129 * - In L android release, if android decides to define
130 * SENSOR_TYPE_ON_HEAD_DETECTOR and STRING_SENSOR_TYPE_ON_HEAD_DETECTOR,
131 * those types should replace the Glass-team-specific types in all future
132 * launches.
133 * - When launching glass on the L release, Google should now use the official
134 * type (SENSOR_TYPE_ON_HEAD_DETECTOR) and stringType.
135 * - This way, all applications can now use this sensor.
Mathias Agopiana4557722012-11-28 17:21:55 -0800136 */
137
138/*
Mathias Agopian1599ec62013-08-19 14:34:47 -0700139 * Base for device manufacturers private sensor types.
140 * These sensor types can't be exposed in the SDK.
141 */
142#define SENSOR_TYPE_DEVICE_PRIVATE_BASE 0x10000
143
144/*
Mathias Agopian16671c52013-07-24 21:07:40 -0700145 * SENSOR_TYPE_META_DATA
146 * trigger-mode: n/a
147 * wake-up sensor: n/a
148 *
149 * NO SENSOR OF THAT TYPE MUST BE RETURNED (*get_sensors_list)()
150 *
151 * SENSOR_TYPE_META_DATA is a special token used to populate the
152 * sensors_meta_data_event structure. It doesn't correspond to a physical
153 * sensor. sensors_meta_data_event are special, they exist only inside
154 * the HAL and are generated spontaneously, as opposed to be related to
155 * a physical sensor.
156 *
Mathias Agopianaf32a8d2013-08-06 20:33:38 -0700157 * sensors_meta_data_event_t.version must be META_DATA_VERSION
158 * sensors_meta_data_event_t.sensor must be 0
159 * sensors_meta_data_event_t.type must be SENSOR_TYPE_META_DATA
160 * sensors_meta_data_event_t.reserved must be 0
161 * sensors_meta_data_event_t.timestamp must be 0
Mathias Agopian16671c52013-07-24 21:07:40 -0700162 *
163 * The payload is a meta_data_event_t, where:
164 * meta_data_event_t.what can take the following values:
165 *
166 * META_DATA_FLUSH_COMPLETE
167 * This event indicates that a previous (*flush)() call has completed for the sensor
168 * handle specified in meta_data_event_t.sensor.
169 * see (*flush)() for more details
170 *
171 * All other values for meta_data_event_t.what are reserved and
172 * must not be used.
173 *
174 */
Aravind Akella477fbd52014-04-07 22:46:01 +0000175#define SENSOR_TYPE_META_DATA (0)
Mathias Agopian16671c52013-07-24 21:07:40 -0700176
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800177/*
178 * SENSOR_TYPE_ACCELEROMETER
Mathias Agopiana4557722012-11-28 17:21:55 -0800179 * trigger-mode: continuous
180 * wake-up sensor: no
The Android Open Source Projectf53ebec2009-03-03 19:32:14 -0800181 *
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800182 * All values are in SI units (m/s^2) and measure the acceleration of the
183 * device minus the force of gravity.
184 *
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800185 */
186#define SENSOR_TYPE_ACCELEROMETER (1)
Aravind Akella477fbd52014-04-07 22:46:01 +0000187#define SENSOR_STRING_TYPE_ACCELEROMETER "android.sensor.accelerometer"
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800188
189/*
190 * SENSOR_TYPE_GEOMAGNETIC_FIELD
Mathias Agopiana4557722012-11-28 17:21:55 -0800191 * trigger-mode: continuous
192 * wake-up sensor: no
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800193 *
194 * All values are in micro-Tesla (uT) and measure the geomagnetic
195 * field in the X, Y and Z axis.
196 *
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800197 */
198#define SENSOR_TYPE_GEOMAGNETIC_FIELD (2)
199#define SENSOR_TYPE_MAGNETIC_FIELD SENSOR_TYPE_GEOMAGNETIC_FIELD
Aravind Akella477fbd52014-04-07 22:46:01 +0000200#define SENSOR_STRING_TYPE_MAGNETIC_FIELD "android.sensor.magnetic_field"
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800201
202/*
Mathias Agopiane9eaf372011-11-07 21:32:34 -0800203 * SENSOR_TYPE_ORIENTATION
Mathias Agopiana4557722012-11-28 17:21:55 -0800204 * trigger-mode: continuous
205 * wake-up sensor: no
Clay Murphy8db1fb42013-12-19 09:58:28 -0800206 *
The Android Open Source Projectf53ebec2009-03-03 19:32:14 -0800207 * All values are angles in degrees.
Clay Murphy8db1fb42013-12-19 09:58:28 -0800208 *
Mathias Agopian66a40952010-07-22 17:11:50 -0700209 * Orientation sensors return sensor events for all 3 axes at a constant
210 * rate defined by setDelay().
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800211 */
212#define SENSOR_TYPE_ORIENTATION (3)
Aravind Akella477fbd52014-04-07 22:46:01 +0000213#define SENSOR_STRING_TYPE_ORIENTATION "android.sensor.orientation"
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800214
215/*
Mathias Agopiane9eaf372011-11-07 21:32:34 -0800216 * SENSOR_TYPE_GYROSCOPE
Mathias Agopiana4557722012-11-28 17:21:55 -0800217 * trigger-mode: continuous
218 * wake-up sensor: no
Mathias Agopiane9eaf372011-11-07 21:32:34 -0800219 *
Kevin Powellb01a0432010-07-19 19:12:15 -0700220 * All values are in radians/second and measure the rate of rotation
Clay Murphy8db1fb42013-12-19 09:58:28 -0800221 * around the X, Y and Z axis.
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800222 */
223#define SENSOR_TYPE_GYROSCOPE (4)
Aravind Akella477fbd52014-04-07 22:46:01 +0000224#define SENSOR_STRING_TYPE_GYROSCOPE "android.sensor.gyroscope"
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800225
226/*
227 * SENSOR_TYPE_LIGHT
Mathias Agopiana4557722012-11-28 17:21:55 -0800228 * trigger-mode: on-change
229 * wake-up sensor: no
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800230 *
231 * The light sensor value is returned in SI lux units.
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800232 */
233#define SENSOR_TYPE_LIGHT (5)
Aravind Akella477fbd52014-04-07 22:46:01 +0000234#define SENSOR_STRING_TYPE_LIGHT "android.sensor.light"
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800235
236/*
237 * SENSOR_TYPE_PRESSURE
Mathias Agopiana4557722012-11-28 17:21:55 -0800238 * trigger-mode: continuous
239 * wake-up sensor: no
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800240 *
241 * The pressure sensor return the athmospheric pressure in hectopascal (hPa)
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800242 */
243#define SENSOR_TYPE_PRESSURE (6)
Aravind Akella477fbd52014-04-07 22:46:01 +0000244#define SENSOR_STRING_TYPE_PRESSURE "android.sensor.pressure"
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800245
246/* SENSOR_TYPE_TEMPERATURE is deprecated in the HAL */
247#define SENSOR_TYPE_TEMPERATURE (7)
Aravind Akella477fbd52014-04-07 22:46:01 +0000248#define SENSOR_STRING_TYPE_TEMPERATURE "android.sensor.temperature"
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800249
250/*
Mathias Agopiane9eaf372011-11-07 21:32:34 -0800251 * SENSOR_TYPE_PROXIMITY
Mathias Agopiana4557722012-11-28 17:21:55 -0800252 * trigger-mode: on-change
253 * wake-up sensor: yes
Mike Lockwooda2414312009-11-03 10:29:50 -0500254 *
Clay Murphy8db1fb42013-12-19 09:58:28 -0800255 * The value corresponds to the distance to the nearest object in centimeters.
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800256 */
257#define SENSOR_TYPE_PROXIMITY (8)
Aravind Akella477fbd52014-04-07 22:46:01 +0000258#define SENSOR_STRING_TYPE_PROXIMITY "android.sensor.proximity"
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800259
260/*
Mathias Agopiane9eaf372011-11-07 21:32:34 -0800261 * SENSOR_TYPE_GRAVITY
Mathias Agopiana4557722012-11-28 17:21:55 -0800262 * trigger-mode: continuous
263 * wake-up sensor: no
Mathias Agopian42b743c2010-11-22 15:55:32 -0800264 *
Mathias Agopiane9eaf372011-11-07 21:32:34 -0800265 * A gravity output indicates the direction of and magnitude of gravity in
Clay Murphy8db1fb42013-12-19 09:58:28 -0800266 * the devices's coordinates.
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800267 */
268#define SENSOR_TYPE_GRAVITY (9)
Aravind Akella477fbd52014-04-07 22:46:01 +0000269#define SENSOR_STRING_TYPE_GRAVITY "android.sensor.gravity"
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800270
271/*
Mathias Agopiane9eaf372011-11-07 21:32:34 -0800272 * SENSOR_TYPE_LINEAR_ACCELERATION
Mathias Agopiana4557722012-11-28 17:21:55 -0800273 * trigger-mode: continuous
274 * wake-up sensor: no
Mathias Agopiane9eaf372011-11-07 21:32:34 -0800275 *
276 * Indicates the linear acceleration of the device in device coordinates,
277 * not including gravity.
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800278 */
279#define SENSOR_TYPE_LINEAR_ACCELERATION (10)
Aravind Akella477fbd52014-04-07 22:46:01 +0000280#define SENSOR_STRING_TYPE_LINEAR_ACCELERATION "android.sensor.linear_acceleration"
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800281
282
283/*
Mathias Agopiane9eaf372011-11-07 21:32:34 -0800284 * SENSOR_TYPE_ROTATION_VECTOR
Mathias Agopiana4557722012-11-28 17:21:55 -0800285 * trigger-mode: continuous
286 * wake-up sensor: no
Mathias Agopiane9eaf372011-11-07 21:32:34 -0800287 *
Etienne Le Grand28f04112013-03-27 18:59:10 -0700288 * The rotation vector symbolizes the orientation of the device relative to the
Clay Murphy8db1fb42013-12-19 09:58:28 -0800289 * East-North-Up coordinates frame.
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800290 */
291#define SENSOR_TYPE_ROTATION_VECTOR (11)
Aravind Akella477fbd52014-04-07 22:46:01 +0000292#define SENSOR_STRING_TYPE_ROTATION_VECTOR "android.sensor.rotation_vector"
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800293
294/*
Mathias Agopiane9eaf372011-11-07 21:32:34 -0800295 * SENSOR_TYPE_RELATIVE_HUMIDITY
Mathias Agopiana4557722012-11-28 17:21:55 -0800296 * trigger-mode: on-change
297 * wake-up sensor: no
Urs Fleischd2ed15a2010-12-29 17:00:33 +0100298 *
299 * A relative humidity sensor measures relative ambient air humidity and
300 * returns a value in percent.
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800301 */
302#define SENSOR_TYPE_RELATIVE_HUMIDITY (12)
Aravind Akella477fbd52014-04-07 22:46:01 +0000303#define SENSOR_STRING_TYPE_RELATIVE_HUMIDITY "android.sensor.relative_humidity"
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800304
305/*
Mathias Agopiane9eaf372011-11-07 21:32:34 -0800306 * SENSOR_TYPE_AMBIENT_TEMPERATURE
Mathias Agopiana4557722012-11-28 17:21:55 -0800307 * trigger-mode: on-change
308 * wake-up sensor: no
Mathias Agopian54f9dd02011-03-22 18:42:03 -0700309 *
310 * The ambient (room) temperature in degree Celsius.
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800311 */
312#define SENSOR_TYPE_AMBIENT_TEMPERATURE (13)
Aravind Akella477fbd52014-04-07 22:46:01 +0000313#define SENSOR_STRING_TYPE_AMBIENT_TEMPERATURE "android.sensor.ambient_temperature"
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800314
315/*
316 * SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED
Mathias Agopiana4557722012-11-28 17:21:55 -0800317 * trigger-mode: continuous
318 * wake-up sensor: no
Mathias Agopian54f9dd02011-03-22 18:42:03 -0700319 *
Etienne Le Grandca858142013-02-26 19:17:20 -0800320 * Similar to SENSOR_TYPE_MAGNETIC_FIELD, but the hard iron calibration is
321 * reported separately instead of being included in the measurement.
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800322 */
323#define SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED (14)
Aravind Akella477fbd52014-04-07 22:46:01 +0000324#define SENSOR_STRING_TYPE_MAGNETIC_FIELD_UNCALIBRATED "android.sensor.magnetic_field_uncalibrated"
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800325
326/*
327 * SENSOR_TYPE_GAME_ROTATION_VECTOR
Mathias Agopiana4557722012-11-28 17:21:55 -0800328 * trigger-mode: continuous
329 * wake-up sensor: no
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800330 *
Etienne Le Grandca858142013-02-26 19:17:20 -0800331 * Similar to SENSOR_TYPE_ROTATION_VECTOR, but not using the geomagnetic
Clay Murphy8db1fb42013-12-19 09:58:28 -0800332 * field.
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800333 */
334#define SENSOR_TYPE_GAME_ROTATION_VECTOR (15)
Aravind Akella477fbd52014-04-07 22:46:01 +0000335#define SENSOR_STRING_TYPE_GAME_ROTATION_VECTOR "android.sensor.game_rotation_vector"
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800336
337/*
338 * SENSOR_TYPE_GYROSCOPE_UNCALIBRATED
Mathias Agopiana4557722012-11-28 17:21:55 -0800339 * trigger-mode: continuous
340 * wake-up sensor: no
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800341 *
342 * All values are in radians/second and measure the rate of rotation
Clay Murphy8db1fb42013-12-19 09:58:28 -0800343 * around the X, Y and Z axis.
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800344 */
345#define SENSOR_TYPE_GYROSCOPE_UNCALIBRATED (16)
Aravind Akella477fbd52014-04-07 22:46:01 +0000346#define SENSOR_STRING_TYPE_GYROSCOPE_UNCALIBRATED "android.sensor.gyroscope_uncalibrated"
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800347
Mathias Agopiana4557722012-11-28 17:21:55 -0800348/*
349 * SENSOR_TYPE_SIGNIFICANT_MOTION
350 * trigger-mode: one-shot
351 * wake-up sensor: yes
352 *
353 * A sensor of this type triggers an event each time significant motion
354 * is detected and automatically disables itself.
355 * The only allowed value to return is 1.0.
Mathias Agopiana4557722012-11-28 17:21:55 -0800356 */
357
358#define SENSOR_TYPE_SIGNIFICANT_MOTION (17)
Aravind Akella477fbd52014-04-07 22:46:01 +0000359#define SENSOR_STRING_TYPE_SIGNIFICANT_MOTION "android.sensor.significant_motion"
Mathias Agopiana4557722012-11-28 17:21:55 -0800360
361/*
Mathias Agopian2f276f52013-01-28 17:54:41 -0800362 * SENSOR_TYPE_STEP_DETECTOR
Mathias Agopiana4557722012-11-28 17:21:55 -0800363 * trigger-mode: special
364 * wake-up sensor: no
365 *
366 * A sensor of this type triggers an event each time a step is taken
Clay Murphy8db1fb42013-12-19 09:58:28 -0800367 * by the user. The only allowed value to return is 1.0 and an event
368 * is generated for each step.
Mathias Agopiana4557722012-11-28 17:21:55 -0800369 */
370
Mathias Agopian2f276f52013-01-28 17:54:41 -0800371#define SENSOR_TYPE_STEP_DETECTOR (18)
Aravind Akella477fbd52014-04-07 22:46:01 +0000372#define SENSOR_STRING_TYPE_STEP_DETECTOR "android.sensor.step_detector"
Mathias Agopiana4557722012-11-28 17:21:55 -0800373
374
375/*
376 * SENSOR_TYPE_STEP_COUNTER
377 * trigger-mode: on-change
378 * wake-up sensor: no
379 *
380 * A sensor of this type returns the number of steps taken by the user since
Mathias Agopian1144bea2013-01-29 15:52:10 -0800381 * the last reboot while activated. The value is returned as a uint64_t and is
Etienne Le Grandf770b7a2013-07-10 14:08:40 -0700382 * reset to zero only on a system / android reboot.
Mathias Agopiana4557722012-11-28 17:21:55 -0800383 */
384
385#define SENSOR_TYPE_STEP_COUNTER (19)
Aravind Akella477fbd52014-04-07 22:46:01 +0000386#define SENSOR_STRING_TYPE_STEP_COUNTER "android.sensor.step_counter"
Mathias Agopiana4557722012-11-28 17:21:55 -0800387
Etienne Le Grandca858142013-02-26 19:17:20 -0800388/*
389 * SENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR
390 * trigger-mode: continuous
391 * wake-up sensor: no
392 *
393 * Similar to SENSOR_TYPE_ROTATION_VECTOR, but using a magnetometer instead
394 * of using a gyroscope.
Etienne Le Grandca858142013-02-26 19:17:20 -0800395 */
Aravind Akella477fbd52014-04-07 22:46:01 +0000396#define SENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR (20)
397#define SENSOR_STRING_TYPE_GEOMAGNETIC_ROTATION_VECTOR "android.sensor.geomagnetic_rotation_vector"
398
399/*
400 * SENSOR_TYPE_HEART_RATE
401 * trigger-mode: on-change
402 * wake-up sensor: no
403 *
404 * A sensor of this type returns the current heart rate if activated.
405 * The value is returned as a float which represents the heart rate in beats
406 * per minute (BPM).
407 * When the sensor cannot measure the heart rate, the returned value must be 0.
408 * sensor_t.requiredPermission must be set to SENSOR_PERMISSION_BODY_SENSORS.
409 */
410#define SENSOR_TYPE_HEART_RATE (21)
411#define SENSOR_STRING_TYPE_HEART_RATE "android.sensor.heart_rate"
Mathias Agopiana4557722012-11-28 17:21:55 -0800412
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800413/**
414 * Values returned by the accelerometer in various locations in the universe.
415 * all values are in SI units (m/s^2)
416 */
417#define GRAVITY_SUN (275.0f)
418#define GRAVITY_EARTH (9.80665f)
419
420/** Maximum magnetic field on Earth's surface */
421#define MAGNETIC_FIELD_EARTH_MAX (60.0f)
422
423/** Minimum magnetic field on Earth's surface */
424#define MAGNETIC_FIELD_EARTH_MIN (30.0f)
425
426
427/**
428 * status of orientation sensor
The Android Open Source Projectf53ebec2009-03-03 19:32:14 -0800429 */
Kevin Powellb01a0432010-07-19 19:12:15 -0700430
Mathias Agopian56f66cc2012-11-08 15:57:38 -0800431#define SENSOR_STATUS_UNRELIABLE 0
432#define SENSOR_STATUS_ACCURACY_LOW 1
433#define SENSOR_STATUS_ACCURACY_MEDIUM 2
434#define SENSOR_STATUS_ACCURACY_HIGH 3
435
436
437/**
438 * sensor event data
439 */
The Android Open Source Projectf53ebec2009-03-03 19:32:14 -0800440typedef struct {
441 union {
442 float v[3];
443 struct {
444 float x;
445 float y;
446 float z;
447 };
448 struct {
449 float azimuth;
450 float pitch;
451 float roll;
452 };
453 };
454 int8_t status;
455 uint8_t reserved[3];
456} sensors_vec_t;
457
458/**
Etienne Le Grandca858142013-02-26 19:17:20 -0800459 * uncalibrated gyroscope and magnetometer event data
460 */
461typedef struct {
Etienne Le Grand28f04112013-03-27 18:59:10 -0700462 union {
463 float uncalib[3];
464 struct {
465 float x_uncalib;
466 float y_uncalib;
467 float z_uncalib;
468 };
469 };
470 union {
471 float bias[3];
472 struct {
473 float x_bias;
474 float y_bias;
475 float z_bias;
476 };
477 };
Etienne Le Grandca858142013-02-26 19:17:20 -0800478} uncalibrated_event_t;
479
Mathias Agopian16671c52013-07-24 21:07:40 -0700480typedef struct meta_data_event {
481 int32_t what;
482 int32_t sensor;
483} meta_data_event_t;
484
Etienne Le Grandca858142013-02-26 19:17:20 -0800485/**
The Android Open Source Projectf53ebec2009-03-03 19:32:14 -0800486 * Union of the various types of sensor data
487 * that can be returned.
488 */
Mathias Agopiancdefccd2010-07-15 18:29:03 -0700489typedef struct sensors_event_t {
490 /* must be sizeof(struct sensors_event_t) */
491 int32_t version;
492
493 /* sensor identifier */
494 int32_t sensor;
495
496 /* sensor type */
497 int32_t type;
498
499 /* reserved */
500 int32_t reserved0;
501
502 /* time is in nanosecond */
503 int64_t timestamp;
504
505 union {
Mathias Agopian27e16682013-07-08 14:00:54 -0700506 union {
507 float data[16];
Mathias Agopiancdefccd2010-07-15 18:29:03 -0700508
Mathias Agopian27e16682013-07-08 14:00:54 -0700509 /* acceleration values are in meter per second per second (m/s^2) */
510 sensors_vec_t acceleration;
Mathias Agopiancdefccd2010-07-15 18:29:03 -0700511
Mathias Agopian27e16682013-07-08 14:00:54 -0700512 /* magnetic vector values are in micro-Tesla (uT) */
513 sensors_vec_t magnetic;
Mathias Agopiancdefccd2010-07-15 18:29:03 -0700514
Mathias Agopian27e16682013-07-08 14:00:54 -0700515 /* orientation values are in degrees */
516 sensors_vec_t orientation;
Mathias Agopiancdefccd2010-07-15 18:29:03 -0700517
Mathias Agopian27e16682013-07-08 14:00:54 -0700518 /* gyroscope values are in rad/s */
519 sensors_vec_t gyro;
Makarand Karvekar3120b582010-08-11 15:10:10 -0700520
Mathias Agopian27e16682013-07-08 14:00:54 -0700521 /* temperature is in degrees centigrade (Celsius) */
522 float temperature;
Mathias Agopiancdefccd2010-07-15 18:29:03 -0700523
Mathias Agopian27e16682013-07-08 14:00:54 -0700524 /* distance in centimeters */
525 float distance;
Mathias Agopiancdefccd2010-07-15 18:29:03 -0700526
Mathias Agopian27e16682013-07-08 14:00:54 -0700527 /* light in SI lux units */
528 float light;
Mathias Agopian1832f552010-07-29 15:22:30 -0700529
Mathias Agopian27e16682013-07-08 14:00:54 -0700530 /* pressure in hectopascal (hPa) */
531 float pressure;
Urs Fleischd2ed15a2010-12-29 17:00:33 +0100532
Mathias Agopian27e16682013-07-08 14:00:54 -0700533 /* relative humidity in percent */
534 float relative_humidity;
Mathias Agopiana4557722012-11-28 17:21:55 -0800535
Mathias Agopian27e16682013-07-08 14:00:54 -0700536 /* uncalibrated gyroscope values are in rad/s */
537 uncalibrated_event_t uncalibrated_gyro;
Etienne Le Grandca858142013-02-26 19:17:20 -0800538
Mathias Agopian27e16682013-07-08 14:00:54 -0700539 /* uncalibrated magnetometer values are in micro-Teslas */
540 uncalibrated_event_t uncalibrated_magnetic;
Mathias Agopian16671c52013-07-24 21:07:40 -0700541
Aravind Akella477fbd52014-04-07 22:46:01 +0000542 /* heart rate in bpm */
543 float heart_rate;
544
Mathias Agopian16671c52013-07-24 21:07:40 -0700545 /* this is a special event. see SENSOR_TYPE_META_DATA above.
546 * sensors_meta_data_event_t events are all reported with a type of
547 * SENSOR_TYPE_META_DATA. The handle is ignored and must be zero.
548 */
549 meta_data_event_t meta_data;
Mathias Agopian27e16682013-07-08 14:00:54 -0700550 };
Etienne Le Grandca858142013-02-26 19:17:20 -0800551
Mathias Agopian27e16682013-07-08 14:00:54 -0700552 union {
553 uint64_t data[8];
554
555 /* step-counter */
556 uint64_t step_counter;
557 } u64;
Mathias Agopiancdefccd2010-07-15 18:29:03 -0700558 };
Mathias Agopian27e16682013-07-08 14:00:54 -0700559 uint32_t reserved1[4];
Mathias Agopiancdefccd2010-07-15 18:29:03 -0700560} sensors_event_t;
561
562
Mathias Agopian16671c52013-07-24 21:07:40 -0700563/* see SENSOR_TYPE_META_DATA */
564typedef sensors_event_t sensors_meta_data_event_t;
565
Mathias Agopiancdefccd2010-07-15 18:29:03 -0700566
The Android Open Source Projectf53ebec2009-03-03 19:32:14 -0800567struct sensor_t;
568
569/**
570 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
571 * and the fields of this data structure must begin with hw_module_t
572 * followed by module specific information.
573 */
574struct sensors_module_t {
575 struct hw_module_t common;
576
577 /**
578 * Enumerate all available sensors. The list is returned in "list".
579 * @return number of sensors in the list
580 */
581 int (*get_sensors_list)(struct sensors_module_t* module,
582 struct sensor_t const** list);
583};
584
585struct sensor_t {
Mathias Agopian1144bea2013-01-29 15:52:10 -0800586
587 /* Name of this sensor.
588 * All sensors of the same "type" must have a different "name".
589 */
The Android Open Source Projectf53ebec2009-03-03 19:32:14 -0800590 const char* name;
Mathias Agopiana4557722012-11-28 17:21:55 -0800591
The Android Open Source Projectf53ebec2009-03-03 19:32:14 -0800592 /* vendor of the hardware part */
593 const char* vendor;
Mathias Agopiana4557722012-11-28 17:21:55 -0800594
Mathias Agopiane9eaf372011-11-07 21:32:34 -0800595 /* version of the hardware part + driver. The value of this field
596 * must increase when the driver is updated in a way that changes the
597 * output of this sensor. This is important for fused sensors when the
598 * fusion algorithm is updated.
The Android Open Source Projectf53ebec2009-03-03 19:32:14 -0800599 */
600 int version;
Mathias Agopiana4557722012-11-28 17:21:55 -0800601
602 /* handle that identifies this sensors. This handle is used to reference
603 * this sensor throughout the HAL API.
The Android Open Source Projectf53ebec2009-03-03 19:32:14 -0800604 */
605 int handle;
Mathias Agopiana4557722012-11-28 17:21:55 -0800606
The Android Open Source Projectf53ebec2009-03-03 19:32:14 -0800607 /* this sensor's type. */
608 int type;
Mathias Agopiana4557722012-11-28 17:21:55 -0800609
610 /* maximum range of this sensor's value in SI units */
The Android Open Source Projectf53ebec2009-03-03 19:32:14 -0800611 float maxRange;
Mathias Agopiana4557722012-11-28 17:21:55 -0800612
The Android Open Source Projectf53ebec2009-03-03 19:32:14 -0800613 /* smallest difference between two values reported by this sensor */
614 float resolution;
Mathias Agopiana4557722012-11-28 17:21:55 -0800615
The Android Open Source Projectf53ebec2009-03-03 19:32:14 -0800616 /* rough estimate of this sensor's power consumption in mA */
617 float power;
Mathias Agopiana4557722012-11-28 17:21:55 -0800618
619 /* this value depends on the trigger mode:
620 *
621 * continuous: minimum sample period allowed in microseconds
622 * on-change : 0
623 * one-shot :-1
624 * special : 0, unless otherwise noted
625 */
Mathias Agopian1511e202010-07-29 15:33:22 -0700626 int32_t minDelay;
Mathias Agopiana4557722012-11-28 17:21:55 -0800627
Mathias Agopian16671c52013-07-24 21:07:40 -0700628 /* number of events reserved for this sensor in the batch mode FIFO.
629 * If there is a dedicated FIFO for this sensor, then this is the
630 * size of this FIFO. If the FIFO is shared with other sensors,
631 * this is the size reserved for that sensor and it can be zero.
632 */
633 uint32_t fifoReservedEventCount;
634
635 /* maximum number of events of this sensor that could be batched.
636 * This is especially relevant when the FIFO is shared between
637 * several sensors; this value is then set to the size of that FIFO.
638 */
639 uint32_t fifoMaxEventCount;
640
Aravind Akella477fbd52014-04-07 22:46:01 +0000641 /* type of this sensor as a string. Set to corresponding
642 * SENSOR_STRING_TYPE_*.
643 * When defining an OEM specific sensor or sensor manufacturer specific
644 * sensor, use your reserve domain name as a prefix.
645 * ex: com.google.glass.onheaddetector
646 * For sensors of known type, the android framework might overwrite this
647 * string automatically.
648 */
649 const char* stringType;
650
651 /* permission required to see this sensor, register to it and receive data.
652 * Set to "" if no permission is required. Some sensor types like the
653 * heart rate monitor have a mandatory require_permission.
654 * For sensors that always require a specific permission, like the heart
655 * rate monitor, the android framework might overwrite this string
656 * automatically.
657 */
658 const char* requiredPermission;
659
The Android Open Source Projectf53ebec2009-03-03 19:32:14 -0800660 /* reserved fields, must be zero */
Aravind Akella477fbd52014-04-07 22:46:01 +0000661 void* reserved[4];
The Android Open Source Projectf53ebec2009-03-03 19:32:14 -0800662};
663
664
Mathias Agopiana4557722012-11-28 17:21:55 -0800665/*
666 * sensors_poll_device_t is used with SENSORS_DEVICE_API_VERSION_0_1
667 * and is present for backward binary and source compatibility.
Clay Murphy8db1fb42013-12-19 09:58:28 -0800668 * See the Sensors HAL interface section for complete descriptions of the
669 * following functions:
670 * http://source.android.com/devices/sensors/index.html#hal
The Android Open Source Projectf53ebec2009-03-03 19:32:14 -0800671 */
Mathias Agopianb1e212e2010-07-08 16:44:54 -0700672struct sensors_poll_device_t {
673 struct hw_device_t common;
Mathias Agopianb1e212e2010-07-08 16:44:54 -0700674 int (*activate)(struct sensors_poll_device_t *dev,
675 int handle, int enabled);
Mathias Agopianb1e212e2010-07-08 16:44:54 -0700676 int (*setDelay)(struct sensors_poll_device_t *dev,
677 int handle, int64_t ns);
Mathias Agopianb1e212e2010-07-08 16:44:54 -0700678 int (*poll)(struct sensors_poll_device_t *dev,
Mathias Agopiancdefccd2010-07-15 18:29:03 -0700679 sensors_event_t* data, int count);
Mathias Agopianb1e212e2010-07-08 16:44:54 -0700680};
681
Mathias Agopiana4557722012-11-28 17:21:55 -0800682/*
683 * struct sensors_poll_device_1 is used with SENSORS_DEVICE_API_VERSION_1_0
684 */
685typedef struct sensors_poll_device_1 {
686 union {
687 /* sensors_poll_device_1 is compatible with sensors_poll_device_t,
688 * and can be down-cast to it
689 */
Andrew Hsieh1082c0b2012-12-11 20:51:41 -0800690 struct sensors_poll_device_t v0;
Mathias Agopiana4557722012-11-28 17:21:55 -0800691
692 struct {
693 struct hw_device_t common;
694
Clay Murphy8db1fb42013-12-19 09:58:28 -0800695 /* Activate/de-activate one sensor. Return 0 on success, negative
Mathias Agopiana4557722012-11-28 17:21:55 -0800696 *
697 * handle is the handle of the sensor to change.
698 * enabled set to 1 to enable, or 0 to disable the sensor.
699 *
Clay Murphy8db1fb42013-12-19 09:58:28 -0800700 * Return 0 on success, negative errno code otherwise.
Mathias Agopiana4557722012-11-28 17:21:55 -0800701 */
702 int (*activate)(struct sensors_poll_device_t *dev,
703 int handle, int enabled);
704
705 /**
Mathias Agopian1144bea2013-01-29 15:52:10 -0800706 * Set the events's period in nanoseconds for a given sensor.
Mathias Agopiana4557722012-11-28 17:21:55 -0800707 */
708 int (*setDelay)(struct sensors_poll_device_t *dev,
Mathias Agopian1144bea2013-01-29 15:52:10 -0800709 int handle, int64_t period_ns);
Mathias Agopiana4557722012-11-28 17:21:55 -0800710
711 /**
712 * Returns an array of sensor data.
Mathias Agopiana4557722012-11-28 17:21:55 -0800713 */
714 int (*poll)(struct sensors_poll_device_t *dev,
715 sensors_event_t* data, int count);
716 };
717 };
718
Mathias Agopiana4557722012-11-28 17:21:55 -0800719
720 /*
Clay Murphy8db1fb42013-12-19 09:58:28 -0800721 * Enables batch mode for the given sensor and sets the delay between events.
722 * See the Batching sensor results page for details:
723 * http://source.android.com/devices/sensors/batching.html
Mathias Agopiana4557722012-11-28 17:21:55 -0800724 */
725 int (*batch)(struct sensors_poll_device_1* dev,
Mathias Agopian1144bea2013-01-29 15:52:10 -0800726 int handle, int flags, int64_t period_ns, int64_t timeout);
Mathias Agopiana4557722012-11-28 17:21:55 -0800727
Mathias Agopian16671c52013-07-24 21:07:40 -0700728 /*
729 * Flush adds a META_DATA_FLUSH_COMPLETE event (sensors_event_meta_data_t)
730 * to the end of the "batch mode" FIFO for the specified sensor and flushes
Clay Murphy8db1fb42013-12-19 09:58:28 -0800731 * the FIFO.
Mathias Agopian16671c52013-07-24 21:07:40 -0700732 */
733 int (*flush)(struct sensors_poll_device_1* dev, int handle);
734
Mathias Agopiana4557722012-11-28 17:21:55 -0800735 void (*reserved_procs[8])(void);
736
737} sensors_poll_device_1_t;
738
739
740
The Android Open Source Projectf53ebec2009-03-03 19:32:14 -0800741/** convenience API for opening and closing a device */
742
Mathias Agopianb1e212e2010-07-08 16:44:54 -0700743static inline int sensors_open(const struct hw_module_t* module,
744 struct sensors_poll_device_t** device) {
745 return module->methods->open(module,
746 SENSORS_HARDWARE_POLL, (struct hw_device_t**)device);
747}
748
749static inline int sensors_close(struct sensors_poll_device_t* device) {
750 return device->common.close(&device->common);
751}
752
Mathias Agopiana4557722012-11-28 17:21:55 -0800753static inline int sensors_open_1(const struct hw_module_t* module,
Andrew Hsieh1082c0b2012-12-11 20:51:41 -0800754 sensors_poll_device_1_t** device) {
Mathias Agopiana4557722012-11-28 17:21:55 -0800755 return module->methods->open(module,
756 SENSORS_HARDWARE_POLL, (struct hw_device_t**)device);
757}
758
Andrew Hsieh1082c0b2012-12-11 20:51:41 -0800759static inline int sensors_close_1(sensors_poll_device_1_t* device) {
Mathias Agopiana4557722012-11-28 17:21:55 -0800760 return device->common.close(&device->common);
761}
762
The Android Open Source Projectf53ebec2009-03-03 19:32:14 -0800763__END_DECLS
764
The Android Open Source Projectf53ebec2009-03-03 19:32:14 -0800765#endif // ANDROID_SENSORS_INTERFACE_H