/* * 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. *

*

* 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_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_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). *

* * @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]; } }