The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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 | |
Artur Satayev | 2695800 | 2019-12-10 17:47:52 +0000 | [diff] [blame] | 19 | import android.compat.annotation.UnsupportedAppUsage; |
Mathew Inwood | bcbe440 | 2018-08-08 15:42:59 +0100 | [diff] [blame] | 20 | |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 21 | /** |
Mathias Agopian | 74cde2c | 2010-06-16 18:55:46 -0700 | [diff] [blame] | 22 | * This class represents a {@link android.hardware.Sensor Sensor} event and |
Peng Xu | fb1c941 | 2016-03-29 21:50:43 -0700 | [diff] [blame] | 23 | * holds information such as the sensor's type, the time-stamp, accuracy and of |
Mathias Agopian | 74cde2c | 2010-06-16 18:55:46 -0700 | [diff] [blame] | 24 | * course the sensor's {@link SensorEvent#values data}. |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 25 | * |
Mathias Agopian | 74cde2c | 2010-06-16 18:55:46 -0700 | [diff] [blame] | 26 | * <p> |
| 27 | * <u>Definition of the coordinate system used by the SensorEvent API.</u> |
| 28 | * </p> |
| 29 | * |
| 30 | * <p> |
Mathias Agopian | 0f791a7 | 2010-06-22 21:55:01 -0700 | [diff] [blame] | 31 | * The coordinate-system is defined relative to the screen of the phone in its |
Mathias Agopian | 74cde2c | 2010-06-16 18:55:46 -0700 | [diff] [blame] | 32 | * default orientation. The axes are not swapped when the device's screen |
| 33 | * orientation changes. |
| 34 | * </p> |
| 35 | * |
| 36 | * <p> |
Mathias Agopian | 0f791a7 | 2010-06-22 21:55:01 -0700 | [diff] [blame] | 37 | * The X axis is horizontal and points to the right, the Y axis is vertical and |
| 38 | * points up and the Z axis points towards the outside of the front face of the |
| 39 | * screen. In this system, coordinates behind the screen have negative Z values. |
| 40 | * </p> |
| 41 | * |
| 42 | * <p> |
| 43 | * <center><img src="../../../images/axis_device.png" |
| 44 | * alt="Sensors coordinate-system diagram." border="0" /></center> |
Mathias Agopian | 74cde2c | 2010-06-16 18:55:46 -0700 | [diff] [blame] | 45 | * </p> |
| 46 | * |
| 47 | * <p> |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 48 | * <b>Note:</b> This coordinate system is different from the one used in the |
Mathias Agopian | 74cde2c | 2010-06-16 18:55:46 -0700 | [diff] [blame] | 49 | * Android 2D APIs where the origin is in the top-left corner. |
| 50 | * </p> |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 51 | * |
Mathias Agopian | 0f791a7 | 2010-06-22 21:55:01 -0700 | [diff] [blame] | 52 | * @see SensorManager |
| 53 | * @see SensorEvent |
| 54 | * @see Sensor |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 55 | * |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 56 | */ |
| 57 | |
| 58 | public class SensorEvent { |
| 59 | /** |
Mathias Agopian | 74cde2c | 2010-06-16 18:55:46 -0700 | [diff] [blame] | 60 | * <p> |
Mathias Agopian | 0f791a7 | 2010-06-22 21:55:01 -0700 | [diff] [blame] | 61 | * The length and contents of the {@link #values values} array depends on |
| 62 | * which {@link android.hardware.Sensor sensor} type is being monitored (see |
| 63 | * also {@link SensorEvent} for a definition of the coordinate system used). |
Mathias Agopian | 74cde2c | 2010-06-16 18:55:46 -0700 | [diff] [blame] | 64 | * </p> |
Mathias Agopian | 210fc91 | 2010-02-26 13:51:39 -0800 | [diff] [blame] | 65 | * |
Mathias Agopian | 0f791a7 | 2010-06-22 21:55:01 -0700 | [diff] [blame] | 66 | * <h4>{@link android.hardware.Sensor#TYPE_ACCELEROMETER |
| 67 | * Sensor.TYPE_ACCELEROMETER}:</h4> All values are in SI units (m/s^2) |
kmccormick | 5d555a7 | 2013-04-24 16:52:43 -0700 | [diff] [blame] | 68 | * |
Mathias Agopian | 74cde2c | 2010-06-16 18:55:46 -0700 | [diff] [blame] | 69 | * <ul> |
Jaikumar Ganesh | 9a8df4d | 2013-02-12 16:31:32 -0800 | [diff] [blame] | 70 | * <li> values[0]: Acceleration minus Gx on the x-axis </li> |
| 71 | * <li> values[1]: Acceleration minus Gy on the y-axis </li> |
| 72 | * <li> values[2]: Acceleration minus Gz on the z-axis </li> |
Mathias Agopian | 74cde2c | 2010-06-16 18:55:46 -0700 | [diff] [blame] | 73 | * </ul> |
kmccormick | 5d555a7 | 2013-04-24 16:52:43 -0700 | [diff] [blame] | 74 | * |
Mathias Agopian | 74cde2c | 2010-06-16 18:55:46 -0700 | [diff] [blame] | 75 | * <p> |
Mathias Agopian | 0f791a7 | 2010-06-22 21:55:01 -0700 | [diff] [blame] | 76 | * A sensor of this type measures the acceleration applied to the device |
| 77 | * (<b>Ad</b>). Conceptually, it does so by measuring forces applied to the |
| 78 | * sensor itself (<b>Fs</b>) using the relation: |
| 79 | * </p> |
kmccormick | 5d555a7 | 2013-04-24 16:52:43 -0700 | [diff] [blame] | 80 | * |
Brad Fitzpatrick | 612ff27 | 2010-09-06 19:22:09 -0700 | [diff] [blame] | 81 | * <b><center>Ad = - ∑Fs / mass</center></b> |
kmccormick | 5d555a7 | 2013-04-24 16:52:43 -0700 | [diff] [blame] | 82 | * |
Mathias Agopian | 0f791a7 | 2010-06-22 21:55:01 -0700 | [diff] [blame] | 83 | * <p> |
| 84 | * In particular, the force of gravity is always influencing the measured |
| 85 | * acceleration: |
| 86 | * </p> |
kmccormick | 5d555a7 | 2013-04-24 16:52:43 -0700 | [diff] [blame] | 87 | * |
Brad Fitzpatrick | 612ff27 | 2010-09-06 19:22:09 -0700 | [diff] [blame] | 88 | * <b><center>Ad = -g - ∑F / mass</center></b> |
kmccormick | 5d555a7 | 2013-04-24 16:52:43 -0700 | [diff] [blame] | 89 | * |
Mathias Agopian | 0f791a7 | 2010-06-22 21:55:01 -0700 | [diff] [blame] | 90 | * <p> |
| 91 | * For this reason, when the device is sitting on a table (and obviously not |
| 92 | * accelerating), the accelerometer reads a magnitude of <b>g</b> = 9.81 |
| 93 | * m/s^2 |
| 94 | * </p> |
kmccormick | 5d555a7 | 2013-04-24 16:52:43 -0700 | [diff] [blame] | 95 | * |
Mathias Agopian | 0f791a7 | 2010-06-22 21:55:01 -0700 | [diff] [blame] | 96 | * <p> |
| 97 | * Similarly, when the device is in free-fall and therefore dangerously |
| 98 | * accelerating towards to ground at 9.81 m/s^2, its accelerometer reads a |
| 99 | * magnitude of 0 m/s^2. |
| 100 | * </p> |
kmccormick | 5d555a7 | 2013-04-24 16:52:43 -0700 | [diff] [blame] | 101 | * |
Mathias Agopian | 0f791a7 | 2010-06-22 21:55:01 -0700 | [diff] [blame] | 102 | * <p> |
| 103 | * It should be apparent that in order to measure the real acceleration of |
| 104 | * the device, the contribution of the force of gravity must be eliminated. |
| 105 | * This can be achieved by applying a <i>high-pass</i> filter. Conversely, a |
| 106 | * <i>low-pass</i> filter can be used to isolate the force of gravity. |
| 107 | * </p> |
Mathias Agopian | fa33565 | 2010-11-09 13:40:41 -0800 | [diff] [blame] | 108 | * |
| 109 | * <pre class="prettyprint"> |
| 110 | * |
| 111 | * public void onSensorChanged(SensorEvent event) |
| 112 | * { |
| 113 | * // alpha is calculated as t / (t + dT) |
| 114 | * // with t, the low-pass filter's time-constant |
| 115 | * // and dT, the event delivery rate |
| 116 | * |
| 117 | * final float alpha = 0.8; |
| 118 | * |
Scott Main | d11ee90 | 2011-02-23 10:55:17 -0800 | [diff] [blame] | 119 | * gravity[0] = alpha * gravity[0] + (1 - alpha) * event.values[0]; |
| 120 | * gravity[1] = alpha * gravity[1] + (1 - alpha) * event.values[1]; |
| 121 | * gravity[2] = alpha * gravity[2] + (1 - alpha) * event.values[2]; |
Mathias Agopian | fa33565 | 2010-11-09 13:40:41 -0800 | [diff] [blame] | 122 | * |
Scott Main | d11ee90 | 2011-02-23 10:55:17 -0800 | [diff] [blame] | 123 | * linear_acceleration[0] = event.values[0] - gravity[0]; |
| 124 | * linear_acceleration[1] = event.values[1] - gravity[1]; |
| 125 | * linear_acceleration[2] = event.values[2] - gravity[2]; |
Mathias Agopian | fa33565 | 2010-11-09 13:40:41 -0800 | [diff] [blame] | 126 | * } |
| 127 | * </pre> |
| 128 | * |
Mathias Agopian | 0f791a7 | 2010-06-22 21:55:01 -0700 | [diff] [blame] | 129 | * <p> |
| 130 | * <u>Examples</u>: |
| 131 | * <ul> |
| 132 | * <li>When the device lies flat on a table and is pushed on its left side |
| 133 | * toward the right, the x acceleration value is positive.</li> |
kmccormick | 5d555a7 | 2013-04-24 16:52:43 -0700 | [diff] [blame] | 134 | * |
Mathias Agopian | 0f791a7 | 2010-06-22 21:55:01 -0700 | [diff] [blame] | 135 | * <li>When the device lies flat on a table, the acceleration value is |
| 136 | * +9.81, which correspond to the acceleration of the device (0 m/s^2) minus |
| 137 | * the force of gravity (-9.81 m/s^2).</li> |
kmccormick | 5d555a7 | 2013-04-24 16:52:43 -0700 | [diff] [blame] | 138 | * |
Mathias Agopian | 0f791a7 | 2010-06-22 21:55:01 -0700 | [diff] [blame] | 139 | * <li>When the device lies flat on a table and is pushed toward the sky |
| 140 | * with an acceleration of A m/s^2, the acceleration value is equal to |
| 141 | * A+9.81 which correspond to the acceleration of the device (+A m/s^2) |
| 142 | * minus the force of gravity (-9.81 m/s^2).</li> |
| 143 | * </ul> |
kmccormick | 5d555a7 | 2013-04-24 16:52:43 -0700 | [diff] [blame] | 144 | * |
| 145 | * |
Mathias Agopian | 0f791a7 | 2010-06-22 21:55:01 -0700 | [diff] [blame] | 146 | * <h4>{@link android.hardware.Sensor#TYPE_MAGNETIC_FIELD |
| 147 | * Sensor.TYPE_MAGNETIC_FIELD}:</h4> |
| 148 | * All values are in micro-Tesla (uT) and measure the ambient magnetic field |
| 149 | * in the X, Y and Z axis. |
kmccormick | 5d555a7 | 2013-04-24 16:52:43 -0700 | [diff] [blame] | 150 | * |
Mathias Agopian | ad7f33a | 2011-09-07 15:56:03 -0700 | [diff] [blame] | 151 | * <h4>{@link android.hardware.Sensor#TYPE_GYROSCOPE Sensor.TYPE_GYROSCOPE}: |
| 152 | * </h4> All values are in radians/second and measure the rate of rotation |
| 153 | * around the device's local X, Y and Z axis. The coordinate system is the |
| 154 | * same as is used for the acceleration sensor. Rotation is positive in the |
| 155 | * counter-clockwise direction. That is, an observer looking from some |
| 156 | * positive location on the x, y or z axis at a device positioned on the |
| 157 | * origin would report positive rotation if the device appeared to be |
| 158 | * rotating counter clockwise. Note that this is the standard mathematical |
| 159 | * definition of positive rotation and does not agree with the definition of |
| 160 | * roll given earlier. |
Mathias Agopian | fa33565 | 2010-11-09 13:40:41 -0800 | [diff] [blame] | 161 | * <ul> |
Jaikumar Ganesh | 9a8df4d | 2013-02-12 16:31:32 -0800 | [diff] [blame] | 162 | * <li> values[0]: Angular speed around the x-axis </li> |
| 163 | * <li> values[1]: Angular speed around the y-axis </li> |
| 164 | * <li> values[2]: Angular speed around the z-axis </li> |
Mathias Agopian | fa33565 | 2010-11-09 13:40:41 -0800 | [diff] [blame] | 165 | * </ul> |
| 166 | * <p> |
Mathias Agopian | ad7f33a | 2011-09-07 15:56:03 -0700 | [diff] [blame] | 167 | * Typically the output of the gyroscope is integrated over time to |
Peng Xu | fb1c941 | 2016-03-29 21:50:43 -0700 | [diff] [blame] | 168 | * calculate a rotation describing the change of angles over the time step, |
Mathias Agopian | ad7f33a | 2011-09-07 15:56:03 -0700 | [diff] [blame] | 169 | * for example: |
Mathias Agopian | fa33565 | 2010-11-09 13:40:41 -0800 | [diff] [blame] | 170 | * </p> |
Mathias Agopian | ad7f33a | 2011-09-07 15:56:03 -0700 | [diff] [blame] | 171 | * |
Mathias Agopian | fa33565 | 2010-11-09 13:40:41 -0800 | [diff] [blame] | 172 | * <pre class="prettyprint"> |
| 173 | * private static final float NS2S = 1.0f / 1000000000.0f; |
Mathias Agopian | ad7f33a | 2011-09-07 15:56:03 -0700 | [diff] [blame] | 174 | * private final float[] deltaRotationVector = new float[4](); |
Mathias Agopian | fa33565 | 2010-11-09 13:40:41 -0800 | [diff] [blame] | 175 | * private float timestamp; |
Mathias Agopian | ad7f33a | 2011-09-07 15:56:03 -0700 | [diff] [blame] | 176 | * |
| 177 | * public void onSensorChanged(SensorEvent event) { |
Peng Xu | fb1c941 | 2016-03-29 21:50:43 -0700 | [diff] [blame] | 178 | * // This time step's delta rotation to be multiplied by the current rotation |
Mathias Agopian | ad7f33a | 2011-09-07 15:56:03 -0700 | [diff] [blame] | 179 | * // after computing it from the gyro sample data. |
Mathias Agopian | fa33565 | 2010-11-09 13:40:41 -0800 | [diff] [blame] | 180 | * if (timestamp != 0) { |
| 181 | * final float dT = (event.timestamp - timestamp) * NS2S; |
Mathias Agopian | ad7f33a | 2011-09-07 15:56:03 -0700 | [diff] [blame] | 182 | * // Axis of the rotation sample, not normalized yet. |
| 183 | * float axisX = event.values[0]; |
| 184 | * float axisY = event.values[1]; |
| 185 | * float axisZ = event.values[2]; |
| 186 | * |
| 187 | * // Calculate the angular speed of the sample |
| 188 | * float omegaMagnitude = sqrt(axisX*axisX + axisY*axisY + axisZ*axisZ); |
| 189 | * |
| 190 | * // Normalize the rotation vector if it's big enough to get the axis |
| 191 | * if (omegaMagnitude > EPSILON) { |
| 192 | * axisX /= omegaMagnitude; |
| 193 | * axisY /= omegaMagnitude; |
| 194 | * axisZ /= omegaMagnitude; |
| 195 | * } |
| 196 | * |
Peng Xu | fb1c941 | 2016-03-29 21:50:43 -0700 | [diff] [blame] | 197 | * // Integrate around this axis with the angular speed by the time step |
| 198 | * // in order to get a delta rotation from this sample over the time step |
Mathias Agopian | ad7f33a | 2011-09-07 15:56:03 -0700 | [diff] [blame] | 199 | * // We will convert this axis-angle representation of the delta rotation |
| 200 | * // into a quaternion before turning it into the rotation matrix. |
| 201 | * float thetaOverTwo = omegaMagnitude * dT / 2.0f; |
| 202 | * float sinThetaOverTwo = sin(thetaOverTwo); |
| 203 | * float cosThetaOverTwo = cos(thetaOverTwo); |
| 204 | * deltaRotationVector[0] = sinThetaOverTwo * axisX; |
| 205 | * deltaRotationVector[1] = sinThetaOverTwo * axisY; |
| 206 | * deltaRotationVector[2] = sinThetaOverTwo * axisZ; |
| 207 | * deltaRotationVector[3] = cosThetaOverTwo; |
Mathias Agopian | fa33565 | 2010-11-09 13:40:41 -0800 | [diff] [blame] | 208 | * } |
| 209 | * timestamp = event.timestamp; |
Mathias Agopian | ad7f33a | 2011-09-07 15:56:03 -0700 | [diff] [blame] | 210 | * float[] deltaRotationMatrix = new float[9]; |
| 211 | * SensorManager.getRotationMatrixFromVector(deltaRotationMatrix, deltaRotationVector); |
Peng Xu | 62f2c87 | 2017-09-22 11:50:33 -0700 | [diff] [blame] | 212 | * // User code should concatenate the delta rotation we computed with the current |
| 213 | * // rotation in order to get the updated rotation. |
Mathias Agopian | ad7f33a | 2011-09-07 15:56:03 -0700 | [diff] [blame] | 214 | * // rotationCurrent = rotationCurrent * deltaRotationMatrix; |
Mathias Agopian | fa33565 | 2010-11-09 13:40:41 -0800 | [diff] [blame] | 215 | * } |
| 216 | * </pre> |
Mathias Agopian | ad7f33a | 2011-09-07 15:56:03 -0700 | [diff] [blame] | 217 | * <p> |
| 218 | * In practice, the gyroscope noise and offset will introduce some errors |
| 219 | * which need to be compensated for. This is usually done using the |
| 220 | * information from other sensors, but is beyond the scope of this document. |
| 221 | * </p> |
Mathias Agopian | 0f791a7 | 2010-06-22 21:55:01 -0700 | [diff] [blame] | 222 | * <h4>{@link android.hardware.Sensor#TYPE_LIGHT Sensor.TYPE_LIGHT}:</h4> |
Mathias Agopian | 0f791a7 | 2010-06-22 21:55:01 -0700 | [diff] [blame] | 223 | * <ul> |
Jaikumar Ganesh | 9a8df4d | 2013-02-12 16:31:32 -0800 | [diff] [blame] | 224 | * <li>values[0]: Ambient light level in SI lux units </li> |
Mathias Agopian | 0f791a7 | 2010-06-22 21:55:01 -0700 | [diff] [blame] | 225 | * </ul> |
kmccormick | 5d555a7 | 2013-04-24 16:52:43 -0700 | [diff] [blame] | 226 | * |
Mathias Agopian | 1260a89 | 2011-05-02 18:57:38 -0700 | [diff] [blame] | 227 | * <h4>{@link android.hardware.Sensor#TYPE_PRESSURE Sensor.TYPE_PRESSURE}:</h4> |
| 228 | * <ul> |
Jaikumar Ganesh | 9a8df4d | 2013-02-12 16:31:32 -0800 | [diff] [blame] | 229 | * <li>values[0]: Atmospheric pressure in hPa (millibar) </li> |
Mathias Agopian | 1260a89 | 2011-05-02 18:57:38 -0700 | [diff] [blame] | 230 | * </ul> |
| 231 | * |
Mathias Agopian | 0f791a7 | 2010-06-22 21:55:01 -0700 | [diff] [blame] | 232 | * <h4>{@link android.hardware.Sensor#TYPE_PROXIMITY Sensor.TYPE_PROXIMITY}: |
| 233 | * </h4> |
kmccormick | 5d555a7 | 2013-04-24 16:52:43 -0700 | [diff] [blame] | 234 | * |
Mathias Agopian | 0f791a7 | 2010-06-22 21:55:01 -0700 | [diff] [blame] | 235 | * <ul> |
Jaikumar Ganesh | 9a8df4d | 2013-02-12 16:31:32 -0800 | [diff] [blame] | 236 | * <li>values[0]: Proximity sensor distance measured in centimeters </li> |
Mathias Agopian | 0f791a7 | 2010-06-22 21:55:01 -0700 | [diff] [blame] | 237 | * </ul> |
kmccormick | 5d555a7 | 2013-04-24 16:52:43 -0700 | [diff] [blame] | 238 | * |
Mathias Agopian | 0f791a7 | 2010-06-22 21:55:01 -0700 | [diff] [blame] | 239 | * <p> |
| 240 | * <b>Note:</b> Some proximity sensors only support a binary <i>near</i> or |
| 241 | * <i>far</i> measurement. In this case, the sensor should report its |
| 242 | * {@link android.hardware.Sensor#getMaximumRange() maximum range} value in |
| 243 | * the <i>far</i> state and a lesser value in the <i>near</i> state. |
| 244 | * </p> |
kmccormick | 5d555a7 | 2013-04-24 16:52:43 -0700 | [diff] [blame] | 245 | * |
Kevin Powell | 7a0541d | 2010-07-19 19:10:40 -0700 | [diff] [blame] | 246 | * <h4>{@link android.hardware.Sensor#TYPE_GRAVITY Sensor.TYPE_GRAVITY}:</h4> |
Mathias Agopian | 7badd2c | 2010-11-22 15:48:10 -0800 | [diff] [blame] | 247 | * <p>A three dimensional vector indicating the direction and magnitude of gravity. Units |
| 248 | * are m/s^2. The coordinate system is the same as is used by the acceleration sensor.</p> |
Peng Xu | 62f2c87 | 2017-09-22 11:50:33 -0700 | [diff] [blame] | 249 | * <p><b>Note:</b> When the device is at rest, the output of the gravity sensor should be |
| 250 | * identical to that of the accelerometer.</p> |
Kevin Powell | 7a0541d | 2010-07-19 19:10:40 -0700 | [diff] [blame] | 251 | * |
Peng Xu | 62f2c87 | 2017-09-22 11:50:33 -0700 | [diff] [blame] | 252 | * <h4> |
| 253 | * {@link android.hardware.Sensor#TYPE_LINEAR_ACCELERATION Sensor.TYPE_LINEAR_ACCELERATION}: |
| 254 | * </h4> A three dimensional vector indicating acceleration along each device axis, not |
| 255 | * including gravity. All values have units of m/s^2. The coordinate system is the same as is |
| 256 | * used by the acceleration sensor. |
Mathias Agopian | 7badd2c | 2010-11-22 15:48:10 -0800 | [diff] [blame] | 257 | * <p>The output of the accelerometer, gravity and linear-acceleration sensors must obey the |
| 258 | * following relation:</p> |
Peng Xu | 62f2c87 | 2017-09-22 11:50:33 -0700 | [diff] [blame] | 259 | * <p><ul>acceleration = gravity + linear-acceleration</ul></p> |
Kevin Powell | 7a0541d | 2010-07-19 19:10:40 -0700 | [diff] [blame] | 260 | * |
| 261 | * <h4>{@link android.hardware.Sensor#TYPE_ROTATION_VECTOR Sensor.TYPE_ROTATION_VECTOR}:</h4> |
Peng Xu | 62f2c87 | 2017-09-22 11:50:33 -0700 | [diff] [blame] | 262 | * <p>The rotation vector represents the orientation of the device as a combination of an |
| 263 | * <i>angle</i> and an <i>axis</i>, in which the device has rotated through an angle θ |
| 264 | * around an axis <x, y, z>.</p> |
Mathias Agopian | 7badd2c | 2010-11-22 15:48:10 -0800 | [diff] [blame] | 265 | * <p>The three elements of the rotation vector are |
| 266 | * <x*sin(θ/2), y*sin(θ/2), z*sin(θ/2)>, such that the magnitude of the rotation |
| 267 | * vector is equal to sin(θ/2), and the direction of the rotation vector is equal to the |
| 268 | * direction of the axis of rotation.</p> |
| 269 | * </p>The three elements of the rotation vector are equal to |
| 270 | * the last three components of a <b>unit</b> quaternion |
| 271 | * <cos(θ/2), x*sin(θ/2), y*sin(θ/2), z*sin(θ/2)>.</p> |
| 272 | * <p>Elements of the rotation vector are unitless. |
| 273 | * The x,y, and z axis are defined in the same way as the acceleration |
| 274 | * sensor.</p> |
Mathias Agopian | d84d2b7b | 2011-05-02 19:08:53 -0700 | [diff] [blame] | 275 | * The reference coordinate system is defined as a direct orthonormal basis, |
| 276 | * where: |
| 277 | * </p> |
| 278 | * |
| 279 | * <ul> |
| 280 | * <li>X is defined as the vector product <b>Y.Z</b> (It is tangential to |
| 281 | * the ground at the device's current location and roughly points East).</li> |
| 282 | * <li>Y is tangential to the ground at the device's current location and |
Scott Main | 52bfc24 | 2012-02-09 10:09:14 -0800 | [diff] [blame] | 283 | * points towards magnetic north.</li> |
Mathias Agopian | d84d2b7b | 2011-05-02 19:08:53 -0700 | [diff] [blame] | 284 | * <li>Z points towards the sky and is perpendicular to the ground.</li> |
| 285 | * </ul> |
| 286 | * |
| 287 | * <p> |
| 288 | * <center><img src="../../../images/axis_globe.png" |
| 289 | * alt="World coordinate-system diagram." border="0" /></center> |
| 290 | * </p> |
| 291 | * |
Mathias Agopian | 7badd2c | 2010-11-22 15:48:10 -0800 | [diff] [blame] | 292 | * <ul> |
Jaikumar Ganesh | 9a8df4d | 2013-02-12 16:31:32 -0800 | [diff] [blame] | 293 | * <li> values[0]: x*sin(θ/2) </li> |
| 294 | * <li> values[1]: y*sin(θ/2) </li> |
| 295 | * <li> values[2]: z*sin(θ/2) </li> |
Jaikumar Ganesh | 6d0c1d78 | 2013-03-27 17:41:33 -0700 | [diff] [blame] | 296 | * <li> values[3]: cos(θ/2) </li> |
| 297 | * <li> values[4]: estimated heading Accuracy (in radians) (-1 if unavailable)</li> |
Mathias Agopian | 7badd2c | 2010-11-22 15:48:10 -0800 | [diff] [blame] | 298 | * </ul> |
Jaikumar Ganesh | 6d0c1d78 | 2013-03-27 17:41:33 -0700 | [diff] [blame] | 299 | * <p> values[3], originally optional, will always be present from SDK Level 18 onwards. |
| 300 | * values[4] is a new value that has been added in SDK Level 18. |
| 301 | * </p> |
Kevin Powell | 7a0541d | 2010-07-19 19:10:40 -0700 | [diff] [blame] | 302 | * |
Mathias Agopian | 0f791a7 | 2010-06-22 21:55:01 -0700 | [diff] [blame] | 303 | * <h4>{@link android.hardware.Sensor#TYPE_ORIENTATION |
| 304 | * Sensor.TYPE_ORIENTATION}:</h4> All values are angles in degrees. |
kmccormick | 5d555a7 | 2013-04-24 16:52:43 -0700 | [diff] [blame] | 305 | * |
Mathias Agopian | 0f791a7 | 2010-06-22 21:55:01 -0700 | [diff] [blame] | 306 | * <ul> |
Jaikumar Ganesh | 9a8df4d | 2013-02-12 16:31:32 -0800 | [diff] [blame] | 307 | * <li> values[0]: Azimuth, angle between the magnetic north direction and the |
Mathias Agopian | 0f791a7 | 2010-06-22 21:55:01 -0700 | [diff] [blame] | 308 | * y-axis, around the z-axis (0 to 359). 0=North, 90=East, 180=South, |
kmccormick | 5d555a7 | 2013-04-24 16:52:43 -0700 | [diff] [blame] | 309 | * 270=West |
| 310 | * </p> |
| 311 | * |
| 312 | * <p> |
| 313 | * values[1]: Pitch, rotation around x-axis (-180 to 180), with positive |
| 314 | * values when the z-axis moves <b>toward</b> the y-axis. |
| 315 | * </p> |
| 316 | * |
| 317 | * <p> |
Peng Xu | ca09d8c | 2015-05-21 18:06:06 -0700 | [diff] [blame] | 318 | * values[2]: Roll, rotation around the y-axis (-90 to 90) |
kmccormick | 5d555a7 | 2013-04-24 16:52:43 -0700 | [diff] [blame] | 319 | * increasing as the device moves clockwise. |
| 320 | * </p> |
Mathias Agopian | 0f791a7 | 2010-06-22 21:55:01 -0700 | [diff] [blame] | 321 | * </ul> |
kmccormick | 5d555a7 | 2013-04-24 16:52:43 -0700 | [diff] [blame] | 322 | * |
Mathias Agopian | 74cde2c | 2010-06-16 18:55:46 -0700 | [diff] [blame] | 323 | * <p> |
| 324 | * <b>Note:</b> This definition is different from <b>yaw, pitch and roll</b> |
| 325 | * used in aviation where the X axis is along the long side of the plane |
| 326 | * (tail to nose). |
Mathias Agopian | 0f791a7 | 2010-06-22 21:55:01 -0700 | [diff] [blame] | 327 | * </p> |
kmccormick | 5d555a7 | 2013-04-24 16:52:43 -0700 | [diff] [blame] | 328 | * |
Mathias Agopian | 74cde2c | 2010-06-16 18:55:46 -0700 | [diff] [blame] | 329 | * <p> |
| 330 | * <b>Note:</b> This sensor type exists for legacy reasons, please use |
Peng Xu | ca09d8c | 2015-05-21 18:06:06 -0700 | [diff] [blame] | 331 | * {@link android.hardware.Sensor#TYPE_ROTATION_VECTOR |
| 332 | * rotation vector sensor type} and |
Mathias Agopian | 74cde2c | 2010-06-16 18:55:46 -0700 | [diff] [blame] | 333 | * {@link android.hardware.SensorManager#getRotationMatrix |
| 334 | * getRotationMatrix()} in conjunction with |
| 335 | * {@link android.hardware.SensorManager#remapCoordinateSystem |
| 336 | * remapCoordinateSystem()} and |
| 337 | * {@link android.hardware.SensorManager#getOrientation getOrientation()} to |
| 338 | * compute these values instead. |
Mathias Agopian | 0f791a7 | 2010-06-22 21:55:01 -0700 | [diff] [blame] | 339 | * </p> |
kmccormick | 5d555a7 | 2013-04-24 16:52:43 -0700 | [diff] [blame] | 340 | * |
Mathias Agopian | 74cde2c | 2010-06-16 18:55:46 -0700 | [diff] [blame] | 341 | * <p> |
Mathias Agopian | 0f791a7 | 2010-06-22 21:55:01 -0700 | [diff] [blame] | 342 | * <b>Important note:</b> For historical reasons the roll angle is positive |
| 343 | * in the clockwise direction (mathematically speaking, it should be |
| 344 | * positive in the counter-clockwise direction). |
| 345 | * </p> |
Urs Fleisch | 5819051 | 2010-12-29 17:02:02 +0100 | [diff] [blame] | 346 | * |
| 347 | * <h4>{@link android.hardware.Sensor#TYPE_RELATIVE_HUMIDITY |
| 348 | * Sensor.TYPE_RELATIVE_HUMIDITY}:</h4> |
| 349 | * <ul> |
Jaikumar Ganesh | 9a8df4d | 2013-02-12 16:31:32 -0800 | [diff] [blame] | 350 | * <li> values[0]: Relative ambient air humidity in percent </li> |
Urs Fleisch | 5819051 | 2010-12-29 17:02:02 +0100 | [diff] [blame] | 351 | * </ul> |
| 352 | * <p> |
| 353 | * When relative ambient air humidity and ambient temperature are |
| 354 | * measured, the dew point and absolute humidity can be calculated. |
| 355 | * </p> |
| 356 | * <u>Dew Point</u> |
| 357 | * <p> |
| 358 | * The dew point is the temperature to which a given parcel of air must be |
| 359 | * cooled, at constant barometric pressure, for water vapor to condense |
| 360 | * into water. |
| 361 | * </p> |
| 362 | * <center><pre> |
| 363 | * ln(RH/100%) + m·t/(T<sub>n</sub>+t) |
| 364 | * t<sub>d</sub>(t,RH) = T<sub>n</sub> · ------------------------------ |
| 365 | * m - [ln(RH/100%) + m·t/(T<sub>n</sub>+t)] |
| 366 | * </pre></center> |
| 367 | * <dl> |
| 368 | * <dt>t<sub>d</sub></dt> <dd>dew point temperature in °C</dd> |
| 369 | * <dt>t</dt> <dd>actual temperature in °C</dd> |
| 370 | * <dt>RH</dt> <dd>actual relative humidity in %</dd> |
| 371 | * <dt>m</dt> <dd>17.62</dd> |
| 372 | * <dt>T<sub>n</sub></dt> <dd>243.12 °C</dd> |
| 373 | * </dl> |
| 374 | * <p>for example:</p> |
| 375 | * <pre class="prettyprint"> |
| 376 | * h = Math.log(rh / 100.0) + (17.62 * t) / (243.12 + t); |
| 377 | * td = 243.12 * h / (17.62 - h); |
| 378 | * </pre> |
| 379 | * <u>Absolute Humidity</u> |
| 380 | * <p> |
| 381 | * The absolute humidity is the mass of water vapor in a particular volume |
| 382 | * of dry air. The unit is g/m<sup>3</sup>. |
| 383 | * </p> |
| 384 | * <center><pre> |
| 385 | * RH/100%·A·exp(m·t/(T<sub>n</sub>+t)) |
| 386 | * d<sub>v</sub>(t,RH) = 216.7 · ------------------------- |
| 387 | * 273.15 + t |
| 388 | * </pre></center> |
| 389 | * <dl> |
| 390 | * <dt>d<sub>v</sub></dt> <dd>absolute humidity in g/m<sup>3</sup></dd> |
| 391 | * <dt>t</dt> <dd>actual temperature in °C</dd> |
| 392 | * <dt>RH</dt> <dd>actual relative humidity in %</dd> |
| 393 | * <dt>m</dt> <dd>17.62</dd> |
| 394 | * <dt>T<sub>n</sub></dt> <dd>243.12 °C</dd> |
| 395 | * <dt>A</dt> <dd>6.112 hPa</dd> |
| 396 | * </dl> |
| 397 | * <p>for example:</p> |
| 398 | * <pre class="prettyprint"> |
| 399 | * dv = 216.7 * |
| 400 | * (rh / 100.0 * 6.112 * Math.exp(17.62 * t / (243.12 + t)) / (273.15 + t)); |
| 401 | * </pre> |
Ashutosh Joshi | af1a266 | 2016-01-25 20:24:20 -0800 | [diff] [blame] | 402 | * |
Mathias Agopian | 462db22 | 2011-03-22 18:44:26 -0700 | [diff] [blame] | 403 | * <h4>{@link android.hardware.Sensor#TYPE_AMBIENT_TEMPERATURE Sensor.TYPE_AMBIENT_TEMPERATURE}: |
| 404 | * </h4> |
| 405 | * |
| 406 | * <ul> |
Jaikumar Ganesh | 9a8df4d | 2013-02-12 16:31:32 -0800 | [diff] [blame] | 407 | * <li> values[0]: ambient (room) temperature in degree Celsius.</li> |
Mathias Agopian | 462db22 | 2011-03-22 18:44:26 -0700 | [diff] [blame] | 408 | * </ul> |
| 409 | * |
Jaikumar Ganesh | 9a8df4d | 2013-02-12 16:31:32 -0800 | [diff] [blame] | 410 | * |
Scott Main | 92053f8 | 2013-06-13 16:32:50 -0700 | [diff] [blame] | 411 | * <h4>{@link android.hardware.Sensor#TYPE_MAGNETIC_FIELD_UNCALIBRATED |
| 412 | * Sensor.TYPE_MAGNETIC_FIELD_UNCALIBRATED}:</h4> |
Jaikumar Ganesh | 6d0c1d78 | 2013-03-27 17:41:33 -0700 | [diff] [blame] | 413 | * Similar to {@link android.hardware.Sensor#TYPE_MAGNETIC_FIELD}, |
| 414 | * but the hard iron calibration is reported separately instead of being included |
| 415 | * in the measurement. Factory calibration and temperature compensation will still |
| 416 | * be applied to the "uncalibrated" measurement. Assumptions that the magnetic field |
| 417 | * is due to the Earth's poles is avoided. |
Jaikumar Ganesh | 9a8df4d | 2013-02-12 16:31:32 -0800 | [diff] [blame] | 418 | * <p> |
Jaikumar Ganesh | 6d0c1d78 | 2013-03-27 17:41:33 -0700 | [diff] [blame] | 419 | * The values array is shown below: |
| 420 | * <ul> |
| 421 | * <li> values[0] = x_uncalib </li> |
| 422 | * <li> values[1] = y_uncalib </li> |
| 423 | * <li> values[2] = z_uncalib </li> |
| 424 | * <li> values[3] = x_bias </li> |
| 425 | * <li> values[4] = y_bias </li> |
| 426 | * <li> values[5] = z_bias </li> |
| 427 | * </ul> |
| 428 | * </p> |
| 429 | * <p> |
| 430 | * x_uncalib, y_uncalib, z_uncalib are the measured magnetic field in X, Y, Z axes. |
| 431 | * Soft iron and temperature calibrations are applied. But the hard iron |
| 432 | * calibration is not applied. The values are in micro-Tesla (uT). |
| 433 | * </p> |
| 434 | * <p> |
| 435 | * x_bias, y_bias, z_bias give the iron bias estimated in X, Y, Z axes. |
| 436 | * Each field is a component of the estimated hard iron calibration. |
| 437 | * The values are in micro-Tesla (uT). |
| 438 | * </p> |
Peng Xu | fb1c941 | 2016-03-29 21:50:43 -0700 | [diff] [blame] | 439 | * <p> Hard iron - These distortions arise due to the magnetized iron, steel or permanent |
Jaikumar Ganesh | 6d0c1d78 | 2013-03-27 17:41:33 -0700 | [diff] [blame] | 440 | * magnets on the device. |
Peng Xu | fb1c941 | 2016-03-29 21:50:43 -0700 | [diff] [blame] | 441 | * Soft iron - These distortions arise due to the interaction with the earth's magnetic |
Jaikumar Ganesh | 6d0c1d78 | 2013-03-27 17:41:33 -0700 | [diff] [blame] | 442 | * field. |
| 443 | * </p> |
Ashutosh Joshi | 576ea41 | 2017-01-13 17:06:41 -0800 | [diff] [blame] | 444 | * <h4> {@link android.hardware.Sensor#TYPE_GAME_ROTATION_VECTOR |
| 445 | * Sensor.TYPE_GAME_ROTATION_VECTOR}:</h4> |
Jaikumar Ganesh | 6d0c1d78 | 2013-03-27 17:41:33 -0700 | [diff] [blame] | 446 | * Identical to {@link android.hardware.Sensor#TYPE_ROTATION_VECTOR} except that it |
| 447 | * doesn't use the geomagnetic field. Therefore the Y axis doesn't |
| 448 | * point north, but instead to some other reference, that reference is |
| 449 | * allowed to drift by the same order of magnitude as the gyroscope |
| 450 | * drift around the Z axis. |
| 451 | * <p> |
| 452 | * In the ideal case, a phone rotated and returning to the same real-world |
| 453 | * orientation will report the same game rotation vector |
| 454 | * (without using the earth's geomagnetic field). However, the orientation |
| 455 | * may drift somewhat over time. See {@link android.hardware.Sensor#TYPE_ROTATION_VECTOR} |
| 456 | * for a detailed description of the values. This sensor will not have |
| 457 | * the estimated heading accuracy value. |
Jaikumar Ganesh | 9a8df4d | 2013-02-12 16:31:32 -0800 | [diff] [blame] | 458 | * </p> |
| 459 | * |
Scott Main | 92053f8 | 2013-06-13 16:32:50 -0700 | [diff] [blame] | 460 | * <h4> {@link android.hardware.Sensor#TYPE_GYROSCOPE_UNCALIBRATED |
| 461 | * Sensor.TYPE_GYROSCOPE_UNCALIBRATED}:</h4> |
Jaikumar Ganesh | 9a8df4d | 2013-02-12 16:31:32 -0800 | [diff] [blame] | 462 | * All values are in radians/second and measure the rate of rotation |
| 463 | * around the X, Y and Z axis. An estimation of the drift on each axis is |
| 464 | * reported as well. |
| 465 | * <p> |
| 466 | * No gyro-drift compensation is performed. Factory calibration and temperature |
| 467 | * compensation is still applied to the rate of rotation (angular speeds). |
| 468 | * </p> |
| 469 | * <p> |
| 470 | * The coordinate system is the same as is used for the |
| 471 | * {@link android.hardware.Sensor#TYPE_ACCELEROMETER} |
| 472 | * Rotation is positive in the counter-clockwise direction (right-hand rule). |
| 473 | * That is, an observer looking from some positive location on the x, y or z axis |
| 474 | * at a device positioned on the origin would report positive rotation if the device |
| 475 | * appeared to be rotating counter clockwise. |
| 476 | * The range would at least be 17.45 rad/s (ie: ~1000 deg/s). |
| 477 | * <ul> |
| 478 | * <li> values[0] : angular speed (w/o drift compensation) around the X axis in rad/s </li> |
| 479 | * <li> values[1] : angular speed (w/o drift compensation) around the Y axis in rad/s </li> |
| 480 | * <li> values[2] : angular speed (w/o drift compensation) around the Z axis in rad/s </li> |
| 481 | * <li> values[3] : estimated drift around X axis in rad/s </li> |
| 482 | * <li> values[4] : estimated drift around Y axis in rad/s </li> |
| 483 | * <li> values[5] : estimated drift around Z axis in rad/s </li> |
| 484 | * </ul> |
| 485 | * </p> |
Scott Main | 92053f8 | 2013-06-13 16:32:50 -0700 | [diff] [blame] | 486 | * <p><b>Pro Tip:</b> Always use the length of the values array while performing operations |
| 487 | * on it. In earlier versions, this used to be always 3 which has changed now. </p> |
| 488 | * |
Ashutosh Joshi | 17efe02 | 2016-01-14 22:23:58 -0800 | [diff] [blame] | 489 | * <h4>{@link android.hardware.Sensor#TYPE_POSE_6DOF |
| 490 | * Sensor.TYPE_POSE_6DOF}:</h4> |
| 491 | * |
| 492 | * A TYPE_POSE_6DOF event consists of a rotation expressed as a quaternion and a translation |
| 493 | * expressed in SI units. The event also contains a delta rotation and translation that show |
| 494 | * how the device?s pose has changed since the previous sequence numbered pose. |
| 495 | * The event uses the cannonical Android Sensor axes. |
| 496 | * |
| 497 | * |
| 498 | * <ul> |
Peng Xu | fb1c941 | 2016-03-29 21:50:43 -0700 | [diff] [blame] | 499 | * <li> values[0]: x*sin(θ/2) </li> |
| 500 | * <li> values[1]: y*sin(θ/2) </li> |
| 501 | * <li> values[2]: z*sin(θ/2) </li> |
| 502 | * <li> values[3]: cos(θ/2) </li> |
Ashutosh Joshi | 17efe02 | 2016-01-14 22:23:58 -0800 | [diff] [blame] | 503 | * |
| 504 | * |
| 505 | * <li> values[4]: Translation along x axis from an arbitrary origin. </li> |
Peng Xu | fb1c941 | 2016-03-29 21:50:43 -0700 | [diff] [blame] | 506 | * <li> values[5]: Translation along y axis from an arbitrary origin. </li> |
Ashutosh Joshi | 17efe02 | 2016-01-14 22:23:58 -0800 | [diff] [blame] | 507 | * <li> values[6]: Translation along z axis from an arbitrary origin. </li> |
| 508 | * |
| 509 | * <li> values[7]: Delta quaternion rotation x*sin(θ/2) </li> |
| 510 | * <li> values[8]: Delta quaternion rotation y*sin(θ/2) </li> |
| 511 | * <li> values[9]: Delta quaternion rotation z*sin(θ/2) </li> |
| 512 | * <li> values[10]: Delta quaternion rotation cos(θ/2) </li> |
| 513 | * |
| 514 | * <li> values[11]: Delta translation along x axis. </li> |
| 515 | * <li> values[12]: Delta translation along y axis. </li> |
| 516 | * <li> values[13]: Delta translation along z axis. </li> |
| 517 | * |
| 518 | * <li> values[14]: Sequence number </li> |
| 519 | * |
| 520 | * </ul> |
| 521 | * |
Ashutosh Joshi | af1a266 | 2016-01-25 20:24:20 -0800 | [diff] [blame] | 522 | * <h4>{@link android.hardware.Sensor#TYPE_STATIONARY_DETECT |
| 523 | * Sensor.TYPE_STATIONARY_DETECT}:</h4> |
| 524 | * |
| 525 | * A TYPE_STATIONARY_DETECT event is produced if the device has been |
| 526 | * stationary for at least 5 seconds with a maximal latency of 5 |
| 527 | * additional seconds. ie: it may take up anywhere from 5 to 10 seconds |
| 528 | * afte the device has been at rest to trigger this event. |
| 529 | * |
| 530 | * The only allowed value is 1.0. |
| 531 | * |
| 532 | * <ul> |
| 533 | * <li> values[0]: 1.0 </li> |
| 534 | * </ul> |
| 535 | * |
| 536 | * <h4>{@link android.hardware.Sensor#TYPE_MOTION_DETECT |
| 537 | * Sensor.TYPE_MOTION_DETECT}:</h4> |
| 538 | * |
| 539 | * A TYPE_MOTION_DETECT event is produced if the device has been in |
| 540 | * motion for at least 5 seconds with a maximal latency of 5 |
| 541 | * additional seconds. ie: it may take up anywhere from 5 to 10 seconds |
| 542 | * afte the device has been at rest to trigger this event. |
| 543 | * |
| 544 | * The only allowed value is 1.0. |
| 545 | * |
| 546 | * <ul> |
| 547 | * <li> values[0]: 1.0 </li> |
| 548 | * </ul> |
| 549 | * |
| 550 | * <h4>{@link android.hardware.Sensor#TYPE_HEART_BEAT |
| 551 | * Sensor.TYPE_HEART_BEAT}:</h4> |
| 552 | * |
| 553 | * A sensor of this type returns an event everytime a hear beat peak is |
| 554 | * detected. |
| 555 | * |
| 556 | * Peak here ideally corresponds to the positive peak in the QRS complex of |
| 557 | * an ECG signal. |
| 558 | * |
| 559 | * <ul> |
| 560 | * <li> values[0]: confidence</li> |
| 561 | * </ul> |
| 562 | * |
| 563 | * <p> |
| 564 | * A confidence value of 0.0 indicates complete uncertainty - that a peak |
| 565 | * is as likely to be at the indicated timestamp as anywhere else. |
| 566 | * A confidence value of 1.0 indicates complete certainly - that a peak is |
| 567 | * completely unlikely to be anywhere else on the QRS complex. |
| 568 | * </p> |
Ashutosh Joshi | e33eb92 | 2017-01-10 21:55:50 -0800 | [diff] [blame] | 569 | * |
Nick Vaccaro | 6432bf7 | 2017-01-12 21:09:37 -0800 | [diff] [blame] | 570 | * <h4>{@link android.hardware.Sensor#TYPE_LOW_LATENCY_OFFBODY_DETECT |
| 571 | * Sensor.TYPE_LOW_LATENCY_OFFBODY_DETECT}:</h4> |
| 572 | * |
| 573 | * <p> |
| 574 | * A sensor of this type returns an event every time the device transitions |
| 575 | * from off-body to on-body and from on-body to off-body (e.g. a wearable |
| 576 | * device being removed from the wrist would trigger an event indicating an |
| 577 | * off-body transition). The event returned will contain a single value to |
| 578 | * indicate off-body state: |
| 579 | * </p> |
| 580 | * |
| 581 | * <ul> |
| 582 | * <li> values[0]: off-body state</li> |
| 583 | * </ul> |
| 584 | * |
| 585 | * <p> |
| 586 | * Valid values for off-body state: |
| 587 | * <ul> |
| 588 | * <li> 1.0 (device is on-body)</li> |
| 589 | * <li> 0.0 (device is off-body)</li> |
| 590 | * </ul> |
| 591 | * </p> |
| 592 | * |
| 593 | * <p> |
| 594 | * When a sensor of this type is activated, it must deliver the initial |
| 595 | * on-body or off-body event representing the current device state within |
| 596 | * 5 seconds of activating the sensor. |
| 597 | * </p> |
| 598 | * |
| 599 | * <p> |
| 600 | * This sensor must be able to detect and report an on-body to off-body |
| 601 | * transition within 1 second of the device being removed from the body, |
| 602 | * and must be able to detect and report an off-body to on-body transition |
| 603 | * within 5 seconds of the device being put back onto the body. |
| 604 | * </p> |
| 605 | * |
Ashutosh Joshi | e33eb92 | 2017-01-10 21:55:50 -0800 | [diff] [blame] | 606 | * <h4>{@link android.hardware.Sensor#TYPE_ACCELEROMETER_UNCALIBRATED |
| 607 | * Sensor.TYPE_ACCELEROMETER_UNCALIBRATED}:</h4> All values are in SI |
| 608 | * units (m/s^2) |
| 609 | * |
| 610 | * Similar to {@link android.hardware.Sensor#TYPE_ACCELEROMETER}, |
| 611 | * Factory calibration and temperature compensation will still be applied |
| 612 | * to the "uncalibrated" measurement. |
| 613 | * |
| 614 | * <p> |
| 615 | * The values array is shown below: |
| 616 | * <ul> |
| 617 | * <li> values[0] = x_uncalib without bias compensation </li> |
| 618 | * <li> values[1] = y_uncalib without bias compensation </li> |
| 619 | * <li> values[2] = z_uncalib without bias compensation </li> |
| 620 | * <li> values[3] = estimated x_bias </li> |
| 621 | * <li> values[4] = estimated y_bias </li> |
| 622 | * <li> values[5] = estimated z_bias </li> |
| 623 | * </ul> |
| 624 | * </p> |
| 625 | * <p> |
| 626 | * x_uncalib, y_uncalib, z_uncalib are the measured acceleration in X, Y, Z |
| 627 | * axes similar to the {@link android.hardware.Sensor#TYPE_ACCELEROMETER}, |
| 628 | * without any bias correction (factory bias compensation and any |
| 629 | * temperature compensation is allowed). |
| 630 | * x_bias, y_bias, z_bias are the estimated biases. |
| 631 | * </p> |
Ashutosh Joshi | 576ea41 | 2017-01-13 17:06:41 -0800 | [diff] [blame] | 632 | * |
Anthony Stange | 51a0c35 | 2020-01-16 14:56:27 -0500 | [diff] [blame] | 633 | * <h4>{@link android.hardware.Sensor#TYPE_HINGE_ANGLE Sensor.TYPE_HINGE_ANGLE}:</h4> |
| 634 | * |
| 635 | * A sensor of this type measures the angle, in degrees, between two integral parts of the |
| 636 | * device. Movement of a hinge measured by this sensor type is expected to alter the ways in |
| 637 | * which the user may interact with the device, for example by unfolding or revealing a display. |
| 638 | * |
| 639 | * <ul> |
| 640 | * <li> values[0]: Measured hinge angle between 0 and 360 degrees inclusive</li> |
| 641 | * </ul> |
| 642 | * |
Ashutosh Joshi | 576ea41 | 2017-01-13 17:06:41 -0800 | [diff] [blame] | 643 | * @see GeomagneticField |
Mike Lockwood | 4115c51 | 2009-11-03 10:35:43 -0500 | [diff] [blame] | 644 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 645 | public final float[] values; |
| 646 | |
| 647 | /** |
Mathias Agopian | 74cde2c | 2010-06-16 18:55:46 -0700 | [diff] [blame] | 648 | * The sensor that generated this event. See |
| 649 | * {@link android.hardware.SensorManager SensorManager} for details. |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 650 | */ |
Jaikumar Ganesh | 9a8df4d | 2013-02-12 16:31:32 -0800 | [diff] [blame] | 651 | public Sensor sensor; |
Mathias Agopian | 74cde2c | 2010-06-16 18:55:46 -0700 | [diff] [blame] | 652 | |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 653 | /** |
Mathias Agopian | 74cde2c | 2010-06-16 18:55:46 -0700 | [diff] [blame] | 654 | * The accuracy of this event. See {@link android.hardware.SensorManager |
| 655 | * SensorManager} for details. |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 656 | */ |
| 657 | public int accuracy; |
Mathias Agopian | 74cde2c | 2010-06-16 18:55:46 -0700 | [diff] [blame] | 658 | |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 659 | /** |
Anthony Stange | d2c1159 | 2020-03-16 17:31:03 -0400 | [diff] [blame] | 660 | * The time in nanoseconds at which the event happened. For a given sensor, |
| 661 | * each new sensor event should be monotonically increasing using the same |
| 662 | * time base as {@link android.os.SystemClock#elapsedRealtimeNanos()}. |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 663 | */ |
| 664 | public long timestamp; |
| 665 | |
Mathew Inwood | bcbe440 | 2018-08-08 15:42:59 +0100 | [diff] [blame] | 666 | @UnsupportedAppUsage |
Jaikumar Ganesh | 6d0c1d78 | 2013-03-27 17:41:33 -0700 | [diff] [blame] | 667 | SensorEvent(int valueSize) { |
| 668 | values = new float[valueSize]; |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 669 | } |
| 670 | } |