1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
page.title=Base sensors and trigger modes
@jd:body
<!--
Copyright 2013 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol id="auto-toc">
</ol>
</div>
</div>
<h2 id="triggers">Trigger modes</h2>
<p>Sensors can report events in different ways called trigger modes; each sensor
type has one and only one trigger mode associated to it. Four trigger modes
exist:</p>
<h3 id="continuous">Continuous</h3>
<p>Events are reported at a constant rate defined by setDelay(). Example sensors
using the continuous trigger mode are accelerometers and gyroscopes.</p>
<h3 id="on-change">On-change</h3>
<p>Events are reported only if the sensor's value has changed. Activating the
sensor also triggers an event, meaning the HAL must return an event immediately
when an on-change sensor is activated. Example sensors using the on-change
trigger mode are the step counter and proximity sensor types.</p>
<p>Here is how the <code>period_ns</code> parameter affects setDelay(...) and
batch(...). The <code>period_ns</code> parameter is used to set a lower limit
to the reporting period, meaning the minimum time between consecutive events.
Here is an example: If activating the step counter with period_ns = 10 seconds,
walking for 1 minute, and then not walking for 1 minute, the events will
be generated every 10 seconds during the first minute, and no event will be
generated in the second minute.</p>
<h3 id="one-shot">One-shot</h3>
<p>Upon detection of an event, the sensor deactivates itself and then sends a
single event. Order matters to avoid race conditions. No other event is sent
until the sensor is reactivated. setDelay() is ignored.
<a
href="{@docRoot}devices/sensors/composite_sensors.html#Significant">Significant
motion</a> is an example of this kind of sensor.</p>
<h3 id="special">Special</h3>
<p>See the individual sensor type descriptions for details.</p>
<h2 id="categories">Categories</h2>
<p>Sensors fall into four primary categories:</p>
<blockquote>
<p><em>Base</em> - records core measurements from which all other sensors are derived <br/>
<em>Activity</em> - detects user or device movement<br/>
<em>Attitude</em> - measures the orientation of the device<br/>
<em>Uncalibrated</em> - is identical to the corresponding base sensor except the
dynamic calibration is reported separately rather than applied to the results</p>
</blockquote>
<h2 id="base">Base sensors</h2>
<p>These sensor types are listed first because they are the fundamental sensors
upon which all other sensor types are based.</p>
<h3 id="Accelerometer">Accelerometer</h3>
<p><em>Trigger-mode: Continuous<br/>
Wake-up sensor: No</em></p>
<p>All values are in SI units (m/s^2) and measure the acceleration of the device
minus the force of gravity.</p>
<p>Acceleration sensors return sensor events for all three axes at a constant rate
defined by setDelay().</p>
<ul>
<li>x: Acceleration on the x-axis</li>
<li>y: Acceleration on the y-axis</li>
<li>z: Acceleration on the z-axis</li>
</ul>
<p>Note the readings from the accelerometer include the acceleration due to gravity
(which is opposite the direction of the gravity vector).</p>
<p>Here are examples:</p>
<ul>
<li>The norm of (x, y, z) should be close to 0 when in free fall.</li>
<li>When the device lies flat on a table and is pushed on its left side toward the
right, the x acceleration value is positive.</li>
<li>When the device lies flat on a table, the acceleration value is +9.81, which
corresponds to the acceleration of the device (0 m/s^2) minus the force of
gravity (-9.81 m/s^2).</li>
<li>When the device lies flat on a table and is pushed toward the sky, the
acceleration value is greater than +9.81, which corresponds to the
acceleration of the device (+A m/s^2) minus the force of gravity (-9.81
m/s^2).</li>
</ul>
<h3 id="Ambient">Ambient temperature</h3>
<p><em>Trigger-mode: On-change<br/>
Wake-up sensor: No</em></p>
<p>This sensor provides the ambient (room) temperature in degrees Celsius.</p>
<h3 id="Geomagnetic">Geomagnetic field</h3>
<p><em>Trigger-mode: Continuous<br/>
Wake-up sensor: No</em></p>
<p>All values are in micro-Tesla (uT) and measure the geomagnetic field in the X, Y
and Z axis.</p>
<p>Returned values include calibration mechanisms so the vector is aligned with the
magnetic declination and heading of the earth's geomagnetic field.</p>
<p>Magnetic field sensors return sensor events for all three axes at a constant
rate defined by setDelay().</p>
<h3 id="Gyroscope">Gyroscope</h3>
<p><em>Trigger-mode: Continuous<br/>
Wake-up sensor: No</em></p>
<p>All values are in radians/second and measure the rate of rotation around the X,
Y and Z axis. The coordinate system is the same as is used for the acceleration
sensor. Rotation is positive in the counter-clockwise direction (right-hand
rule).</p>
<p>That is, an observer looking from some positive location on the x, y or z axis
at a device positioned on the origin would report positive rotation if the
device appeared to be rotating counter clockwise. Note that this is the standard
mathematical definition of positive rotation and does not agree with the
definition of roll given elsewhere.</p>
<p>The range should at least be 17.45 rad/s (ie: ~1000 deg/s).</p>
<p>Automatic gyro-drift compensation is required.</p>
<h3 id="Light">Light</h3>
<p><em>Trigger-mode: On-change<br/>
Wake-up sensor: No</em></p>
<p>The light sensor value is returned in SI lux units.</p>
<h3 id="Proximity">Proximity</h3>
<p><em>Trigger-mode: On-change<br/>
Wake-up sensor: Yes</em></p>
<p>Measures the distance from the sensor to the closest visible surface. As this is
a wake-up sensor, it should wake up the SoC when it is running and detects a
change in proximity. The distance value is measured in centimeters. Note that
some proximity sensors only support a binary "near" or "far" measurement. In
this case, the sensor should report its maxRange value in the "far" state and a
value less than maxRange in the "near" state.</p>
<p>To ensure the applications have the time to receive the event before the
application processor goes back to sleep, the driver must hold a "timeout wake
lock" for 200 milliseconds for every wake-up sensor. That is, the application
processor should not be allowed to go back to sleep in the 200 milliseconds
following a wake-up interrupt.</p>
<h3 id="Pressure">Pressure</h3>
<p><em>Trigger-mode: Continuous<br/>
Wake-up sensor: No</em></p>
<p>The pressure sensor uses a barometer to return the atmospheric pressure in
hectopascal (hPa).</p>
<h3 id="humidity">Relative humidity</h3>
<p><em>Trigger-mode: On-change<br/>
Wake-up sensor: No</em></p>
<p>A relative humidity sensor measures relative ambient air humidity and returns a
value in percent.</p>
|
