/* * 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 sensor event and holds informations such as the * sensor type (eg: accelerometer, orientation, etc...), 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 space 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 OpenGL ES coordinate system is used. The origin is in the
 * lower-left corner  with respect to the screen, with the X axis horizontal
 * and pointing  right, the Y axis vertical and pointing up and the Z axis
 * pointing outside the front face of the screen. In this system, coordinates
 * behind the screen have negative Z values.
 * 
 * Note: This coordinate system is different from the one used in the
 * Android 2D APIs where the origin is in the top-left corner. 
 *
 *   x<0         x>0
 *                ^
 *                |
 *    +-----------+-->  y>0
 *    |           |
 *    |           |
 *    |           |
 *    |           |   / z<0
 *    |           |  /
 *    |           | /
 *    O-----------+/
 *    |[]  [ ]  []/
 *    +----------/+     y<0
 *              /
 *             /
 *           |/ z>0 (toward the sky)
 *
 *    O: Origin (x=0,y=0,z=0)
 *
*/ public class SensorEvent { /** * The length and contents of the values array vary depending on which * sensor type is being monitored (see also {@link SensorEvent} for a * definition of the coordinate system used): * *

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

* All values are angles in degrees. * *

values[0]: Azimuth, angle between the magnetic north direction and * the Y axis, around the Z axis (0 to 359). * 0=North, 90=East, 180=South, 270=West * *

values[1]: Pitch, rotation around X axis (-180 to 180), * with positive values when the z-axis moves toward the y-axis. * *

values[2]: Roll, rotation around Y axis (-90 to 90), with * positive values when the x-axis moves toward the z-axis. * *

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

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

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

* All values are in SI units (m/s^2) and measure the acceleration applied * to the phone minus the force of gravity. * *

values[0]: Acceleration minus Gx on the x-axis *

values[1]: Acceleration minus Gy on the y-axis *

values[2]: Acceleration minus Gz on the z-axis * *

Examples: *

  • When the device lies flat on a table and is pushed on its left * side toward the right, the x acceleration value is positive.
    • * *
  • When the device lies flat on a table, the acceleration value is * +9.81, which correspond to the acceleration of the device (0 m/s^2) * minus the force of gravity (-9.81 m/s^2).
    • * *
  • When the device lies flat on a table and is pushed toward the sky * with an acceleration of A m/s^2, the acceleration value is equal to * A+9.81 which correspond to the acceleration of the * device (+A m/s^2) minus the force of gravity (-9.81 m/s^2).
    • * * *

    {@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}:

    * *

    values[0]: Ambient light level in SI lux units * *

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

    * *

    values[0]: Proximity sensor distance measured in centimeters * *

    Note that some proximity sensors only support a binary "close" or "far" measurement. * In this case, the sensor should report its maxRange value in the "far" state and a value * less than maxRange in the "near" state. */ 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]; } }