1 page.title=Sensor types 2 @jd:body 3 4 <!-- 5 Copyright 2014 The Android Open Source Project 6 7 Licensed under the Apache License, Version 2.0 (the "License"); 8 you may not use this file except in compliance with the License. 9 You may obtain a copy of the License at 10 11 http://www.apache.org/licenses/LICENSE-2.0 12 13 Unless required by applicable law or agreed to in writing, software 14 distributed under the License is distributed on an "AS IS" BASIS, 15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 See the License for the specific language governing permissions and 17 limitations under the License. 18 --> 19 <div id="qv-wrapper"> 20 <div id="qv"> 21 <h2>In this document</h2> 22 <ol id="auto-toc"> 23 </ol> 24 </div> 25 </div> 26 27 <h2 id="sensor_axis_definition">Sensor axis definition</h2> 28 <p>Sensor event values from many sensors are expressed in a specific frame that is 29 static relative to the phone. This API is relative only to the NATURAL 30 orientation of the screen. In other words, the axes are not swapped when the 31 device's screen orientation changes.</p> 32 33 <div class="figure" style="width:269px"> 34 <img src="http://developer.android.com/images/axis_device.png" 35 alt="Coordinate system of sensor API" height="225" /> 36 <p class="img-caption"> 37 <strong>Figure 1.</strong> Coordinate system (relative to a device) that's 38 used by the Sensor API. 39 </p> 40 </div> 41 42 <h2 id="base_sensors">Base sensors</h2> 43 <p>Some sensor types are named directly after the physical sensors they represent. 44 Sensors with such types are called base sensors, referring to the fact they 45 relay data from a single physical sensor, contrary to composite sensors, for 46 which the data is generated out of other sensors.</p> 47 <p>Examples of base sensor types:</p> 48 <ul> 49 <li><code>SENSOR_TYPE_ACCELEROMETER</code></li> 50 <li><code>SENSOR_TYPE_GYROSCOPE</code></li> 51 <li><code>SENSOR_TYPE_MAGNETOMETER</code></li> 52 </ul> 53 <p> See the list of Android sensor types below for more details on each 54 <h3 id="base_sensors_=_not_equal_to_physical_sensors">Base sensors != (not equal to) physical sensors</h3> 55 <p>Base sensors are not to be confused with their underlying physical sensor. The 56 data from a base sensor is not the raw output of the physical sensor: 57 corrections are be applied, such as bias compensation and temperature 58 compensation.</p> 59 <p>The characteristics of a base sensor might be different from the 60 characteristics of its underlying physical sensor.</p> 61 <ul> 62 <li> For example, a gyroscope chip might be rated to have a bias range of 1 deg/sec. 63 <ul> 64 <li> After factory calibration, temperature compensation and bias compensation are 65 applied, the actual bias of the Android sensor will be reduced, may be to a 66 point where the bias is guaranteed to be below 0.01deg/sec. </li> 67 <li> In this situation, we say that the Android sensor has a bias below 0.01 68 deg/sec, even though the data sheet of the underlying sensor said 1 deg/sec. </li> 69 </ul> 70 </li> 71 <li> As another example, a barometer might have a power consumption of 100uW. 72 <ul> 73 <li> Because the generated data needs to be transported from the chip to the SoC, 74 the actual power cost to gather data from the barometer Android sensor might be 75 much higher, for example 1000uW. </li> 76 <li> In this situation, we say that the Android sensor has a power consumption of 77 1000uW, even though the power consumption measured at the barometer chip leads 78 is 100uW. </li> 79 </ul> 80 </li> 81 <li> As a third example, a magnetometer might consume 100uW when calibrated, but 82 consume more when calibrating. 83 <ul> 84 <li> Its calibration routine might require activating the gyroscope, consuming 85 5000uW, and running some algorithm, costing another 900uW. </li> 86 <li> In this situation, we say that the maximum power consumption of the 87 (magnetometer) Android sensor is 6000uW. </li> 88 <li> In this case, the average power consumption is the more useful measure, and it 89 is what is reported in the sensor static characteristics through the HAL. </li> 90 </ul> 91 </li> 92 </ul> 93 <h3 id="accelerometer">Accelerometer</h3> 94 <p>Reporting-mode: <em><a href="report-modes.html#continuous">Continuous</a></em></p> 95 <p><code>getDefaultSensor(SENSOR_TYPE_ACCELEROMETER)</code> <em>returns a non-wake-up sensor</em></p> 96 <p>An accelerometer sensor reports the acceleration of the device along the 3 97 sensor axes. The measured acceleration includes both the physical acceleration 98 (change of velocity) and the gravity. The measurement is reported in the x, y 99 and z fields of sensors_event_t.acceleration.</p> 100 <p>All values are in SI units (m/s^2) and measure the acceleration of the device 101 minus the force of gravity along the 3 sensor axes.</p> 102 <p>Here are examples:</p> 103 <ul> 104 <li> The norm of (x, y, z) should be close to 0 when in free fall. </li> 105 <li> When the device lies flat on a table and is pushed on its left side toward the 106 right, the x acceleration value is positive. </li> 107 <li> When the device lies flat on a table, the acceleration value along z is +9.81 108 alo, which corresponds to the acceleration of the device (0 m/s^2) minus the 109 force of gravity (-9.81 m/s^2). </li> 110 <li> When the device lies flat on a table and is pushed toward the sky, the 111 acceleration value is greater than +9.81, which corresponds to the acceleration 112 of the device (+A m/s^2) minus the force of gravity (-9.81 m/s^2). </li> 113 </ul> 114 <p>The readings are calibrated using:</p> 115 <ul> 116 <li> temperature compensation </li> 117 <li> online bias calibration </li> 118 <li> online scale calibration </li> 119 </ul> 120 <p>The bias and scale calibration must only be updated while the sensor is 121 deactivated, so as to avoid causing jumps in values during streaming.</p> 122 <p>The accelerometer also reports how accurate it expects its readings to be 123 through <code>sensors_event_t.acceleration.status</code>. See the <a 124 href="http://developer.android.com/reference/android/hardware/SensorManager.html">SensorManager</a>s 125 <a href="http://developer.android.com/reference/android/hardware/SensorManager.html#SENSOR_STATUS_ACCURACY_HIGH"><code>SENSOR_STATUS_* </code></a> constants for more information on possible values for this field.</p> 126 <h3 id="ambient_temperature">Ambient temperature</h3> 127 <p>Reporting-mode: <em><a href="report-modes.html#on-change">On-change</a></em></p> 128 <p><code>getDefaultSensor(SENSOR_TYPE_AMBIENT_TEMPERATURE)</code> <em>returns a non-wake-up sensor</em></p> 129 <p>This sensor provides the ambient (room) temperature in degrees Celsius.</p> 130 <h3 id="magnetic_field_sensor">Magnetic field sensor</h3> 131 <p>Reporting-mode: <em><a href="report-modes.html#continuous">Continuous</a></em></p> 132 <p><code>getDefaultSensor(SENSOR_TYPE_MAGNETIC_FIELD)</code> <em>returns a non-wake-up sensor</em></p> 133 <p><code>SENSOR_TYPE_GEOMAGNETIC_FIELD == SENSOR_TYPE_MAGNETIC_FIELD</code></p> 134 <p>A magnetic field sensor (also known as magnetometer) reports the ambient 135 magnetic field, as measured along the 3 sensor axes.</p> 136 <p>The measurement is reported in the x, y and z fields of 137 <code>sensors_event_t.magnetic</code> and all values are in micro-Tesla (uT).</p> 138 <p>The magnetometer also reports how accurate it expects its readings to be 139 through <code>sensors_event_t.magnetic.status</code>. See the <a 140 href="http://developer.android.com/reference/android/hardware/SensorManager.html">SensorManager</a>s 141 <a href="http://developer.android.com/reference/android/hardware/SensorManager.html#SENSOR_STATUS_ACCURACY_HIGH"><code>SENSOR_STATUS_*</code></a> constants for more information on possible values for this field.</p> 142 <p>The readings are calibrated using:</p> 143 <ul> 144 <li> temperature compensation </li> 145 <li> factory (or online) soft-iron calibration </li> 146 <li> online hard-iron calibration </li> 147 </ul> 148 <h3 id="gyroscope">Gyroscope</h3> 149 <p>Reporting-mode: <em><a href="report-modes.html#continuous">Continuous</a></em></p> 150 <p><code>getDefaultSensor(SENSOR_TYPE_GYROSCOPE)</code> <em>returns a non-wake-up sensor</em></p> 151 <p>A gyroscope sensor reports the rate of rotation of the device around the 3 152 sensor axes.</p> 153 <p>Rotation is positive in the counterclockwise direction (right-hand rule). That 154 is, an observer looking from some positive location on the x, y or z axis at a 155 device positioned on the origin would report positive rotation if the device 156 appeared to be rotating counter clockwise. Note that this is the standard 157 mathematical definition of positive rotation and does not agree with the 158 aerospace definition of roll.</p> 159 <p>The measurement is reported in the x, y and z fields of <code>sensors_event_t.gyro</code> 160 and all values are in radians per second (rad/s).</p> 161 <p>The readings are calibrated using:</p> 162 <ul> 163 <li> temperature compensation </li> 164 <li> factory (or online) scale compensation </li> 165 <li> online bias calibration (to remove drift) </li> 166 </ul> 167 <p>The gyroscope also reports how accurate it expects its readings to be through 168 <code>sensors_event_t.gyro.status</code>. See the <a 169 href="http://developer.android.com/reference/android/hardware/SensorManager.html">SensorManager</a>s 170 <a 171 href="http://developer.android.com/reference/android/hardware/SensorManager.html#SENSOR_STATUS_ACCURACY_HIGH"><code>SENSOR_STATUS_*</code></a> constants for more information on possible values for this field.</p> 172 <p>The gyroscope cannot be emulated based on magnetometers and accelerometers, as 173 this would cause it to have reduced local consistency and responsiveness. It 174 must be based on a usual gyroscope chip.</p> 175 <h3 id="heart_rate">Heart Rate</h3> 176 <p>Reporting-mode: <em><a href="report-modes.html#on-change">On-change</a></em></p> 177 <p><code>getDefaultSensor(SENSOR_TYPE_HEART_RATE)</code> <em>returns a non-wake-up sensor</em></p> 178 <p>A heart rate sensor reports the current heart rate of the person touching the 179 device.</p> 180 <p>The current heart rate in beats per minute (BPM) is reported in 181 <code>sensors_event_t.heart_rate.bpm</code> and the status of the sensor is reported in 182 <code>sensors_event_t.heart_rate.status</code>. See the <a 183 href="http://developer.android.com/reference/android/hardware/SensorManager.html">SensorManager</a>s 184 <a href="http://developer.android.com/reference/android/hardware/SensorManager.html#SENSOR_STATUS_ACCURACY_HIGH"><code>SENSOR_STATUS_*</code></a> constants for more information on possible values for this field. In 185 particular, upon the first activation, unless the device is known to not be on 186 the body, the status field of the first event must be set to 187 <code>SENSOR_STATUS_UNRELIABLE</code>. Because this sensor is on-change, 188 events are generated when and only when <code>heart_rate.bpm</code> or 189 <code>heart_rate.status</code> have changed since the last event. The events 190 are generated no faster than every <code>sampling_period</code>.</p> 191 <p><code>sensor_t.requiredPermission</code> is always <code>SENSOR_PERMISSION_BODY_SENSORS</code>.</p> 192 <h3 id="light">Light</h3> 193 <p>Reporting-mode: <em><a href="report-modes.html#on-change">On-change</a></em></p> 194 <p><code>getDefaultSensor(SENSOR_TYPE_LIGHT)</code> <em>returns a non-wake-up sensor</em></p> 195 <p>A light sensor reports the current illumination in SI lux units.</p> 196 <p>The measurement is reported in <code>sensors_event_t.light</code>.</p> 197 <h3 id="proximity">Proximity</h3> 198 <p>Reporting-mode: <em><a href="report-modes.html#on-change">On-change</a></em></p> 199 <p>Usually defined as a wake-up sensor</p> 200 <p><code>getDefaultSensor(SENSOR_TYPE_PROXIMITY)</code> <em>returns a wake-up sensor</em></p> 201 <p>A proximity sensor reports the distance from the sensor to the closest visible 202 surface.</p> 203 <p>Up to Android KitKat, the proximity sensors were always wake-up sensors, waking 204 up the SoC when detecting a change in proximity. After Android KitKat, we 205 advise to implement the wake-up version of this sensor first, as it is the one 206 that is used to turn the screen on and off while making phone calls.</p> 207 <p>The measurement is reported in centimeters in <code>sensors_event_t.distance</code>. Note 208 that some proximity sensors only support a binary "near" or "far" measurement. 209 In this case, the sensor report its <code>sensor_t.maxRange</code> value in the "far" state 210 and a value less than <code>sensor_t.maxRange</code> in the "near" state.</p> 211 <h3 id="pressure">Pressure</h3> 212 <p>Reporting-mode: <em><a href="report-modes.html#continuous">Continuous</a></em></p> 213 <p><code>getDefaultSensor(SENSOR_TYPE_PRESSURE)</code> <em>returns a non-wake-up sensor</em></p> 214 <p>A pressure sensor (also known as barometer) reports the atmospheric pressure in 215 hectopascal (hPa).</p> 216 <p>The readings are calibrated using</p> 217 <ul> 218 <li> temperature compensation </li> 219 <li> factory bias calibration </li> 220 <li> factory scale calibration </li> 221 </ul> 222 <p>The barometer is often used to estimate elevation changes. To estimate absolute 223 elevation, the sea-level pressure (changing depending on the weather) must be 224 used as a reference.</p> 225 <h3 id="relative_humidity">Relative humidity</h3> 226 <p>Reporting-mode: <em><a href="report-modes.html#on-change">On-change</a></em></p> 227 <p><code>getDefaultSensor(SENSOR_TYPE_RELATIVE_HUMIDITY)</code> <em>returns a non-wake-up sensor</em></p> 228 <p>A relative humidity sensor measures relative ambient air humidity and returns a 229 value in percent.</p> 230 <h2 id="composite_sensor_types">Composite sensor types</h2> 231 <p>Any sensor that is not a base sensor is called a composite sensor. Composite 232 sensors generate their data by processing and/or fusing data from one or 233 several physical sensors.</p> 234 <p>Examples of composite sensor types:</p> 235 <ul> 236 <li><a href="#step_detector">Step detector</a> and <a href="#significant_motion">Significant motion</a>, which are usually based on an accelerometer, but could be based on other 237 sensors as well, if the power consumption and accuracy was acceptable. </li> 238 <li><a href="#game_rotation_vector">Game rotation vector</a>, based on an 239 accelerometer and a gyroscope. </li> 240 <li><a href="#gyroscope_uncalibrated">Uncalibrated gyroscope</a>, which is 241 similar to the gyroscope base sensor, but with 242 the bias calibration being reported separately instead of being corrected in 243 the measurement. </li> 244 </ul> 245 <p>Just like base sensors, the characteristics of the composite sensors come from 246 the characteristics of their final data.</p> 247 <ul> 248 <li> For example, the power consumption of a game rotation vector is probably equal 249 to the sum of the power consumptions of: the accelerometer chip, the gyroscope 250 chip, the chip processing the data, and the busses transporting the data. </li> 251 <li> As another example, the drift of a game rotation vector will depend as much on 252 the quality of the calibration algorithm as on the physical sensor 253 characteristics. </li> 254 </ul> 255 <h2 id="composite_sensor_type_summary">Composite sensor type summary</h2> 256 <p>The following table lists the composite sensor types. Each composite sensor 257 relies on data from one or several physical sensors. Choosing other underlying 258 physical sensors to approximate results should be avoided as they will provide 259 a poor user experience.</p> 260 <p>When there is no gyroscope on the device, and only when there is no gyroscope, 261 you may implement the rotation vector, linear acceleration and gravity sensors 262 without using the gyroscope.</p> 263 <table> 264 <tr> 265 <th><p>Sensor type</p></th> 266 <th><p>Category</p></th> 267 <th><p>Underlying physical sensors</p></th> 268 <th><p>Reporting mode</p></th> 269 </tr> 270 <tr> 271 <td><p><a href="#game_rotation_vector">Game rotation vector</a></p></td> 272 <td><p>Attitude</p></td> 273 <td><p>Accelerometer, Gyroscope MUST NOT USE Magnetometer</p></td> 274 <td><p>Continuous</p></td> 275 </tr> 276 <tr> 277 <td><p><a href="#geomagnetic_rotation_vector">Geomagnetic rotation 278 vector</a> <img src="images/battery_icon.png" width="20" height="20" alt="Low 279 power sensor" /></p></td> 280 <td><p>Attitude</p></td> 281 <td><p>Accelerometer, Magnetometer, MUST NOT USE Gyroscope</p></td> 282 <td><p>Continuous</p></td> 283 </tr> 284 <tr> 285 <td><a href="#glance_gesture">Glance gesture</a> <img 286 src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" 287 /></p></td> 288 <td><p>Interaction</p></td> 289 <td><p>Undefined</p></td> 290 <td><p>One-shot</p></td> 291 </tr> 292 <tr> 293 <td><p><a href="#gravity">Gravity</a></p></td> 294 <td><p>Attitude</p></td> 295 <td><p>Accelerometer, Gyroscope</p></td> 296 <td><p>Continuous</p></td> 297 </tr> 298 <tr> 299 <td><p><a href="#gyroscope_uncalibrated">Gyroscope uncalibrated</a></p></td> 300 <td><p>Uncalibrated</p></td> 301 <td><p>Gyroscope</p></td> 302 <td><p>Continuous</p></td> 303 </tr> 304 <tr> 305 <td><p><a href="#linear_acceleration">Linear acceleration</a></p></td> 306 <td><p>Activity</p></td> 307 <td><p>Accelerometer, Gyroscope (if present) or Magnetometer (if gyro not present)</p></td> 308 <td><p>Continuous</p></td> 309 </tr> 310 <tr> 311 <td><p><a href="#magnetic_field_uncalibrated">Magnetic field uncalibrated</a></p></td> 312 <td><p>Uncalibrated</p></td> 313 <td><p>Magnetometer</p></td> 314 <td><p>Continuous</p></td> 315 </tr> 316 <tr> 317 <td><p><a href="#orientation_deprecated">Orientation</a> (deprecated)</p></td> 318 <td><p>Attitude</p></td> 319 <td><p>Accelerometer, Magnetometer PREFERRED Gyroscope</p></td> 320 <td><p>Continuous</p></td> 321 </tr> 322 <tr> 323 <td><p><a href="#pick_up_gesture">Pick up gesture</a> <img 324 src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" 325 /></p></td> 326 <td><p>Interaction</p></td> 327 <td><p>Undefined</p></td> 328 <td><p>One-shot</p></td> 329 </tr> 330 <tr> 331 <td><p><a href="#rotation_vector">Rotation vector</a></p></td> 332 <td><p>Attitude</p></td> 333 <td><p>Accelerometer, Magnetometer, AND (when present) <em>Gyroscope </em></p></td> 334 <td><p>Continuous</p></td> 335 </tr> 336 <tr> 337 <td><p><a href="#significant_motion">Significant motion</a> <img 338 src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" 339 /></p></td> 340 <td><p>Activity</p></td> 341 <td><p>Accelerometer (or another as long as very low power)</p></td> 342 <td><p>One-shot</p></td> 343 </tr> 344 <tr> 345 <td><p><a href="#step_counter">Step counter</a> <img 346 src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" 347 /></p></td> 348 <td><p>Activity</p></td> 349 <td><p>Accelerometer</p></td> 350 <td><p>On-change</p></td> 351 </tr> 352 <tr> 353 <td><p><a href="#step_detector">Step detector</a> <img 354 src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" 355 /></p></td> <td><p>Activity</p></td> 356 <td><p>Accelerometer</p></td> 357 <td><p>Special</p></td> 358 </tr> 359 <tr> 360 <td><p><a href="#tilt_detector">Tilt detector</a> <img 361 src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" 362 /></p></td> 363 <td><p>Activity</p></td> 364 <td><p>Accelerometer</p></td> 365 <td><p>Special</p></td> 366 </tr> 367 <tr> 368 <td><p><a href="#wake_up_gesture">Wake up gesture</a> <img 369 src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" 370 /></p></td> 371 <td><p>Interaction</p></td> 372 <td><p>Undefined</p></td> 373 <td><p>One-shot</p></td> 374 </tr> 375 </table> 376 <p><img src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" /> = Low power sensor</p> 377 <h2 id="activity_composite_sensors">Activity composite sensors</h2> 378 <h3 id="linear_acceleration">Linear acceleration</h3> 379 <p>Underlying physical sensors: Accelerometer and (if present) Gyroscope (or 380 magnetometer if gyroscope not present)</p> 381 <p>Reporting-mode: <em><a href="report-modes.html#continuous">Continuous</a></em></p> 382 <p><code>getDefaultSensor(SENSOR_TYPE_LINEAR_ACCELERATION)</code> <em>returns a non-wake-up sensor</em></p> 383 <p>A linear acceleration sensor reports the linear acceleration of the device in 384 the sensor frame, not including gravity.</p> 385 <p>The output is conceptually: output of the <a 386 href="#accelerometer">accelerometer</a> minus the output of the <a 387 href="#gravity">gravity sensor</a>. It is reported in m/s^2 in the x, y and z 388 fields of <code>sensors_event_t.acceleration</code>.</p> 389 <p>Readings on all axes should be close to 0 when the device is immobile.</p> 390 <p>If the device possesses a gyroscope, the linear acceleration sensor must use 391 the accelerometer gyroscope and accelerometer as input.</p> 392 <p>If the device doesnt possess a gyroscope, the linear acceleration sensor must 393 use the accelerometer and the magnetometer as input.</p> 394 <h3 id="significant_motion">Significant motion</h3> 395 <p>Underlying physical sensor: Accelerometer (or another as long as low power)</p> 396 <p>Reporting-mode: <em><a href="report-modes.html#one-shot">One-shot</a></em></p> 397 <p>Low-power</p> 398 <p>Implement only the wake-up version of this sensor.</p> 399 <p><code>getDefaultSensor(SENSOR_TYPE_SIGNIFICANT_MOTION)</code> <em>returns a non-wake-up sensor</em></p> 400 <p>A significant motion detector triggers when the detecting a significant 401 motion: a motion that might lead to a change in the user location.</p> 402 <p>Examples of such significant motions are:</p> 403 <ul> 404 <li> walking or biking </li> 405 <li> sitting in a moving car, coach or train </li> 406 </ul> 407 <p>Examples of situations that do not trigger significant motion:</p> 408 <ul> 409 <li> phone in pocket and person is not moving </li> 410 <li> phone is on a table and the table shakes a bit due to nearby traffic or washing 411 machine </li> 412 </ul> 413 <p>At the high level, the significant motion detector is used to reduce the power 414 consumption of location determination. When the localization algorithms detect 415 that the device is static, they can switch to a low power mode, where they rely 416 on significant motion to wake the device up when the user is changing location.</p> 417 <p>This sensor must be low power. It makes a tradeoff for power consumption that 418 may result in a small amount of false negatives. This is done for a few 419 reasons:</p> 420 <ul> 421 <li> The goal of this sensor is to save power. </li> 422 <li> Triggering an event when the user is not moving (false positive) is costly in 423 terms of power, so it should be avoided. </li> 424 <li> Not triggering an event when the user is moving (false negative) is acceptable 425 as long as it is not done repeatedly. If the user has been walking for 10 426 seconds, not triggering an event within those 10 seconds is not acceptable. </li> 427 </ul> 428 <p>Each sensor event reports 1 in <code>sensors_event_t.data[0]</code></p> 429 <h3 id="step_detector">Step detector</h3> 430 <p>Underlying physical sensor: Accelerometer (+ possibly others as long as low 431 power)</p> 432 <p>Reporting-mode: <em><a href="report-modes.html#special">Special</a> (one event per step taken)</em></p> 433 <p>Low-power</p> 434 <p><code>getDefaultSensor(SENSOR_TYPE_STEP_DETECTOR)</code> <em>returns a non-wake-up sensor</em></p> 435 <p>A step detector generates an event each time a step is taken by the user.</p> 436 <p>The timestamp of the event <code>sensors_event_t.timestamp</code> corresponds to when the 437 foot hit the ground, generating a high variation in acceleration.</p> 438 <p>Compared to the step counter, the step detector should have a lower latency 439 (less than 2 seconds). Both the step detector and the step counter detect when 440 the user is walking, running and walking up the stairs. They should not trigger 441 when the user is biking, driving or in other vehicles.</p> 442 <p>This sensor must be low power. That is, if the step detection cannot be done in 443 hardware, this sensor should not be defined. In particular, when the step 444 detector is activated and the accelerometer is not, only steps should trigger 445 interrupts (not every accelerometer reading).</p> 446 <p><code>sampling_period_ns</code> has no impact on step detectors.</p> 447 <p>Each sensor event reports 1 in <code>sensors_event_t.data[0]</code></p> 448 <h3 id="step_counter">Step counter</h3> 449 <p>Underlying physical sensor: Accelerometer (+ possibly others as long as low 450 power)</p> 451 <p>Reporting-mode: <em><a href="report-modes.html#on-change">On-change</a></em></p> 452 <p>Low-power</p> 453 <p><code>getDefaultSensor(SENSOR_TYPE_STEP_COUNTER)</code> <em>returns a non-wake-up sensor</em></p> 454 <p>A step counter reports the number of steps taken by the user since the last 455 reboot while activated.</p> 456 <p>The measurement is reported as a <code>uint64_t</code> in 457 <code>sensors_event_t.step_counter</code> and 458 is reset to zero only on a system reboot.</p> 459 <p>The timestamp of the event is set to the time when the last step for that event 460 was taken.</p> 461 <p>See the <a href="#step_detector">Step detector</a> sensor type for the signification of the time of a step.</p> 462 <p>Compared to the step detector, the step counter can have a higher latency (up 463 to 10 seconds). Thanks to this latency, this sensor has a high accuracy; the 464 step count after a full day of measures should be within 10% of the actual step 465 count. Both the step detector and the step counter detect when the user is 466 walking, running and walking up the stairs. They should not trigger when the 467 user is biking, driving or in other vehicles.</p> 468 <p>The hardware must ensure the internal step count never overflows. The minimum 469 size of the hardware's internal counter shall be 16 bits. In case of imminent 470 overflow (at most every ~2^16 steps), the SoC can be woken up so the driver can 471 do the counter maintenance.</p> 472 <p>As stated in <a href="interaction.html">Interaction</a>, while this sensor 473 operates, it shall not disrupt any other sensors, in particular, the 474 accelerometer, which might very well be in use.</p> 475 <p>If a particular device cannot support these modes of operation, then this 476 sensor type must not be reported by the HAL. ie: it is not acceptable to 477 "emulate" this sensor in the HAL.</p> 478 <p>This sensor must be low power. That is, if the step detection cannot be done in 479 hardware, this sensor should not be defined. In particular, when the step 480 counter is activated and the accelerometer is not, only steps should trigger 481 interrupts (not accelerometer data).</p> 482 <h3 id="tilt_detector">Tilt detector</h3> 483 <p>Underlying physical sensor: Accelerometer (+ possibly others as long as low 484 power)</p> 485 <p>Reporting-mode: <em><a href="report-modes.html#special">Special</a></em></p> 486 <p>Low-power</p> 487 <p>Implement only the wake-up version of this sensor.</p> 488 <p><code>getDefaultSensor(SENSOR_TYPE_TILT_DETECTOR)</code> <em>returns a wake-up sensor</em></p> 489 <p>A tilt detector generates an event each time a tilt event is detected.</p> 490 <p>A tilt event is defined by the direction of the 2-seconds window average 491 gravity changing by at least 35 degrees since the activation or the last event 492 generated by the sensor. Here is the algorithm:</p> 493 <ul> 494 <li> <code>reference_estimated_gravity</code> = average of accelerometer measurements over the 495 first second after activation or the estimated gravity when the last tilt event 496 was generated. </li> 497 <li> <code>current_estimated_gravity</code> = average of accelerometer measurements over the last 498 2 seconds. </li> 499 <li> trigger when <code>angle(reference_estimated_gravity, current_estimated_gravity) > 35 500 degrees</code> </li> 501 </ul> 502 <p>Large accelerations without a change in phone orientation should not trigger a 503 tilt event. For example, a sharp turn or strong acceleration while driving a 504 car should not trigger a tilt event, even though the angle of the average 505 acceleration might vary by more than 35 degrees. 506 Typically, this sensor is 507 implemented with the help of only an accelerometer. Other sensors can be used 508 as well if they do not increase the power consumption significantly. This is a 509 low power sensor that should allow the SoC to go into suspend mode. Do not 510 emulate this sensor in the HAL. Each sensor event reports 1 in 511 <code>sensors_event_t.data[0]</code>.</p> 512 <h2 id="attitude_composite_sensors">Attitude composite sensors</h2> 513 <h3 id="rotation_vector">Rotation vector</h3> 514 <p>Underlying physical sensors: Accelerometer, Magnetometer, and (when present) 515 Gyroscope</p> 516 <p>Reporting-mode: <em><a href="report-modes.html#continuous">Continuous</a></em></p> 517 <p><code>getDefaultSensor(SENSOR_TYPE_ROTATION_VECTOR)</code> <em>returns a non-wake-up sensor</em></p> 518 <p>A rotation vector sensor reports the orientation of the device relative to the 519 East-North-Up coordinates frame. It is usually obtained by integration of 520 accelerometer, gyroscope and magnetometer readings.</p> 521 <p>The East-North-Up coordinate system is defined as a direct orthonormal basis 522 where:</p> 523 <ul> 524 <li> X points east and is tangential to the ground. </li> 525 <li> Y points north and is tangential to the ground. </li> 526 <li> Z points towards the sky and is perpendicular to the ground. </li> 527 </ul> 528 <p>The orientation of the phone is represented by the rotation necessary to align 529 the East-North-Up coordinates with the phone's coordinates. That is, applying 530 the rotation to the world frame (X,Y,Z) would align them with the phone 531 coordinates (x,y,z).</p> 532 <p>The rotation can be seen as rotating the phone by an angle theta around an axis 533 rot_axis to go from the reference (East-North-Up aligned) device orientation to 534 the current device orientation.</p> 535 <p>The rotation is encoded as the four unit-less x, y, z, w components of a unit 536 quaternion:</p> 537 <ul> 538 <li> <code>sensors_event_t.data[0] = rot_axis.x*sin(theta/2)</code> </li> 539 <li> <code>sensors_event_t.data[1] = rot_axis.y*sin(theta/2)</code> </li> 540 <li> <code>sensors_event_t.data[2] = rot_axis.z*sin(theta/2)</code> </li> 541 <li> <code>sensors_event_t.data[3] = cos(theta/2)</code> </li> 542 </ul> 543 <p>Where:</p> 544 <ul> 545 <li> the x, y and z fields of <code>rot_axis</code> are the East-North-Up 546 coordinates of a unit length vector representing the rotation axis </li> 547 <li> <code>theta</code> is the rotation angle </li> 548 </ul> 549 <p>The quaternion is a unit quaternion: it must be of norm 1. Failure to ensure 550 this will cause erratic client behaviour.</p> 551 <p>In addition, this sensor reports an estimated heading accuracy:</p> 552 <p><code>sensors_event_t.data[4] = estimated_accuracy</code> (in radians)</p> 553 <p>The heading error must be less than <code>estimated_accuracy</code> 95% of the time. This 554 sensor must use a gyroscope as main orientation change input unless there is no 555 gyroscope on the device.</p> 556 <p>This sensor also includes the accelerometer and magnetometer input to make up 557 for gyroscope drift, but it cannot be implemented using only the magnetometer 558 and accelerometer, unless there is no gyroscope on the device.</p> 559 <h3 id="game_rotation_vector">Game rotation vector</h3> 560 <p>Underlying physical sensors: Accelerometer and Gyroscope (no Magnetometer)</p> 561 <p>Reporting-mode: <em><a href="report-modes.html#continuous">Continuous</a></em></p> 562 <p><code>getDefaultSensor(SENSOR_TYPE_GAME_ROTATION_VECTOR)</code> <em>returns a non-wake-up sensor</em></p> 563 <p>A game rotation vector sensor is similar to a rotation vector sensor but not 564 using the geomagnetic field. Therefore the Y axis doesn't point north but 565 instead to some other reference. That reference is allowed to drift by the same 566 order of magnitude as the gyroscope drifts around the Z axis.</p> 567 <p>See the <a href="#rotation_vector">Rotation vector</a> sensor for details on 568 how to set <code>sensors_event_t.data[0-3]</code>. This sensor does 569 not report an estimated heading accuracy: 570 <code>sensors_event_t.data[4]</code> is reserved and should be set to 0.</p> 571 <p>In an ideal case, a phone rotated and returned to the same real-world 572 orientation should report the same game rotation vector.</p> 573 <p>This sensor must be based on a gyroscope and an accelerometer. It cannot use 574 magnetometer as an input, besides, indirectly, through estimation of the 575 gyroscope bias.</p> 576 <h3 id="gravity">Gravity</h3> 577 <p>Underlying physical sensors: Accelerometer and (if present) Gyroscope (or 578 magnetometer if gyroscope not present)</p> 579 <p>Reporting-mode: <em><a href="report-modes.html#continuous">Continuous</a></em></p> 580 <p><code>getDefaultSensor(SENSOR_TYPE_GRAVITY)</code> <em>returns a non-wake-up sensor</em></p> 581 <p>A gravity sensor reports the direction and magnitude of gravity in the device's 582 coordinates.</p> 583 <p>The gravity vector components are reported in m/s^2 in the x, y and z fields of 584 <code>sensors_event_t.acceleration</code>.</p> 585 <p>When the device is at rest, the output of the gravity sensor should be 586 identical to that of the accelerometer. On Earth, the magnitude is around 9.8 587 m/s^2.</p> 588 <p>If the device possesses a gyroscope, the gravity sensor must use the 589 accelerometer gyroscope and accelerometer as input.</p> 590 <p>If the device doesnt possess a gyroscope, the gravity sensor must use the 591 accelerometer and the magnetometer as input.</p> 592 <h3 id="geomagnetic_rotation_vector">Geomagnetic rotation vector</h3> 593 <p>Underlying physical sensors: Accelerometer and Magnetometer (no Gyroscope)</p> 594 <p>Reporting-mode: <em><a href="report-modes.html#continuous">Continuous</a></em></p> 595 <p>Low-power</p> 596 <p><code>getDefaultSensor(SENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR)</code> <em>returns a non-wake-up sensor</em></p> 597 <p>A geomagnetic rotation vector is similar to a rotation vector sensor but using 598 a magnetometer and no gyroscope.</p> 599 <p>This sensor must be based on a magnetometer. It cannot be implemented using a 600 gyroscope, and gyroscope input cannot be used by this sensor.</p> 601 <p>See the <a href="#rotation_vector">Rotation vector</a> sensor for details on 602 how to set <code>sensors_event_t.data[0-4]</code>.</p> 603 <p>Just like for the rotation vector sensor, the heading error must be less than 604 the estimated accuracy (<code>sensors_event_t.data[4]</code>) 95% of the time.</p> 605 <p>This sensor must be low power, so it has to be implemented in hardware.</p> 606 <h3 id="orientation_deprecated">Orientation (deprecated)</h3> 607 <p>Underlying physical sensors: Accelerometer, Magnetometer and (if present) 608 Gyroscope</p> 609 <p>Reporting-mode: <em><a href="report-modes.html#continuous">Continuous</a></em></p> 610 <p><code>getDefaultSensor(SENSOR_TYPE_ORIENTATION)</code> <em>returns a non-wake-up sensor</em></p> 611 <p>Note: This is an older sensor type that has been deprecated in the Android SDK. 612 It has been replaced by the rotation vector sensor, which is more clearly 613 defined. Use the rotation vector sensor over the orientation sensor whenever 614 possible.</p> 615 <p>An orientation sensor reports the attitude of the device. The measurements are 616 reported in degrees in the x, y and z fields of <code>sensors_event_t.orientation</code>:</p> 617 <ul> 618 <li> <code>sensors_event_t.orientation.x</code>: azimuth, the angle between the magnetic north 619 direction and the Y axis, around the Z axis (<code>0<=azimuth<360</code>). 0=North, 90=East, 620 180=South, 270=West </li> 621 <li> <code>sensors_event_t.orientation.y</code>: pitch, rotation around X axis 622 (<code>-180<=pitch<=180</code>), with positive values when the z-axis moves toward the 623 y-axis. </li> 624 <li> <code>sensors_event_t.orientation.z</code>: roll, rotation around Y axis (<code>-90<=roll<=90</code>), 625 with positive values when the x-axis moves towards the z-axis. </li> 626 </ul> 627 <p>Please note, for historical reasons the roll angle is positive in the clockwise 628 direction. (Mathematically speaking, it should be positive in the 629 counter-clockwise direction):</p> 630 <div class="figure" style="width:264px"> 631 <img src="images/axis_positive_roll.png" alt="Depiction of orientation 632 relative to a device" height="253" /> 633 <p class="img-caption"> 634 <strong>Figure 2.</strong> Orientation relative to a device. 635 </p> 636 </div> 637 <p>This definition is different from yaw, pitch and roll used in aviation where 638 the X axis is along the long side of the plane (tail to nose).</p> 639 <p>The orientation sensor also reports how accurate it expects its readings to be 640 through sensors_event_t.orientation.status. See the <a href="http://developer.android.com/reference/android/hardware/SensorManager.html">SensorManager</a>s <a href="http://developer.android.com/reference/android/hardware/SensorManager.html#SENSOR_STATUS_ACCURACY_HIGH">SENSOR_STATUS_</a>* constants for more information on possible values for this field.</p> 641 <h2 id="uncalibrated_sensors">Uncalibrated sensors</h2> 642 <p>Uncalibrated sensors provide more raw results and may include some bias but 643 also contain fewer "jumps" from corrections applied through calibration. Some 644 applications may prefer these uncalibrated results as smoother and more 645 reliable. For instance, if an application is attempting to conduct its own 646 sensor fusion, introducing calibrations can actually distort results.</p> 647 <h3 id="gyroscope_uncalibrated">Gyroscope uncalibrated</h3> 648 <p>Underlying physical sensor: Gyroscope</p> 649 <p>Reporting-mode: <em><a href="report-modes.html#continuous">Continuous</a></em></p> 650 <p><code>getDefaultSensor(SENSOR_TYPE_GYROSCOPE_UNCALIBRATED)</code> <em>returns a non-wake-up sensor</em></p> 651 <p>An uncalibrated gyroscope reports the rate of rotation around the sensor axes 652 without applying bias compensation to them, along with a bias estimate. All 653 values are in radians/second and are reported in the fields of 654 <code>sensors_event_t.uncalibrated_gyro</code>:</p> 655 <ul> 656 <li> <code>x_uncalib</code>: angular speed (w/o drift compensation) around the X axis </li> 657 <li> <code>y_uncalib</code>: angular speed (w/o drift compensation) around the Y axis </li> 658 <li> <code>z_uncalib</code>: angular speed (w/o drift compensation) around the Z axis </li> 659 <li> <code>x_bias</code>: estimated drift around X axis </li> 660 <li> <code>y_bias</code>: estimated drift around Y axis </li> 661 <li> <code>z_bias</code>: estimated drift around Z axis </li> 662 </ul> 663 <p>Conceptually, the uncalibrated measurement is the sum of the calibrated 664 measurement and the bias estimate: <code>_uncalibrated = _calibrated + _bias</code>.</p> 665 <p>The <code>x/y/z_bias</code> values are expected to jump as soon as the estimate of the bias 666 changes, and they should be stable the rest of the time.</p> 667 <p>See the definition of the <a href="#gyroscope">gyroscope</a> sensor for 668 details on the coordinate system used.</p> 669 <p>Factory calibration and temperature compensation must be applied to the 670 measurements. Also, gyroscope drift estimation must be implemented so that 671 reasonable estimates can be reported in <code>x_bias</code>, 672 <code>y_bias</code> and <code>z_bias</code>. If the 673 implementation is not able to estimate the drift, then this sensor must not be 674 implemented.</p> 675 <p>If this sensor is present, then the corresponding Gyroscope sensor must also be 676 present and both sensors must share the same <code>sensor_t.name</code> and 677 <code>sensor_t.vendor</code> values.</p> 678 <h3 id="magnetic_field_uncalibrated">Magnetic field uncalibrated</h3> 679 <p>Underlying physical sensor: Magnetometer</p> 680 <p>Reporting-mode: <em><a href="report-modes.html#continuous">Continuous</a></em></p> 681 <p><code>getDefaultSensor(SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED)</code> <em>returns a non-wake-up sensor</em></p> 682 <p>An uncalibrated magnetic field sensor reports the ambient magnetic field 683 together with a hard iron calibration estimate. All values are in micro-Tesla 684 (uT) and are reported in the fields of <code>sensors_event_t.uncalibrated_magnetic</code>:</p> 685 <ul> 686 <li> <code>x_uncalib</code>: magnetic field (w/o hard-iron compensation) along the X axis </li> 687 <li> <code>y_uncalib</code>: magnetic field (w/o hard-iron compensation) along the Y axis </li> 688 <li> <code>z_uncalib</code>: magnetic field (w/o hard-iron compensation) along the Z axis </li> 689 <li> <code>x_bias</code>: estimated hard-iron bias along the X axis </li> 690 <li> <code>y_bias</code>: estimated hard-iron bias along the Y axis </li> 691 <li> <code>z_bias</code>: estimated hard-iron bias along the Z axis </li> 692 </ul> 693 <p>Conceptually, the uncalibrated measurement is the sum of the calibrated 694 measurement and the bias estimate: <code>_uncalibrated = _calibrated + _bias</code>.</p> 695 <p>The uncalibrated magnetometer allows higher level algorithms to handle bad hard 696 iron estimation. The <code>x/y/z_bias</code> values are expected to jump as soon as the 697 estimate of the hard-iron changes, and they should be stable the rest of the 698 time.</p> 699 <p>Soft-iron calibration and temperature compensation must be applied to the 700 measurements. Also, hard-iron estimation must be implemented so that reasonable 701 estimates can be reported in <code>x_bias</code>, <code>y_bias</code> and 702 <code>z_bias</code>. If the implementation is not able to estimate the bias, 703 then this sensor must not be implemented.</p> 704 <p>If this sensor is present, then the corresponding magnetic field sensor must be 705 present and both sensors must share the same <code>sensor_t.name</code> and 706 <code>sensor_t.vendor</code> values.</p> 707 <h2 id="interaction_composite_sensors">Interaction composite sensors</h2> 708 <p>Some sensors are mostly used to detect interactions with the user. We do not 709 define how those sensors must be implemented, but they must be low power and it 710 is the responsibility of the device manufacturer to verify their quality in 711 terms of user experience.</p> 712 <h3 id="wake_up_gesture">Wake up gesture</h3> 713 <p>Underlying physical sensors: Undefined (anything low power)</p> 714 <p>Reporting-mode: <em><a href="report-modes.html#one-shot">One-shot</a></em></p> 715 <p>Low-power</p> 716 <p>Implement only the wake-up version of this sensor.</p> 717 <p><code>getDefaultSensor(SENSOR_TYPE_WAKE_GESTURE)</code> <em>returns a wake-up sensor</em></p> 718 <p>A wake up gesture sensor enables waking up the device based on a device 719 specific motion. When this sensor triggers, the device behaves as if the power 720 button was pressed, turning the screen on. This behavior (turning on the screen 721 when this sensor triggers) might be deactivated by the user in the device 722 settings. Changes in settings do not impact the behavior of the sensor: only 723 whether the framework turns the screen on when it triggers. 724 The actual gesture to be detected is not specified, and can be chosen by the 725 manufacturer of the device.</p> 726 <p>This sensor must be low power, as it is likely to be activated 24/7.</p> 727 <p>Each sensor event reports 1 in <code>sensors_event_t.data[0]</code>.</p> 728 <h3 id="pick_up_gesture">Pick up gesture</h3> 729 <p>Underlying physical sensors: Undefined (anything low power)</p> 730 <p>Reporting-mode: <em><a href="report-modes.html#one-shot">One-shot</a></em></p> 731 <p>Low-power</p> 732 <p>Implement only the wake-up version of this sensor.</p> 733 <p><code>getDefaultSensor(SENSOR_TYPE_PICK_UP_GESTURE)</code> <em>returns a wake-up sensor</em></p> 734 <p>A pick-up gesture sensor sensor triggers when the device is picked up 735 regardless of wherever is was before (desk, pocket, bag).</p> 736 <p>Each sensor event reports 1 in <code>sensors_event_t.data[0]</code>.</p> 737 <h3 id="glance_gesture">Glance gesture</h3> 738 <p>Underlying physical sensors: Undefined (anything low power)</p> 739 <p>Reporting-mode: <em><a href="report-modes.html#one-shot">One-shot</a></em></p> 740 <p>Low-power</p> 741 <p>Implement only the wake-up version of this sensor.</p> 742 <p><code>getDefaultSensor(SENSOR_TYPE_GLANCE_GESTURE)</code> <em>returns a wake-up sensor</em></p> 743 <p>A glance gesture sensor enables briefly turning the screen on to enable the 744 user to glance content on screen based on a specific motion. When this sensor 745 triggers, the device will turn the screen on momentarily to allow the user to 746 glance notifications or other content while the device remains locked in a 747 non-interactive state (dozing), then the screen will turn off again. This 748 behavior (briefly turning on the screen when this sensor triggers) might be 749 deactivated by the user in the device settings. Changes in settings do not 750 impact the behavior of the sensor: only whether the framework briefly turns the 751 screen on when it triggers. The actual gesture to be detected is not specified, 752 and can be chosen by the manufacturer of the device.</p> 753 <p>This sensor must be low power, as it is likely to be activated 24/7. 754 Each sensor event reports 1 in <code>sensors_event_t.data[0]</code>.</p> 755