Reading orientation events

How to

Read orientation data and events on the BlackBerry PlayBook tablet to determine the orientation of the device.

Solution

int orientation_angle = 0;
orientation_direction_t direction; 

bps_initialize();
                
orientation_get(&direction, &orientation_angle);

if (sensor_is_supported(SENSOR_TYPE_AZIMUTH_PITCH_ROLL)) {

    static const int SENSOR_RATE = 25000;
    sensor_set_rate(SENSOR_TYPE_AZIMUTH_PITCH_ROLL, SENSOR_RATE);
    sensor_set_skip_duplicates(SENSOR_TYPE_AZIMUTH_PITCH_ROLL, true);
    sensor_request_events(SENSOR_TYPE_AZIMUTH_PITCH_ROLL);
} else {
    printf("Sensor not supported by device!");
    bps_shutdown();
    return EXIT_FAILURE;
}

int sensor_domain = sensor_get_domain(); 

while (!shutdown) {
    bps_event_t *event = NULL;
    bps_get_event(&event, 0);      //0 means that the function
                                   //doesn't wait for an event

    if (event) {
        if (bps_event_get_domain(event) == sensor_domain) {
            if (bps_event_get_code(event) ==
                SENSOR_AZIMUTH_PITCH_ROLL_READING) {

            float azimuth, pitch, roll;

            sensor_event_get_apr(event, &azimuth, &pitch, &roll);

            // Handle new direction and orientation angle here 
           }
        }
    }
}

Build requirements

You must include the following header files from the BlackBerry Platform Services (BPS) library:

#include <bps/orientation.h>
#include <bps/bps.h>
#include <bps/sensor.h>

Discussion

The orientation of a device relates to its position in space, measured as x, y, and z-axis angles from 0. This can be used to determine the screen display mode of the device. For example, if a user holds the BlackBerry PlayBook tablet with the BlackBerry logo at the bottom, the screen is in landscape mode. If the user rotates the device 90° to the left or right, the screen is in portrait mode. An angle of 0 indicates landscape mode.

There are two ways to obtain orientation data. First, you can obtain the current orientation of the device by calling the orientation_get() function. You can also obtain orientation data when the user changes the orientation using sensor events.

The user can hold the device in multiple directions that relate to the possible orientations listed in orientation_direction_t, which is contained in orientation.h. The values are ORIENTATION_FACE_UP, ORIENTATION_TOP_UP, ORIENTATION_BOTTOM_UP, ORIENTATION_LEFT_UP, ORIENTATION_RIGHT_UP, and ORIENTATION_FACE_DOWN.

Before you start using the sensor service, you must ensure the device supports it. This can be done through a simple call to sensor_is_supported(). This function is needed to distinguish between an actual device and the BlackBerry Tablet Simulator.

The hardware update rate is the frequency at which the sensor data is updated from the hardware. It is the maximum waiting time (in microseconds) before taking a sensor reading. The sensor_set_skip_duplicates() function enables or disables the skipping of duplicate events that are received from the sensor.

After your application is registered to receive sensor events using sensor_request_events(), you can call bps_get_event() to retrieve the next available event from BlackBerry Platform Services. You can use an event loop with a simple exit condition to process events continuously while your application is running. After an event is received, you should determine whether it's an orientation event by using sensor_get_domain().

The sensor_event_get_apr() function returns the values for the azimuth, pitch, and roll of the device, in degrees.