docs/html/guide/topics/sensors/sensors_environment.jd

page.title=Environment Sensors
parent.title=Sensors
parent.link=index.html
@jd:body

<div id="qv-wrapper">
  <div id="qv">
  <h2>In this document</h2>
    <ol>
      <li><a href="#sensors-using-temp">Using the Light, Pressure, and Temperature
Sensors</a></li>
      <li><a href="#sensors-using-humid">Using the Humidity Sensor</a></li>
    </ol>
  <h2>Related samples</h2>
  <ol>
    <li><a href="{@docRoot}resources/samples/AccelerometerPlay/index.html">Accelerometer
        Play</a></li>
    <li><a
href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/os/RotationVectorDemo.html">
API Demos (OS - RotationVectorDemo)</a></li>
    <li><a
href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/os/Sensors.html">API Demos
(OS - Sensors)</a></li>
  </ol>
  <h2>See also</h2>
  <ol>
    <li><a href="{@docRoot}guide/topics/sensors/index.html">Sensors</a></li>
    <li><a href="{@docRoot}guide/topics/sensors/sensors_overview.html">Sensors Overview</a></li>
    <li><a href="{@docRoot}guide/topics/sensors/sensors_position.html">Position Sensors</a></li>
    <li><a href="{@docRoot}guide/topics/sensors/sensors_motion.html">Motion
        Sensors</a></li>
  </ol>
  </div>
</div>

<p>The Android platform provides four sensors that let you monitor various environmental properties.
You can use these sensors to monitor relative ambient humidity, illuminance, ambient pressure, and
ambient temperature near an Android-powered device. All four environment sensors are hardware-based
and are available only if a device manufacturer has built them into a device. With the exception of
the light sensor, which most device manufacturers use to control screen brightness, environment
sensors are not always available on devices. Because of this, it's particularly important that you
verify at runtime whether an environment sensor exists before you attempt to acquire data from
it.</p>

<p>Unlike most motion sensors and position sensors, which return a multi-dimensional array of sensor
values for each {@link android.hardware.SensorEvent}, environment sensors return a single sensor
value for each data event. For example, the temperature in &deg;C or the pressure in hPa.
Also, unlike motion sensors and position sensors, which often require high-pass or low-pass
filtering, environment sensors do not typically require any data filtering or data processing. Table
1 provides a summary of the environment sensors that are supported on the Android platform.</p>

<p class="table-caption" id="table1">
  <strong>Table 1.</strong> Environment sensors that are supported on the Android platform.</p>
