net.rim.device.api.system
Class AccelerometerSensor

java.lang.Object
  |
  +--net.rim.device.api.system.AccelerometerSensor

public class AccelerometerSensor
extends Object

Provides accelerometer sensor query and listener registration methods.

Overview

There are two types of accelerometer data:

Acceleration sensors return G-force values along the X, Y, and Z axes, relative to the ground, as follows:

For example, if the handheld is lying flat on a table, the X and Y values are equal to 0, while Z is equal to 1000 (which represents G-Force, or 9.80665m/sec2). In freefall, all three values are equal to 0. The G-Force value is specified by G_FORCE_VALUE constant.

Hardware Limitations

Accelerometer sensor hardware is limited by the following factors:

Battery Considerations

Subscribing to accelerometer sensor readings is costly for the device battery, and should therefore only be used only when necessary. To turn on the accelerometer sensor, invoke the openRawDataChannel(Application) or openOrientationDataChannel(Application) methods. While the returned channel is open, the accelerometer sensor is powered and is sampled for changes. When the returned channel is closed, the accelerometer sensor is not queried.

Code Samples

The following code sample illustrates how to retrieve periodic acceleration data in a dedicated thread:

 public void run()
 {
     // open channel
     Channel rawDataChannel = AccelerometerSensor.openRawDataChannel( Application.getApplication() );
     // create raw sample vector with three components - X, Y, Z
     short[] xyz = new short[ 3 ];
     while( running ) {
         // read acceleration
         rawDataChannel.getLastAccelerationData( xyz );
         // process the acceleration
         process( xyz );
         // sleep for maintaining query rate
         Thread.sleep( 500 );
     }
     // close the channel to stop sensor query routine
     rawDataChannel.close();
 }
 

When using orientation values instead of raw sample values, the most efficient way is to receive orientation change notifications using a listener. This approach avoids having to create another applications thread for periodic orientation checks. The following code sample illustrates how to use an orientation listener:

 private Channel orientationChannel;
 
 public void register()
 {
     // open channel
     orientationChannel = AccelerometerSensor.openOrientationDataChannel( Application.getApplication() );
     orientationChannel.setAccelerometerListener( this );
 }
 
 public void onData( AccelerometerData accData )
 {
     // get the new orientation
     int newOrientation = accData.getOrientation();
     // relayout accordingly
     relayout( newOrientation );
 }
 
 public void unregister()
 {
     // close the channel to save power
     orientationChannel.close();
 }
 

The following code sample illustrates how to specify background raw data listening:

 // create channel config
 AccelerometerChannelConfig channelConfig = new AccelerometerChannelConfig( AccelerometerChannelConfig.TYPE_RAW );
 // specify background mode support
 channelConfig.setBackgroundMode( true );
 // open accelerometer channel that is active in background
 Channel channel = AccelerometerSensor.openChannel( Application.getApplication(), channelConfig );
 

The following code sample illustrates how to configure channel to accumulate samples in a buffer:

 // create channel config
 AccelerometerChannelConfig channelConfig = new AccelerometerChannelConfig( AccelerometerChannelConfig.TYPE_RAW );
 // specify number of raw acceleration samples to keep in buffer
 channelConfig.setSamplesCount( 500 );
 // open accelerometer channel
 Channel bufferedChannel = AccelerometerSensor.openChannel( Application.getApplication(), channelConfig );
 
The following code sample illustrates how to query for accumulated raw acceleration samples:
 AccelerometerData accData;
 while( running ) {
     // query for buffered accelerometer data
     accData = bufferedChannel.getAccelerometerData();
     // get the number of new acceleration samples
     int newBatchSize = accData.getNewBatchLength();
     // get samples buffers
     short[] xAccel = accData.getXAccHistory();
     short[] yAccel = accData.getYAccHistory();
     short[] zAccel = accData.getZAccHistory();
     // process new batch
     process( xAccel, yAccel, zAccel );
     // sleep for some seconds
     Thread.sleep( 4000 );
 }
 

Since:
JDE 4.7.0

Inner Class Summary
static class AccelerometerSensor.Channel
          Encapsulates an active connection to accelerometer sensor.
 
Field Summary
static int G_FORCE_VALUE
          Constant for raw acceleration value that is equal to G-Force.
static int ORIENTATION_BACK_UP
          Orientation constant indicating the BlackBerry device display is directly facing the ground.
