sensors_position.jd revision 64461bf4f261164cb9e3022761fd217fd0028ac5
1page.title=Position Sensors 2page.tags="sensorevent","orientation","proximity" 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 25href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/os/RotationVectorDemo.html"> 26API Demos (OS - RotationVectorDemo)</a></li> 27 <li><a 28href="{@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 44geomagnetic field sensor and the orientation sensor. The Android platform also 45provides a sensor that lets you determine how close the face of a device is to an object (known as 46the proximity sensor). The geomagnetic field sensor and the proximity sensor are hardware-based. 47Most 48handset and tablet manufacturers include a geomagnetic field sensor. Likewise, handset manufacturers 49usually 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 51from 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 54Level 8).</p> 55 56<p>Position sensors are useful for determining a device's physical position in the 57world's frame of reference. For example, you can use the geomagnetic field sensor in 58combination with the accelerometer to determine a device's position relative to 59the magnetic North Pole. You can also use the orientation sensor (or similar sensor-based 60orientation methods) to determine a device's position in your application's frame of reference. 61Position sensors are not typically used to monitor device movement or motion, such as shake, tilt, 62or thrust (for more information, see <a 63href="{@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 66values 67for each {@link android.hardware.SensorEvent}. For example, the orientation sensor provides 68geomagnetic 69field strength values for each of the three coordinate axes during a single sensor event. Likewise, 70the orientation sensor provides azimuth (yaw), pitch, and roll values during a single sensor event. 71For more information about the coordinate systems that are used by sensors, see <a 72href="{@docRoot}guide/topics/sensors/sensors_overview.html#sensors-coords">Sensor Coordinate 73Systems</a>. The proximity sensor provides a single value for each sensor event. Table 1 summarizes 74the 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 123discussed 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 126representing 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 131reference (specifically, magnetic north). The following code shows you how to get an instance of the 132default orientation sensor :</p> 133 134<pre> 135private SensorManager mSensorManager; 136private Sensor mSensor; 137... 138mSensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE); 139mSensor = 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 143combination with a device's accelerometer. Using these two hardware sensors, an orientation sensor 144provides 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 148and the device's y axis. For example, if the device's y axis is aligned with magnetic north 149this value is 0, and if the device's y axis is pointing south this value is 180. Likewise, when 150the 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 152rotates toward the positive y axis, and it is negative when the positive z axis 153rotates toward the negative y axis. The range of values is 180 degrees to -180 154degrees.</li> 155 <li>Roll (degrees of rotation around the y axis). This value is positive when the positive z axis 156rotates toward the positive x axis, and it is negative when the positive z axis 157rotates toward the negative x axis. The range of values is 90 degrees to -90 158degrees.</li> 159</ul> 160 161<p>This definition is different from yaw, pitch, and roll used in aviation, where the X axis is 162along the long side of the plane (tail to nose). Also, for historical reasons the roll angle is 163positive in the clockwise direction (mathematically speaking, it should be positive in the 164counter-clockwise direction).</p> 165 166<p>The orientation sensor derives its data by processing the raw sensor data from the accelerometer 167and the geomagnetic field sensor. Because of the heavy processing that is involved, the accuracy and 168precision of the orientation sensor is diminished (specifically, this sensor is only reliable when 169the roll component is 0). As a result, the orientation sensor was deprecated in Android 2.2 (API 170level 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 172with the {@link android.hardware#getOrientation getOrientation()} method to compute orientation 173values. You can also use the {@link android.hardware.SensorManager#remapCoordinateSystem 174remapCoordinateSystem()} method to translate the orientation values to your application's frame of 175reference.</p> 176 177<p>The following code sample shows how to acquire orientation data directly from the orientation 178sensor. We recommend that you do this only if a device has negligible roll.</p> 179 180<pre> 181public 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 224obtain from an orientation sensor, other than translating the sensor's coordinate system to your 225application's frame of reference. The <a 226href="{@docRoot}resources/samples/AccelerometerPlay/index.html">Accelerometer Play</a> sample shows 227you how to translate acceleration sensor data into another frame of reference; the technique is 228similar 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 233following code shows you how to get an instance of the default geomagnetic field sensor:</p> 234 235<pre> 236private SensorManager mSensorManager; 237private Sensor mSensor; 238... 239mSensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE); 240mSensor = 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. 244Usually, you do not need to use this sensor directly. Instead, you can use the rotation vector 245sensor to determine raw rotational movement or you can use the accelerometer and geomagnetic field 246sensor in conjunction with the {@link android.hardware.SensorManager#getRotationMatrix 247getRotationMatrix()} method to obtain the rotation matrix and the inclination matrix. You can then 248use these matrices with the {@link android.hardware.SensorManager#getOrientation getOrientation()} 249and {@link android.hardware.SensorManager#getInclination getInclination()} methods to obtain azimuth 250and 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 254code shows you how to get an instance of the default proximity sensor:</p> 255 256<pre> 257private SensorManager mSensorManager; 258private Sensor mSensor; 259... 260mSensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE); 261mSensor = 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 265of a handset device (for example, when a user is making or receiving a phone call). Most 266proximity sensors return the absolute distance, in cm, but some return only near and 267far values. The following code shows you how to use the proximity sensor:</p> 268 269<pre> 270public 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 314and a lesser value in the near state. Typically, the far value is a value > 5 cm, but this can vary 315from sensor to sensor. You can determine a sensor's maximum range by using the {@link 316android.hardware.Sensor#getMaximumRange} method.</p>