Devices running BlackBerry 10 have many sensors that collect data about the device and its external environment. Some are low-level, real-time sensors such as the accelerometer, and others are higher-level, event-driven sensors, like the holster sensor.

If you are developing a Cascades app, you can use the Sensors API to access sensor data on the device. The Sensors API is a component of the Qt Mobility Project. For a complete list of the sensors that are currently supported on BlackBerry 10 devices in Cascades, see Using Qt sensors and Supported sensors.

If you are developing an app using C or C++, you can access sensors using the BlackBerry Platform Services (libbps) library. For a complete list of sensors that are supported by BPS, see Using BPS sensors and Supported sensors.

You can also use the Sensor library. However, this guide focuses on accessing sensors using the Qt and BPS libraries.

Sensor readings

If sensor readings are not changed at all to reflect the orientation of the device, the following conventions apply:

Unless otherwise specified, sensors use the right-hand Cartesian coordinate system.

A graphic that shows the right-hand Cartesian coordinate system as it relates to the device.

To allow for measurements in all six directions, negative values are used.

A graphic that shows how the coordinate system works in negative directions.

Where rotation around an axis is used, the rotation is expressed as a right-hand rotation.

A graphic that shows how device rotations work.

In general, sensor data is oriented to the top of the device.

A graphic that shows where the top and bottom of the device are.

If values are displayed on the screen, you might need to translate the values so that they match the user interface orientation.

A sensor may define its data as being oriented to the UI. This situation is noted in the documentation for the sensor.

Influences on sensors

Some influences from outside of the device can affect sensor data. In particular, you should consider the impact of the Earth's magnetic field and the orientation of the device.

Magnetic field

The Earth's magnetic field affects readings from the following sensors:

If you want to point your device to true north, instead of magnetic north, you must adjust your sensor readings to account for magnetic declination. Magnetic declination is the angle between north (the direction that the north end of a compass needle points to) and true north (the direction to the North Pole). The time and the location of the device determine the value of this angle. You can retrieve the geomagnetic field, which includes the magnetic declination value, by calling wmm_get_geomagnetic_field().

You should call wmm_get_geomagnetic_field() only when the location of the device has changed. Your app should handle a location change in a BPS event handling loop by calling a function that updates a global variable containing the geomagnetic field value. Using a globally accessible instance of the geomagnetic field value in your app avoids the need to call wmm_get_geomagnetic_field() in multiple places.

Device orientation

If you are developing a Cascades app, there are several sensors that can have their sensor readings changed to reflect the orientation of the device (for example, QRotationSensor, QCompass, and QMagnetometer). The AxesOrientationMode enum contains the different settings that describe how sensor readings are affected by the device orientation. When using FixedOrientation, sensor values are displayed regardless of the orientation of the device. With AutomaticOrientation, the sensor readings are automatically rotated based on the device orientation. When using UserOrientation, the reading values are rotated based on the angle of the userOrientation property, which is an integer that reflects the screen orientation. The only valid values for the userOrientation property are 0, 90, 180, and 270.

If you are developing an app using C and your app's UI depends on sensor readings, you might need to remap the data to match the device's orientation. The orientation of a device has no impact on its sensor data. The sensor coordinate system remains the same, regardless of the orientation of the device, while the device's screen coordinates change when the device is rotated. To successfully incorporate sensor readings into an app when the UI is affected by orientation changes, you must map the sensor data to the screen coordinates from the sensor coordinates. For more information, see Remapping sensor data based on device orientation and Orientation in C.

Related resources

Web-based training

Core sample apps

Last modified: 2015-03-31

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

comments powered by Disqus