Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Accelerometer

A BlackBerry device with a touch screen includes an accelerometer, which is designed to sense the orientation and acceleration of the BlackBerry device. When a BlackBerry device user moves the BlackBerry device, the accelerometer can sense the movement in 3-D space along the x, y, and z axis. A device user can change the orientation of the device which can change the display direction of a screen for a BlackBerry device application between portrait and landscape.

You can use the Accelerometer APIs in the net.rim.device.api.system package to respond to the orientation and acceleration of a BlackBerry device. For example, you can manipulate a game application to change the direction and speed of a moving object on the screen as a user moves and rotates the BlackBerry device at different speeds.

To download a sample application that demonstrates how to use the accelerometer, visit www.blackberry.com/go/accelerometersample. For more information about the sample application, visit www.blackberry.com/go/devguides to read the Accelerometer Sample Application Overview.

Types of accelerometer data

A BlackBerry device application can retrieve data from the accelerometer.

Data type

Description

orientation

The orientation of the BlackBerry device with respect to the ground.

acceleration

The acceleration of the rotation of the BlackBerry device.

For more information about types of data from the accelerometer, see the API reference for the BlackBerry Java Development Environment.

Retrieving accelerometer data

The accelerometer is designed to track the direction and speed of the movement along an x, y, and z axis when a BlackBerry device user moves the BlackBerry device. The x axis is parallel to the width of the BlackBerry device. The y axis is parallel to the length of the BlackBerry device. The z axis is parallel to the depth (front to back) of the BlackBerry device. For more information about the x, y, and z axes of the accelerometer, see the net.rim.device.api.system.AccelerometerSensor class in the API reference for the BlackBerry Java Development Environment.

You can enable a BlackBerry device application to react to the acceleration of the BlackBerry device that includes an accelerometer. For example, a BlackBerry device user could move the BlackBerry device to control the direction and speed of an object that moves through a maze in a game application.

You can use the Accelerometer APIs, in the net.rim.device.api.system package, to react to the acceleration of the BlackBerry device. You must first determine whether the BlackBerry device supports an accelerometer by invoking net.rim.device.api.system.AccelerometerSensor.isSupported(). If the method returns the value true, the BlackBerry device supports an accelerometer.

You can use the AccelerometerData class to identify the direction the user moves the BlackBerry device. Invoking AccelerometerData.getOrientation() returns one of the AccelerometerSensor class constants that correspond to the direction of the BlackBerry device. For example, if AccelerometerData.getOrientation() returns a value equal to AccelerometerSensor.ORIENTATION_LEFT_UP, the left side of the BlackBerry device is in an upward direction.

You can use the AccelerometerSensor class to retrieve acceleration data from the BlackBerry device. Invoking AccelerometerSensor.openRawDataChannel() returns an object of the net.rim.device.api.system.AccelerometerSensor.Channel class. The AccelerometerSensor.Channel class allows you to open a connection to the accelerometer. You can retrieve data from the accelerometer by invoking AccelerometerSensor.Channel.getLastAccelerationData().

Maintaining a connection to the accelerometer uses power from the BlackBerry device battery. When the BlackBerry device application no longer needs to retrieve data from the accelerometer, you should invoke AccelerometerSensor.Channel.close() to close the connection.

Code sample: Retrieving data from the accelerometer
short[] xyz = new short[3];
while( running ) {
    channel.getLastAccelerationData(xyz);
}
channel.close();

Retrieve accelerometer data at specific intervals

