public abstract class MotionSensorManager

  1. Object
  2. MotionSensorManager

Cross platform access to the device motion sensors (accelerometer, gyroscope, magnetometer and the derived gravity, linear acceleration and orientation) together with high level gesture detection (shake, flip, tilt, pick up and free fall).

Obtain the singleton through getInstance(). The instance is always non null; on a device or port without motion sensors every sensor simply reports as unsupported and no events are delivered.

Reading a sensor

MotionSensorManager m = MotionSensorManager.getInstance();
MotionSensor accel = m.getSensor(MotionSensorManager.TYPE_ACCELEROMETER);
if (accel != null) {
    accel.addListener(new MotionSensorListener() {
        public void motionReceived(MotionEvent evt) {
            // evt.getX(), evt.getY(), evt.getZ() are in m/s^2
        }
    });
}

Listening for a gesture

MotionSensorManager.getInstance().addGestureListener(GestureEvent.TYPE_SHAKE, new GestureListener() {
    public void gestureDetected(GestureEvent evt) {
        Dialog.show("Shaken", "You shook the device", "OK", null);
    }
});

All callbacks are delivered on the EDT. Sampling is reference counted so the hardware sensors are only powered while at least one listener (sensor or gesture) is registered; remember to remove your listeners to save battery.

iOS note: access to the motion hardware requires the build argument ios.NSMotionUsageDescription describing why the app reads motion data.

Fields

public static final int TYPE_ACCELEROMETER = 1Accelerometer including the effect of gravity, in meters per second squared.
public static final int TYPE_LINEAR_ACCELERATION = 2Acceleration with the effect of gravity removed, in meters per second squared.
public static final int TYPE_GRAVITY = 3The gravity vector in meters per second squared.
public static final int TYPE_GYROSCOPE = 4Rate of rotation around the three axes in radians per second.
public static final int TYPE_MAGNETOMETER = 5The ambient magnetic field in microtesla.
public static final int TYPE_ORIENTATION = 6Device orientation as azimuth, pitch and roll in radians.
public static final double STANDARD_GRAVITY = 9.80665Standard earth gravity in meters per second squared, the unit used by the acceleration sensors.

Constructors

public MotionSensorManager()

Methods

public static MotionSensorManager getInstance()Returns the shared motion sensor manager.
protected abstract boolean isNativeSensorSupported(int type)Whether the named hardware sensor is present on this device.
protected abstract void startNativeSensor(int type)Starts the named hardware sensor.
protected abstract void stopNativeSensor(int type)Stops the named hardware sensor.
protected abstract boolean readNativeSensor(int type, float[] out)Reads the latest value of the named hardware sensor.
public boolean isSensorSupported(int type)Whether the given sensor type can deliver readings on this device.
public MotionSensor getSensor(int type)Returns the sensor object for the given type, or null if the type is not supported on this device.
public void addGestureListener(int gestureType, GestureListener l)Registers a listener for a specific gesture.
public void removeGestureListener(int gestureType, GestureListener l)Removes a previously registered gesture listener.
public int getSamplingInterval()The requested time between sensor samples in milliseconds.
public void setSamplingInterval(int millis)Sets the requested time between sensor samples in milliseconds.
public void setShakeThreshold(double threshold)Sets the linear acceleration spike, in meters per second squared, above which jolts are counted towards a shake.
public void setTiltThreshold(double radians)Sets the tilt angle, in radians, at which the tilt gestures fire.
public void setFreeFallThreshold(double threshold)Sets the total acceleration, in meters per second squared, below which the device is considered to be in free fall.
public void stop()Stops every sensor and removes all registered listeners.

Inherited methods

Field details

TYPE_ACCELEROMETER

public static final int TYPE_ACCELEROMETER = 1
Accelerometer including the effect of gravity, in meters per second squared.

TYPE_LINEAR_ACCELERATION

public static final int TYPE_LINEAR_ACCELERATION = 2
Acceleration with the effect of gravity removed, in meters per second squared. Derived in the core from the accelerometer when the platform does not provide it natively.

TYPE_GRAVITY

public static final int TYPE_GRAVITY = 3
The gravity vector in meters per second squared. Derived in the core from the accelerometer when the platform does not provide it natively.

