sensors.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2012 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 
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)
34 #define SENSORS_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION_2(1, 0, SENSORS_HEADER_VERSION)
35 #define SENSORS_DEVICE_API_VERSION_1_1 HARDWARE_DEVICE_API_VERSION_2(1, 1, SENSORS_HEADER_VERSION)
36 #define SENSORS_DEVICE_API_VERSION_1_2 HARDWARE_DEVICE_API_VERSION_2(1, 2, SENSORS_HEADER_VERSION)
37 #define SENSORS_DEVICE_API_VERSION_1_3 HARDWARE_DEVICE_API_VERSION_2(1, 3, SENSORS_HEADER_VERSION)
38 #define SENSORS_DEVICE_API_VERSION_1_4 HARDWARE_DEVICE_API_VERSION_2(1, 4, SENSORS_HEADER_VERSION)
39 
40 /**
41  * Please see the Sensors section of source.android.com for an
42  * introduction to and detailed descriptions of Android sensor types:
43  * http://source.android.com/devices/sensors/index.html
44  */
45 
46 /**
47  * The id of this module
48  */
49 #define SENSORS_HARDWARE_MODULE_ID "sensors"
50 
51 /**
52  * Name of the sensors device to open
53  */
54 #define SENSORS_HARDWARE_POLL "poll"
55 
56 /**
57  * Handles must be higher than SENSORS_HANDLE_BASE and must be unique.
58  * A Handle identifies a given sensors. The handle is used to activate
59  * and/or deactivate sensors.
60  * In this version of the API there can only be 256 handles.
61  */
62 #define SENSORS_HANDLE_BASE 0
63 #define SENSORS_HANDLE_BITS 8
64 #define SENSORS_HANDLE_COUNT (1<<SENSORS_HANDLE_BITS)
65 
66 
67 /*
68  * **** Deprecated *****
69  * flags for (*batch)()
70  * Availability: SENSORS_DEVICE_API_VERSION_1_0
71  * see (*batch)() documentation for details.
72  * Deprecated as of SENSORS_DEVICE_API_VERSION_1_3.
73  * WAKE_UP_* sensors replace WAKE_UPON_FIFO_FULL concept.
74  */
75 enum {
76  SENSORS_BATCH_DRY_RUN = 0x00000001,
78 };
79 
80 /*
81  * what field for meta_data_event_t
82  */
83 enum {
84  /* a previous flush operation has completed */
86  META_DATA_VERSION /* always last, leave auto-assigned */
87 };
88 
89 /*
90  * The permission to use for body sensors (like heart rate monitors).
91  * See sensor types for more details on what sensors should require this
92  * permission.
93  */
94 #define SENSOR_PERMISSION_BODY_SENSORS "android.permission.BODY_SENSORS"
95 
96 /*
97  * Availability: SENSORS_DEVICE_API_VERSION_1_4
98  * Sensor HAL modes used in set_operation_mode method
99  */
100 enum {
101  /*
102  * Operating modes for the HAL.
103  */
104 
105  /*
106  * Normal mode operation. This is the default state of operation.
107  * The HAL shall initialize into this mode on device startup.
108  */
110 
111  /*
112  * Data Injection mode. In this mode, the device shall not source data from the
113  * physical sensors as it would in normal mode. Instead sensor data is
114  * injected by the sensor service.
115  */
117 };
118 
119 #define SENSOR_FLAG_MASK(nbit, shift) (((1<<(nbit))-1)<<(shift))
120 #define SENSOR_FLAG_MASK_1(shift) SENSOR_FLAG_MASK(1, shift)
121 
122 /*
123  * Mask and shift for reporting mode sensor flags defined above.
124  */
125 #define REPORTING_MODE_SHIFT (1)
126 #define REPORTING_MODE_NBIT (3)
127 #define REPORTING_MODE_MASK SENSOR_FLAG_MASK(REPORTING_MODE_NBIT, REPORTING_MODE_SHIFT)
128  // 0xE
129 
130 /*
131  * Mask and shift for data_injection mode sensor flags defined above.
132  */
133 #define DATA_INJECTION_SHIFT (4)
134 #define DATA_INJECTION_MASK SENSOR_FLAG_MASK_1(DATA_INJECTION_SHIFT) //0x10
135 
136 /*
137  * Mask and shift for dynamic sensor flag.
138  */
139 #define DYNAMIC_SENSOR_SHIFT (5)
140 #define DYNAMIC_SENSOR_MASK SENSOR_FLAG_MASK_1(DYNAMIC_SENSOR_SHIFT) //0x20
141 
142 /*
143  * Mask and shift for sensor additional information support.
144  */
145 #define ADDITIONAL_INFO_SHIFT (6)
146 #define ADDITIONAL_INFO_MASK SENSOR_FLAG_MASK_1(ADDITIONAL_INFO_SHIFT) //0x40
147 
148 /*
149  * Availability: SENSORS_DEVICE_API_VERSION_1_3
150  * Sensor flags used in sensor_t.flags.
151  */
152 enum {
153  /*
154  * Whether this sensor wakes up the AP from suspend mode when data is available. Whenever
155  * sensor events are delivered from a wake_up sensor, the driver needs to hold a wake_lock till
156  * the events are read by the SensorService i.e till sensors_poll_device_t.poll() is called the
157  * next time. Once poll is called again it means events have been read by the SensorService, the
158  * driver can safely release the wake_lock. SensorService will continue to hold a wake_lock till
159  * the app actually reads the events.
160  */
162  /*
163  * Reporting modes for various sensors. Each sensor will have exactly one of these modes set.
164  * The least significant 2nd, 3rd and 4th bits are used to represent four possible reporting
165  * modes.
166  */
171 
172  /*
173  * Set this flag if the sensor supports data_injection mode and allows data to be injected
174  * from the SensorService. When in data_injection ONLY sensors with this flag set are injected
175  * sensor data and only sensors with this flag set are activated. Eg: Accelerometer and Step
176  * Counter sensors can be set with this flag and SensorService will inject accelerometer data
177  * and read the corresponding step counts.
178  */
180 
181  /*
182  * Set this flag if the sensor is a dynamically connected sensor. See
183  * dynamic_sensor_meta_event_t and SENSOR_TYPE_DYNAMIC_SENSOR_META for details.
184  */
186 
187  /*
188  * Set this flag if sensor additional information is supported. See SENSOR_TYPE_ADDITIONAL_INFO
189  * and additional_info_event_t for details.
190  */
192 };
193 
194 
195 /*
196  * Sensor type
197  *
198  * Each sensor has a type which defines what this sensor measures and how
199  * measures are reported. See the Base sensors and Composite sensors lists
200  * for complete descriptions:
201  * http://source.android.com/devices/sensors/base_triggers.html
202  * http://source.android.com/devices/sensors/composite_sensors.html
203  *
204  * Device manufacturers (OEMs) can define their own sensor types, for
205  * their private use by applications or services provided by them. Such
206  * sensor types are specific to an OEM and can't be exposed in the SDK.
207  * These types must start at SENSOR_TYPE_DEVICE_PRIVATE_BASE.
208  *
209  * All sensors defined outside of the device private range must correspond to
210  * a type defined in this file, and must satisfy the characteristics listed in
211  * the description of the sensor type.
212  *
213  * Starting with version SENSORS_DEVICE_API_VERSION_1_2, each sensor also
214  * has a stringType.
215  * - StringType of sensors inside of the device private range MUST be prefixed
216  * by the sensor provider's or OEM reverse domain name. In particular, they
217  * cannot use the "android.sensor" prefix.
218  * - StringType of sensors outside of the device private range MUST correspond
219  * to the one defined in this file (starting with "android.sensor").
220  * For example, accelerometers must have
221  * type=SENSOR_TYPE_ACCELEROMETER and
222  * stringType=SENSOR_STRING_TYPE_ACCELEROMETER
223  *
224  * When android introduces a new sensor type that can replace an OEM-defined
225  * sensor type, the OEM must use the official sensor type and stringType on
226  * versions of the HAL that support this new official sensor type.
227  *
228  * Example (made up): Suppose Google's Glass team wants to surface a sensor
229  * detecting that Glass is on a head.
230  * - Such a sensor is not officially supported in android KitKat
231  * - Glass devices launching on KitKat can implement a sensor with
232  * type = 0x10001 and stringType = "com.google.glass.onheaddetector"
233  * - In L android release, if android decides to define
234  * SENSOR_TYPE_ON_HEAD_DETECTOR and STRING_SENSOR_TYPE_ON_HEAD_DETECTOR,
235  * those types should replace the Glass-team-specific types in all future
236  * launches.
237  * - When launching Glass on the L release, Google should now use the official
238  * type (SENSOR_TYPE_ON_HEAD_DETECTOR) and stringType.
239  * - This way, all applications can now use this sensor.
240  */
241 
242 /*
243  * Base for device manufacturers private sensor types.
244  * These sensor types can't be exposed in the SDK.
245  */
246 #define SENSOR_TYPE_DEVICE_PRIVATE_BASE 0x10000
247 
248 /*
249  * SENSOR_TYPE_META_DATA
250  * reporting-mode: n/a
251  * wake-up sensor: n/a
252  *
253  * NO SENSOR OF THAT TYPE MUST BE RETURNED (*get_sensors_list)()
254  *
255  * SENSOR_TYPE_META_DATA is a special token used to populate the
256  * sensors_meta_data_event structure. It doesn't correspond to a physical
257  * sensor. sensors_meta_data_event are special, they exist only inside
258  * the HAL and are generated spontaneously, as opposed to be related to
259  * a physical sensor.
260  *
261  * sensors_meta_data_event_t.version must be META_DATA_VERSION
262  * sensors_meta_data_event_t.sensor must be 0
263  * sensors_meta_data_event_t.type must be SENSOR_TYPE_META_DATA
264  * sensors_meta_data_event_t.reserved must be 0
265  * sensors_meta_data_event_t.timestamp must be 0
266  *
267  * The payload is a meta_data_event_t, where:
268  * meta_data_event_t.what can take the following values:
269  *
270  * META_DATA_FLUSH_COMPLETE
271  * This event indicates that a previous (*flush)() call has completed for the sensor
272  * handle specified in meta_data_event_t.sensor.
273  * see (*flush)() for more details
274  *
275  * All other values for meta_data_event_t.what are reserved and
276  * must not be used.
277  *
278  */
279 #define SENSOR_TYPE_META_DATA (0)
280 
281 /*
282  * Wake up sensors.
283  * Each sensor may have either or both a wake-up and a non-wake variant.
284  * When registered in batch mode, wake-up sensors will wake up the AP when
285  * their FIFOs are full or when the batch timeout expires. A separate FIFO has
286  * to be maintained for wake up sensors and non wake up sensors. The non wake-up
287  * sensors need to overwrite their FIFOs when they are full till the AP wakes up
288  * and the wake-up sensors will wake-up the AP when their FIFOs are full or when
289  * the batch timeout expires without losing events. Wake-up and non wake-up variants
290  * of each sensor can be activated at different rates independently of each other.
291  *
292  * Note: Proximity sensor and significant motion sensor which were defined in previous
293  * releases are also wake-up sensors and should be treated as such. Wake-up one-shot
294  * sensors like SIGNIFICANT_MOTION cannot be batched, hence the text about batch above
295  * doesn't apply to them. See the definitions of SENSOR_TYPE_PROXIMITY and
296  * SENSOR_TYPE_SIGNIFICANT_MOTION for more info.
297  *
298  * Set SENSOR_FLAG_WAKE_UP flag for all wake-up sensors.
299  *
300  * For example, A device can have two sensors both of SENSOR_TYPE_ACCELEROMETER and
301  * one of them can be a wake_up sensor (with SENSOR_FLAG_WAKE_UP flag set) and the other
302  * can be a regular non wake_up sensor. Both of these sensors must be activated/deactivated
303  * independently of the other.
304  */
305 
306 /*
307  * SENSOR_TYPE_ACCELEROMETER
308  * reporting-mode: continuous
309  *
310  * All values are in SI units (m/s^2) and measure the acceleration of the
311  * device minus the force of gravity.
312  *
313  * Implement the non-wake-up version of this sensor and implement the wake-up
314  * version if the system possesses a wake up fifo.
315  */
316 #define SENSOR_TYPE_ACCELEROMETER (1)
317 #define SENSOR_STRING_TYPE_ACCELEROMETER "android.sensor.accelerometer"
318 
319 /*
320  * SENSOR_TYPE_GEOMAGNETIC_FIELD
321  * reporting-mode: continuous
322  *
323  * All values are in micro-Tesla (uT) and measure the geomagnetic
324  * field in the X, Y and Z axis.
325  *
326  * Implement the non-wake-up version of this sensor and implement the wake-up
327  * version if the system possesses a wake up fifo.
328  */
329 #define SENSOR_TYPE_GEOMAGNETIC_FIELD (2)
330 #define SENSOR_TYPE_MAGNETIC_FIELD SENSOR_TYPE_GEOMAGNETIC_FIELD
331 #define SENSOR_STRING_TYPE_MAGNETIC_FIELD "android.sensor.magnetic_field"
332 
333 /*
334  * SENSOR_TYPE_ORIENTATION
335  * reporting-mode: continuous
336  *
337  * All values are angles in degrees.
338  *
339  * Orientation sensors return sensor events for all 3 axes at a constant
340  * rate defined by setDelay().
341  *
342  * Implement the non-wake-up version of this sensor and implement the wake-up
343  * version if the system possesses a wake up fifo.
344  */
345 #define SENSOR_TYPE_ORIENTATION (3)
346 #define SENSOR_STRING_TYPE_ORIENTATION "android.sensor.orientation"
347 
348 /*
349  * SENSOR_TYPE_GYROSCOPE
350  * reporting-mode: continuous
351  *
352  * All values are in radians/second and measure the rate of rotation
353  * around the X, Y and Z axis.
354  *
355  * Implement the non-wake-up version of this sensor and implement the wake-up
356  * version if the system possesses a wake up fifo.
357  */
358 #define SENSOR_TYPE_GYROSCOPE (4)
359 #define SENSOR_STRING_TYPE_GYROSCOPE "android.sensor.gyroscope"
360 
361 /*
362  * SENSOR_TYPE_LIGHT
363  * reporting-mode: on-change
364  *
365  * The light sensor value is returned in SI lux units.
366  *
367  * Both wake-up and non wake-up versions are useful.
368  */
369 #define SENSOR_TYPE_LIGHT (5)
370 #define SENSOR_STRING_TYPE_LIGHT "android.sensor.light"
371 
372 /*
373  * SENSOR_TYPE_PRESSURE
374  * reporting-mode: continuous
375  *
376  * The pressure sensor return the athmospheric pressure in hectopascal (hPa)
377  *
378  * Implement the non-wake-up version of this sensor and implement the wake-up
379  * version if the system possesses a wake up fifo.
380  */
381 #define SENSOR_TYPE_PRESSURE (6)
382 #define SENSOR_STRING_TYPE_PRESSURE "android.sensor.pressure"
383 
384 /* SENSOR_TYPE_TEMPERATURE is deprecated in the HAL */
385 #define SENSOR_TYPE_TEMPERATURE (7)
386 #define SENSOR_STRING_TYPE_TEMPERATURE "android.sensor.temperature"
387 
388 /*
389  * SENSOR_TYPE_PROXIMITY
390  * reporting-mode: on-change
391  *
392  * The proximity sensor which turns the screen off and back on during calls is the
393  * wake-up proximity sensor. Implement wake-up proximity sensor before implementing
394  * a non wake-up proximity sensor. For the wake-up proximity sensor set the flag
395  * SENSOR_FLAG_WAKE_UP.
396  * The value corresponds to the distance to the nearest object in centimeters.
397  */
398 #define SENSOR_TYPE_PROXIMITY (8)
399 #define SENSOR_STRING_TYPE_PROXIMITY "android.sensor.proximity"
400 
401 /*
402  * SENSOR_TYPE_GRAVITY
403  * reporting-mode: continuous
404  *
405  * A gravity output indicates the direction of and magnitude of gravity in
406  * the devices's coordinates.
407  *
408  * Implement the non-wake-up version of this sensor and implement the wake-up
409  * version if the system possesses a wake up fifo.
410  */
411 #define SENSOR_TYPE_GRAVITY (9)
412 #define SENSOR_STRING_TYPE_GRAVITY "android.sensor.gravity"
413 
414 /*
415  * SENSOR_TYPE_LINEAR_ACCELERATION
416  * reporting-mode: continuous
417  *
418  * Indicates the linear acceleration of the device in device coordinates,
419  * not including gravity.
420  *
421  * Implement the non-wake-up version of this sensor and implement the wake-up
422  * version if the system possesses a wake up fifo.
423  */
424 #define SENSOR_TYPE_LINEAR_ACCELERATION (10)
425 #define SENSOR_STRING_TYPE_LINEAR_ACCELERATION "android.sensor.linear_acceleration"
426 
427 
428 /*
429  * SENSOR_TYPE_ROTATION_VECTOR
430  * reporting-mode: continuous
431  *
432  * The rotation vector symbolizes the orientation of the device relative to the
433  * East-North-Up coordinates frame.
434  *
435  * Implement the non-wake-up version of this sensor and implement the wake-up
436  * version if the system possesses a wake up fifo.
437  */
438 #define SENSOR_TYPE_ROTATION_VECTOR (11)
439 #define SENSOR_STRING_TYPE_ROTATION_VECTOR "android.sensor.rotation_vector"
440 
441 /*
442  * SENSOR_TYPE_RELATIVE_HUMIDITY
443  * reporting-mode: on-change
444  *
445  * A relative humidity sensor measures relative ambient air humidity and
446  * returns a value in percent.
447  *
448  * Both wake-up and non wake-up versions are useful.
449  */
450 #define SENSOR_TYPE_RELATIVE_HUMIDITY (12)
451 #define SENSOR_STRING_TYPE_RELATIVE_HUMIDITY "android.sensor.relative_humidity"
452 
453 /*
454  * SENSOR_TYPE_AMBIENT_TEMPERATURE
455  * reporting-mode: on-change
456  *
457  * The ambient (room) temperature in degree Celsius.
458  *
459  * Both wake-up and non wake-up versions are useful.
460  */
461 #define SENSOR_TYPE_AMBIENT_TEMPERATURE (13)
462 #define SENSOR_STRING_TYPE_AMBIENT_TEMPERATURE "android.sensor.ambient_temperature"
463 
464 /*
465  * SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED
466  * reporting-mode: continuous
467  *
468  * Similar to SENSOR_TYPE_MAGNETIC_FIELD, but the hard iron calibration is
469  * reported separately instead of being included in the measurement.
470  *
471  * Implement the non-wake-up version of this sensor and implement the wake-up
472  * version if the system possesses a wake up fifo.
473  */
474 #define SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED (14)
475 #define SENSOR_STRING_TYPE_MAGNETIC_FIELD_UNCALIBRATED "android.sensor.magnetic_field_uncalibrated"
476 
477 /*
478  * SENSOR_TYPE_GAME_ROTATION_VECTOR
479  * reporting-mode: continuous
480  *
481  * Similar to SENSOR_TYPE_ROTATION_VECTOR, but not using the geomagnetic
482  * field.
483  *
484  * Implement the non-wake-up version of this sensor and implement the wake-up
485  * version if the system possesses a wake up fifo.
486  */
487 #define SENSOR_TYPE_GAME_ROTATION_VECTOR (15)
488 #define SENSOR_STRING_TYPE_GAME_ROTATION_VECTOR "android.sensor.game_rotation_vector"
489 
490 /*
491  * SENSOR_TYPE_GYROSCOPE_UNCALIBRATED
492  * reporting-mode: continuous
493  *
494  * All values are in radians/second and measure the rate of rotation
495  * around the X, Y and Z axis.
496  *
497  * Implement the non-wake-up version of this sensor and implement the wake-up
498  * version if the system possesses a wake up fifo.
499  */
500 #define SENSOR_TYPE_GYROSCOPE_UNCALIBRATED (16)
501 #define SENSOR_STRING_TYPE_GYROSCOPE_UNCALIBRATED "android.sensor.gyroscope_uncalibrated"
502 
503 /*
504  * SENSOR_TYPE_SIGNIFICANT_MOTION
505  * reporting-mode: one-shot
506  *
507  * A sensor of this type triggers an event each time significant motion
508  * is detected and automatically disables itself.
509  * For Significant Motion sensor to be useful, it must be defined as a
510  * wake-up sensor. (set SENSOR_FLAG_WAKE_UP). Implement the wake-up significant motion
511  * sensor. A non wake-up version is not useful.
512  * The only allowed value to return is 1.0.
513  */
514 
515 #define SENSOR_TYPE_SIGNIFICANT_MOTION (17)
516 #define SENSOR_STRING_TYPE_SIGNIFICANT_MOTION "android.sensor.significant_motion"
517 
518 /*
519  * SENSOR_TYPE_STEP_DETECTOR
520  * reporting-mode: special
521  *
522  * A sensor of this type triggers an event each time a step is taken
523  * by the user. The only allowed value to return is 1.0 and an event
524  * is generated for each step.
525  *
526  * Both wake-up and non wake-up versions are useful.
527  */
528 
529 #define SENSOR_TYPE_STEP_DETECTOR (18)
530 #define SENSOR_STRING_TYPE_STEP_DETECTOR "android.sensor.step_detector"
531 
532 
533 /*
534  * SENSOR_TYPE_STEP_COUNTER
535  * reporting-mode: on-change
536  *
537  * A sensor of this type returns the number of steps taken by the user since
538  * the last reboot while activated. The value is returned as a uint64_t and is
539  * reset to zero only on a system / android reboot.
540  *
541  * Implement the non-wake-up version of this sensor and implement the wake-up
542  * version if the system possesses a wake up fifo.
543  */
544 
545 #define SENSOR_TYPE_STEP_COUNTER (19)
546 #define SENSOR_STRING_TYPE_STEP_COUNTER "android.sensor.step_counter"
547 
548 /*
549  * SENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR
550  * reporting-mode: continuous
551  *
552  * Similar to SENSOR_TYPE_ROTATION_VECTOR, but using a magnetometer instead
553  * of using a gyroscope.
554  *
555  * Implement the non-wake-up version of this sensor and implement the wake-up
556  * version if the system possesses a wake up fifo.
557  */
558 #define SENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR (20)
559 #define SENSOR_STRING_TYPE_GEOMAGNETIC_ROTATION_VECTOR "android.sensor.geomagnetic_rotation_vector"
560 
561 /*
562  * SENSOR_TYPE_HEART_RATE
563  * reporting-mode: on-change
564  *
565  * A sensor of this type returns the current heart rate.
566  * The events contain the current heart rate in beats per minute (BPM) and the
567  * status of the sensor during the measurement. See heart_rate_event_t for more
568  * details.
569  *
570  * Because this sensor is on-change, events must be generated when and only
571  * when heart_rate.bpm or heart_rate.status have changed since the last
572  * event. In particular, upon the first activation, unless the device is known
573  * to not be on the body, the status field of the first event must be set to
574  * SENSOR_STATUS_UNRELIABLE. The event should be generated no faster than every
575  * period_ns passed to setDelay() or to batch().
576  * See the definition of the on-change reporting mode for more information.
577  *
578  * sensor_t.requiredPermission must be set to SENSOR_PERMISSION_BODY_SENSORS.
579  *
580  * Both wake-up and non wake-up versions are useful.
581  */
582 #define SENSOR_TYPE_HEART_RATE (21)
583 #define SENSOR_STRING_TYPE_HEART_RATE "android.sensor.heart_rate"
584 
585 /*
586  * SENSOR_TYPE_WAKE_UP_TILT_DETECTOR
587  * reporting-mode: special (setDelay has no impact)
588  *
589  * A sensor of this type generates an event each time a tilt event is detected. A tilt event
590  * should be generated if the direction of the 2-seconds window average gravity changed by at least
591  * 35 degrees since the activation or the last trigger of the sensor.
592  * reference_estimated_gravity = average of accelerometer measurements over the first
593  * 1 second after activation or the estimated gravity at the last
594  * trigger.
595  * current_estimated_gravity = average of accelerometer measurements over the last 2 seconds.
596  * trigger when angle (reference_estimated_gravity, current_estimated_gravity) > 35 degrees
597  *
598  * Large accelerations without a change in phone orientation should not trigger a tilt event.
599  * For example, a sharp turn or strong acceleration while driving a car should not trigger a tilt
600  * event, even though the angle of the average acceleration might vary by more than 35 degrees.
601  *
602  * Typically, this sensor is implemented with the help of only an accelerometer. Other sensors can
603  * be used as well if they do not increase the power consumption significantly. This is a low power
604  * sensor that should allow the AP to go into suspend mode. Do not emulate this sensor in the HAL.
605  * Like other wake up sensors, the driver is expected to a hold a wake_lock with a timeout of 200 ms
606  * while reporting this event. The only allowed return value is 1.0.
607  *
608  * Implement only the wake-up version of this sensor.
609  */
610 #define SENSOR_TYPE_TILT_DETECTOR (22)
611 #define SENSOR_STRING_TYPE_TILT_DETECTOR "android.sensor.tilt_detector"
612 
613 /*
614  * SENSOR_TYPE_WAKE_GESTURE
615  * reporting-mode: one-shot
616  *
617  * A sensor enabling waking up the device based on a device specific motion.
618  *
619  * When this sensor triggers, the device behaves as if the power button was
620  * pressed, turning the screen on. This behavior (turning on the screen when
621  * this sensor triggers) might be deactivated by the user in the device
622  * settings. Changes in settings do not impact the behavior of the sensor:
623  * only whether the framework turns the screen on when it triggers.
624  *
625  * The actual gesture to be detected is not specified, and can be chosen by
626  * the manufacturer of the device.
627  * This sensor must be low power, as it is likely to be activated 24/7.
628  * The only allowed value to return is 1.0.
629  *
630  * Implement only the wake-up version of this sensor.
631  */
632 #define SENSOR_TYPE_WAKE_GESTURE (23)
633 #define SENSOR_STRING_TYPE_WAKE_GESTURE "android.sensor.wake_gesture"
634 
635 /*
636  * SENSOR_TYPE_GLANCE_GESTURE
637  * reporting-mode: one-shot
638  *
639  * A sensor enabling briefly turning the screen on to enable the user to
640  * glance content on screen based on a specific motion. The device should
641  * turn the screen off after a few moments.
642  *
643  * When this sensor triggers, the device turns the screen on momentarily
644  * to allow the user to glance notifications or other content while the
645  * device remains locked in a non-interactive state (dozing). This behavior
646  * (briefly turning on the screen when this sensor triggers) might be deactivated
647  * by the user in the device settings. Changes in settings do not impact the
648  * behavior of the sensor: only whether the framework briefly turns the screen on
649  * when it triggers.
650  *
651  * The actual gesture to be detected is not specified, and can be chosen by
652  * the manufacturer of the device.
653  * This sensor must be low power, as it is likely to be activated 24/7.
654  * The only allowed value to return is 1.0.
655  *
656  * Implement only the wake-up version of this sensor.
657  */
658 #define SENSOR_TYPE_GLANCE_GESTURE (24)
659 #define SENSOR_STRING_TYPE_GLANCE_GESTURE "android.sensor.glance_gesture"
660 
661 /**
662  * SENSOR_TYPE_PICK_UP_GESTURE
663  * reporting-mode: one-shot
664  *
665  * A sensor of this type triggers when the device is picked up regardless of wherever is was
666  * before (desk, pocket, bag). The only allowed return value is 1.0.
667  * This sensor de-activates itself immediately after it triggers.
668  *
669  * Implement only the wake-up version of this sensor.
670  */
671 #define SENSOR_TYPE_PICK_UP_GESTURE (25)
672 #define SENSOR_STRING_TYPE_PICK_UP_GESTURE "android.sensor.pick_up_gesture"
673 
674 /*
675  * SENSOR_TYPE_WRIST_TILT_GESTURE
676  * trigger-mode: special
677  * wake-up sensor: yes
678  *
679  * A sensor of this type triggers an event each time a tilt of the wrist-worn
680  * device is detected.
681  *
682  * This sensor must be low power, as it is likely to be activated 24/7.
683  * The only allowed value to return is 1.0.
684  *
685  * Implement only the wake-up version of this sensor.
686  */
687 #define SENSOR_TYPE_WRIST_TILT_GESTURE (26)
688 #define SENSOR_STRING_TYPE_WRIST_TILT_GESTURE "android.sensor.wrist_tilt_gesture"
689 
690 /*
691  * SENSOR_TYPE_DEVICE_ORIENTATION
692  * reporting-mode: on-change
693  *
694  * The current orientation of the device. The value should be reported in the
695  * first element of the 'data' member variable in sensors_event_t. The only
696  * values that can be reported are (please refer to Android Sensor Coordinate
697  * System to understand the X and Y axis direction with respect to default
698  * orientation):
699  * - 0: device is in default orientation (Y axis is vertical and points up)
700  * - 1: device is rotated 90 degrees counter-clockwise from default
701  * orientation (X axis is vertical and points up)
702  * - 2: device is rotated 180 degrees from default orientation (Y axis is
703  * vertical and points down)
704  * - 3: device is rotated 90 degrees clockwise from default orientation (X axis
705  * is vertical and points down)
706  *
707  * Moving the device to an orientation where the Z axis is vertical (either up
708  * or down) should not cause a new event to be reported.
709  *
710  * To improve the user experience of this sensor, it is recommended to implement
711  * some physical (i.e., rotation angle) and temporal (i.e., delay) hysteresis.
712  * In other words, minor or transient rotations should not cause a new event to
713  * be reported.
714  *
715  * This sensor should only be implemented with the help of an accelerometer.
716  * This is a low power sensor that should reduce the number of interrupts of the
717  * AP. Do not emulate this sensor in the HAL.
718  *
719  * Both wake-up and non wake-up versions are useful.
720  */
721 #define SENSOR_TYPE_DEVICE_ORIENTATION (27)
722 #define SENSOR_STRING_TYPE_DEVICE_ORIENTATION "android.sensor.device_orientation"
723 
724 /*
725  * SENSOR_TYPE_POSE_6DOF
726  * trigger-mode: continuous
727  *
728  * A sensor of this type returns the pose of the device.
729  * Pose of the device is defined as the orientation of the device from a
730  * Earth Centered Earth Fixed frame and the translation from an arbitrary
731  * point at subscription.
732  *
733  * This sensor can be high power. It can use any and all of the following
734  * . Accelerometer
735  * . Gyroscope
736  * . Camera
737  * . Depth Camera
738  *
739  */
740 #define SENSOR_TYPE_POSE_6DOF (28)
741 #define SENSOR_STRING_TYPE_POSE_6DOF "android.sensor.pose_6dof"
742 
743 /*
744  * SENSOR_TYPE_STATIONARY_DETECT
745  * trigger mode: one shot
746  *
747  * A sensor of this type returns an event if the device is still/stationary for
748  * a while. The period of time to monitor for statinarity should be greater than
749  * 5 seconds, and less than 10 seconds.
750  *
751  * Stationarity here refers to absolute stationarity. eg: device on desk.
752  *
753  * The only allowed value to return is 1.0.
754  */
755 #define SENSOR_TYPE_STATIONARY_DETECT (29)
756 #define SENSOR_STRING_TYPE_STATIONARY_DETECT "android.sensor.stationary_detect"
757 
758 /*
759  * SENSOR_TYPE_MOTION_DETECT
760  * trigger mode: one shot
761  *
762  * A sensor of this type returns an event if the device is not still for
763  * a while. The period of time to monitor for statinarity should be greater than
764  * 5 seconds, and less than 10 seconds.
765  *
766  * Motion here refers to any mechanism in which the device is causes to be
767  * moved in its inertial frame. eg: Pickin up the device and walking with it
768  * to a nearby room may trigger motion wherewas keeping the device on a table
769  * on a smooth train moving at constant velocity may not trigger motion.
770  *
771  * The only allowed value to return is 1.0.
772  */
773 #define SENSOR_TYPE_MOTION_DETECT (30)
774 #define SENSOR_STRING_TYPE_MOTION_DETECT "android.sensor.motion_detect"
775 
776 /*
777  * SENSOR_TYPE_HEART_BEAT
778  * trigger mode: continuous
779  *
780  * A sensor of this type returns an event everytime a hear beat peak is
781  * detected.
782  *
783  * Peak here ideally corresponds to the positive peak in the QRS complex of
784  * and ECG signal.
785  *
786  * The sensor is not expected to be optimized for latency. As a guide, a
787  * latency of up to 10 seconds is acceptable. However the timestamp attached
788  * to the event should be accurate and should correspond to the time the peak
789  * occured.
790  *
791  * The sensor event contains a parameter for the confidence in the detection
792  * of the peak where 0.0 represent no information at all, and 1.0 represents
793  * certainty.
794  */
795 #define SENSOR_TYPE_HEART_BEAT (31)
796 #define SENSOR_STRING_TYPE_HEART_BEAT "android.sensor.heart_beat"
797 
798 /**
799  * SENSOR_TYPE_DYNAMIC_SENSOR_META
800  * trigger-mode: special
801  *
802  * A sensor event of this type is received when a dynamic sensor is added to or removed from the
803  * system. At most one sensor of this type can be present in one sensor HAL implementation and
804  * presence of a sensor of this type in sensor HAL implementation indicates that this sensor HAL
805  * supports dynamic sensor feature. Operations, such as batch, activate and setDelay, to this
806  * special purpose sensor should be treated as no-op and return successful.
807  *
808  * A dynamic sensor connection indicates connection of a physical device or instantiation of a
809  * virtual sensor backed by algorithm; and a dynamic sensor disconnection indicates the the
810  * opposite. A sensor event of SENSOR_TYPE_DYNAMIC_SENSOR_META type should be delivered regardless
811  * of the activation status of the sensor in the event of dynamic sensor connection and
812  * disconnection. In the sensor event, besides the common data entries, "dynamic_sensor_meta", which
813  * includes fields for connection status, handle of the sensor involved, pointer to sensor_t
814  * structure and a uuid field, should be populated.
815  *
816  * At a dynamic sensor connection event, fields of sensor_t structure referenced by a pointer in
817  * dynamic_sensor_meta should be filled as if it was regular sensors. Sensor HAL is responsible for
818  * recovery of memory if the corresponding data is dynamicially allocated. However, the the pointer
819  * must be valid until the first activate call to the sensor reported in this connection event. At a
820  * dynamic sensor disconnection, the sensor_t pointer should be NULL.
821  *
822  * The sensor handle assigned to dynamic sensors should never be the same as that of any regular
823  * static sensors, and should be unique until next boot. In another word, if a handle h is used for
824  * a dynamic sensor A, that same number cannot be used for the same dynamic sensor A or another
825  * dynamic sensor B even after disconnection of A until reboot.
826  *
827  * The UUID field will be used for identifying the sensor in addition to name, vendor and version
828  * and type. For physical sensors of the same model, all sensors will have the same values in
829  * sensor_t, but the UUID should be unique and persistent for each individual unit. An all zero UUID
830  * indicates it is not possible to differentiate individual sensor unit.
831  *
832  */
833 #define SENSOR_TYPE_DYNAMIC_SENSOR_META (32)
834 #define SENSOR_STRING_TYPE_DYNAMIC_SENSOR_META "android.sensor.dynamic_sensor_meta"
835 
836 /**
837  * SENSOR_TYPE_ADDITIONAL_INFO
838  * reporting-mode: N/A
839  *
840  * This sensor type is for delivering additional sensor information aside from sensor event data.
841  * Additional information may include sensor front-end group delay, internal calibration parameters,
842  * noise level metrics, device internal temperature, etc.
843  *
844  * This type will never bind to a sensor. In other words, no sensor in the sensor list should be of
845  * the type SENSOR_TYPE_ADDITIONAL_INFO. If a sensor HAL supports sensor additional information
846  * feature, it reports sensor_event_t with "sensor" field set to handle of the reporting sensor and
847  * "type" field set to SENSOR_TYPE_ADDITIONAL_INFO. Delivery of additional information events is
848  * triggered under two conditions: an enable activate() call or a flush() call to the corresponding
849  * sensor.
850  *
851  * A single additional information report consists of multiple frames. Sequences of these frames are
852  * ordered using timestamps, which means the timestamps of sequential frames have to be at least 1
853  * nanosecond apart from each other. Each frame is a sensor_event_t delivered through the HAL
854  * interface, with related data stored in the "additional_info" field, which is of type
855  * additional_info_event_t. The "type" field of additional_info_event_t denotes the nature of the
856  * payload data (see additional_info_type_t). The "serial" field is used to keep the sequence of
857  * payload data that spans multiple frames. The first frame of the entire report is always of type
858  * AINFO_BEGIN, and the last frame is always AINFO_END.
859  *
860  * All additional information frames have to be delivered after flush complete event if flush() was
861  * triggering the report.
862  */
863 #define SENSOR_TYPE_ADDITIONAL_INFO (33)
864 #define SENSOR_STRING_TYPE_ADDITIONAL_INFO "android.sensor.additional_info"
865 
866 /**
867  * Values returned by the accelerometer in various locations in the universe.
868  * all values are in SI units (m/s^2)
869  */
870 #define GRAVITY_SUN (275.0f)
871 #define GRAVITY_EARTH (9.80665f)
872 
873 /** Maximum magnetic field on Earth's surface */
874 #define MAGNETIC_FIELD_EARTH_MAX (60.0f)
875 
876 /** Minimum magnetic field on Earth's surface */
877 #define MAGNETIC_FIELD_EARTH_MIN (30.0f)
878 
879 /**
880  * Possible values of the status field of sensor events.
881  */
882 #define SENSOR_STATUS_NO_CONTACT -1
883 #define SENSOR_STATUS_UNRELIABLE 0
884 #define SENSOR_STATUS_ACCURACY_LOW 1
885 #define SENSOR_STATUS_ACCURACY_MEDIUM 2
886 #define SENSOR_STATUS_ACCURACY_HIGH 3
887 
888 
889 struct sensor_t;
890 
891 /**
892  * sensor event data
893  */
894 typedef struct {
895  union {
896  float v[3];
897  struct {
898  float x;
899  float y;
900  float z;
901  };
902  struct {
903  float azimuth;
904  float pitch;
905  float roll;
906  };
907  };
908  int8_t status;
909  uint8_t reserved[3];
910 } sensors_vec_t;
911 
912 /**
913  * uncalibrated gyroscope and magnetometer event data
914  */
915 typedef struct {
916  union {
917  float uncalib[3];
918  struct {
919  float x_uncalib;
920  float y_uncalib;
921  float z_uncalib;
922  };
923  };
924  union {
925  float bias[3];
926  struct {
927  float x_bias;
928  float y_bias;
929  float z_bias;
930  };
931  };
933 
934 /**
935  * Meta data event data
936  */
937 typedef struct meta_data_event {
938  int32_t what;
939  int32_t sensor;
941 
942 /**
943  * Dynamic sensor meta event. See the description of SENSOR_TYPE_DYNAMIC_SENSOR_META type for
944  * details.
945  */
947  int32_t connected;
948  int32_t handle;
949  const struct sensor_t * sensor; // should be NULL if connected == false
950  uint8_t uuid[16]; // UUID of a dynamic sensor (using RFC 4122 byte order)
951  // For UUID 12345678-90AB-CDEF-1122-334455667788 the uuid field
952  // should be initialized as:
953  // {0x12, 0x34, 0x56, 0x78, 0x90, 0xAB, 0xCD, 0xEF, 0x11, ...}
955 
956 /**
957  * Heart rate event data
958  */
959 typedef struct {
960  // Heart rate in beats per minute.
961  // Set to 0 when status is SENSOR_STATUS_UNRELIABLE or ..._NO_CONTACT
962  float bpm;
963  // Status of the sensor for this reading. Set to one SENSOR_STATUS_...
964  // Note that this value should only be set for sensors that explicitly define
965  // the meaning of this field. This field is not piped through the framework
966  // for other sensors.
967  int8_t status;
969 
970 typedef struct {
971  int32_t type; // type of payload data, see additional_info_type_t
972  int32_t serial; // sequence number of this frame for this type
973  union {
974  // for each frame, a single data type, either int32_t or float, should be used.
975  int32_t data_int32[14];
976  float data_float[14];
977  };
979 
980 typedef enum additional_info_type {
981  //
982  AINFO_BEGIN = 0x0, // Marks the beginning of additional information frames
983  AINFO_END = 0x1, // Marks the end of additional information frames
984  // Basic information
985  AINFO_UNTRACKED_DELAY = 0x10000, // Estimation of the delay that is not tracked by sensor
986  // timestamps. This includes delay introduced by
987  // sensor front-end filtering, data transport, etc.
988  // float[2]: delay in seconds
989  // standard deviation of estimated value
990  //
991  AINFO_INTERNAL_TEMPERATURE, // float: Celsius temperature.
992  //
993  AINFO_VEC3_CALIBRATION, // First three rows of a homogeneous matrix, which
994  // represents calibration to a three-element vector
995  // raw sensor reading.
996  // float[12]: 3x4 matrix in row major order
997  //
998  AINFO_SENSOR_PLACEMENT, // Location and orientation of sensor element in the
999  // device frame: origin is the geometric center of the
1000  // mobile device screen surface; the axis definition
1001  // corresponds to Android sensor definitions.
1002  // float[12]: 3x4 matrix in row major order
1003  //
1004  AINFO_SAMPLING, // float[2]: raw sample period in seconds,
1005  // standard deviation of sampling period
1006 
1007  // Sampling channel modeling information
1008  AINFO_CHANNEL_NOISE = 0x20000, // int32_t: noise type
1009  // float[n]: parameters
1010  //
1011  AINFO_CHANNEL_SAMPLER, // float[3]: sample period
1012  // standard deviation of sample period,
1013  // quantization unit
1014  //
1015  AINFO_CHANNEL_FILTER, // Represents a filter:
1016  // \sum_j a_j y[n-j] == \sum_i b_i x[n-i]
1017  //
1018  // int32_t[3]: number of feedforward coefficients, M,
1019  // number of feedback coefficients, N, for
1020  // FIR filter, N=1.
1021  // bit mask that represents which element to
1022  // which the filter is applied, bit 0 == 1
1023  // means this filter applies to vector
1024  // element 0.
1025  // float[M+N]: filter coefficients (b0, b1, ..., BM-1),
1026  // then (a0, a1, ..., aN-1), a0 is always 1.
1027  // Multiple frames may be needed for higher
1028  // number of taps.
1029  //
1030  AINFO_CHANNEL_LINEAR_TRANSFORM, // int32_t[2]: size in (row, column) ... 1st frame
1031  // float[n]: matrix element values in row major order.
1032  //
1033  AINFO_CHANNEL_NONLINEAR_MAP, // int32_t[2]: extrapolate method
1034  // interpolate method
1035  // float[n]: mapping key points in pairs, (in, out)...
1036  // (may be used to model saturation)
1037  //
1038  AINFO_CHANNEL_RESAMPLER, // int32_t: resample method (0-th order, 1st order...)
1039  // float[1]: resample ratio (upsampling if < 1.0;
1040  // downsampling if > 1.0).
1041  //
1042 
1043  // Custom information
1044  AINFO_CUSTOM_START = 0x10000000, //
1045  // Debugging
1046  AINFO_DEBUGGING_START = 0x40000000, //
1048 
1049 /**
1050  * Union of the various types of sensor data
1051  * that can be returned.
1052  */
1053 typedef struct sensors_event_t {
1054  /* must be sizeof(struct sensors_event_t) */
1055  int32_t version;
1056 
1057  /* sensor identifier */
1058  int32_t sensor;
1059 
1060  /* sensor type */
1061  int32_t type;
1062 
1063  /* reserved */
1064  int32_t reserved0;
1065 
1066  /* time is in nanosecond */
1067  int64_t timestamp;
1068 
1069  union {
1070  union {
1071  float data[16];
1072 
1073  /* acceleration values are in meter per second per second (m/s^2) */
1075 
1076  /* magnetic vector values are in micro-Tesla (uT) */
1078 
1079  /* orientation values are in degrees */
1081 
1082  /* gyroscope values are in rad/s */
1084 
1085  /* temperature is in degrees centigrade (Celsius) */
1087 
1088  /* distance in centimeters */
1089  float distance;
1090 
1091  /* light in SI lux units */
1092  float light;
1093 
1094  /* pressure in hectopascal (hPa) */
1095  float pressure;
1096 
1097  /* relative humidity in percent */
1099 
1100  /* uncalibrated gyroscope values are in rad/s */
1102 
1103  /* uncalibrated magnetometer values are in micro-Teslas */
1105 
1106  /* heart rate data containing value in bpm and status */
1108 
1109  /* this is a special event. see SENSOR_TYPE_META_DATA above.
1110  * sensors_meta_data_event_t events are all reported with a type of
1111  * SENSOR_TYPE_META_DATA. The handle is ignored and must be zero.
1112  */
1114 
1115  /* dynamic sensor meta event. See SENSOR_TYPE_DYNAMIC_SENSOR_META type for details */
1117 
1118  /*
1119  * special additional sensor information frame, see
1120  * SENSOR_TYPE_ADDITIONAL_INFO for details.
1121  */
1123  };
1124 
1125  union {
1126  uint64_t data[8];
1127 
1128  /* step-counter */
1129  uint64_t step_counter;
1130  } u64;
1131  };
1132 
1133  /* Reserved flags for internal use. Set to zero. */
1134  uint32_t flags;
1135 
1136  uint32_t reserved1[3];
1137 } sensors_event_t;
1138 
1139 
1140 /* see SENSOR_TYPE_META_DATA */
1142 
1143 
1144 /**
1145  * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
1146  * and the fields of this data structure must begin with hw_module_t
1147  * followed by module specific information.
1148  */
1151 
1152  /**
1153  * Enumerate all available sensors. The list is returned in "list".
1154  * @return number of sensors in the list
1155  */
1156  int (*get_sensors_list)(struct sensors_module_t* module,
1157  struct sensor_t const** list);
1158 
1159  /**
1160  * Place the module in a specific mode. The following modes are defined
1161  *
1162  * 0 - Normal operation. Default state of the module.
1163  * 1 - Loopback mode. Data is injected for the supported
1164  * sensors by the sensor service in this mode.
1165  * @return 0 on success
1166  * -EINVAL if requested mode is not supported
1167  * -EPERM if operation is not allowed
1168  */
1169  int (*set_operation_mode)(unsigned int mode);
1170 };
1171 
1172 struct sensor_t {
1173 
1174  /* Name of this sensor.
1175  * All sensors of the same "type" must have a different "name".
1176  */
1177  const char* name;
1178 
1179  /* vendor of the hardware part */
1180  const char* vendor;
1181 
1182  /* version of the hardware part + driver. The value of this field
1183  * must increase when the driver is updated in a way that changes the
1184  * output of this sensor. This is important for fused sensors when the
1185  * fusion algorithm is updated.
1186  */
1187  int version;
1188 
1189  /* handle that identifies this sensors. This handle is used to reference
1190  * this sensor throughout the HAL API.
1191  */
1192  int handle;
1193 
1194  /* this sensor's type. */
1195  int type;
1196 
1197  /* maximum range of this sensor's value in SI units */
1198  float maxRange;
1199 
1200  /* smallest difference between two values reported by this sensor */
1201  float resolution;
1202 
1203  /* rough estimate of this sensor's power consumption in mA */
1204  float power;
1205 
1206  /* this value depends on the reporting mode:
1207  *
1208  * continuous: minimum sample period allowed in microseconds
1209  * on-change : 0
1210  * one-shot :-1
1211  * special : 0, unless otherwise noted
1212  */
1213  int32_t minDelay;
1214 
1215  /* number of events reserved for this sensor in the batch mode FIFO.
1216  * If there is a dedicated FIFO for this sensor, then this is the
1217  * size of this FIFO. If the FIFO is shared with other sensors,
1218  * this is the size reserved for that sensor and it can be zero.
1219  */
1221 
1222  /* maximum number of events of this sensor that could be batched.
1223  * This is especially relevant when the FIFO is shared between
1224  * several sensors; this value is then set to the size of that FIFO.
1225  */
1227 
1228  /* type of this sensor as a string. Set to corresponding
1229  * SENSOR_STRING_TYPE_*.
1230  * When defining an OEM specific sensor or sensor manufacturer specific
1231  * sensor, use your reserve domain name as a prefix.
1232  * ex: com.google.glass.onheaddetector
1233  * For sensors of known type, the android framework might overwrite this
1234  * string automatically.
1235  */
1236  const char* stringType;
1237 
1238  /* permission required to see this sensor, register to it and receive data.
1239  * Set to "" if no permission is required. Some sensor types like the
1240  * heart rate monitor have a mandatory require_permission.
1241  * For sensors that always require a specific permission, like the heart
1242  * rate monitor, the android framework might overwrite this string
1243  * automatically.
1244  */
1245  const char* requiredPermission;
1246 
1247  /* This value is defined only for continuous mode and on-change sensors. It is the delay between
1248  * two sensor events corresponding to the lowest frequency that this sensor supports. When lower
1249  * frequencies are requested through batch()/setDelay() the events will be generated at this
1250  * frequency instead. It can be used by the framework or applications to estimate when the batch
1251  * FIFO may be full.
1252  *
1253  * NOTE: 1) period_ns is in nanoseconds where as maxDelay/minDelay are in microseconds.
1254  * continuous, on-change: maximum sampling period allowed in microseconds.
1255  * one-shot, special : 0
1256  * 2) maxDelay should always fit within a 32 bit signed integer. It is declared as 64 bit
1257  * on 64 bit architectures only for binary compatibility reasons.
1258  * Availability: SENSORS_DEVICE_API_VERSION_1_3
1259  */
1260  #ifdef __LP64__
1261  int64_t maxDelay;
1262  #else
1263  int32_t maxDelay;
1264  #endif
1265 
1266  /* Flags for sensor. See SENSOR_FLAG_* above. Only the least significant 32 bits are used here.
1267  * It is declared as 64 bit on 64 bit architectures only for binary compatibility reasons.
1268  * Availability: SENSORS_DEVICE_API_VERSION_1_3
1269  */
1270  #ifdef __LP64__
1271  uint64_t flags;
1272  #else
1273  uint32_t flags;
1274  #endif
1275 
1276  /* reserved fields, must be zero */
1277  void* reserved[2];
1278 };
1279 
1280 
1281 /*
1282  * sensors_poll_device_t is used with SENSORS_DEVICE_API_VERSION_0_1
1283  * and is present for backward binary and source compatibility.
1284  * See the Sensors HAL interface section for complete descriptions of the
1285  * following functions:
1286  * http://source.android.com/devices/sensors/index.html#hal
1287  */
1290  int (*activate)(struct sensors_poll_device_t *dev,
1291  int sensor_handle, int enabled);
1292  int (*setDelay)(struct sensors_poll_device_t *dev,
1293  int sensor_handle, int64_t sampling_period_ns);
1294  int (*poll)(struct sensors_poll_device_t *dev,
1295  sensors_event_t* data, int count);
1296 };
1297 
1298 /*
1299  * struct sensors_poll_device_1 is used in HAL versions >= SENSORS_DEVICE_API_VERSION_1_0
1300  */
1301 typedef struct sensors_poll_device_1 {
1302  union {
1303  /* sensors_poll_device_1 is compatible with sensors_poll_device_t,
1304  * and can be down-cast to it
1305  */
1307 
1308  struct {
1310 
1311  /* Activate/de-activate one sensor. Return 0 on success, negative
1312  *
1313  * sensor_handle is the handle of the sensor to change.
1314  * enabled set to 1 to enable, or 0 to disable the sensor.
1315  *
1316  * Return 0 on success, negative errno code otherwise.
1317  */
1318  int (*activate)(struct sensors_poll_device_t *dev,
1319  int sensor_handle, int enabled);
1320 
1321  /**
1322  * Set the events's period in nanoseconds for a given sensor.
1323  * If sampling_period_ns > max_delay it will be truncated to
1324  * max_delay and if sampling_period_ns < min_delay it will be
1325  * replaced by min_delay.
1326  */
1327  int (*setDelay)(struct sensors_poll_device_t *dev,
1328  int sensor_handle, int64_t sampling_period_ns);
1329 
1330  /**
1331  * Returns an array of sensor data.
1332  */
1333  int (*poll)(struct sensors_poll_device_t *dev,
1334  sensors_event_t* data, int count);
1335  };
1336  };
1337 
1338 
1339  /*
1340  * Sets a sensor’s parameters, including sampling frequency and maximum
1341  * report latency. This function can be called while the sensor is
1342  * activated, in which case it must not cause any sensor measurements to
1343  * be lost: transitioning from one sampling rate to the other cannot cause
1344  * lost events, nor can transitioning from a high maximum report latency to
1345  * a low maximum report latency.
1346  * See the Batching sensor results page for details:
1347  * http://source.android.com/devices/sensors/batching.html
1348  */
1349  int (*batch)(struct sensors_poll_device_1* dev,
1350  int sensor_handle, int flags, int64_t sampling_period_ns,
1351  int64_t max_report_latency_ns);
1352 
1353  /*
1354  * Flush adds a META_DATA_FLUSH_COMPLETE event (sensors_event_meta_data_t)
1355  * to the end of the "batch mode" FIFO for the specified sensor and flushes
1356  * the FIFO.
1357  * If the FIFO is empty or if the sensor doesn't support batching (FIFO size zero),
1358  * it should return SUCCESS along with a trivial META_DATA_FLUSH_COMPLETE event added to the
1359  * event stream. This applies to all sensors other than one-shot sensors.
1360  * If the sensor is a one-shot sensor, flush must return -EINVAL and not generate
1361  * any flush complete metadata.
1362  * If the sensor is not active at the time flush() is called, flush() should return
1363  * -EINVAL.
1364  */
1365  int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle);
1366 
1367  /*
1368  * Inject a single sensor sample to be to this device.
1369  * data points to the sensor event to be injected
1370  * @return 0 on success
1371  * -EPERM if operation is not allowed
1372  * -EINVAL if sensor event cannot be injected
1373  */
1375 
1376  void (*reserved_procs[7])(void);
1377 
1379 
1380 
1381 /** convenience API for opening and closing a device */
1382 
1383 static inline int sensors_open(const struct hw_module_t* module,
1384  struct sensors_poll_device_t** device) {
1385  return module->methods->open(module,
1386  SENSORS_HARDWARE_POLL, (struct hw_device_t**)device);
1387 }
1388 
1389 static inline int sensors_close(struct sensors_poll_device_t* device) {
1390  return device->common.close(&device->common);
1391 }
1392 
1393 static inline int sensors_open_1(const struct hw_module_t* module,
1394  sensors_poll_device_1_t** device) {
1395  return module->methods->open(module,
1396  SENSORS_HARDWARE_POLL, (struct hw_device_t**)device);
1397 }
1398 
1399 static inline int sensors_close_1(sensors_poll_device_1_t* device) {
1400  return device->common.close(&device->common);
1401 }
1402 
1403 __END_DECLS
1404 
1405 #endif // ANDROID_SENSORS_INTERFACE_H
uint32_t flags
Definition: sensors.h:1134
sensors_event_t sensors_meta_data_event_t
Definition: sensors.h:1141
additional_info_event_t additional_info
Definition: sensors.h:1122
int(* setDelay)(struct sensors_poll_device_t *dev, int sensor_handle, int64_t sampling_period_ns)
Definition: sensors.h:1292
int32_t sensor
Definition: sensors.h:939
int(* batch)(struct sensors_poll_device_1 *dev, int sensor_handle, int flags, int64_t sampling_period_ns, int64_t max_report_latency_ns)
Definition: sensors.h:1349
float azimuth
Definition: sensors.h:903
additional_info_type
Definition: sensors.h:980
int(* open)(const struct hw_module_t *module, const char *id, struct hw_device_t **device)
Definition: hardware.h:158
struct sensors_poll_device_1 sensors_poll_device_1_t
const struct sensor_t * sensor
Definition: sensors.h:949
int(* set_operation_mode)(unsigned int mode)
Definition: sensors.h:1169
int handle
Definition: sensors.h:1192
int(* close)(struct hw_device_t *device)
Definition: hardware.h:200
int type
Definition: sensors.h:1195
int(* inject_sensor_data)(struct sensors_poll_device_1 *dev, const sensors_event_t *data)
Definition: sensors.h:1374
float temperature
Definition: sensors.h:1086
uint32_t flags
Definition: sensors.h:1273
float maxRange
Definition: sensors.h:1198
int32_t what
Definition: sensors.h:938
float distance
Definition: sensors.h:1089
void(* reserved_procs[7])(void)
Definition: sensors.h:1376
struct dynamic_sensor_meta_event dynamic_sensor_meta_event_t
int8_t status
Definition: sensors.h:908
union sensors_event_t::@77::@81 u64
int(* poll)(struct sensors_poll_device_t *dev, sensors_event_t *data, int count)
Definition: sensors.h:1333
void * reserved[2]
Definition: sensors.h:1277
int(* setDelay)(struct sensors_poll_device_t *dev, int sensor_handle, int64_t sampling_period_ns)
Definition: sensors.h:1327
struct hw_module_t common
Definition: sensors.h:1150
int32_t version
Definition: sensors.h:1055
struct hw_device_t common
Definition: sensors.h:1309
heart_rate_event_t heart_rate
Definition: sensors.h:1107
float data[16]
Definition: sensors.h:1071
uint32_t fifoMaxEventCount
Definition: sensors.h:1226
int32_t maxDelay
Definition: sensors.h:1263
const char * name
Definition: sensors.h:1177
uncalibrated_event_t uncalibrated_gyro
Definition: sensors.h:1101
sensors_vec_t orientation
Definition: sensors.h:1080
float power
Definition: sensors.h:1204
int32_t reserved0
Definition: sensors.h:1064
sensors_vec_t acceleration
Definition: sensors.h:1074
sensors_vec_t gyro
Definition: sensors.h:1083
float resolution
Definition: sensors.h:1201
uncalibrated_event_t uncalibrated_magnetic
Definition: sensors.h:1104
int64_t timestamp
Definition: sensors.h:1067
struct meta_data_event meta_data_event_t
int(* poll)(struct sensors_poll_device_t *dev, sensors_event_t *data, int count)
Definition: sensors.h:1294
struct sensors_poll_device_t v0
Definition: sensors.h:1306
int32_t type
Definition: sensors.h:1061
int version
Definition: sensors.h:1187
#define DYNAMIC_SENSOR_MASK
Definition: sensors.h:140
enum additional_info_type additional_info_type_t
float roll
Definition: sensors.h:905
meta_data_event_t meta_data
Definition: sensors.h:1113
int32_t sensor
Definition: sensors.h:1058
dynamic_sensor_meta_event_t dynamic_sensor_meta
Definition: sensors.h:1116
float pressure
Definition: sensors.h:1095
int(* flush)(struct sensors_poll_device_1 *dev, int sensor_handle)
Definition: sensors.h:1365
int32_t minDelay
Definition: sensors.h:1213
uint32_t reserved1[3]
Definition: sensors.h:1136
#define SENSORS_HARDWARE_POLL
Definition: sensors.h:54
struct hw_module_methods_t * methods
Definition: hardware.h:142
const char * vendor
Definition: sensors.h:1180
const char * stringType
Definition: sensors.h:1236
float pitch
Definition: sensors.h:904
int(* activate)(struct sensors_poll_device_t *dev, int sensor_handle, int enabled)
Definition: sensors.h:1290
sensors_vec_t magnetic
Definition: sensors.h:1077
float relative_humidity
Definition: sensors.h:1098
struct sensors_event_t sensors_event_t
uint64_t step_counter
Definition: sensors.h:1129
#define ADDITIONAL_INFO_MASK
Definition: sensors.h:146
struct hw_device_t common
Definition: sensors.h:1289
#define DATA_INJECTION_MASK
Definition: sensors.h:134
const char * requiredPermission
Definition: sensors.h:1245
int(* get_sensors_list)(struct sensors_module_t *module, struct sensor_t const **list)
Definition: sensors.h:1156
int(* activate)(struct sensors_poll_device_t *dev, int sensor_handle, int enabled)
Definition: sensors.h:1318
uint32_t fifoReservedEventCount
Definition: sensors.h:1220