/* * Copyright (C) 2008 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.hardware; /** *

* This class represents a {@link android.hardware.Sensor Sensor} event and * holds informations such as the sensor's type, the time-stamp, accuracy and of * course the sensor's {@link SensorEvent#values data}. *

* *

* Definition of the coordinate system used by the SensorEvent API. *

* *

* The coordinate-system is defined relative to the screen of the phone in its * default orientation. The axes are not swapped when the device's screen * orientation changes. *

* *

* The X axis is horizontal and points to the right, the Y axis is vertical and * points up and the Z axis points towards the outside of the front face of the * screen. In this system, coordinates behind the screen have negative Z values. *

* *

*

Sensors coordinate-system diagram.
*

* *

* Note: This coordinate system is different from the one used in the * Android 2D APIs where the origin is in the top-left corner. *

* * @see SensorManager * @see SensorEvent * @see Sensor * */ public class SensorEvent { /** *

* The length and contents of the {@link #values values} array depends on * which {@link android.hardware.Sensor sensor} type is being monitored (see * also {@link SensorEvent} for a definition of the coordinate system used). *

* *

{@link android.hardware.Sensor#TYPE_ACCELEROMETER * Sensor.TYPE_ACCELEROMETER}:

All values are in SI units (m/s^2) * * * *

* A sensor of this type measures the acceleration applied to the device * (Ad). Conceptually, it does so by measuring forces applied to the * sensor itself (Fs) using the relation: *

* *
Ad = - ∑Fs / mass
 * *

* In particular, the force of gravity is always influencing the measured * acceleration: *

* *
Ad = -g - ∑F / mass
 * *

* For this reason, when the device is sitting on a table (and obviously not * accelerating), the accelerometer reads a magnitude of g = 9.81 * m/s^2 *

* *

* Similarly, when the device is in free-fall and therefore dangerously * accelerating towards to ground at 9.81 m/s^2, its accelerometer reads a * magnitude of 0 m/s^2. *

* *

* It should be apparent that in order to measure the real acceleration of * the device, the contribution of the force of gravity must be eliminated. * This can be achieved by applying a high-pass filter. Conversely, a * low-pass filter can be used to isolate the force of gravity. *

* * 
     *
     *     public void onSensorChanged(SensorEvent event)
     *     {
     *          // alpha is calculated as t / (t + dT)
     *          // with t, the low-pass filter's time-constant
     *          // and dT, the event delivery rate
     *
     *          final float alpha = 0.8;
     *
     *          gravity[0] = alpha * gravity[0] + (1 - alpha) * event.values[0];
     *          gravity[1] = alpha * gravity[1] + (1 - alpha) * event.values[1];
     *          gravity[2] = alpha * gravity[2] + (1 - alpha) * event.values[2];
     *
     *          linear_acceleration[0] = event.values[0] - gravity[0];
     *          linear_acceleration[1] = event.values[1] - gravity[1];
     *          linear_acceleration[2] = event.values[2] - gravity[2];
     *     }
     *
* *

* Examples: *

* * *

{@link android.hardware.Sensor#TYPE_MAGNETIC_FIELD * Sensor.TYPE_MAGNETIC_FIELD}:

* All values are in micro-Tesla (uT) and measure the ambient magnetic field * in the X, Y and Z axis. * *

{@link android.hardware.Sensor#TYPE_GYROSCOPE Sensor.TYPE_GYROSCOPE}:

* All values are in radians/second and measure the rate of rotation * around the X, Y and Z axis. The coordinate system is the same as is * used for the acceleration sensor. Rotation is positive in the counter-clockwise * direction. That is, an observer looking from some positive location on the x, y. * or z axis at a device positioned on the origin would report positive rotation * if the device appeared to be rotating counter clockwise. Note that this is the * standard mathematical definition of positive rotation and does not agree with the * definition of roll given earlier. * * *

* Typically the output of the gyroscope is integrated over time to calculate * an angle, for example: *

* 
     *     private static final float NS2S = 1.0f / 1000000000.0f;
     *     private float timestamp;
     *     public void onSensorChanged(SensorEvent event)
     *     {
     *          if (timestamp != 0) {
     *              final float dT = (event.timestamp - timestamp) * NS2S;
     *              angle[0] += event.values[0] * dT;
     *              angle[1] += event.values[1] * dT;
     *              angle[2] += event.values[2] * dT;
     *          }
     *          timestamp = event.timestamp;
     *     }
     *
* *

In practice, the gyroscope noise and offset will introduce some errors which need * to be compensated for. This is usually done using the information from other * sensors, but is beyond the scope of this document.

* *

{@link android.hardware.Sensor#TYPE_LIGHT Sensor.TYPE_LIGHT}:

* * *

{@link android.hardware.Sensor#TYPE_PROXIMITY Sensor.TYPE_PROXIMITY}: *

* * * *

* Note: Some proximity sensors only support a binary near or * far measurement. In this case, the sensor should report its * {@link android.hardware.Sensor#getMaximumRange() maximum range} value in * the far state and a lesser value in the near state. *

* *

{@link android.hardware.Sensor#TYPE_GRAVITY Sensor.TYPE_GRAVITY}:

*

A three dimensional vector indicating the direction and magnitude of gravity. Units * are m/s^2. The coordinate system is the same as is used by the acceleration sensor.

*

Note: When the device is at rest, the output of the gravity sensor should be identical * to that of the accelerometer.

* *

{@link android.hardware.Sensor#TYPE_LINEAR_ACCELERATION Sensor.TYPE_LINEAR_ACCELERATION}:

* A three dimensional vector indicating acceleration along each device axis, not including * gravity. All values have units of m/s^2. The coordinate system is the same as is used by the * acceleration sensor. *

The output of the accelerometer, gravity and linear-acceleration sensors must obey the * following relation:

*

* *

{@link android.hardware.Sensor#TYPE_ROTATION_VECTOR Sensor.TYPE_ROTATION_VECTOR}:

*

The rotation vector represents the orientation of the device as a combination of an angle * and an axis, in which the device has rotated through an angle θ around an axis * <x, y, z>.

*

The three elements of the rotation vector are * <x*sin(θ/2), y*sin(θ/2), z*sin(θ/2)>, such that the magnitude of the rotation * vector is equal to sin(θ/2), and the direction of the rotation vector is equal to the * direction of the axis of rotation.

*

The three elements of the rotation vector are equal to * the last three components of a unit quaternion * <cos(θ/2), x*sin(θ/2), y*sin(θ/2), z*sin(θ/2)>.

*

Elements of the rotation vector are unitless. * The x,y, and z axis are defined in the same way as the acceleration * sensor.

* * *

{@link android.hardware.Sensor#TYPE_ORIENTATION * Sensor.TYPE_ORIENTATION}:

All values are angles in degrees. * * * *

* Note: This definition is different from yaw, pitch and roll * used in aviation where the X axis is along the long side of the plane * (tail to nose). *

* *

* Note: This sensor type exists for legacy reasons, please use * {@link android.hardware.SensorManager#getRotationMatrix * getRotationMatrix()} in conjunction with * {@link android.hardware.SensorManager#remapCoordinateSystem * remapCoordinateSystem()} and * {@link android.hardware.SensorManager#getOrientation getOrientation()} to * compute these values instead. *

* *

* Important note: For historical reasons the roll angle is positive * in the clockwise direction (mathematically speaking, it should be * positive in the counter-clockwise direction). *

* *

{@link android.hardware.Sensor#TYPE_AMBIENT_TEMPERATURE Sensor.TYPE_AMBIENT_TEMPERATURE}: *

* * * * @see SensorEvent * @see GeomagneticField */ public final float[] values; /** * The sensor that generated this event. See * {@link android.hardware.SensorManager SensorManager} for details. */ public Sensor sensor; /** * The accuracy of this event. See {@link android.hardware.SensorManager * SensorManager} for details. */ public int accuracy; /** * The time in nanosecond at which the event happened */ public long timestamp; SensorEvent(int size) { values = new float[size]; } }