static int ORIENTATION_BOTTOM_UP
          Orientation constant indicating the bottom side of the Blackberry device is moving upwards.
static int ORIENTATION_FRONT_UP
          Orientation constant indicating the BlackBerry device display is facing 180 degrees from the ground.
static int ORIENTATION_LEFT_UP
          Orientation constant indicating the left side of the BlackBerry device is moving upwards.
static int ORIENTATION_RIGHT_UP
          Orientation constant indicating the right side of the BlackBerry device is moving upwards.
static int ORIENTATION_TOP_UP
          Orientation constant indicating the top side of the Blackberry device is moving upwards.
static int ORIENTATION_UNKNOWN
          Orientation constant indicating an unknown BlackBerry device orientation.
 
Method Summary
static boolean isSupported()
          Returns if accelerometer sensor is supported on this device.
static AccelerometerSensor.Channel openChannel(Application app, AccelerometerChannelConfig cfg)
          Turns on accelerometer sensor based on channel configuration.
static AccelerometerSensor.Channel openOrientationDataChannel(Application app)
          Turns on accelerometer sensor for orientation data.
static AccelerometerSensor.Channel openRawDataChannel(Application app)
          Turns on accelerometer sensor for raw acceleration data.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

G_FORCE_VALUE

public static final int G_FORCE_VALUE
Constant for raw acceleration value that is equal to G-Force.
Since:
JDE 4.7.0

ORIENTATION_BACK_UP

public static final int ORIENTATION_BACK_UP
Orientation constant indicating the BlackBerry device display is directly facing the ground.
Since:
JDE 4.7.0

ORIENTATION_BOTTOM_UP

public static final int ORIENTATION_BOTTOM_UP
Orientation constant indicating the bottom side of the Blackberry device is moving upwards.
Since:
JDE 4.7.0

ORIENTATION_FRONT_UP

public static final int ORIENTATION_FRONT_UP
Orientation constant indicating the BlackBerry device display is facing 180 degrees from the ground.
Since:
JDE 4.7.0

ORIENTATION_LEFT_UP

public static final int ORIENTATION_LEFT_UP
Orientation constant indicating the left side of the BlackBerry device is moving upwards.
Since:
JDE 4.7.0

ORIENTATION_RIGHT_UP

public static final int ORIENTATION_RIGHT_UP
Orientation constant indicating the right side of the BlackBerry device is moving upwards.
Since:
JDE 4.7.0

ORIENTATION_TOP_UP

public static final int ORIENTATION_TOP_UP
Orientation constant indicating the top side of the Blackberry device is moving upwards.
Since:
JDE 4.7.0

ORIENTATION_UNKNOWN

public static final int ORIENTATION_UNKNOWN
Orientation constant indicating an unknown BlackBerry device orientation.
Since:
JDE 4.7.0
Method Detail

isSupported

public static boolean isSupported()
Returns if accelerometer sensor is supported on this device. If there is no accelerometer sensor, the channel registration methods throw IllegalStateException.
Returns:
true if supported; false otherwise.
Since:
JDE 4.7.0

openChannel

public static AccelerometerSensor.Channel openChannel(Application app,
                                                      AccelerometerChannelConfig cfg)
                                               throws IllegalStateException,
                                                      IllegalArgumentException
Turns on accelerometer sensor based on channel configuration.
Throws:
IllegalStateException - if the handheld does not have accelerometer sensor, or if channel is already opened for an application, or both foreground and background modes are off.
IllegalArgumentException - if channel is configured for raw data, and count is less than 1.
Since:
JDE 4.7.0

openOrientationDataChannel

public static AccelerometerSensor.Channel openOrientationDataChannel(Application app)
Turns on accelerometer sensor for orientation data. The channel can be queried for orientation data by invoking the AccelerometerSensor.Channel.getOrientation() method. Alternatively, a listener can be registered by invoking the AccelerometerSensor.Channel.setAccelerometerListener(AccelerometerListener) method. An applicaton can open only one accelerometer channel.
Since:
JDE 4.7.0

openRawDataChannel

public static AccelerometerSensor.Channel openRawDataChannel(Application app)
Turns on accelerometer sensor for raw acceleration data. The channel can be queried for acceleration data by invoking the AccelerometerSensor.Channel.getLastAccelerationData(short[]) method. An applicaton can open only one accelerometer channel.
Since:
JDE 4.7.0



Copyright 1999-2009 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.