1 /* 2 * Copyright (C) 2008 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.hardware; 18 19 import android.annotation.NonNull; 20 import android.annotation.SuppressLint; 21 import android.compat.annotation.UnsupportedAppUsage; 22 23 /** 24 * This class represents a {@link android.hardware.Sensor Sensor} event and 25 * holds information such as the sensor's type, the time-stamp, accuracy and of 26 * course the sensor's {@link SensorEvent#values data}. 27 * 28 * <p> 29 * <u>Definition of the coordinate system used by the SensorEvent API.</u> 30 * </p> 31 * 32 * <p> 33 * The coordinate-system is defined relative to the screen of the phone in its 34 * default orientation. The axes are not swapped when the device's screen 35 * orientation changes. 36 * </p> 37 * 38 * <p> 39 * The X axis is horizontal and points to the right, the Y axis is vertical and 40 * points up and the Z axis points towards the outside of the front face of the 41 * screen. In this system, coordinates behind the screen have negative Z values. 42 * </p> 43 * 44 * <p> 45 * <center><img src="../../../images/axis_device.png" 46 * alt="Sensors coordinate-system diagram." border="0" /></center> 47 * </p> 48 * 49 * <p> 50 * <b>Note:</b> This coordinate system is different from the one used in the 51 * Android 2D APIs where the origin is in the top-left corner. 52 * </p> 53 * 54 * @see SensorManager 55 * @see SensorEvent 56 * @see Sensor 57 * 58 */ 59 60 public class SensorEvent { 61 /** 62 * <p> 63 * The length and contents of the {@link #values values} array depends on 64 * which {@link android.hardware.Sensor sensor} type is being monitored (see 65 * also {@link SensorEvent} for a definition of the coordinate system used). 66 * </p> 67 * 68 * <h4>{@link android.hardware.Sensor#TYPE_ACCELEROMETER 69 * Sensor.TYPE_ACCELEROMETER}:</h4> All values are in SI units (m/s^2) 70 * 71 * <ul> 72 * <li> values[0]: Acceleration minus Gx on the x-axis </li> 73 * <li> values[1]: Acceleration minus Gy on the y-axis </li> 74 * <li> values[2]: Acceleration minus Gz on the z-axis </li> 75 * </ul> 76 * 77 * <p> 78 * A sensor of this type measures the acceleration applied to the device 79 * (<b>Ad</b>). Conceptually, it does so by measuring forces applied to the 80 * sensor itself (<b>Fs</b>) using the relation: 81 * </p> 82 * 83 * <b><center>Ad = - ∑Fs / mass</center></b> 84 * 85 * <p> 86 * In particular, the force of gravity is always influencing the measured 87 * acceleration: 88 * </p> 89 * 90 * <b><center>Ad = -g - ∑F / mass</center></b> 91 * 92 * <p> 93 * For this reason, when the device is sitting on a table (and obviously not 94 * accelerating), the accelerometer reads a magnitude of <b>g</b> = 9.81 95 * m/s^2 96 * </p> 97 * 98 * <p> 99 * Similarly, when the device is in free-fall and therefore dangerously 100 * accelerating towards to ground at 9.81 m/s^2, its accelerometer reads a 101 * magnitude of 0 m/s^2. 102 * </p> 103 * 104 * <p> 105 * It should be apparent that in order to measure the real acceleration of 106 * the device, the contribution of the force of gravity must be eliminated. 107 * This can be achieved by applying a <i>high-pass</i> filter. Conversely, a 108 * <i>low-pass</i> filter can be used to isolate the force of gravity. 109 * </p> 110 * 111 * <pre class="prettyprint"> 112 * 113 * public void onSensorChanged(SensorEvent event) 114 * { 115 * // alpha is calculated as t / (t + dT) 116 * // with t, the low-pass filter's time-constant 117 * // and dT, the event delivery rate 118 * 119 * final float alpha = 0.8; 120 * 121 * gravity[0] = alpha * gravity[0] + (1 - alpha) * event.values[0]; 122 * gravity[1] = alpha * gravity[1] + (1 - alpha) * event.values[1]; 123 * gravity[2] = alpha * gravity[2] + (1 - alpha) * event.values[2]; 124 * 125 * linear_acceleration[0] = event.values[0] - gravity[0]; 126 * linear_acceleration[1] = event.values[1] - gravity[1]; 127 * linear_acceleration[2] = event.values[2] - gravity[2]; 128 * } 129 * </pre> 130 * 131 * <p> 132 * <u>Examples</u>: 133 * <ul> 134 * <li>When the device lies flat on a table and is pushed on its left side 135 * toward the right, the x acceleration value is positive.</li> 136 * 137 * <li>When the device lies flat on a table, the acceleration value is 138 * +9.81, which correspond to the acceleration of the device (0 m/s^2) minus 139 * the force of gravity (-9.81 m/s^2).</li> 140 * 141 * <li>When the device lies flat on a table and is pushed toward the sky 142 * with an acceleration of A m/s^2, the acceleration value is equal to 143 * A+9.81 which correspond to the acceleration of the device (+A m/s^2) 144 * minus the force of gravity (-9.81 m/s^2).</li> 145 * </ul> 146 * 147 * 148 * <h4>{@link android.hardware.Sensor#TYPE_MAGNETIC_FIELD 149 * Sensor.TYPE_MAGNETIC_FIELD}:</h4> 150 * All values are in micro-Tesla (uT) and measure the ambient magnetic field 151 * in the X, Y and Z axis. 152 * 153 * <h4>{@link android.hardware.Sensor#TYPE_GYROSCOPE Sensor.TYPE_GYROSCOPE}: 154 * </h4> All values are in radians/second and measure the rate of rotation 155 * around the device's local X, Y and Z axis. The coordinate system is the 156 * same as is used for the acceleration sensor. Rotation is positive in the 157 * counter-clockwise direction. That is, an observer looking from some 158 * positive location on the x, y or z axis at a device positioned on the 159 * origin would report positive rotation if the device appeared to be 160 * rotating counter clockwise. Note that this is the standard mathematical 161 * definition of positive rotation and does not agree with the definition of 162 * roll given earlier. 163 * <ul> 164 * <li> values[0]: Angular speed around the x-axis </li> 165 * <li> values[1]: Angular speed around the y-axis </li> 166 * <li> values[2]: Angular speed around the z-axis </li> 167 * </ul> 168 * <p> 169 * Typically the output of the gyroscope is integrated over time to 170 * calculate a rotation describing the change of angles over the time step, 171 * for example: 172 * </p> 173 * 174 * <pre class="prettyprint"> 175 * private static final float NS2S = 1.0f / 1000000000.0f; 176 * private final float[] deltaRotationVector = new float[4](); 177 * private float timestamp; 178 * 179 * public void onSensorChanged(SensorEvent event) { 180 * // This time step's delta rotation to be multiplied by the current rotation 181 * // after computing it from the gyro sample data. 182 * if (timestamp != 0) { 183 * final float dT = (event.timestamp - timestamp) * NS2S; 184 * // Axis of the rotation sample, not normalized yet. 185 * float axisX = event.values[0]; 186 * float axisY = event.values[1]; 187 * float axisZ = event.values[2]; 188 * 189 * // Calculate the angular speed of the sample 190 * float omegaMagnitude = sqrt(axisX*axisX + axisY*axisY + axisZ*axisZ); 191 * 192 * // Normalize the rotation vector if it's big enough to get the axis 193 * if (omegaMagnitude > EPSILON) { 194 * axisX /= omegaMagnitude; 195 * axisY /= omegaMagnitude; 196 * axisZ /= omegaMagnitude; 197 * } 198 * 199 * // Integrate around this axis with the angular speed by the time step 200 * // in order to get a delta rotation from this sample over the time step 201 * // We will convert this axis-angle representation of the delta rotation 202 * // into a quaternion before turning it into the rotation matrix. 203 * float thetaOverTwo = omegaMagnitude * dT / 2.0f; 204 * float sinThetaOverTwo = sin(thetaOverTwo); 205 * float cosThetaOverTwo = cos(thetaOverTwo); 206 * deltaRotationVector[0] = sinThetaOverTwo * axisX; 207 * deltaRotationVector[1] = sinThetaOverTwo * axisY; 208 * deltaRotationVector[2] = sinThetaOverTwo * axisZ; 209 * deltaRotationVector[3] = cosThetaOverTwo; 210 * } 211 * timestamp = event.timestamp; 212 * float[] deltaRotationMatrix = new float[9]; 213 * SensorManager.getRotationMatrixFromVector(deltaRotationMatrix, deltaRotationVector); 214 * // User code should concatenate the delta rotation we computed with the current 215 * // rotation in order to get the updated rotation. 216 * // rotationCurrent = rotationCurrent * deltaRotationMatrix; 217 * } 218 * </pre> 219 * <p> 220 * In practice, the gyroscope noise and offset will introduce some errors 221 * which need to be compensated for. This is usually done using the 222 * information from other sensors, but is beyond the scope of this document. 223 * </p> 224 * <h4>{@link android.hardware.Sensor#TYPE_LIGHT Sensor.TYPE_LIGHT}:</h4> 225 * <ul> 226 * <li>values[0]: Ambient light level in SI lux units </li> 227 * </ul> 228 * 229 * <h4>{@link android.hardware.Sensor#TYPE_PRESSURE Sensor.TYPE_PRESSURE}:</h4> 230 * <ul> 231 * <li>values[0]: Atmospheric pressure in hPa (millibar) </li> 232 * </ul> 233 * 234 * <h4>{@link android.hardware.Sensor#TYPE_PROXIMITY Sensor.TYPE_PROXIMITY}: 235 * </h4> 236 * 237 * <ul> 238 * <li>values[0]: Proximity sensor distance measured in centimeters </li> 239 * </ul> 240 * 241 * <p> 242 * <b>Note:</b> Some proximity sensors only support a binary <i>near</i> or 243 * <i>far</i> measurement. In this case, the sensor should report its 244 * {@link android.hardware.Sensor#getMaximumRange() maximum range} value in 245 * the <i>far</i> state and a lesser value in the <i>near</i> state. 246 * </p> 247 * 248 * <h4>{@link android.hardware.Sensor#TYPE_GRAVITY Sensor.TYPE_GRAVITY}:</h4> 249 * <p>A three dimensional vector indicating the direction and magnitude of gravity. Units 250 * are m/s^2. The coordinate system is the same as is used by the acceleration sensor.</p> 251 * <p><b>Note:</b> When the device is at rest, the output of the gravity sensor should be 252 * identical to that of the accelerometer.</p> 253 * 254 * <h4> 255 * {@link android.hardware.Sensor#TYPE_LINEAR_ACCELERATION Sensor.TYPE_LINEAR_ACCELERATION}: 256 * </h4> A three dimensional vector indicating acceleration along each device axis, not 257 * including gravity. All values have units of m/s^2. The coordinate system is the same as is 258 * used by the acceleration sensor. 259 * <p>The output of the accelerometer, gravity and linear-acceleration sensors must obey the 260 * following relation:</p> 261 * <p><ul>acceleration = gravity + linear-acceleration</ul></p> 262 * 263 * <h4>{@link android.hardware.Sensor#TYPE_ROTATION_VECTOR Sensor.TYPE_ROTATION_VECTOR}:</h4> 264 * <p>The rotation vector represents the orientation of the device as a combination of an 265 * <i>angle</i> and an <i>axis</i>, in which the device has rotated through an angle θ 266 * around an axis <x, y, z>.</p> 267 * <p>The three elements of the rotation vector are 268 * <x*sin(θ/2), y*sin(θ/2), z*sin(θ/2)>, such that the magnitude of the rotation 269 * vector is equal to sin(θ/2), and the direction of the rotation vector is equal to the 270 * direction of the axis of rotation.</p> 271 * </p>The three elements of the rotation vector are equal to 272 * the last three components of a <b>unit</b> quaternion 273 * <cos(θ/2), x*sin(θ/2), y*sin(θ/2), z*sin(θ/2)>.</p> 274 * <p>Elements of the rotation vector are unitless. 275 * The x,y, and z axis are defined in the same way as the acceleration 276 * sensor.</p> 277 * The reference coordinate system is defined as a direct orthonormal basis, 278 * where: 279 * </p> 280 * 281 * <ul> 282 * <li>X is defined as the vector product <b>Y.Z</b> (It is tangential to 283 * the ground at the device's current location and roughly points East).</li> 284 * <li>Y is tangential to the ground at the device's current location and 285 * points towards magnetic north.</li> 286 * <li>Z points towards the sky and is perpendicular to the ground.</li> 287 * </ul> 288 * 289 * <p> 290 * <center><img src="../../../images/axis_globe.png" 291 * alt="World coordinate-system diagram." border="0" /></center> 292 * </p> 293 * 294 * <ul> 295 * <li> values[0]: x*sin(θ/2) </li> 296 * <li> values[1]: y*sin(θ/2) </li> 297 * <li> values[2]: z*sin(θ/2) </li> 298 * <li> values[3]: cos(θ/2) </li> 299 * <li> values[4]: estimated heading Accuracy (in radians) (-1 if unavailable)</li> 300 * </ul> 301 * <p> values[3], originally optional, will always be present from SDK Level 18 onwards. 302 * values[4] is a new value that has been added in SDK Level 18. 303 * </p> 304 * 305 * <h4>{@link android.hardware.Sensor#TYPE_ORIENTATION 306 * Sensor.TYPE_ORIENTATION}:</h4> All values are angles in degrees. 307 * 308 * <ul> 309 * <li> values[0]: Azimuth, angle between the magnetic north direction and the 310 * y-axis, around the z-axis (0 to 359). 0=North, 90=East, 180=South, 311 * 270=West 312 * </p> 313 * 314 * <p> 315 * values[1]: Pitch, rotation around x-axis (-180 to 180), with positive 316 * values when the z-axis moves <b>toward</b> the y-axis. 317 * </p> 318 * 319 * <p> 320 * values[2]: Roll, rotation around the y-axis (-90 to 90) 321 * increasing as the device moves clockwise. 322 * </p> 323 * </ul> 324 * 325 * <p> 326 * <b>Note:</b> This definition is different from <b>yaw, pitch and roll</b> 327 * used in aviation where the X axis is along the long side of the plane 328 * (tail to nose). 329 * </p> 330 * 331 * <p> 332 * <b>Note:</b> This sensor type exists for legacy reasons, please use 333 * {@link android.hardware.Sensor#TYPE_ROTATION_VECTOR 334 * rotation vector sensor type} and 335 * {@link android.hardware.SensorManager#getRotationMatrix 336 * getRotationMatrix()} in conjunction with 337 * {@link android.hardware.SensorManager#remapCoordinateSystem 338 * remapCoordinateSystem()} and 339 * {@link android.hardware.SensorManager#getOrientation getOrientation()} to 340 * compute these values instead. 341 * </p> 342 * 343 * <p> 344 * <b>Important note:</b> For historical reasons the roll angle is positive 345 * in the clockwise direction (mathematically speaking, it should be 346 * positive in the counter-clockwise direction). 347 * </p> 348 * 349 * <h4>{@link android.hardware.Sensor#TYPE_RELATIVE_HUMIDITY 350 * Sensor.TYPE_RELATIVE_HUMIDITY}:</h4> 351 * <ul> 352 * <li> values[0]: Relative ambient air humidity in percent </li> 353 * </ul> 354 * <p> 355 * When relative ambient air humidity and ambient temperature are 356 * measured, the dew point and absolute humidity can be calculated. 357 * </p> 358 * <u>Dew Point</u> 359 * <p> 360 * The dew point is the temperature to which a given parcel of air must be 361 * cooled, at constant barometric pressure, for water vapor to condense 362 * into water. 363 * </p> 364 * <center><pre> 365 * ln(RH/100%) + m·t/(T<sub>n</sub>+t) 366 * t<sub>d</sub>(t,RH) = T<sub>n</sub> · ------------------------------ 367 * m - [ln(RH/100%) + m·t/(T<sub>n</sub>+t)] 368 * </pre></center> 369 * <dl> 370 * <dt>t<sub>d</sub></dt> <dd>dew point temperature in °C</dd> 371 * <dt>t</dt> <dd>actual temperature in °C</dd> 372 * <dt>RH</dt> <dd>actual relative humidity in %</dd> 373 * <dt>m</dt> <dd>17.62</dd> 374 * <dt>T<sub>n</sub></dt> <dd>243.12 °C</dd> 375 * </dl> 376 * <p>for example:</p> 377 * <pre class="prettyprint"> 378 * h = Math.log(rh / 100.0) + (17.62 * t) / (243.12 + t); 379 * td = 243.12 * h / (17.62 - h); 380 * </pre> 381 * <u>Absolute Humidity</u> 382 * <p> 383 * The absolute humidity is the mass of water vapor in a particular volume 384 * of dry air. The unit is g/m<sup>3</sup>. 385 * </p> 386 * <center><pre> 387 * RH/100%·A·exp(m·t/(T<sub>n</sub>+t)) 388 * d<sub>v</sub>(t,RH) = 216.7 · ------------------------- 389 * 273.15 + t 390 * </pre></center> 391 * <dl> 392 * <dt>d<sub>v</sub></dt> <dd>absolute humidity in g/m<sup>3</sup></dd> 393 * <dt>t</dt> <dd>actual temperature in °C</dd> 394 * <dt>RH</dt> <dd>actual relative humidity in %</dd> 395 * <dt>m</dt> <dd>17.62</dd> 396 * <dt>T<sub>n</sub></dt> <dd>243.12 °C</dd> 397 * <dt>A</dt> <dd>6.112 hPa</dd> 398 * </dl> 399 * <p>for example:</p> 400 * <pre class="prettyprint"> 401 * dv = 216.7 * 402 * (rh / 100.0 * 6.112 * Math.exp(17.62 * t / (243.12 + t)) / (273.15 + t)); 403 * </pre> 404 * 405 * <h4>{@link android.hardware.Sensor#TYPE_AMBIENT_TEMPERATURE Sensor.TYPE_AMBIENT_TEMPERATURE}: 406 * </h4> 407 * 408 * <ul> 409 * <li> values[0]: ambient (room) temperature in degree Celsius.</li> 410 * </ul> 411 * 412 * 413 * <h4>{@link android.hardware.Sensor#TYPE_MAGNETIC_FIELD_UNCALIBRATED 414 * Sensor.TYPE_MAGNETIC_FIELD_UNCALIBRATED}:</h4> 415 * Similar to {@link android.hardware.Sensor#TYPE_MAGNETIC_FIELD}, 416 * but the hard iron calibration is reported separately instead of being included 417 * in the measurement. Factory calibration and temperature compensation will still 418 * be applied to the "uncalibrated" measurement. Assumptions that the magnetic field 419 * is due to the Earth's poles is avoided. 420 * <p> 421 * The values array is shown below: 422 * <ul> 423 * <li> values[0] = x_uncalib </li> 424 * <li> values[1] = y_uncalib </li> 425 * <li> values[2] = z_uncalib </li> 426 * <li> values[3] = x_bias </li> 427 * <li> values[4] = y_bias </li> 428 * <li> values[5] = z_bias </li> 429 * </ul> 430 * </p> 431 * <p> 432 * x_uncalib, y_uncalib, z_uncalib are the measured magnetic field in X, Y, Z axes. 433 * Soft iron and temperature calibrations are applied. But the hard iron 434 * calibration is not applied. The values are in micro-Tesla (uT). 435 * </p> 436 * <p> 437 * x_bias, y_bias, z_bias give the iron bias estimated in X, Y, Z axes. 438 * Each field is a component of the estimated hard iron calibration. 439 * The values are in micro-Tesla (uT). 440 * </p> 441 * <p> Hard iron - These distortions arise due to the magnetized iron, steel or permanent 442 * magnets on the device. 443 * Soft iron - These distortions arise due to the interaction with the earth's magnetic 444 * field. 445 * </p> 446 * <h4> {@link android.hardware.Sensor#TYPE_GAME_ROTATION_VECTOR 447 * Sensor.TYPE_GAME_ROTATION_VECTOR}:</h4> 448 * Identical to {@link android.hardware.Sensor#TYPE_ROTATION_VECTOR} except that it 449 * doesn't use the geomagnetic field. Therefore the Y axis doesn't 450 * point north, but instead to some other reference, that reference is 451 * allowed to drift by the same order of magnitude as the gyroscope 452 * drift around the Z axis. 453 * <p> 454 * In the ideal case, a phone rotated and returning to the same real-world 455 * orientation will report the same game rotation vector 456 * (without using the earth's geomagnetic field). However, the orientation 457 * may drift somewhat over time. See {@link android.hardware.Sensor#TYPE_ROTATION_VECTOR} 458 * for a detailed description of the values. This sensor will not have 459 * the estimated heading accuracy value. 460 * </p> 461 * 462 * <h4> {@link android.hardware.Sensor#TYPE_GYROSCOPE_UNCALIBRATED 463 * Sensor.TYPE_GYROSCOPE_UNCALIBRATED}:</h4> 464 * All values are in radians/second and measure the rate of rotation 465 * around the X, Y and Z axis. An estimation of the drift on each axis is 466 * reported as well. 467 * <p> 468 * No gyro-drift compensation is performed. Factory calibration and temperature 469 * compensation is still applied to the rate of rotation (angular speeds). 470 * </p> 471 * <p> 472 * The coordinate system is the same as is used for the 473 * {@link android.hardware.Sensor#TYPE_ACCELEROMETER} 474 * Rotation is positive in the counter-clockwise direction (right-hand rule). 475 * That is, an observer looking from some positive location on the x, y or z axis 476 * at a device positioned on the origin would report positive rotation if the device 477 * appeared to be rotating counter clockwise. 478 * The range would at least be 17.45 rad/s (ie: ~1000 deg/s). 479 * <ul> 480 * <li> values[0] : angular speed (w/o drift compensation) around the X axis in rad/s </li> 481 * <li> values[1] : angular speed (w/o drift compensation) around the Y axis in rad/s </li> 482 * <li> values[2] : angular speed (w/o drift compensation) around the Z axis in rad/s </li> 483 * <li> values[3] : estimated drift around X axis in rad/s </li> 484 * <li> values[4] : estimated drift around Y axis in rad/s </li> 485 * <li> values[5] : estimated drift around Z axis in rad/s </li> 486 * </ul> 487 * </p> 488 * <p><b>Pro Tip:</b> Always use the length of the values array while performing operations 489 * on it. In earlier versions, this used to be always 3 which has changed now. </p> 490 * 491 * <h4>{@link android.hardware.Sensor#TYPE_POSE_6DOF 492 * Sensor.TYPE_POSE_6DOF}:</h4> 493 * 494 * A TYPE_POSE_6DOF event consists of a rotation expressed as a quaternion and a translation 495 * expressed in SI units. The event also contains a delta rotation and translation that show 496 * how the device?s pose has changed since the previous sequence numbered pose. 497 * The event uses the cannonical Android Sensor axes. 498 * 499 * 500 * <ul> 501 * <li> values[0]: x*sin(θ/2) </li> 502 * <li> values[1]: y*sin(θ/2) </li> 503 * <li> values[2]: z*sin(θ/2) </li> 504 * <li> values[3]: cos(θ/2) </li> 505 * 506 * 507 * <li> values[4]: Translation along x axis from an arbitrary origin. </li> 508 * <li> values[5]: Translation along y axis from an arbitrary origin. </li> 509 * <li> values[6]: Translation along z axis from an arbitrary origin. </li> 510 * 511 * <li> values[7]: Delta quaternion rotation x*sin(θ/2) </li> 512 * <li> values[8]: Delta quaternion rotation y*sin(θ/2) </li> 513 * <li> values[9]: Delta quaternion rotation z*sin(θ/2) </li> 514 * <li> values[10]: Delta quaternion rotation cos(θ/2) </li> 515 * 516 * <li> values[11]: Delta translation along x axis. </li> 517 * <li> values[12]: Delta translation along y axis. </li> 518 * <li> values[13]: Delta translation along z axis. </li> 519 * 520 * <li> values[14]: Sequence number </li> 521 * 522 * </ul> 523 * 524 * <h4>{@link android.hardware.Sensor#TYPE_STATIONARY_DETECT 525 * Sensor.TYPE_STATIONARY_DETECT}:</h4> 526 * 527 * A TYPE_STATIONARY_DETECT event is produced if the device has been 528 * stationary for at least 5 seconds with a maximal latency of 5 529 * additional seconds. ie: it may take up anywhere from 5 to 10 seconds 530 * afte the device has been at rest to trigger this event. 531 * 532 * The only allowed value is 1.0. 533 * 534 * <ul> 535 * <li> values[0]: 1.0 </li> 536 * </ul> 537 * 538 * <h4>{@link android.hardware.Sensor#TYPE_MOTION_DETECT 539 * Sensor.TYPE_MOTION_DETECT}:</h4> 540 * 541 * A TYPE_MOTION_DETECT event is produced if the device has been in 542 * motion for at least 5 seconds with a maximal latency of 5 543 * additional seconds. ie: it may take up anywhere from 5 to 10 seconds 544 * afte the device has been at rest to trigger this event. 545 * 546 * The only allowed value is 1.0. 547 * 548 * <ul> 549 * <li> values[0]: 1.0 </li> 550 * </ul> 551 * 552 * <h4>{@link android.hardware.Sensor#TYPE_HEART_BEAT 553 * Sensor.TYPE_HEART_BEAT}:</h4> 554 * 555 * A sensor of this type returns an event everytime a heart beat peak is 556 * detected. 557 * 558 * Peak here ideally corresponds to the positive peak in the QRS complex of 559 * an ECG signal. 560 * 561 * <ul> 562 * <li> values[0]: confidence</li> 563 * </ul> 564 * 565 * <p> 566 * A confidence value of 0.0 indicates complete uncertainty - that a peak 567 * is as likely to be at the indicated timestamp as anywhere else. 568 * A confidence value of 1.0 indicates complete certainly - that a peak is 569 * completely unlikely to be anywhere else on the QRS complex. 570 * </p> 571 * 572 * <h4>{@link android.hardware.Sensor#TYPE_LOW_LATENCY_OFFBODY_DETECT 573 * Sensor.TYPE_LOW_LATENCY_OFFBODY_DETECT}:</h4> 574 * 575 * <p> 576 * A sensor of this type returns an event every time the device transitions 577 * from off-body to on-body and from on-body to off-body (e.g. a wearable 578 * device being removed from the wrist would trigger an event indicating an 579 * off-body transition). The event returned will contain a single value to 580 * indicate off-body state: 581 * </p> 582 * 583 * <ul> 584 * <li> values[0]: off-body state</li> 585 * </ul> 586 * 587 * <p> 588 * Valid values for off-body state: 589 * <ul> 590 * <li> 1.0 (device is on-body)</li> 591 * <li> 0.0 (device is off-body)</li> 592 * </ul> 593 * </p> 594 * 595 * <p> 596 * When a sensor of this type is activated, it must deliver the initial 597 * on-body or off-body event representing the current device state within 598 * 5 seconds of activating the sensor. 599 * </p> 600 * 601 * <p> 602 * This sensor must be able to detect and report an on-body to off-body 603 * transition within 1 second of the device being removed from the body, 604 * and must be able to detect and report an off-body to on-body transition 605 * within 5 seconds of the device being put back onto the body. 606 * </p> 607 * 608 * <h4>{@link android.hardware.Sensor#TYPE_ACCELEROMETER_UNCALIBRATED 609 * Sensor.TYPE_ACCELEROMETER_UNCALIBRATED}:</h4> All values are in SI 610 * units (m/s^2) 611 * 612 * Similar to {@link android.hardware.Sensor#TYPE_ACCELEROMETER}, 613 * Factory calibration and temperature compensation will still be applied 614 * to the "uncalibrated" measurement. 615 * 616 * <p> 617 * The values array is shown below: 618 * <ul> 619 * <li> values[0] = x_uncalib without bias compensation </li> 620 * <li> values[1] = y_uncalib without bias compensation </li> 621 * <li> values[2] = z_uncalib without bias compensation </li> 622 * <li> values[3] = estimated x_bias </li> 623 * <li> values[4] = estimated y_bias </li> 624 * <li> values[5] = estimated z_bias </li> 625 * </ul> 626 * </p> 627 * <p> 628 * x_uncalib, y_uncalib, z_uncalib are the measured acceleration in X, Y, Z 629 * axes similar to the {@link android.hardware.Sensor#TYPE_ACCELEROMETER}, 630 * without any bias correction (factory bias compensation and any 631 * temperature compensation is allowed). 632 * x_bias, y_bias, z_bias are the estimated biases. 633 * </p> 634 * 635 * <h4>{@link android.hardware.Sensor#TYPE_HINGE_ANGLE Sensor.TYPE_HINGE_ANGLE}:</h4> 636 * 637 * A sensor of this type measures the angle, in degrees, between two integral parts of the 638 * device. Movement of a hinge measured by this sensor type is expected to alter the ways in 639 * which the user may interact with the device, for example by unfolding or revealing a display. 640 * 641 * <ul> 642 * <li> values[0]: Measured hinge angle between 0 and 360 degrees inclusive</li> 643 * </ul> 644 * 645 * <h4>{@link android.hardware.Sensor#TYPE_HEAD_TRACKER Sensor.TYPE_HEAD_TRACKER}:</h4> 646 * 647 * A sensor of this type measures the orientation of a user's head relative to an arbitrary 648 * reference frame, as well as the rate of rotation. 649 * 650 * Events produced by this sensor follow a special head-centric coordinate frame, where: 651 * <ul> 652 * <li> The X axis crosses through the user's ears, with the positive X direction extending 653 * out of the user's right ear</li> 654 * <li> The Y axis crosses from the back of the user's head through their nose, with the 655 * positive direction extending out of the nose, and the X/Y plane being nominally 656 * parallel to the ground when the user is upright and looking straight ahead</li> 657 * <li> The Z axis crosses from the neck through the top of the user's head, with the 658 * positive direction extending out from the top of the head</li> 659 * </ul> 660 * 661 * Data is provided in Euler vector representation, which is a vector whose direction indicates 662 * the axis of rotation and magnitude indicates the angle to rotate around that axis, in 663 * radians. 664 * 665 * The first three elements provide the transform from the (arbitrary, possibly slowly drifting) 666 * reference frame to the head frame. The magnitude of this vector is in range [0, π] 667 * radians, while the value of individual axes is in range [-π, π]. The next three 668 * elements optionally provide the estimated rotational velocity of the user's head relative to 669 * itself, in radians per second. If a given sensor does not support determining velocity, these 670 * elements are set to 0. 671 * 672 * <ul> 673 * <li> values[0] : X component of Euler vector representing rotation</li> 674 * <li> values[1] : Y component of Euler vector representing rotation</li> 675 * <li> values[2] : Z component of Euler vector representing rotation</li> 676 * <li> values[3] : X component of Euler vector representing angular velocity (if 677 * supported, otherwise 0)</li> 678 * <li> values[4] : Y component of Euler vector representing angular velocity (if 679 * supported, otherwise 0)</li> 680 * <li> values[5] : Z component of Euler vector representing angular velocity (if 681 * supported, otherwise 0)</li> 682 * </ul> 683 * 684 * <h4>{@link android.hardware.Sensor#TYPE_ACCELEROMETER_LIMITED_AXES 685 * Sensor.TYPE_ACCELEROMETER_LIMITED_AXES}: 686 * </h4> Equivalent to TYPE_ACCELEROMETER, but supporting cases where one 687 * or two axes are not supported. 688 * 689 * The last three values represent whether the acceleration value for a 690 * given axis is supported. A value of 1.0 indicates that the axis is 691 * supported, while a value of 0 means it isn't supported. The supported 692 * axes should be determined at build time and these values do not change 693 * during runtime. 694 * 695 * The acceleration values for axes that are not supported are set to 0. 696 * 697 * Similar to {@link android.hardware.Sensor#TYPE_ACCELEROMETER}. 698 * 699 * <ul> 700 * <li> values[0]: Acceleration minus Gx on the x-axis (if supported)</li> 701 * <li> values[1]: Acceleration minus Gy on the y-axis (if supported)</li> 702 * <li> values[2]: Acceleration minus Gz on the z-axis (if supported)</li> 703 * <li> values[3]: Acceleration supported for x-axis</li> 704 * <li> values[4]: Acceleration supported for y-axis</li> 705 * <li> values[5]: Acceleration supported for z-axis</li> 706 * </ul> 707 * 708 * <h4>{@link android.hardware.Sensor#TYPE_GYROSCOPE_LIMITED_AXES 709 * Sensor.TYPE_GYROSCOPE_LIMITED_AXES}: 710 * </h4> Equivalent to TYPE_GYROSCOPE, but supporting cases where one or two 711 * axes are not supported. 712 * 713 * The last three values represent whether the angular speed value for a 714 * given axis is supported. A value of 1.0 indicates that the axis is 715 * supported, while a value of 0 means it isn't supported. The supported 716 * axes should be determined at build time and these values do not change 717 * during runtime. 718 * 719 * The angular speed values for axes that are not supported are set to 0. 720 * 721 * Similar to {@link android.hardware.Sensor#TYPE_GYROSCOPE}. 722 * 723 * <ul> 724 * <li> values[0]: Angular speed around the x-axis (if supported)</li> 725 * <li> values[1]: Angular speed around the y-axis (if supported)</li> 726 * <li> values[2]: Angular speed around the z-axis (if supported)</li> 727 * <li> values[3]: Angular speed supported for x-axis</li> 728 * <li> values[4]: Angular speed supported for y-axis</li> 729 * <li> values[5]: Angular speed supported for z-axis</li> 730 * </ul> 731 * <p> 732 * 733 * <h4>{@link android.hardware.Sensor#TYPE_ACCELEROMETER_LIMITED_AXES_UNCALIBRATED 734 * Sensor.TYPE_ACCELEROMETER_LIMITED_AXES_UNCALIBRATED}: 735 * </h4> Equivalent to TYPE_ACCELEROMETER_UNCALIBRATED, but supporting cases 736 * where one or two axes are not supported. 737 * 738 * The last three values represent whether the acceleration value for a 739 * given axis is supported. A value of 1.0 indicates that the axis is 740 * supported, while a value of 0 means it isn't supported. The supported 741 * axes should be determined at build time and these values do not change 742 * during runtime. 743 * 744 * The acceleration values and bias values for axes that are not supported 745 * are set to 0. 746 * 747 * <ul> 748 * <li> values[0]: x_uncalib without bias compensation (if supported)</li> 749 * <li> values[1]: y_uncalib without bias compensation (if supported)</li> 750 * <li> values[2]: z_uncalib without bias compensation (if supported)</li> 751 * <li> values[3]: estimated x_bias (if supported)</li> 752 * <li> values[4]: estimated y_bias (if supported)</li> 753 * <li> values[5]: estimated z_bias (if supported)</li> 754 * <li> values[6]: Acceleration supported for x-axis</li> 755 * <li> values[7]: Acceleration supported for y-axis</li> 756 * <li> values[8]: Acceleration supported for z-axis</li> 757 * </ul> 758 * </p> 759 * 760 * <h4> {@link android.hardware.Sensor#TYPE_GYROSCOPE_LIMITED_AXES_UNCALIBRATED 761 * Sensor.TYPE_GYROSCOPE_LIMITED_AXES_UNCALIBRATED}: 762 * </h4> Equivalent to TYPE_GYROSCOPE_UNCALIBRATED, but supporting cases 763 * where one or two axes are not supported. 764 * 765 * The last three values represent whether the angular speed value for a 766 * given axis is supported. A value of 1.0 indicates that the axis is 767 * supported, while a value of 0 means it isn't supported. The supported 768 * axes should be determined at build time and these values do not change 769 * during runtime. 770 * 771 * The angular speed values and drift values for axes that are not supported 772 * are set to 0. 773 * 774 * <ul> 775 * <li> values[0]: Angular speed (w/o drift compensation) around the X axis (if supported)</li> 776 * <li> values[1]: Angular speed (w/o drift compensation) around the Y axis (if supported)</li> 777 * <li> values[2]: Angular speed (w/o drift compensation) around the Z axis (if supported)</li> 778 * <li> values[3]: estimated drift around X axis (if supported)</li> 779 * <li> values[4]: estimated drift around Y axis (if supported)</li> 780 * <li> values[5]: estimated drift around Z axis (if supported)</li> 781 * <li> values[6]: Angular speed supported for x-axis</li> 782 * <li> values[7]: Angular speed supported for y-axis</li> 783 * <li> values[8]: Angular speed supported for z-axis</li> 784 * </ul> 785 * </p> 786 * 787 * <h4>{@link android.hardware.Sensor#TYPE_HEADING Sensor.TYPE_HEADING}:</h4> 788 * 789 * A sensor of this type measures the direction in which the device is 790 * pointing relative to true north in degrees. The value must be between 791 * 0.0 (inclusive) and 360.0 (exclusive), with 0 indicating north, 90 east, 792 * 180 south, and 270 west. 793 * 794 * Accuracy is defined at 68% confidence. In the case where the underlying 795 * distribution is assumed Gaussian normal, this would be considered one 796 * standard deviation. For example, if heading returns 60 degrees, and 797 * accuracy returns 10 degrees, then there is a 68 percent probability of 798 * the true heading being between 50 degrees and 70 degrees. 799 * 800 * <ul> 801 * <li> values[0]: Measured heading in degrees.</li> 802 * <li> values[1]: Heading accuracy in degrees.</li> 803 * </ul> 804 * 805 * @see GeomagneticField 806 */ 807 public final float[] values; 808 809 /** 810 * The sensor that generated this event. See 811 * {@link android.hardware.SensorManager SensorManager} for details. 812 */ 813 public Sensor sensor; 814 815 /** 816 * The accuracy of this event. See {@link android.hardware.SensorManager 817 * SensorManager} for details. 818 */ 819 public int accuracy; 820 821 /** 822 * The time in nanoseconds at which the event happened. For a given sensor, 823 * each new sensor event should be monotonically increasing using the same 824 * time base as {@link android.os.SystemClock#elapsedRealtimeNanos()}. 825 */ 826 public long timestamp; 827 828 /** 829 * Set to true when this is the first sensor event after a discontinuity. 830 * 831 * The exact meaning of discontinuity depends on the sensor type. For 832 * {@link android.hardware.Sensor#TYPE_HEAD_TRACKER Sensor.TYPE_HEAD_TRACKER}, this means that 833 * the reference frame has suddenly and significantly changed, for example if the head tracking 834 * device was removed then put back. 835 * 836 * Note that this concept is either not relevant to or not supported by most sensor types, 837 * {@link android.hardware.Sensor#TYPE_HEAD_TRACKER Sensor.TYPE_HEAD_TRACKER} being the notable 838 * exception. 839 */ 840 @SuppressLint("MutableBareField") 841 public boolean firstEventAfterDiscontinuity; 842 843 @UnsupportedAppUsage SensorEvent(int valueSize)844 SensorEvent(int valueSize) { 845 values = new float[valueSize]; 846 } 847 848 /** 849 * Construct a sensor event object by sensor object, accuracy, timestamp and values. 850 * This is only used for constructing an input device sensor event object. 851 * @hide 852 */ SensorEvent(@onNull Sensor sensor, int accuracy, long timestamp, float[] values)853 public SensorEvent(@NonNull Sensor sensor, int accuracy, long timestamp, float[] values) { 854 this.sensor = sensor; 855 this.accuracy = accuracy; 856 this.timestamp = timestamp; 857 this.values = values; 858 } 859 } 860
