Clay Murphy | d01c551 | 2014-09-18 18:28:04 -0700 | [diff] [blame^] | 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><img src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" /> |
| 278 | <p>i<a href="#geomagnetic_rotation_vector"Geomagnetic rotation vector</a></p></td> |
| 279 | <td><p>Attitude</p></td> |
| 280 | <td><p>Accelerometer, Magnetometer, MUST NOT USE Gyroscope</p></td> |
| 281 | <td><p>Continuous</p></td> |
| 282 | </tr> |
| 283 | <tr> |
| 284 | <td><img src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" /> |
| 285 | <p><a href="#glance_gesture">Glance gesture</a></p></td> |
| 286 | <td><p>Interaction</p></td> |
| 287 | <td><p>Undefined</p></td> |
| 288 | <td><p>One-shot</p></td> |
| 289 | </tr> |
| 290 | <tr> |
| 291 | <td><p><a href="#gravity">Gravity</a></p></td> |
| 292 | <td><p>Attitude</p></td> |
| 293 | <td><p>Accelerometer, Gyroscope</p></td> |
| 294 | <td><p>Continuous</p></td> |
| 295 | </tr> |
| 296 | <tr> |
| 297 | <td><p><a href="#gyroscope_uncalibrated">Gyroscope uncalibrated</a></p></td> |
| 298 | <td><p>Uncalibrated</p></td> |
| 299 | <td><p>Gyroscope</p></td> |
| 300 | <td><p>Continuous</p></td> |
| 301 | </tr> |
| 302 | <tr> |
| 303 | <td><p><a href="#linear_acceleration">Linear acceleration</a></p></td> |
| 304 | <td><p>Activity</p></td> |
| 305 | <td><p>Accelerometer, Gyroscope (if present) or Magnetometer (if gyro not present)</p></td> |
| 306 | <td><p>Continuous</p></td> |
| 307 | </tr> |
| 308 | <tr> |
| 309 | <td><p><a href="#magnetic_field_uncalibrated">Magnetic field uncalibrated</a></p></td> |
| 310 | <td><p>Uncalibrated</p></td> |
| 311 | <td><p>Magnetometer</p></td> |
| 312 | <td><p>Continuous</p></td> |
| 313 | </tr> |
| 314 | <tr> |
| 315 | <td><p><a href="#orientation_deprecated">Orientation</a> (deprecated)</p></td> |
| 316 | <td><p>Attitude</p></td> |
| 317 | <td><p>Accelerometer, Magnetometer PREFERRED Gyroscope</p></td> |
| 318 | <td><p>Continuous</p></td> |
| 319 | </tr> |
| 320 | <tr> |
| 321 | <td><img src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" /> |
| 322 | <p><a href="#pick_up_gesture">Pick up gesture</a></p></td> |
| 323 | <td><p>Interaction</p></td> |
| 324 | <td><p>Undefined</p></td> |
| 325 | <td><p>One-shot</p></td> |
| 326 | </tr> |
| 327 | <tr> |
| 328 | <td><p><a href="#rotation_vector">Rotation vector</a></p></td> |
| 329 | <td><p>Attitude</p></td> |
| 330 | <td><p>Accelerometer, Magnetometer, AND (when present) <em>Gyroscope </em></p></td> |
| 331 | <td><p>Continuous</p></td> |
| 332 | </tr> |
| 333 | <tr> |
| 334 | <td><img src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" /> |
| 335 | <p><a href="#significant_motion">Significant motion</a></p></td> |
| 336 | <td><p>Activity</p></td> |
| 337 | <td><p>Accelerometer (or another as long as very low power)</p></td> |
| 338 | <td><p>One-shot</p></td> |
| 339 | </tr> |
| 340 | <tr> |
| 341 | <td><img src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" /> |
| 342 | <p><a href="#step_counter">Step counter</a></p></td> |
| 343 | <td><p>Activity</p></td> |
| 344 | <td><p>Accelerometer</p></td> |
| 345 | <td><p>On-change</p></td> |
| 346 | </tr> |
| 347 | <tr> |
| 348 | <td><img src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" /> |
| 349 | <p><a href="#step_detector">Step detector</a></p></td> |
| 350 | <td><p>Activity</p></td> |
| 351 | <td><p>Accelerometer</p></td> |
| 352 | <td><p>Special</p></td> |
| 353 | </tr> |
| 354 | <tr> |
| 355 | <td><img src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" /> |
| 356 | <p><a href="#tilt_detector">Tilt detector</a></p></td> |
| 357 | <td><p>Activity</p></td> |
| 358 | <td><p>Accelerometer</p></td> |
| 359 | <td><p>Special</p></td> |
| 360 | </tr> |
| 361 | <tr> |
| 362 | <td><img src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" /> |
| 363 | <p><a href="#wake_up_gesture">Wake up gesture</a></p></td> |
| 364 | <td><p>Interaction</p></td> |
| 365 | <td><p>Undefined</p></td> |
| 366 | <td><p>One-shot</p></td> |
| 367 | </tr> |
| 368 | </table> |
| 369 | <img src="images/battery_icon.png" width="20" height="20" alt="Low power sensor" /> |
| 370 | <p> = Low power sensor</p> |
| 371 | <h2 id="activity_composite_sensors">Activity composite sensors</h2> |
| 372 | <h3 id="linear_acceleration">Linear acceleration</h3> |
| 373 | <p>Underlying physical sensors: Accelerometer and (if present) Gyroscope (or |
| 374 | magnetometer if gyroscope not present)</p> |
| 375 | <p>Reporting-mode: <em><a href="report-modes.html#continuous">Continuous</a></em></p> |
| 376 | <p><code>getDefaultSensor(SENSOR_TYPE_LINEAR_ACCELERATION)</code> <em>returns a non-wake-up sensor</em></p> |
| 377 | <p>A linear acceleration sensor reports the linear acceleration of the device in |
| 378 | the sensor frame, not including gravity.</p> |
| 379 | <p>The output is conceptually: output of the <a |
| 380 | href="#accelerometer">accelerometer</a> minus the output of the <a |
| 381 | href="#gravity">gravity sensor</a>. It is reported in m/s^2 in the x, y and z |
| 382 | fields of <code>sensors_event_t.acceleration</code>.</p> |
| 383 | <p>Readings on all axes should be close to 0 when the device is immobile.</p> |
| 384 | <p>If the device possesses a gyroscope, the linear acceleration sensor must use |
| 385 | the accelerometer gyroscope and accelerometer as input.</p> |
| 386 | <p>If the device doesn’t possess a gyroscope, the linear acceleration sensor must |
| 387 | use the accelerometer and the magnetometer as input.</p> |
| 388 | <h3 id="significant_motion">Significant motion</h3> |
| 389 | <p>Underlying physical sensor: Accelerometer (or another as long as low power)</p> |
| 390 | <p>Reporting-mode: <em><a href="report-modes.html#one-shot">One-shot</a></em></p> |
| 391 | <p>Low-power</p> |
| 392 | <p>Implement only the wake-up version of this sensor.</p> |
| 393 | <p><code>getDefaultSensor(SENSOR_TYPE_SIGNIFICANT_MOTION)</code> <em>returns a non-wake-up sensor</em></p> |
| 394 | <p>A significant motion detector triggers when the detecting a “significant |
| 395 | motion”: a motion that might lead to a change in the user location.</p> |
| 396 | <p>Examples of such significant motions are:</p> |
| 397 | <ul> |
| 398 | <li> walking or biking </li> |
| 399 | <li> sitting in a moving car, coach or train </li> |
| 400 | </ul> |
| 401 | <p>Examples of situations that do not trigger significant motion:</p> |
| 402 | <ul> |
| 403 | <li> phone in pocket and person is not moving </li> |
| 404 | <li> phone is on a table and the table shakes a bit due to nearby traffic or washing |
| 405 | machine </li> |
| 406 | </ul> |
| 407 | <p>At the high level, the significant motion detector is used to reduce the power |
| 408 | consumption of location determination. When the localization algorithms detect |
| 409 | that the device is static, they can switch to a low power mode, where they rely |
| 410 | on significant motion to wake the device up when the user is changing location.</p> |
| 411 | <p>This sensor must be low power. It makes a tradeoff for power consumption that |
| 412 | may result in a small amount of false negatives. This is done for a few |
| 413 | reasons:</p> |
| 414 | <ul> |
| 415 | <li> The goal of this sensor is to save power. </li> |
| 416 | <li> Triggering an event when the user is not moving (false positive) is costly in |
| 417 | terms of power, so it should be avoided. </li> |
| 418 | <li> Not triggering an event when the user is moving (false negative) is acceptable |
| 419 | as long as it is not done repeatedly. If the user has been walking for 10 |
| 420 | seconds, not triggering an event within those 10 seconds is not acceptable. </li> |
| 421 | </ul> |
| 422 | <p>Each sensor event reports 1 in <code>sensors_event_t.data[0]</code></p> |
| 423 | <h3 id="step_detector">Step detector</h3> |
| 424 | <p>Underlying physical sensor: Accelerometer (+ possibly others as long as low |
| 425 | power)</p> |
| 426 | <p>Reporting-mode: <em><a href="report-modes.html#special">Special</a> (one event per step taken)</em></p> |
| 427 | <p>Low-power</p> |
| 428 | <p><code>getDefaultSensor(SENSOR_TYPE_STEP_DETECTOR)</code> <em>returns a non-wake-up sensor</em></p> |
| 429 | <p>A step detector generates an event each time a step is taken by the user.</p> |
| 430 | <p>The timestamp of the event <code>sensors_event_t.timestamp</code> corresponds to when the |
| 431 | foot hit the ground, generating a high variation in acceleration.</p> |
| 432 | <p>Compared to the step counter, the step detector should have a lower latency |
| 433 | (less than 2 seconds). Both the step detector and the step counter detect when |
| 434 | the user is walking, running and walking up the stairs. They should not trigger |
| 435 | when the user is biking, driving or in other vehicles.</p> |
| 436 | <p>This sensor must be low power. That is, if the step detection cannot be done in |
| 437 | hardware, this sensor should not be defined. In particular, when the step |
| 438 | detector is activated and the accelerometer is not, only steps should trigger |
| 439 | interrupts (not every accelerometer reading).</p> |
| 440 | <p><code>sampling_period_ns</code> has no impact on step detectors.</p> |
| 441 | <p>Each sensor event reports 1 in <code>sensors_event_t.data[0]</code></p> |
| 442 | <h3 id="step_counter">Step counter</h3> |
| 443 | <p>Underlying physical sensor: Accelerometer (+ possibly others as long as low |
| 444 | power)</p> |
| 445 | <p>Reporting-mode: <em><a href="report-modes.html#on-change">On-change</a></em></p> |
| 446 | <p>Low-power</p> |
| 447 | <p><code>getDefaultSensor(SENSOR_TYPE_STEP_COUNTER)</code> <em>returns a non-wake-up sensor</em></p> |
| 448 | <p>A step counter reports the number of steps taken by the user since the last |
| 449 | reboot while activated.</p> |
| 450 | <p>The measurement is reported as a <code>uint64_t</code> in |
| 451 | <code>sensors_event_t.step_counter</code> and |
| 452 | is reset to zero only on a system reboot.</p> |
| 453 | <p>The timestamp of the event is set to the time when the last step for that event |
| 454 | was taken.</p> |
| 455 | <p>See the <a href="#step_detector">Step detector</a> sensor type for the signification of the time of a step.</p> |
| 456 | <p>Compared to the step detector, the step counter can have a higher latency (up |
| 457 | to 10 seconds). Thanks to this latency, this sensor has a high accuracy; the |
| 458 | step count after a full day of measures should be within 10% of the actual step |
| 459 | count. Both the step detector and the step counter detect when the user is |
| 460 | walking, running and walking up the stairs. They should not trigger when the |
| 461 | user is biking, driving or in other vehicles.</p> |
| 462 | <p>The hardware must ensure the internal step count never overflows. The minimum |
| 463 | size of the hardware's internal counter shall be 16 bits. In case of imminent |
| 464 | overflow (at most every ~2^16 steps), the SoC can be woken up so the driver can |
| 465 | do the counter maintenance.</p> |
| 466 | <p>As stated in <a href="interaction.html">Interaction</a>, while this sensor |
| 467 | operates, it shall not disrupt any other sensors, in particular, the |
| 468 | accelerometer, which might very well be in use.</p> |
| 469 | <p>If a particular device cannot support these modes of operation, then this |
| 470 | sensor type must not be reported by the HAL. ie: it is not acceptable to |
| 471 | "emulate" this sensor in the HAL.</p> |
| 472 | <p>This sensor must be low power. That is, if the step detection cannot be done in |
| 473 | hardware, this sensor should not be defined. In particular, when the step |
| 474 | counter is activated and the accelerometer is not, only steps should trigger |
| 475 | interrupts (not accelerometer data).</p> |
| 476 | <h3 id="tilt_detector">Tilt detector</h3> |
| 477 | <p>Underlying physical sensor: Accelerometer (+ possibly others as long as low |
| 478 | power)</p> |
| 479 | <p>Reporting-mode: <em><a href="report-modes.html#special">Special</a></em></p> |
| 480 | <p>Low-power</p> |
| 481 | <p>Implement only the wake-up version of this sensor.</p> |
| 482 | <p><code>getDefaultSensor(SENSOR_TYPE_TILT_DETECTOR)</code> <em>returns a wake-up sensor</em></p> |
| 483 | <p>A tilt detector generates an event each time a tilt event is detected.</p> |
| 484 | <p>A tilt event is defined by the direction of the 2-seconds window average |
| 485 | gravity changing by at least 35 degrees since the activation or the last event |
| 486 | generated by the sensor. Here is the algorithm:</p> |
| 487 | <ul> |
| 488 | <li> <code>reference_estimated_gravity</code> = average of accelerometer measurements over the |
| 489 | first second after activation or the estimated gravity when the last tilt event |
| 490 | was generated. </li> |
| 491 | <li> <code>current_estimated_gravity</code> = average of accelerometer measurements over the last |
| 492 | 2 seconds. </li> |
| 493 | <li> trigger when <code>angle(reference_estimated_gravity, current_estimated_gravity) > 35 |
| 494 | degrees</code> </li> |
| 495 | </ul> |
| 496 | <p>Large accelerations without a change in phone orientation should not trigger a |
| 497 | tilt event. For example, a sharp turn or strong acceleration while driving a |
| 498 | car should not trigger a tilt event, even though the angle of the average |
| 499 | acceleration might vary by more than 35 degrees. |
| 500 | Typically, this sensor is |
| 501 | implemented with the help of only an accelerometer. Other sensors can be used |
| 502 | as well if they do not increase the power consumption significantly. This is a |
| 503 | low power sensor that should allow the SoC to go into suspend mode. Do not |
| 504 | emulate this sensor in the HAL. Each sensor event reports 1 in |
| 505 | <code>sensors_event_t.data[0]</code>.</p> |
| 506 | <h2 id="attitude_composite_sensors">Attitude composite sensors</h2> |
| 507 | <h3 id="rotation_vector">Rotation vector</h3> |
| 508 | <p>Underlying physical sensors: Accelerometer, Magnetometer, and (when present) |
| 509 | Gyroscope</p> |
| 510 | <p>Reporting-mode: <em><a href="report-modes.html#continuous">Continuous</a></em></p> |
| 511 | <p><code>getDefaultSensor(SENSOR_TYPE_ROTATION_VECTOR)</code> <em>returns a non-wake-up sensor</em></p> |
| 512 | <p>A rotation vector sensor reports the orientation of the device relative to the |
| 513 | East-North-Up coordinates frame. It is usually obtained by integration of |
| 514 | accelerometer, gyroscope and magnetometer readings.</p> |
| 515 | <p>The East-North-Up coordinate system is defined as a direct orthonormal basis |
| 516 | where:</p> |
| 517 | <ul> |
| 518 | <li> X points east and is tangential to the ground. </li> |
| 519 | <li> Y points north and is tangential to the ground. </li> |
| 520 | <li> Z points towards the sky and is perpendicular to the ground. </li> |
| 521 | </ul> |
| 522 | <p>The orientation of the phone is represented by the rotation necessary to align |
| 523 | the East-North-Up coordinates with the phone's coordinates. That is, applying |
| 524 | the rotation to the world frame (X,Y,Z) would align them with the phone |
| 525 | coordinates (x,y,z).</p> |
| 526 | <p>The rotation can be seen as rotating the phone by an angle theta around an axis |
| 527 | rot_axis to go from the reference (East-North-Up aligned) device orientation to |
| 528 | the current device orientation.</p> |
| 529 | <p>The rotation is encoded as the four unit-less x, y, z, w components of a unit |
| 530 | quaternion:</p> |
| 531 | <ul> |
| 532 | <li> <code>sensors_event_t.data[0] = rot_axis.x*sin(theta/2)</code> </li> |
| 533 | <li> <code>sensors_event_t.data[1] = rot_axis.y*sin(theta/2)</code> </li> |
| 534 | <li> <code>sensors_event_t.data[2] = rot_axis.z*sin(theta/2)</code> </li> |
| 535 | <li> <code>sensors_event_t.data[3] = cos(theta/2)</code> </li> |
| 536 | </ul> |
| 537 | <p>Where:</p> |
| 538 | <ul> |
| 539 | <li> the x, y and z fields of <code>rot_axis</code> are the East-North-Up |
| 540 | coordinates of a unit length vector representing the rotation axis </li> |
| 541 | <li> <code>theta</code> is the rotation angle </li> |
| 542 | </ul> |
| 543 | <p>The quaternion is a unit quaternion: it must be of norm 1. Failure to ensure |
| 544 | this will cause erratic client behaviour.</p> |
| 545 | <p>In addition, this sensor reports an estimated heading accuracy:</p> |
| 546 | <p><code>sensors_event_t.data[4] = estimated_accuracy</code> (in radians)</p> |
| 547 | <p>The heading error must be less than <code>estimated_accuracy</code> 95% of the time. This |
| 548 | sensor must use a gyroscope as main orientation change input unless there is no |
| 549 | gyroscope on the device.</p> |
| 550 | <p>This sensor also includes the accelerometer and magnetometer input to make up |
| 551 | for gyroscope drift, but it cannot be implemented using only the magnetometer |
| 552 | and accelerometer, unless there is no gyroscope on the device.</p> |
| 553 | <h3 id="game_rotation_vector">Game rotation vector</h3> |
| 554 | <p>Underlying physical sensors: Accelerometer and Gyroscope (no Magnetometer)</p> |
| 555 | <p>Reporting-mode: <em><a href="report-modes.html#continuous">Continuous</a></em></p> |
| 556 | <p><code>getDefaultSensor(SENSOR_TYPE_GAME_ROTATION_VECTOR)</code> <em>returns a non-wake-up sensor</em></p> |
| 557 | <p>A game rotation vector sensor is similar to a rotation vector sensor but not |
| 558 | using the geomagnetic field. Therefore the Y axis doesn't point north but |
| 559 | instead to some other reference. That reference is allowed to drift by the same |
| 560 | order of magnitude as the gyroscope drifts around the Z axis.</p> |
| 561 | <p>See the <a href="#rotation_vector">Rotation vector</a> sensor for details on |
| 562 | how to set <code>sensors_event_t.data[0-3]</code>. This sensor does |
| 563 | not report an estimated heading accuracy: |
| 564 | <code>sensors_event_t.data[4]</code> is reserved and should be set to 0.</p> |
| 565 | <p>In an ideal case, a phone rotated and returned to the same real-world |
| 566 | orientation should report the same game rotation vector.</p> |
| 567 | <p>This sensor must be based on a gyroscope and an accelerometer. It cannot use |
| 568 | magnetometer as an input, besides, indirectly, through estimation of the |
| 569 | gyroscope bias.</p> |
| 570 | <h3 id="gravity">Gravity</h3> |
| 571 | <p>Underlying physical sensors: Accelerometer and (if present) Gyroscope (or |
| 572 | magnetometer if gyroscope not present)</p> |
| 573 | <p>Reporting-mode: <em><a href="report-modes.html#continuous">Continuous</a></em></p> |
| 574 | <p><code>getDefaultSensor(SENSOR_TYPE_GRAVITY)</code> <em>returns a non-wake-up sensor</em></p> |
| 575 | <p>A gravity sensor reports the direction and magnitude of gravity in the device's |
| 576 | coordinates.</p> |
| 577 | <p>The gravity vector components are reported in m/s^2 in the x, y and z fields of |
| 578 | <code>sensors_event_t.acceleration</code>.</p> |
| 579 | <p>When the device is at rest, the output of the gravity sensor should be |
| 580 | identical to that of the accelerometer. On Earth, the magnitude is around 9.8 |
| 581 | m/s^2.</p> |
| 582 | <p>If the device possesses a gyroscope, the gravity sensor must use the |
| 583 | accelerometer gyroscope and accelerometer as input.</p> |
| 584 | <p>If the device doesn’t possess a gyroscope, the gravity sensor must use the |
| 585 | accelerometer and the magnetometer as input.</p> |
| 586 | <h3 id="geomagnetic_rotation_vector">Geomagnetic rotation vector</h3> |
| 587 | <p>Underlying physical sensors: Accelerometer and Magnetometer (no Gyroscope)</p> |
| 588 | <p>Reporting-mode: <em><a href="report-modes.html#continuous">Continuous</a></em></p> |
| 589 | <p>Low-power</p> |
| 590 | <p><code>getDefaultSensor(SENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR)</code> <em>returns a non-wake-up sensor</em></p> |
| 591 | <p>A geomagnetic rotation vector is similar to a rotation vector sensor but using |
| 592 | a magnetometer and no gyroscope.</p> |
| 593 | <p>This sensor must be based on a magnetometer. It cannot be implemented using a |
| 594 | gyroscope, and gyroscope input cannot be used by this sensor.</p> |
| 595 | <p>See the <a href="#rotation_vector">Rotation vector</a> sensor for details on |
| 596 | how to set <code>sensors_event_t.data[0-4]</code>.</p> |
| 597 | <p>Just like for the rotation vector sensor, the heading error must be less than |
| 598 | the estimated accuracy (<code>sensors_event_t.data[4]</code>) 95% of the time.</p> |
| 599 | <p>This sensor must be low power, so it has to be implemented in hardware.</p> |
| 600 | <h3 id="orientation_deprecated">Orientation (deprecated)</h3> |
| 601 | <p>Underlying physical sensors: Accelerometer, Magnetometer and (if present) |
| 602 | Gyroscope</p> |
| 603 | <p>Reporting-mode: <em><a href="report-modes.html#continuous">Continuous</a></em></p> |
| 604 | <p><code>getDefaultSensor(SENSOR_TYPE_ORIENTATION)</code> <em>returns a non-wake-up sensor</em></p> |
| 605 | <p>Note: This is an older sensor type that has been deprecated in the Android SDK. |
| 606 | It has been replaced by the rotation vector sensor, which is more clearly |
| 607 | defined. Use the rotation vector sensor over the orientation sensor whenever |
| 608 | possible.</p> |
| 609 | <p>An orientation sensor reports the attitude of the device. The measurements are |
| 610 | reported in degrees in the x, y and z fields of <code>sensors_event_t.orientation</code>:</p> |
| 611 | <ul> |
| 612 | <li> <code>sensors_event_t.orientation.x</code>: azimuth, the angle between the magnetic north |
| 613 | direction and the Y axis, around the Z axis (<code>0<=azimuth<360</code>). 0=North, 90=East, |
| 614 | 180=South, 270=West </li> |
| 615 | <li> <code>sensors_event_t.orientation.y</code>: pitch, rotation around X axis |
| 616 | (<code>-180<=pitch<=180</code>), with positive values when the z-axis moves toward the |
| 617 | y-axis. </li> |
| 618 | <li> <code>sensors_event_t.orientation.z</code>: roll, rotation around Y axis (<code>-90<=roll<=90</code>), |
| 619 | with positive values when the x-axis moves towards the z-axis. </li> |
| 620 | </ul> |
| 621 | <p>Please note, for historical reasons the roll angle is positive in the clockwise |
| 622 | direction. (Mathematically speaking, it should be positive in the |
| 623 | counter-clockwise direction):</p> |
| 624 | <div class="figure" style="width:264px"> |
| 625 | <imgsrc="images/axis_positive_roll.png" alt="Depiction of orientation |
| 626 | relative to a device" height="253" /> |
| 627 | <p class="img-caption"> |
| 628 | <strong>Figure 2.</strong> Orientation relative to a device. |
| 629 | </p> |
| 630 | </div> |
| 631 | <p>This definition is different from yaw, pitch and roll used in aviation where |
| 632 | the X axis is along the long side of the plane (tail to nose).</p> |
| 633 | <p>The orientation sensor also reports how accurate it expects its readings to be |
| 634 | 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> |
| 635 | <h2 id="uncalibrated_sensors">Uncalibrated sensors</h2> |
| 636 | <p>Uncalibrated sensors provide more raw results and may include some bias but |
| 637 | also contain fewer "jumps" from corrections applied through calibration. Some |
| 638 | applications may prefer these uncalibrated results as smoother and more |
| 639 | reliable. For instance, if an application is attempting to conduct its own |
| 640 | sensor fusion, introducing calibrations can actually distort results.</p> |
| 641 | <h3 id="gyroscope_uncalibrated">Gyroscope uncalibrated</h3> |
| 642 | <p>Underlying physical sensor: Gyroscope</p> |
| 643 | <p>Reporting-mode: <em><a href="report-modes.html#continuous">Continuous</a></em></p> |
| 644 | <p><code>getDefaultSensor(SENSOR_TYPE_GYROSCOPE_UNCALIBRATED)</code> <em>returns a non-wake-up sensor</em></p> |
| 645 | <p>An uncalibrated gyroscope reports the rate of rotation around the sensor axes |
| 646 | without applying bias compensation to them, along with a bias estimate. All |
| 647 | values are in radians/second and are reported in the fields of |
| 648 | <code>sensors_event_t.uncalibrated_gyro</code>:</p> |
| 649 | <ul> |
| 650 | <li> <code>x_uncalib</code>: angular speed (w/o drift compensation) around the X axis </li> |
| 651 | <li> <code>y_uncalib</code>: angular speed (w/o drift compensation) around the Y axis </li> |
| 652 | <li> <code>z_uncalib</code>: angular speed (w/o drift compensation) around the Z axis </li> |
| 653 | <li> <code>x_bias</code>: estimated drift around X axis </li> |
| 654 | <li> <code>y_bias</code>: estimated drift around Y axis </li> |
| 655 | <li> <code>z_bias</code>: estimated drift around Z axis </li> |
| 656 | </ul> |
| 657 | <p>Conceptually, the uncalibrated measurement is the sum of the calibrated |
| 658 | measurement and the bias estimate: <code>_uncalibrated = _calibrated + _bias</code>.</p> |
| 659 | <p>The <code>x/y/z_bias</code> values are expected to jump as soon as the estimate of the bias |
| 660 | changes, and they should be stable the rest of the time.</p> |
| 661 | <p>See the definition of the <a href="#gyroscope">gyroscope</a> sensor for |
| 662 | details on the coordinate system used.</p> |
| 663 | <p>Factory calibration and temperature compensation must be applied to the |
| 664 | measurements. Also, gyroscope drift estimation must be implemented so that |
| 665 | reasonable estimates can be reported in <code>x_bias</code>, |
| 666 | <code>y_bias</code> and <code>z_bias</code>. If the |
| 667 | implementation is not able to estimate the drift, then this sensor must not be |
| 668 | implemented.</p> |
| 669 | <p>If this sensor is present, then the corresponding Gyroscope sensor must also be |
| 670 | present and both sensors must share the same <code>sensor_t.name</code> and |
| 671 | <code>sensor_t.vendor</code> values.</p> |
| 672 | <h3 id="magnetic_field_uncalibrated">Magnetic field uncalibrated</h3> |
| 673 | <p>Underlying physical sensor: Magnetometer</p> |
| 674 | <p>Reporting-mode: <em><a href="report-modes.html#continuous">Continuous</a></em></p> |
| 675 | <p><code>getDefaultSensor(SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED)</code> <em>returns a non-wake-up sensor</em></p> |
| 676 | <p>An uncalibrated magnetic field sensor reports the ambient magnetic field |
| 677 | together with a hard iron calibration estimate. All values are in micro-Tesla |
| 678 | (uT) and are reported in the fields of <code>sensors_event_t.uncalibrated_magnetic</code>:</p> |
| 679 | <ul> |
| 680 | <li> <code>x_uncalib</code>: magnetic field (w/o hard-iron compensation) along the X axis </li> |
| 681 | <li> <code>y_uncalib</code>: magnetic field (w/o hard-iron compensation) along the Y axis </li> |
| 682 | <li> <code>z_uncalib</code>: magnetic field (w/o hard-iron compensation) along the Z axis </li> |
| 683 | <li> <code>x_bias</code>: estimated hard-iron bias along the X axis </li> |
| 684 | <li> <code>y_bias</code>: estimated hard-iron bias along the Y axis </li> |
| 685 | <li> <code>z_bias</code>: estimated hard-iron bias along the Z axis </li> |
| 686 | </ul> |
| 687 | <p>Conceptually, the uncalibrated measurement is the sum of the calibrated |
| 688 | measurement and the bias estimate: <code>_uncalibrated = _calibrated + _bias</code>.</p> |
| 689 | <p>The uncalibrated magnetometer allows higher level algorithms to handle bad hard |
| 690 | iron estimation. The <code>x/y/z_bias</code> values are expected to jump as soon as the |
| 691 | estimate of the hard-iron changes, and they should be stable the rest of the |
| 692 | time.</p> |
| 693 | <p>Soft-iron calibration and temperature compensation must be applied to the |
| 694 | measurements. Also, hard-iron estimation must be implemented so that reasonable |
| 695 | estimates can be reported in <code>x_bias</code>, <code>y_bias</code> and |
| 696 | <code>z_bias</code>. If the implementation is not able to estimate the bias, |
| 697 | then this sensor must not be implemented.</p> |
| 698 | <p>If this sensor is present, then the corresponding magnetic field sensor must be |
| 699 | present and both sensors must share the same <code>sensor_t.name</code> and |
| 700 | <code>sensor_t.vendor</code> values.</p> |
| 701 | <h2 id="interaction_composite_sensors">Interaction composite sensors</h2> |
| 702 | <p>Some sensors are mostly used to detect interactions with the user. We do not |
| 703 | define how those sensors must be implemented, but they must be low power and it |
| 704 | is the responsibility of the device manufacturer to verify their quality in |
| 705 | terms of user experience.</p> |
| 706 | <h3 id="wake_up_gesture">Wake up gesture</h3> |
| 707 | <p>Underlying physical sensors: Undefined (anything low power)</p> |
| 708 | <p>Reporting-mode: <em><a href="report-modes.html#one-shot">One-shot</a></em></p> |
| 709 | <p>Low-power</p> |
| 710 | <p>Implement only the wake-up version of this sensor.</p> |
| 711 | <p><code>getDefaultSensor(SENSOR_TYPE_WAKE_GESTURE)</code> <em>returns a wake-up sensor</em></p> |
| 712 | <p>A wake up gesture sensor enables waking up the device based on a device |
| 713 | specific motion. When this sensor triggers, the device behaves as if the power |
| 714 | button was pressed, turning the screen on. This behavior (turning on the screen |
| 715 | when this sensor triggers) might be deactivated by the user in the device |
| 716 | settings. Changes in settings do not impact the behavior of the sensor: only |
| 717 | whether the framework turns the screen on when it triggers. |
| 718 | The actual gesture to be detected is not specified, and can be chosen by the |
| 719 | manufacturer of the device.</p> |
| 720 | <p>This sensor must be low power, as it is likely to be activated 24/7.</p> |
| 721 | <p>Each sensor event reports 1 in <code>sensors_event_t.data[0]</code>.</p> |
| 722 | <h3 id="pick_up_gesture">Pick up gesture</h3> |
| 723 | <p>Underlying physical sensors: Undefined (anything low power)</p> |
| 724 | <p>Reporting-mode: <em><a href="report-modes.html#one-shot">One-shot</a></em></p> |
| 725 | <p>Low-power</p> |
| 726 | <p>Implement only the wake-up version of this sensor.</p> |
| 727 | <p><code>getDefaultSensor(SENSOR_TYPE_PICK_UP_GESTURE)</code> <em>returns a wake-up sensor</em></p> |
| 728 | <p>A pick-up gesture sensor sensor triggers when the device is picked up |
| 729 | regardless of wherever is was before (desk, pocket, bag).</p> |
| 730 | <p>Each sensor event reports 1 in <code>sensors_event_t.data[0]</code>.</p> |
| 731 | <h3 id="glance_gesture">Glance gesture</h3> |
| 732 | <p>Underlying physical sensors: Undefined (anything low power)</p> |
| 733 | <p>Reporting-mode: <em><a href="report-modes.html#one-shot">One-shot</a></em></p> |
| 734 | <p>Low-power</p> |
| 735 | <p>Implement only the wake-up version of this sensor.</p> |
| 736 | <p><code>getDefaultSensor(SENSOR_TYPE_GLANCE_GESTURE)</code> <em>returns a wake-up sensor</em></p> |
| 737 | <p>A glance gesture sensor enables briefly turning the screen on to enable the |
| 738 | user to glance content on screen based on a specific motion. When this sensor |
| 739 | triggers, the device will turn the screen on momentarily to allow the user to |
| 740 | glance notifications or other content while the device remains locked in a |
| 741 | non-interactive state (dozing), then the screen will turn off again. This |
| 742 | behavior (briefly turning on the screen when this sensor triggers) might be |
| 743 | deactivated by the user in the device settings. Changes in settings do not |
| 744 | impact the behavior of the sensor: only whether the framework briefly turns the |
| 745 | screen on when it triggers. The actual gesture to be detected is not specified, |
| 746 | and can be chosen by the manufacturer of the device.</p> |
| 747 | <p>This sensor must be low power, as it is likely to be activated 24/7. |
| 748 | Each sensor event reports 1 in <code>sensors_event_t.data[0]</code>.</p> |