<table>
  <tr>
    <th scope="col" style="white-space:nowrap">Sensor</th>
    <th scope="col" style="white-space:nowrap">Sensor event data</th>
    <th scope="col" style="white-space:nowrap">Units of measure</th>
    <th scope="col" style="white-space:nowrap">Data description</th>
  </tr>
  <tr>
    <td>{@link android.hardware.Sensor#TYPE_AMBIENT_TEMPERATURE}</td>
    <td><code>event.values[0]</code></td>
    <td>&deg;C</td>
    <td>Ambient air temperature.</td>
  </tr>
  <tr>
    <td>{@link android.hardware.Sensor#TYPE_LIGHT}</td>
    <td><code>event.values[0]</code></td>
    <td>lx</td>
    <td>Illuminance.</td>
  </tr>
  <tr>
    <td>{@link android.hardware.Sensor#TYPE_PRESSURE}</td>
    <td><code>event.values[0]</code></td>
    <td>hPa or mbar</td>
    <td>Ambient air pressure.</td>
  </tr>
  <tr>
    <td>{@link android.hardware.Sensor#TYPE_RELATIVE_HUMIDITY}</td>
    <td><code>event.values[0]</code></td>
    <td>%</td>
    <td>Ambient relative humidity.</td>
  </tr>
  <tr>
    <td>{@link android.hardware.Sensor#TYPE_TEMPERATURE}</td>
    <td><code>event.values[0]</code></td>
    <td>&deg;C</td>
    <td>Device temperature.<sup>1</sup></td>
  </tr>
</table>

<p class="note"><sup><strong>1</strong></sup>  Implementations vary from device to
device. This sensor was deprecated in Android 4.0 (API Level 14).</p>

<h2 id="sensors-using-temp">Using the Light, Pressure, and Temperature Sensors</h2>

<p>The raw data you acquire from the light, pressure, and temperature sensors usually requires no
calibration, filtering, or modification, which makes them some of the easiest sensors to use. To
acquire data from these sensors you first create an instance of the {@link
android.hardware.SensorManager} class, which you can use to get an instance of a physical sensor.
Then you register a sensor listener in the {@link android.app.Activity#onResume
onResume()} method, and start handling incoming sensor data in the {@link
android.hardware.SensorEventListener#onSensorChanged onSensorChanged()} callback method. The
following code shows you how to do this:</p>

<pre>
public class SensorActivity extends Activity implements SensorEventListener {
  private SensorManager mSensorManager;
  private Sensor mPressure;

  &#64;Override
  public final void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

    // Get an instance of the sensor service, and use that to get an instance of
    // a particular sensor.
    mSensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE);
    mPressure = mSensorManager.getDefaultSensor(Sensor.TYPE_PRESSURE);
  }

  &#64;Override
  public final void onAccuracyChanged(Sensor sensor, int accuracy) {
    // Do something here if sensor accuracy changes.
  }

  &#64;Override
  public final void onSensorChanged(SensorEvent event) {
    float millibars_of_pressure = event.values[0];
    // Do something with this sensor data.
  }

  &#64;Override
  protected void onResume() {
    // Register a listener for the sensor.
    super.onResume();
    mSensorManager.registerListener(this, mPressure, SensorManager.SENSOR_DELAY_NORMAL);
  }

  &#64;Override
  protected void onPause() {
    // Be sure to unregister the sensor when the activity pauses.
    super.onPause();
    mSensorManager.unregisterListener(this);
  }
}
</pre>

<p>You must always include implementations of both the {@link
android.hardware.SensorEventListener#onAccuracyChanged onAccuracyChanged()} and {@link
android.hardware.SensorEventListener#onSensorChanged onSensorChanged()} callback methods. Also, be
sure that you always unregister a sensor when an activity pauses. This prevents a sensor from
continually sensing data and draining the battery.</p>

<h2 id="sensors-using-humid">Using the Humidity Sensor</h2>

<p>You can acquire raw relative humidity data by using the humidity sensor the same way that you use
the light, pressure, and temperature sensors. However, if a device has both a humidity sensor
({@link android.hardware.Sensor#TYPE_RELATIVE_HUMIDITY}) and a temperature sensor ({@link
android.hardware.Sensor#TYPE_AMBIENT_TEMPERATURE}) you can use these two data streams to calculate
the dew point and the absolute humidity.</p>

<h4>Dew point</h4>

<p>The dew point is the temperature at which a given volume of air must be cooled, at constant
  barometric pressure, for water vapor to condense into water. The following equation shows how you
can calculate the dew point:</p>

<pre class="no-pretty-print classic">
                       ln(RH/100%) + m·t/(T<sub>n</sub>+t)
t<sub>d</sub>(t,RH) = T<sub>n</sub> · ------------------------------------
                    m - [ln(RH/100%) + m·t/(T<sub>n</sub>+t)]
</pre>

<p>Where,</p>

<ul type="none">
  <li>t<sub>d</sub> = dew point temperature in degrees C</li>
  <li>t = actual temperature in degrees C</li>
  <li>RH = actual relative humidity in percent (%)</li>
  <li>m = 17.62</li>
  <li>T<sub>n</sub> = 243.12</li>
</ul>

<h4>Absolute humidity</h4>

<p>The absolute humidity is the mass of water vapor in a given volume of dry air. Absolute
  humidity is measured in grams/meter<sup>3</sup>. The following equation shows how you
  can calculate the absolute humidity:</p>

<pre class="no-pretty-print classic">
                          (RH/100%) · A · exp(m·t/(T<sub>n</sub>+t)
d<sub>v</sub>(t,RH) = 216.7 · ------------------------------------
                                    273.15 + t
</pre>

<p>Where,</p>

<ul type="none">
  <li>d<sub>v</sub> = absolute humidity in grams/meter<sup>3</sup></li>
  <li>t = actual temperature in degrees C</li>
  <li>RH = actual relative humidity in percent (%)</li>
  <li>m = 17.62</li>
  <li>T<sub>n</sub> = 243.12 degrees C</li>
  <li>A = 6.112 hPa</li>
</ul>