Bill Gruber | f8c029e | 2011-11-01 09:31:57 -0700 | [diff] [blame] | 1 | page.title=Position Sensors |
Joe Fernandez | 33baa5a | 2013-11-14 11:41:19 -0800 | [diff] [blame] | 2 | page.tags=sensorevent,orientation,proximity |
Bill Gruber | f8c029e | 2011-11-01 09:31:57 -0700 | [diff] [blame] | 3 | @jd:body |
| 4 | |
| 5 | <div id="qv-wrapper"> |
| 6 | <div id="qv"> |
| 7 | <h2>In this document</h2> |
| 8 | <ol> |
| 9 | <li><a href="#sensors-pos-orient">Using the Orientation Sensor</a></li> |
| 10 | <li><a href="#sensors-pos-mag">Using the Geomagnetic Field Sensor</a></li> |
| 11 | <li><a href="#sensors-pos-prox">Using the Proximity Sensor</a></li> |
| 12 | </ol> |
| 13 | <h2>Key classes and interfaces</h2> |
| 14 | <ol> |
| 15 | <li>{@link android.hardware.Sensor}</li> |
| 16 | <li>{@link android.hardware.SensorEvent}</li> |
| 17 | <li>{@link android.hardware.SensorManager}</li> |
| 18 | <li>{@link android.hardware.SensorEventListener}</li> |
| 19 | </ol> |
| 20 | <h2>Related samples</h2> |
| 21 | <ol> |
| 22 | <li><a href="{@docRoot}resources/samples/AccelerometerPlay/index.html">Accelerometer |
| 23 | Play</a></li> |
| 24 | <li><a |
| 25 | href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/os/RotationVectorDemo.html"> |
| 26 | API Demos (OS - RotationVectorDemo)</a></li> |
| 27 | <li><a |
| 28 | href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/os/Sensors.html">API Demos |
| 29 | (OS - Sensors)</a></li> |
| 30 | </ol> |
| 31 | <h2>See also</h2> |
| 32 | <ol> |
| 33 | <li><a href="{@docRoot}guide/topics/sensors/index.html">Sensors</a></li> |
| 34 | <li><a href="{@docRoot}guide/topics/sensors/sensors_overview.html">Sensors Overview</a></li> |
| 35 | <li><a href="{@docRoot}guide/topics/sensors/sensors_motion.html">Motion |
| 36 | Sensors</a></li> |
| 37 | <li><a href="{@docRoot}guide/topics/sensors/sensors_environment.html">Environment |
| 38 | Sensors</a></li> |
| 39 | </ol> |
| 40 | </div> |
| 41 | </div> |
| 42 | |
| 43 | <p>The Android platform provides two sensors that let you determine the position of a device: the |
| 44 | geomagnetic field sensor and the orientation sensor. The Android platform also |
| 45 | provides a sensor that lets you determine how close the face of a device is to an object (known as |
| 46 | the proximity sensor). The geomagnetic field sensor and the proximity sensor are hardware-based. |
| 47 | Most |
| 48 | handset and tablet manufacturers include a geomagnetic field sensor. Likewise, handset manufacturers |
| 49 | usually include a proximity sensor to determine when a handset is being held close to a user's face |
| 50 | (for example, during a phone call). The orientation sensor is software-based and derives its data |
| 51 | from the accelerometer and the geomagnetic field sensor.</p> |
| 52 | |
| 53 | <p class="note"><strong>Note:</strong> The orientation sensor was deprecated in Android 2.2 (API |
| 54 | Level 8).</p> |
| 55 | |
| 56 | <p>Position sensors are useful for determining a device's physical position in the |
| 57 | world's frame of reference. For example, you can use the geomagnetic field sensor in |
| 58 | combination with the accelerometer to determine a device's position relative to |
| 59 | the magnetic North Pole. You can also use the orientation sensor (or similar sensor-based |
| 60 | orientation methods) to determine a device's position in your application's frame of reference. |
| 61 | Position sensors are not typically used to monitor device movement or motion, such as shake, tilt, |
| 62 | or thrust (for more information, see <a |
| 63 | href="{@docRoot}guide/topics/sensors/sensors_motion.html">Motion Sensors</a>).</p> |
| 64 | |
| 65 | <p>The geomagnetic field sensor and orientation sensor return multi-dimensional arrays of sensor |
| 66 | values |
| 67 | for each {@link android.hardware.SensorEvent}. For example, the orientation sensor provides |
| 68 | geomagnetic |
| 69 | field strength values for each of the three coordinate axes during a single sensor event. Likewise, |
| 70 | the orientation sensor provides azimuth (yaw), pitch, and roll values during a single sensor event. |
| 71 | For more information about the coordinate systems that are used by sensors, see <a |
| 72 | href="{@docRoot}guide/topics/sensors/sensors_overview.html#sensors-coords">Sensor Coordinate |
| 73 | Systems</a>. The proximity sensor provides a single value for each sensor event. Table 1 summarizes |
| 74 | the position sensors that are supported on the Android platform.</p> |
| 75 | |
| 76 | <p class="table-caption" id="table1"> |
| 77 | <strong>Table 1.</strong> Position sensors that are supported on the Android platform.</p> |
| 78 | <table> |
| 79 | <tr> |
| 80 | <th scope="col" style="white-space:nowrap">Sensor</th> |
| 81 | <th scope="col" style="white-space:nowrap">Sensor event data</th> |
| 82 | <th scope="col" style="white-space:nowrap">Description</th> |
| 83 | <th scope="col" style="white-space:nowrap">Units of measure</th> |
| 84 | </tr> |
| 85 | <tr> |
| 86 | <td rowspan="3">{@link android.hardware.Sensor#TYPE_MAGNETIC_FIELD}</td> |
| 87 | <td><code>SensorEvent.values[0]</code></td> |
| 88 | <td>Geomagnetic field strength along the x axis.</td> |
| 89 | <td rowspan="3">μT</td> |
| 90 | </tr> |
| 91 | <tr> |
| 92 | <td><code>SensorEvent.values[1]</code></td> |
| 93 | <td>Geomagnetic field strength along the y axis.</td> |
| 94 | </tr> |
| 95 | <tr> |
| 96 | <td><code>SensorEvent.values[2]</code></td> |
| 97 | <td>Geomagnetic field strength along the z axis.</td> |
| 98 | </tr> |
| 99 | <tr> |
| 100 | <td rowspan="3">{@link android.hardware.Sensor#TYPE_ORIENTATION}<sup>1</sup></td> |
| 101 | <td><code>SensorEvent.values[0]</code></td> |
| 102 | <td>Azimuth (angle around the z-axis).</td> |
| 103 | <td rowspan="3">Degrees</td> |
| 104 | </tr> |
| 105 | <tr> |
| 106 | <td><code>SensorEvent.values[1]</code></td> |
| 107 | <td>Pitch (angle around the x-axis).</td> |
| 108 | </tr> |
| 109 | <tr> |
| 110 | <td><code>SensorEvent.values[2]</code></td> |
| 111 | <td>Roll (angle around the y-axis).</td> |
| 112 | </tr> |
| 113 | <tr> |
| 114 | <td>{@link android.hardware.Sensor#TYPE_PROXIMITY}</td> |
| 115 | <td><code>SensorEvent.values[0]</code></td> |
| 116 | <td>Distance from object.<sup>2</sup></td> |
| 117 | <td>cm</td> |
| 118 | </tr> |
| 119 | </table> |
| 120 | |
| 121 | <p class="note"><sup><strong>1</strong></sup> This sensor was deprecated in Android 2.2 (API Level |
| 122 | 8). The sensor framework provides alternate methods for acquiring device orientation, which are |
| 123 | discussed in <a href="#sensors-pos-orient">Using the Orientation Sensor</a>.</p> |
| 124 | |
| 125 | <p class="note"><sup><strong>2</strong></sup> Some proximity sensors provide only binary values |
| 126 | representing near and far.</p> |
| 127 | |
| 128 | <h2 id="sensors-pos-orient">Using the Orientation Sensor</h2> |
| 129 | |
| 130 | <p>The orientation sensor lets you monitor the position of a device relative to the earth's frame of |
| 131 | reference (specifically, magnetic north). The following code shows you how to get an instance of the |
| 132 | default orientation sensor :</p> |
| 133 | |
| 134 | <pre> |
| 135 | private SensorManager mSensorManager; |
| 136 | private Sensor mSensor; |
| 137 | ... |
| 138 | mSensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE); |
| 139 | mSensor = mSensorManager.getDefaultSensor(Sensor.TYPE_ORIENTATION); |
| 140 | </pre> |
| 141 | |
| 142 | <p>The orientation sensor derives its data by using a device's geomagnetic field sensor in |
| 143 | combination with a device's accelerometer. Using these two hardware sensors, an orientation sensor |
| 144 | provides data for the following three dimensions:</p> |
| 145 | |
| 146 | <ul> |
| 147 | <li>Azimuth (degrees of rotation around the z axis). This is the angle between magnetic north |
| 148 | and the device's y axis. For example, if the device's y axis is aligned with magnetic north |
| 149 | this value is 0, and if the device's y axis is pointing south this value is 180. Likewise, when |
| 150 | the y axis is pointing east this value is 90 and when it is pointing west this value is 270.</li> |
| 151 | <li>Pitch (degrees of rotation around the x axis). This value is positive when the positive z axis |
| 152 | rotates toward the positive y axis, and it is negative when the positive z axis |
| 153 | rotates toward the negative y axis. The range of values is 180 degrees to -180 |
| 154 | degrees.</li> |
| 155 | <li>Roll (degrees of rotation around the y axis). This value is positive when the positive z axis |
| 156 | rotates toward the positive x axis, and it is negative when the positive z axis |
| 157 | rotates toward the negative x axis. The range of values is 90 degrees to -90 |
| 158 | degrees.</li> |
| 159 | </ul> |
| 160 | |
| 161 | <p>This definition is different from yaw, pitch, and roll used in aviation, where the X axis is |
| 162 | along the long side of the plane (tail to nose). Also, for historical reasons the roll angle is |
| 163 | positive in the clockwise direction (mathematically speaking, it should be positive in the |
| 164 | counter-clockwise direction).</p> |
| 165 | |
| 166 | <p>The orientation sensor derives its data by processing the raw sensor data from the accelerometer |
| 167 | and the geomagnetic field sensor. Because of the heavy processing that is involved, the accuracy and |
| 168 | precision of the orientation sensor is diminished (specifically, this sensor is only reliable when |
| 169 | the roll component is 0). As a result, the orientation sensor was deprecated in Android 2.2 (API |
| 170 | level 8). Instead of using raw data from the orientation sensor, we recommend that you use the |
| 171 | {@link android.hardware.SensorManager#getRotationMatrix getRotationMatrix()} method in conjunction |
| 172 | with the {@link android.hardware#getOrientation getOrientation()} method to compute orientation |
| 173 | values. You can also use the {@link android.hardware.SensorManager#remapCoordinateSystem |
| 174 | remapCoordinateSystem()} method to translate the orientation values to your application's frame of |
| 175 | reference.</p> |
| 176 | |
| 177 | <p>The following code sample shows how to acquire orientation data directly from the orientation |
| 178 | sensor. We recommend that you do this only if a device has negligible roll.</p> |
| 179 | |
| 180 | <pre> |
| 181 | public class SensorActivity extends Activity implements SensorEventListener { |
| 182 | |
| 183 | private SensorManager mSensorManager; |
| 184 | private Sensor mOrientation; |
| 185 | |
| 186 | @Override |
| 187 | public void onCreate(Bundle savedInstanceState) { |
| 188 | super.onCreate(savedInstanceState); |
| 189 | setContentView(R.layout.main); |
| 190 | |
| 191 | mSensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE); |
| 192 | mOrientation = mSensorManager.getDefaultSensor(Sensor.TYPE_ORIENTATION); |
| 193 | } |
| 194 | |
| 195 | @Override |
| 196 | public void onAccuracyChanged(Sensor sensor, int accuracy) { |
| 197 | // Do something here if sensor accuracy changes. |
| 198 | // You must implement this callback in your code. |
| 199 | } |
| 200 | |
| 201 | @Override |
| 202 | protected void onResume() { |
| 203 | super.onResume(); |
| 204 | mSensorManager.registerListener(this, mOrientation, SensorManager.SENSOR_DELAY_NORMAL); |
| 205 | } |
| 206 | |
| 207 | @Override |
| 208 | protected void onPause() { |
| 209 | super.onPause(); |
| 210 | mSensorManager.unregisterListener(this); |
| 211 | } |
| 212 | |
| 213 | @Override |
| 214 | public void onSensorChanged(SensorEvent event) { |
| 215 | float azimuth_angle = event.values[0]; |
| 216 | float pitch_angle = event.values[1]; |
| 217 | float roll_angle = event.values[2]; |
| 218 | // Do something with these orientation angles. |
| 219 | } |
| 220 | } |
| 221 | </pre> |
| 222 | |
| 223 | <p>You do not usually need to perform any data processing or filtering of the raw data that you |
| 224 | obtain from an orientation sensor, other than translating the sensor's coordinate system to your |
| 225 | application's frame of reference. The <a |
| 226 | href="{@docRoot}resources/samples/AccelerometerPlay/index.html">Accelerometer Play</a> sample shows |
| 227 | you how to translate acceleration sensor data into another frame of reference; the technique is |
| 228 | similar to the one you might use with the orientation sensor.</p> |
| 229 | |
| 230 | <h2 id="sensors-pos-mag">Using the Geomagnetic Field Sensor</h2> |
| 231 | |
| 232 | <p>The geomagnetic field sensor lets you monitor changes in the earth's magnetic field. The |
| 233 | following code shows you how to get an instance of the default geomagnetic field sensor:</p> |
| 234 | |
| 235 | <pre> |
| 236 | private SensorManager mSensorManager; |
| 237 | private Sensor mSensor; |
| 238 | ... |
| 239 | mSensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE); |
| 240 | mSensor = mSensorManager.getDefaultSensor(Sensor.TYPE_MAGNETIC_FIELD); |
| 241 | </pre> |
| 242 | |
| 243 | <p>This sensor provides raw field strength data (in μT) for each of the three coordinate axes. |
| 244 | Usually, you do not need to use this sensor directly. Instead, you can use the rotation vector |
| 245 | sensor to determine raw rotational movement or you can use the accelerometer and geomagnetic field |
| 246 | sensor in conjunction with the {@link android.hardware.SensorManager#getRotationMatrix |
| 247 | getRotationMatrix()} method to obtain the rotation matrix and the inclination matrix. You can then |
| 248 | use these matrices with the {@link android.hardware.SensorManager#getOrientation getOrientation()} |
| 249 | and {@link android.hardware.SensorManager#getInclination getInclination()} methods to obtain azimuth |
| 250 | and geomagnetic inclination data.</p> |
| 251 | |
| 252 | <h2 id="sensors-pos-prox">Using the Proximity Sensor</h2> |
| 253 | <p>The proximity sensor lets you determine how far away an object is from a device. The following |
| 254 | code shows you how to get an instance of the default proximity sensor:</p> |
| 255 | |
| 256 | <pre> |
| 257 | private SensorManager mSensorManager; |
| 258 | private Sensor mSensor; |
| 259 | ... |
| 260 | mSensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE); |
| 261 | mSensor = mSensorManager.getDefaultSensor(Sensor.TYPE_PROXIMITY); |
| 262 | </pre> |
| 263 | |
| 264 | <p>The proximity sensor is usually used to determine how far away a person's head is from the face |
| 265 | of a handset device (for example, when a user is making or receiving a phone call). Most |
| 266 | proximity sensors return the absolute distance, in cm, but some return only near and |
| 267 | far values. The following code shows you how to use the proximity sensor:</p> |
| 268 | |
| 269 | <pre> |
| 270 | public class SensorActivity extends Activity implements SensorEventListener { |
| 271 | private SensorManager mSensorManager; |
| 272 | private Sensor mProximity; |
| 273 | |
| 274 | @Override |
| 275 | public final void onCreate(Bundle savedInstanceState) { |
| 276 | super.onCreate(savedInstanceState); |
| 277 | setContentView(R.layout.main); |
| 278 | |
| 279 | // Get an instance of the sensor service, and use that to get an instance of |
| 280 | // a particular sensor. |
| 281 | mSensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE); |
| 282 | mProximity = mSensorManager.getDefaultSensor(Sensor.TYPE_PROXIMITY); |
| 283 | } |
| 284 | |
| 285 | @Override |
| 286 | public final void onAccuracyChanged(Sensor sensor, int accuracy) { |
| 287 | // Do something here if sensor accuracy changes. |
| 288 | } |
| 289 | |
| 290 | @Override |
| 291 | public final void onSensorChanged(SensorEvent event) { |
| 292 | float distance = event.values[0]; |
| 293 | // Do something with this sensor data. |
| 294 | } |
| 295 | |
| 296 | @Override |
| 297 | protected void onResume() { |
| 298 | // Register a listener for the sensor. |
| 299 | super.onResume(); |
| 300 | mSensorManager.registerListener(this, mProximity, SensorManager.SENSOR_DELAY_NORMAL); |
| 301 | } |
| 302 | |
| 303 | @Override |
| 304 | protected void onPause() { |
| 305 | // Be sure to unregister the sensor when the activity pauses. |
| 306 | super.onPause(); |
| 307 | mSensorManager.unregisterListener(this); |
| 308 | } |
| 309 | } |
| 310 | </pre> |
| 311 | |
| 312 | <p class="note"><strong>Note:</strong> Some proximity sensors return binary values that represent |
| 313 | "near" or "far." In this case, the sensor usually reports its maximum range value in the far state |
| 314 | and a lesser value in the near state. Typically, the far value is a value > 5 cm, but this can vary |
| 315 | from sensor to sensor. You can determine a sensor's maximum range by using the {@link |
Joe Fernandez | 33baa5a | 2013-11-14 11:41:19 -0800 | [diff] [blame] | 316 | android.hardware.Sensor#getMaximumRange} method.</p> |