Commit | Line | Data |
---|---|---|
1e494cf4 JB |
1 | /* |
2 | * Copyright (C) 2008 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 | #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> | |
25 | #include <cutils/native_handle.h> | |
26 | ||
27 | __BEGIN_DECLS | |
28 | ||
29 | /** | |
30 | * The id of this module | |
31 | */ | |
32 | #define SENSORS_HARDWARE_MODULE_ID "sensors" | |
33 | ||
34 | /** | |
35 | * Name of the sensors device to open | |
36 | */ | |
37 | #define SENSORS_HARDWARE_POLL "poll" | |
38 | ||
39 | /** | |
40 | * Handles must be higher than SENSORS_HANDLE_BASE and must be unique. | |
41 | * A Handle identifies a given sensors. The handle is used to activate | |
42 | * and/or deactivate sensors. | |
43 | * In this version of the API there can only be 256 handles. | |
44 | */ | |
45 | #define SENSORS_HANDLE_BASE 0 | |
46 | #define SENSORS_HANDLE_BITS 8 | |
47 | #define SENSORS_HANDLE_COUNT (1<<SENSORS_HANDLE_BITS) | |
48 | ||
49 | ||
50 | /** | |
51 | * Sensor types | |
52 | */ | |
53 | #define SENSOR_TYPE_ACCELEROMETER 1 | |
54 | #define SENSOR_TYPE_MAGNETIC_FIELD 2 | |
55 | #define SENSOR_TYPE_ORIENTATION 3 | |
56 | #define SENSOR_TYPE_GYROSCOPE 4 | |
57 | #define SENSOR_TYPE_LIGHT 5 | |
58 | #define SENSOR_TYPE_PRESSURE 6 | |
59 | #define SENSOR_TYPE_TEMPERATURE 7 // deprecated | |
60 | #define SENSOR_TYPE_PROXIMITY 8 | |
61 | #define SENSOR_TYPE_GRAVITY 9 | |
62 | #define SENSOR_TYPE_LINEAR_ACCELERATION 10 | |
63 | #define SENSOR_TYPE_ROTATION_VECTOR 11 | |
64 | #define SENSOR_TYPE_RELATIVE_HUMIDITY 12 | |
65 | #define SENSOR_TYPE_AMBIENT_TEMPERATURE 13 | |
66 | ||
67 | /** | |
68 | * Values returned by the accelerometer in various locations in the universe. | |
69 | * all values are in SI units (m/s^2) | |
70 | */ | |
71 | ||
72 | #define GRAVITY_SUN (275.0f) | |
73 | #define GRAVITY_EARTH (9.80665f) | |
74 | ||
75 | /** Maximum magnetic field on Earth's surface */ | |
76 | #define MAGNETIC_FIELD_EARTH_MAX (60.0f) | |
77 | ||
78 | /** Minimum magnetic field on Earth's surface */ | |
79 | #define MAGNETIC_FIELD_EARTH_MIN (30.0f) | |
80 | ||
81 | ||
82 | /** | |
83 | * status of each sensor | |
84 | */ | |
85 | ||
86 | #define SENSOR_STATUS_UNRELIABLE 0 | |
87 | #define SENSOR_STATUS_ACCURACY_LOW 1 | |
88 | #define SENSOR_STATUS_ACCURACY_MEDIUM 2 | |
89 | #define SENSOR_STATUS_ACCURACY_HIGH 3 | |
90 | ||
91 | /** | |
92 | * Definition of the axis | |
93 | * ---------------------- | |
94 | * | |
95 | * This API is relative to the screen of the device in its default orientation, | |
96 | * that is, if the device can be used in portrait or landscape, this API | |
97 | * is only relative to the NATURAL orientation of the screen. In other words, | |
98 | * the axis are not swapped when the device's screen orientation changes. | |
99 | * Higher level services /may/ perform this transformation. | |
100 | * | |
101 | * x<0 x>0 | |
102 | * ^ | |
103 | * | | |
104 | * +-----------+--> y>0 | |
105 | * | | | |
106 | * | | | |
107 | * | | | |
108 | * | | / z<0 | |
109 | * | | / | |
110 | * | | / | |
111 | * O-----------+/ | |
112 | * |[] [ ] []/ | |
113 | * +----------/+ y<0 | |
114 | * / | |
115 | * / | |
116 | * |/ z>0 (toward the sky) | |
117 | * | |
118 | * O: Origin (x=0,y=0,z=0) | |
119 | * | |
120 | * | |
121 | * SENSOR_TYPE_ORIENTATION | |
122 | * ----------------------- | |
123 | * | |
124 | * All values are angles in degrees. | |
125 | * | |
126 | * Orientation sensors return sensor events for all 3 axes at a constant | |
127 | * rate defined by setDelay(). | |
128 | * | |
129 | * azimuth: angle between the magnetic north direction and the Y axis, around | |
130 | * the Z axis (0<=azimuth<360). | |
131 | * 0=North, 90=East, 180=South, 270=West | |
132 | * | |
133 | * pitch: Rotation around X axis (-180<=pitch<=180), with positive values when | |
134 | * the z-axis moves toward the y-axis. | |
135 | * | |
136 | * roll: Rotation around Y axis (-90<=roll<=90), with positive values when | |
137 | * the x-axis moves towards the z-axis. | |
138 | * | |
139 | * Note: For historical reasons the roll angle is positive in the clockwise | |
140 | * direction (mathematically speaking, it should be positive in the | |
141 | * counter-clockwise direction): | |
142 | * | |
143 | * Z | |
144 | * ^ | |
145 | * (+roll) .--> | | |
146 | * / | | |
147 | * | | roll: rotation around Y axis | |
148 | * X <-------(.) | |
149 | * Y | |
150 | * note that +Y == -roll | |
151 | * | |
152 | * | |
153 | * | |
154 | * Note: This definition is different from yaw, pitch and roll used in aviation | |
155 | * where the X axis is along the long side of the plane (tail to nose). | |
156 | * | |
157 | * | |
158 | * SENSOR_TYPE_ACCELEROMETER | |
159 | * ------------------------- | |
160 | * | |
161 | * All values are in SI units (m/s^2) and measure the acceleration of the | |
162 | * device minus the force of gravity. | |
163 | * | |
164 | * Acceleration sensors return sensor events for all 3 axes at a constant | |
165 | * rate defined by setDelay(). | |
166 | * | |
167 | * x: Acceleration minus Gx on the x-axis | |
168 | * y: Acceleration minus Gy on the y-axis | |
169 | * z: Acceleration minus Gz on the z-axis | |
170 | * | |
171 | * Examples: | |
172 | * When the device lies flat on a table and is pushed on its left side | |
173 | * toward the right, the x acceleration value is positive. | |
174 | * | |
175 | * When the device lies flat on a table, the acceleration value is +9.81, | |
176 | * which correspond to the acceleration of the device (0 m/s^2) minus the | |
177 | * force of gravity (-9.81 m/s^2). | |
178 | * | |
179 | * When the device lies flat on a table and is pushed toward the sky, the | |
180 | * acceleration value is greater than +9.81, which correspond to the | |
181 | * acceleration of the device (+A m/s^2) minus the force of | |
182 | * gravity (-9.81 m/s^2). | |
183 | * | |
184 | * | |
185 | * SENSOR_TYPE_MAGNETIC_FIELD | |
186 | * -------------------------- | |
187 | * | |
188 | * All values are in micro-Tesla (uT) and measure the ambient magnetic | |
189 | * field in the X, Y and Z axis. | |
190 | * | |
191 | * Magnetic Field sensors return sensor events for all 3 axes at a constant | |
192 | * rate defined by setDelay(). | |
193 | * | |
194 | * SENSOR_TYPE_GYROSCOPE | |
195 | * --------------------- | |
196 | * | |
197 | * All values are in radians/second and measure the rate of rotation | |
198 | * around the X, Y and Z axis. The coordinate system is the same as is | |
199 | * used for the acceleration sensor. Rotation is positive in the | |
200 | * counter-clockwise direction (right-hand rule). That is, an observer | |
201 | * looking from some positive location on the x, y or z axis at a device | |
202 | * positioned on the origin would report positive rotation if the device | |
203 | * appeared to be rotating counter clockwise. Note that this is the | |
204 | * standard mathematical definition of positive rotation and does not agree | |
205 | * with the definition of roll given earlier. | |
206 | * The range should at least be 17.45 rad/s (ie: ~1000 deg/s). | |
207 | * | |
208 | * SENSOR_TYPE_PROXIMITY | |
209 | * ---------------------- | |
210 | * | |
211 | * The distance value is measured in centimeters. Note that some proximity | |
212 | * sensors only support a binary "close" or "far" measurement. In this case, | |
213 | * the sensor should report its maxRange value in the "far" state and a value | |
214 | * less than maxRange in the "near" state. | |
215 | * | |
216 | * Proximity sensors report a value only when it changes and each time the | |
217 | * sensor is enabled. | |
218 | * | |
219 | * SENSOR_TYPE_LIGHT | |
220 | * ----------------- | |
221 | * | |
222 | * The light sensor value is returned in SI lux units. | |
223 | * | |
224 | * Light sensors report a value only when it changes and each time the | |
225 | * sensor is enabled. | |
226 | * | |
227 | * SENSOR_TYPE_PRESSURE | |
228 | * -------------------- | |
229 | * | |
230 | * The pressure sensor return the athmospheric pressure in hectopascal (hPa) | |
231 | * | |
232 | * Pressure sensors report events at a constant rate defined by setDelay(). | |
233 | * | |
234 | * SENSOR_TYPE_GRAVITY | |
235 | * ------------------- | |
236 | * | |
237 | * A gravity output indicates the direction of and magnitude of gravity in | |
238 | * the devices's coordinates. On Earth, the magnitude is 9.8 m/s^2. | |
239 | * Units are m/s^2. The coordinate system is the same as is used for the | |
240 | * acceleration sensor. When the device is at rest, the output of the | |
241 | * gravity sensor should be identical to that of the accelerometer. | |
242 | * | |
243 | * SENSOR_TYPE_LINEAR_ACCELERATION | |
244 | * -------------------------------- | |
245 | * | |
246 | * Indicates the linear acceleration of the device in device coordinates, | |
247 | * not including gravity. | |
248 | * This output is essentially Acceleration - Gravity. Units are m/s^2. | |
249 | * The coordinate system is the same as is used for the acceleration sensor. | |
250 | * | |
251 | * | |
252 | * SENSOR_TYPE_ROTATION_VECTOR | |
253 | * --------------------------- | |
254 | * | |
255 | * A rotation vector represents the orientation of the device as a combination | |
256 | * of an angle and an axis, in which the device has rotated through an angle | |
257 | * theta around an axis <x, y, z>. The three elements of the rotation vector | |
258 | * are <x*sin(theta/2), y*sin(theta/2), z*sin(theta/2)>, such that the magnitude | |
259 | * of the rotation vector is equal to sin(theta/2), and the direction of the | |
260 | * rotation vector is equal to the direction of the axis of rotation. The three | |
261 | * elements of the rotation vector are equal to the last three components of a | |
262 | * unit quaternion <cos(theta/2), x*sin(theta/2), y*sin(theta/2), z*sin(theta/2)>. | |
263 | * Elements of the rotation vector are unitless. The x, y, and z axis are defined | |
264 | * in the same was as for the acceleration sensor. | |
265 | * | |
266 | * The reference coordinate system is defined as a direct orthonormal basis, | |
267 | * where: | |
268 | * | |
269 | * - X is defined as the vector product Y.Z (It is tangential to | |
270 | * the ground at the device's current location and roughly points East). | |
271 | * | |
272 | * - Y is tangential to the ground at the device's current location and | |
273 | * points towards the magnetic North Pole. | |
274 | * | |
275 | * - Z points towards the sky and is perpendicular to the ground. | |
276 | * | |
277 | * | |
278 | * The rotation-vector is stored as: | |
279 | * | |
280 | * sensors_event_t.data[0] = x*sin(theta/2) | |
281 | * sensors_event_t.data[1] = y*sin(theta/2) | |
282 | * sensors_event_t.data[2] = z*sin(theta/2) | |
283 | * sensors_event_t.data[3] = cos(theta/2) | |
284 | * | |
285 | * | |
286 | * SENSOR_TYPE_RELATIVE_HUMIDITY | |
287 | * ------------------------------ | |
288 | * | |
289 | * A relative humidity sensor measures relative ambient air humidity and | |
290 | * returns a value in percent. | |
291 | * | |
292 | * Relative humidity sensors report a value only when it changes and each | |
293 | * time the sensor is enabled. | |
294 | * | |
295 | * | |
296 | * SENSOR_TYPE_AMBIENT_TEMPERATURE | |
297 | * ------------------------------- | |
298 | * | |
299 | * The ambient (room) temperature in degree Celsius. | |
300 | * | |
301 | * Temperature sensors report a value only when it changes and each time the | |
302 | * sensor is enabled. | |
303 | * | |
304 | */ | |
305 | ||
306 | typedef struct { | |
307 | union { | |
308 | float v[3]; | |
309 | struct { | |
310 | float x; | |
311 | float y; | |
312 | float z; | |
313 | }; | |
314 | struct { | |
315 | float azimuth; | |
316 | float pitch; | |
317 | float roll; | |
318 | }; | |
319 | }; | |
320 | int8_t status; | |
321 | uint8_t reserved[3]; | |
322 | } sensors_vec_t; | |
323 | ||
324 | /** | |
325 | * Union of the various types of sensor data | |
326 | * that can be returned. | |
327 | */ | |
328 | typedef struct sensors_event_t { | |
329 | /* must be sizeof(struct sensors_event_t) */ | |
330 | int32_t version; | |
331 | ||
332 | /* sensor identifier */ | |
333 | int32_t sensor; | |
334 | ||
335 | /* sensor type */ | |
336 | int32_t type; | |
337 | ||
338 | /* reserved */ | |
339 | int32_t reserved0; | |
340 | ||
341 | /* time is in nanosecond */ | |
342 | int64_t timestamp; | |
343 | ||
344 | union { | |
345 | float data[16]; | |
346 | ||
347 | /* acceleration values are in meter per second per second (m/s^2) */ | |
348 | sensors_vec_t acceleration; | |
349 | ||
350 | /* magnetic vector values are in micro-Tesla (uT) */ | |
351 | sensors_vec_t magnetic; | |
352 | ||
353 | /* orientation values are in degrees */ | |
354 | sensors_vec_t orientation; | |
355 | ||
356 | /* gyroscope values are in rad/s */ | |
357 | sensors_vec_t gyro; | |
358 | ||
359 | /* temperature is in degrees centigrade (Celsius) */ | |
360 | float temperature; | |
361 | ||
362 | /* distance in centimeters */ | |
363 | float distance; | |
364 | ||
365 | /* light in SI lux units */ | |
366 | float light; | |
367 | ||
368 | /* pressure in hectopascal (hPa) */ | |
369 | float pressure; | |
370 | ||
371 | /* relative humidity in percent */ | |
372 | float relative_humidity; | |
373 | }; | |
374 | uint32_t reserved1[4]; | |
375 | } sensors_event_t; | |
376 | ||
377 | ||
378 | ||
379 | struct sensor_t; | |
380 | ||
381 | /** | |
382 | * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM | |
383 | * and the fields of this data structure must begin with hw_module_t | |
384 | * followed by module specific information. | |
385 | */ | |
386 | struct sensors_module_t { | |
387 | struct hw_module_t common; | |
388 | ||
389 | /** | |
390 | * Enumerate all available sensors. The list is returned in "list". | |
391 | * @return number of sensors in the list | |
392 | */ | |
393 | int (*get_sensors_list)(struct sensors_module_t* module, | |
394 | struct sensor_t const** list); | |
395 | }; | |
396 | ||
397 | struct sensor_t { | |
398 | /* name of this sensors */ | |
399 | const char* name; | |
400 | /* vendor of the hardware part */ | |
401 | const char* vendor; | |
402 | /* version of the hardware part + driver. The value of this field | |
403 | * must increase when the driver is updated in a way that changes the | |
404 | * output of this sensor. This is important for fused sensors when the | |
405 | * fusion algorithm is updated. | |
406 | */ | |
407 | int version; | |
408 | /* handle that identifies this sensors. This handle is used to activate | |
409 | * and deactivate this sensor. The value of the handle must be 8 bits | |
410 | * in this version of the API. | |
411 | */ | |
412 | int handle; | |
413 | /* this sensor's type. */ | |
414 | int type; | |
415 | /* maximaum range of this sensor's value in SI units */ | |
416 | float maxRange; | |
417 | /* smallest difference between two values reported by this sensor */ | |
418 | float resolution; | |
419 | /* rough estimate of this sensor's power consumption in mA */ | |
420 | float power; | |
421 | /* minimum delay allowed between events in microseconds. A value of zero | |
422 | * means that this sensor doesn't report events at a constant rate, but | |
423 | * rather only when a new data is available */ | |
424 | int32_t minDelay; | |
425 | /* reserved fields, must be zero */ | |
426 | void* reserved[8]; | |
427 | }; | |
428 | ||
429 | ||
430 | /** | |
431 | * Every device data structure must begin with hw_device_t | |
432 | * followed by module specific public methods and attributes. | |
433 | */ | |
434 | struct sensors_poll_device_t { | |
435 | struct hw_device_t common; | |
436 | ||
437 | /** Activate/deactivate one sensor. | |
438 | * | |
439 | * @param handle is the handle of the sensor to change. | |
440 | * @param enabled set to 1 to enable, or 0 to disable the sensor. | |
441 | * | |
442 | * @return 0 on success, negative errno code otherwise | |
443 | */ | |
444 | int (*activate)(struct sensors_poll_device_t *dev, | |
445 | int handle, int enabled); | |
446 | ||
447 | /** | |
448 | * Set the delay between sensor events in nanoseconds for a given sensor. | |
449 | * | |
450 | * If the requested value is less than sensor_t::minDelay, then it's | |
451 | * silently clamped to sensor_t::minDelay unless sensor_t::minDelay is | |
452 | * 0, in which case it is clamped to >= 1ms. | |
453 | * | |
454 | * @return 0 if successful, < 0 on error | |
455 | */ | |
456 | int (*setDelay)(struct sensors_poll_device_t *dev, | |
457 | int handle, int64_t ns); | |
458 | ||
459 | /** | |
460 | * Returns an array of sensor data. | |
461 | * This function must block until events are available. | |
462 | * | |
463 | * @return the number of events read on success, or -errno in case of an error. | |
464 | * This function should never return 0 (no event). | |
465 | * | |
466 | */ | |
467 | int (*poll)(struct sensors_poll_device_t *dev, | |
468 | sensors_event_t* data, int count); | |
469 | }; | |
470 | ||
471 | /** convenience API for opening and closing a device */ | |
472 | ||
473 | static inline int sensors_open(const struct hw_module_t* module, | |
474 | struct sensors_poll_device_t** device) { | |
475 | return module->methods->open(module, | |
476 | SENSORS_HARDWARE_POLL, (struct hw_device_t**)device); | |
477 | } | |
478 | ||
479 | static inline int sensors_close(struct sensors_poll_device_t* device) { | |
480 | return device->common.close(&device->common); | |
481 | } | |
482 | ||
483 | __END_DECLS | |
484 | ||
485 | #endif // ANDROID_SENSORS_INTERFACE_H |