Reading orientation events

How to

Read orientation data and events on the BlackBerry 10 device to determine its orientation.

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);

                // Correct for true North by getting the magnetic field and 
                // applying the declination.
                wmm_geomagnetic_field_t gmf;
                
                // wmm_get_geomagnetic_field() is an expensive call, and should
                // only be called on a location change, not every time a sensor
                // reading is available. It's called here to demonstrate how to
                // get the magnetic field and apply the declination.
                wmm_get_geomagnetic_field(loc, dt, &gmf);
                azimuth += gmf.declination_deg;
                // Handle new direction and orientation angle 
            }
        }
    }
}

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 a BlackBerry 10 device with the BlackBerry logo at the bottom, the screen is in portrait mode. If the user rotates the device 90 degrees to the left or right, the screen is in landscape mode. An angle of 0 indicates that a device is in its natural orientation (e.g., portrait mode for a BlackBerry 10 device).

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 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.

Last modified: 2014-05-14



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus