ch.aplu.android

Class GGSensor

java.lang.Object

ch.aplu.android.GGSensor

public class GGSensor
extends java.lang.Object

Representation of one of the built-in hardware sensors. The sensor is polled by a system internal thread using a certain polling delay defined in class SensorManager (default SensorManager.SENSOR_DELAY_NORMAL). The measured values are stored and reported by the GGSensor polling method getValues(). If a GGSensorListener is registered, the sensorChanged() callback is fired each time the sensor values change.

Use GameGrid.enumerateSensors() to list the available sensors, but keep in mind that even if a sensor is built-in, it may report zero values only.

This class uses the new (undeprecated) Android sensor API which may deliver inaccurate values for the magnetic field and thus for the calculated orientation (especially for the azimuth) when used with older Android devices. For older devices better use the GGComboSensor class that is based on the old Android sensor API.

To get the orientation using the new API, determine the rotation matrix R with
SensorManager.getRotationMatrix(R, I, acceleration, magneticField)
and call
SensorManager.getOrientation(R, orientation) where
azimuth = orientation[0], zero to north, positive to east (in radians)
pitch = orientation[1], zero when horizontal, positive when the y-axes points downwards (in radians)
roll = orientation[2], zero when horizontal, positive when the x-axes points downwards (in radians)

Constructor Summary

Constructors

Constructor and Description
GGSensor(android.app.Activity activity, int sensorType) Creates a sensor instance using the sensor of given sensor type.
GGSensor(android.app.Activity activity, int sensorType, int sensorDelay) Creates a sensor instance using the sensor of given sensor type.

Method Summary

Methods

Modifier and Type	Method and Description
void	addSensorListener(GGSensorListener listener) Registers a GGSensorListener to get notifications when the sensor reports new values.
static float[]	deviceToWorld(float[] R, float[] vDevice) Returns the result of the matrix multiplication R * vDevice.
static float	getAzimuthCalc(float[] g, float[] B) Returns the azimuth calculated from given gravity and earth magnetic field.
static float	getPitchCalc(float[] g) Returns the pitch calculated from given gravity and earth magnetic field.
static float	getRollCalc(float[] g) Returns the roll calculated from given gravity and earth magnetic field.
int	getType() Returns the sensor type (constants defined in android.hardware.Sensor).
float[]	getValues() Returns the last values received from the sensor.
void	setHighPassFilter(float samplingFreq, float cutoffFreq) Sets the sampling frequency and the cutoff frequency of the high-pass filter applied to the sensor data.
void	setLowPassFilter(float samplingFreq, float cutoffFreq) Sets the sampling frequency and the cutoff frequency of the low-pass filter applied to the sensor data.
void	setNoFilter() Disables filtering of sensor data (default).
static float[]	toDeviceRotation(android.app.Activity activity, float[] device, int sensorType) Converts the values from the device fixed coordinate system to a device coordinate system that is adapted to the current application device rotation (portrait, reverse portrait, landscape, reverse landscape).
static float[]	worldToDevice(float[] R, float[] vWorld) Returns the result of the matrix multiplication R_inverse * vWorld.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GGSensor

public GGSensor(android.app.Activity activity,
        int sensorType,
        int sensorDelay)

Creates a sensor instance using the sensor of given sensor type. If the sensor is not available, no event is triggered and all polled values are zero. The polling period depends on the sensorDelay constant, but varies very much. (Test results show 1 - 100 ms for SensorManager.SENSOR_DELAY_FASTEST, 100 - 200 ms for SensorManager.SENSOR_DELAY_NORMAL).

Parameters:

activity - the activity used to access the system

sensorType - the type of sensor (constants defined in android.hardware.Sensor)

sensorDelay - one of the SENSOR_DELAY constants in class SensorManager

GGSensor

public GGSensor(android.app.Activity activity,
        int sensorType)

Creates a sensor instance using the sensor of given sensor type. If the sensor is not available, no event is triggered and all polled values are zero. The sensor is polled with the standard delay SensorManager.SENSOR_DELAY_NORMAL (100 -200 ms period).

Parameters:

activity - the activity used to access the system

sensorType - the type of sensor (constants defined in android.hardware.Sensor)

Method Detail

addSensorListener

public void addSensorListener(GGSensorListener listener)

Registers a GGSensorListener to get notifications when the sensor reports new values.

Parameters:

listener - the GGSensorListener to register

getType

public int getType()

Returns the sensor type (constants defined in android.hardware.Sensor).

Returns:

the type of the sensor

getValues

public float[] getValues()

Returns the last values received from the sensor. If setLowPassFilter() or setHighPassFilter() was called before, the returned data are low or high-pass filtered. The length of the value array is 3. The content depends on which sensor type is being monitored (array elements not used are set to zero).

Thread.sleep(1) is included to release the thread when polling in a narrow loop.

The device fixed coordinate system is defined as follows:
x short side for smartphones, long side for tablets(positive: to right)
y long side for smartphones, short side for tablets (positive: to front)
z normal (positive: up)

Overview (see class SensorEvent for more details):

Sensor.TYPE_ACCELEROMETER:
Values in m/s^2
values[0]: Device acceleration minus gx on the x-axis
values[1]: Device acceleration minus gy on the y-axis
values[2]: Device acceleration minus gz on the z-axis

Example: Device on a horizontal table: gx = 0, gy = 0 and gz = -9.81; reported values: {0, 0, +9.81}

Keep in mind that when the device is moved the current device acceleration is returned. If only the earth gravitational acceleration component is needed, you must use Sensor.TYPE_GRAVITY or apply a low-pass filter to the data (by calling setLowPassFilter()).

Sensor.TYPE_MAGNETIC_FIELD:
Values inaccurate for older Android devices Values in Microtesla (uT)
values[0]: Magnetic field on the x-axis
values[1]: Magnetic field on the y-axis
values[2]: Magnetic field on the z-axis

Sensor.TYPE_GYROSCOPE:
Values in radians/second (1/s)
values[0]: Angular speed around the x-axis
values[1]: Angular speed around the y-axis
values[2]: Angular speed around the z-axis

Sensor.TYPE_LIGHT:
values[0]: Ambient light level lux

Sensor.TYPE_PRESSURE:
values[0]: Atmospheric pressure in hectopascal (hPa, millibar)

Sensor.TYPE_PROXIMITY:
values[0]: Proximity sensor distance measured in centimeters

Sensor.TYPE_RELATIVE_HUMIDITY:
values[0]: Relative ambient air humidity in percent

Returns:

the last values measured by the sensor (array size = 3)

deviceToWorld

public static float[] deviceToWorld(float[] R,
                    float[] vDevice)

Returns the result of the matrix multiplication R * vDevice. R is the rotation matrix (structured as float array of size 9) as returned from SensorManager.getRotationMatrix(R, I, gravitationAcceleration, earthMagneticField). (gravitationAcceleration and earchMagneticField in device coordinates). gravitationAcceleration should not include the device acceleration caused by a device movement. If Sensor.TYPE_GRAVITY is not available, the values from Sensor.TYPE_ACCELEROMETER should be low-pass filtered by calling setLowPassFilter().

The device fixed coordinate system is defined as follows:
x short side for smartphones, long side for tablets(positive: to right)
y long side for smartphones, short side for tablets (positive: to front)
z normal (positive: up)

The world coordinate system is defined as follows:
(x-y plane is horizontal, z perpenticular)
x to east (tangent to circle of latitude)
y to north (tangent to circle of longitude)
z to zenith

Parameters:

R - the rotation matrix (float array of size 9):

R[0], R[1], R[2]
R[3], R[4], R[5]
R[4], R[7], R[8]

vDevice - the vector in device coordinates

Returns:

the vector in world coordinates

worldToDevice

public static float[] worldToDevice(float[] R,
                    float[] vWorld)

Returns the result of the matrix multiplication R_inverse * vWorld. (see deviceToWorld() for more information on the coordinate systems.

Parameters:

R - the rotation matrix (float array of size 9):

R[0], R[1], R[2]
R[3], R[4], R[5]
R[4], R[7], R[8]

vWorld - the vector in world coordinates

Returns:

the vector in device coordinates

toDeviceRotation

public static float[] toDeviceRotation(android.app.Activity activity,
                       float[] device,
                       int sensorType)

Converts the values from the device fixed coordinate system to a device coordinate system that is adapted to the current application device rotation (portrait, reverse portrait, landscape, reverse landscape).

Parameters:

device - the values in the device fixed coordinate system (float array of size 3)

sensorType - the type of sensor (one of the constants Sensor.TYPE_ACCELEROMETER, Sensor.TYPE_MAGNETIC_FIELD, Sensor.TYPE_ORIENTATION)

Returns:

the values in a coordinate system with rotated x-y-axes (float array of size 3)

getAzimuthCalc

public static float getAzimuthCalc(float[] g,
                   float[] B)

Returns the azimuth calculated from given gravity and earth magnetic field.

The device fixed coordinate system is defined as follows:
x short side for smartphones, long side for tablets(positive: to right)
y long side for smartphones, short side for tablets (positive: to front)
z normal (positive: up)

Parameters:

g - the gravity acceleration vector (gx, gy, gz) in the device fixed coordinate system

B - the earth magnetic field (Bx, By, Bz) (in uT) in the device fixed coordinate system

Returns:

the calculated azimuth (in radians)

getPitchCalc

public static float getPitchCalc(float[] g)

Returns the pitch calculated from given gravity and earth magnetic field.

The device fixed coordinate system is defined as follows:
x short side for smartphones, long side for tablets(positive: to right)
y long side for smartphones, short side for tablets (positive: to front)
z normal (positive: up)

Parameters:

g - the gravity acceleration vector (gx, gy, gz)

Returns:

the calculated pitch (in radians)

getRollCalc

public static float getRollCalc(float[] g)

Returns the roll calculated from given gravity and earth magnetic field.

The device fixed coordinate system is defined as follows:
x short side for smartphones, long side for tablets(positive: to right)
y long side for smartphones, short side for tablets (positive: to front)
z normal (positive: up)

Parameters:

g - the gravity acceleration vector (gx, gy, gz)

Returns:

the calculated roll (in radians)

setHighPassFilter

public void setHighPassFilter(float samplingFreq,
                     float cutoffFreq)

Sets the sampling frequency and the cutoff frequency of the high-pass filter applied to the sensor data. The sampling frequency depends on the sensorDelay parameter in the GGSensor constructor (about 10 Hz for SensorManager.SENSOR_DELAY_NORMAL). The cutoff frequency corresponds roughly to the lower limit of passed frequency components (-3 dB cutoff). To eliminate the static gravity acceleration, samplingFreq = 10 and cutoffFreq = 1 are appropriate.

Parameters:

samplingFreq - (in Hz)

cutoffFreq - (in Hz)

setLowPassFilter

public void setLowPassFilter(float samplingFreq,
                    float cutoffFreq)

Sets the sampling frequency and the cutoff frequency of the low-pass filter applied to the sensor data. The sampling frequency depends on the sensorDelay parameter in the GGSensor constructor (about 10 Hz for SensorManager.SENSOR_DELAY_NORMAL). The cutoff frequency corresponds roughly to the upper limit of passed frequency components (-3 dB cutoff). To eliminate noise and jitter, samplingFreq = 10 and cutoffFreq = 5 are appropriate.

Parameters:

samplingFreq - (in Hz)

cutoffFreq - (in Hz)

setNoFilter

public void setNoFilter()

Disables filtering of sensor data (default).