TYPE_GYROSCOPE

public static final int TYPE_GYROSCOPE = 4
Rate of rotation around the three axes in radians per second.

TYPE_MAGNETOMETER

public static final int TYPE_MAGNETOMETER = 5
The ambient magnetic field in microtesla.

TYPE_ORIENTATION

public static final int TYPE_ORIENTATION = 6
Device orientation as azimuth, pitch and roll in radians. Derived in the core from the gravity vector (and the magnetometer for the azimuth).

STANDARD_GRAVITY

public static final double STANDARD_GRAVITY = 9.80665
Standard earth gravity in meters per second squared, the unit used by the acceleration sensors.

Constructor details

MotionSensorManager

public MotionSensorManager()

Method details

getInstance

public static MotionSensorManager getInstance()
Returns the shared motion sensor manager. Never null: when the active port does not provide motion sensors a no-op manager is returned whose sensors all report as unsupported.

isNativeSensorSupported

protected abstract boolean isNativeSensorSupported(int type)
Whether the named hardware sensor is present on this device. Only the hardware backed types (TYPE_ACCELEROMETER, TYPE_GYROSCOPE, TYPE_MAGNETOMETER and, where the OS exposes them, TYPE_GRAVITY and TYPE_LINEAR_ACCELERATION) are queried here; derived types are resolved by isSensorSupported(int).

Parameters

type int
one of the TYPE_* constants

startNativeSensor

protected abstract void startNativeSensor(int type)
Starts the named hardware sensor. Called when the first listener that needs it is registered.

stopNativeSensor

protected abstract void stopNativeSensor(int type)
Stops the named hardware sensor. Called when the last listener that needed it is removed.

readNativeSensor

protected abstract boolean readNativeSensor(int type, float[] out)
Reads the latest value of the named hardware sensor.

Parameters

type int
one of the TYPE_* constants
out float[]
a three element array to receive the x, y and z values

Returns

true if a value was written, false if no reading is available yet

isSensorSupported

public boolean isSensorSupported(int type)
Whether the given sensor type can deliver readings on this device. Takes into account values that the core derives from other sensors, so for example TYPE_ORIENTATION is supported whenever the accelerometer is.

Parameters

type int
one of the TYPE_* constants

getSensor

public MotionSensor getSensor(int type)
Returns the sensor object for the given type, or null if the type is not supported on this device. The same instance is returned for repeated calls with the same type.

Parameters

type int
one of the TYPE_* constants

addGestureListener

public void addGestureListener(int gestureType, GestureListener l)
Registers a listener for a specific gesture. The accelerometer is powered automatically while at least one gesture listener is registered.

Parameters

gestureType int
one of the GestureEvent.TYPE_* constants
l GestureListener
the listener to invoke when the gesture occurs

removeGestureListener

public void removeGestureListener(int gestureType, GestureListener l)
Removes a previously registered gesture listener.

Parameters

gestureType int
the gesture the listener was registered for
l GestureListener
the listener to remove

getSamplingInterval

public int getSamplingInterval()
The requested time between sensor samples in milliseconds. Defaults to 50ms (20Hz). The actual rate the hardware delivers may differ.

setSamplingInterval

public void setSamplingInterval(int millis)
Sets the requested time between sensor samples in milliseconds. Smaller values give more responsive gestures at a higher battery cost. Values are clamped to the range 10ms..1000ms.

Parameters

millis int
the requested interval

setShakeThreshold

public void setShakeThreshold(double threshold)
Sets the linear acceleration spike, in meters per second squared, above which jolts are counted towards a shake. Larger values require a more vigorous shake. The default is 12.0.

setTiltThreshold

public void setTiltThreshold(double radians)
Sets the tilt angle, in radians, at which the tilt gestures fire. The default is roughly 0.6 (about 34 degrees).

setFreeFallThreshold

public void setFreeFallThreshold(double threshold)
Sets the total acceleration, in meters per second squared, below which the device is considered to be in free fall. The default is 3.0.

stop

public void stop()
Stops every sensor and removes all registered listeners. Mostly useful for tests and for an explicit shutdown.