If a BlackBerry device application opens a channel to the accelerometer when the application is in the foreground, when the application is in the background, the channel pauses and the accelerometer is not queried. If a BlackBerry device application invokes AccelerometerSensor.Channel. getLastAccelerationData(short[]) at close intervals or when the BlackBerry device is not in motion, the method might return duplicate values.

  1. Import the following classes:

    • net.rim.device.api.system.AccelerometerSensor.Channel;
    • net.rim.device.api.system.AccelerometerSensor;
  2. Open a channel to the accelerometer. While a channel is open, the BlackBerry device application will query the accelerometer for information.

    Channel rawDataChannel = AccelerometerSensor.openRawDataChannel(
         Application.getApplication() );
  3. Create an array to store the accelerometer data.

    short[] xyz = new short[ 3 ];
  4. Create a thread.

     while( running ) {
  5. Invoke Channel.getLastAccelerationData(short[]) to retrieve data from the accelerometer.

    rawDataChannel.getLastAccelerationData( xyz );
  6. Invoke Thread.sleep() to specify the interval between queries to the accelerometer, in milliseconds.

    Thread.sleep( 500 );
  7. Invoke Channel.close() to close the channel to the accelerometer.

    rawDataChannel.close();

Query the accelerometer when the application is in the foreground

  1. Import the following classes:

    • net.rim.device.api.system.AccelerometerChannelConfig
    • net.rim.device.api.system.AccelerometerSensor.Channel
  2. Open a channel to retrieve acceleration data from the accelerometer.

    Channel channel =
        AccelerometerSensor.openRawAccelerationChannel( Application.getApplication());
  3. Invoke Thread.sleep() to specify the interval between queries to the accelerometer, in milliseconds.

    short[] xyz = new short[ 3 ];
      while( running ) {
           channel.getLastAccelerationData( xyz );
           Thread.sleep( 500 );
      }
  4. Invoke Channel.close() to close the channel to the accelerometer.

    channel.close();

Query the accelerometer when the application is in the background

  1. Import the following classes:

    • net.rim.device.api.system.AccelerometerChannelConfig;
    • net.rim.device.api.system.AccelerometerSensor.Channel;
  2. Create a configuration for a channel to the accelerometer.

    AccelerometerChannelConfig channelConfig = 
          new AccelerometerChannelConfig( AccelerometerChannelConfig.TYPE_RAW );
    
  3. Invoke AccelerometerChannelConfig.setBackgroundMode(Boolean), to specify support for an application that is in the background.

    channelConfig.setBackgroundMode( true );
    
  4. Invoke AccelerometerSensor.openChannel(), to open a background channel to the accelerometer.

    Channel channel = AccelerometerSensor.openChannel( 
           Application.getApplication(), channelConfig );
    
  5. Invoke Thread.sleep() to specify the interval between queries to the accelerometer, in milliseconds.

    short[] xyz = new short[ 3 ];
      while( running ) {
           channel.getLastAccelerationData( xyz );
           Thread.sleep( 500 );
    }
  6. Invoke Channel.close() to close the channel to the accelerometer.

    channel.close();

Store accelerometer readings in a buffer

  1. Import the following classes:

    • net.rim.device.api.system.AccelerometerChannelConfig;
    • net.rim.device.api.system.AccelerometerSensor.Channel;
  2. Create a configuration for a channel to the accelerometer.

    AccelerometerChannelConfig channelConfig = 
         new AccelerometerChannelConfig( AccelerometerChannelConfig.TYPE_RAW );
    
  3. Invoke AccelerometerChannelConfig.setSamplesCount(), to specify the number of acceleration readings to store in the buffer. Each element in the buffer contains acceleration readings for the x, y, and z axes and data on when the reading took place.

    channelConfig.setSamplesCount( 500 );
    

  4. Invoke AccelerometerSensor.openChannel() to open a channel to the accelerometer.

    Channel bufferedChannel = AccelerometerSensor.openChannel(
         Application.getApplication(), channelConfig );
    

Retrieve accelerometer readings from a buffer

  1. Import the following classes:

    • net.rim.device.api.system.AccelerometerData;
    • net.rim.device.api.system.AccelerometerSensor.Channel;
  2. Query the buffer for accelerometer data.

    AccelerometerData accData = bufferedChannel.getAccelerometerData();
    
  3. Invoke AccelerometerData.getNewBatchLength(), to get the number of readings retrieved since the last query.

    int newBatchSize = accData.getNewBatchLength();
    
  4. Invoke AccelerometerData.getXAccHistory(), AccelerometerData.getYAccHistory(), and AccelerometerData.getZAccHistory() to retrieve accelerometer data from the buffer for each axis.

    short[] xAccel = accData.getXAccHistory();
    short[] yAccel = accData.getYAccHistory();
    short[] zAccel = accData.getZAccHistory();

Get the time a reading was taken from the accelerometer

  1. Import the net.rim.device.api.system.AccelerometerData class.

  2. Query the buffer for accelerometer data.

    AccelerometerData accData;
    accData = bufferedChannel.getAccelerometerData();
  3. Invoke AccelerometerData.getSampleTsHistory().

    long[] queryTimestamps = accData.getSampleTsHistory();