It seems like the browser you are using has JavaScript disabled. As a result, the site will not function properly. We really want you to enable it so you may experience our site as we intended it. If you have no idea what we are talking about or if you need help, visit http://www.enable-javascript.com×
This website uses cookies. By continuing to browse this site you are agreeing to our use of cookies. Find out more on our cookie page.×

Oops, it seems like you're using an old browser that we do not fully support. If you're able to, please upgrade your browser here.×
This website uses cookies. By continuing to browse this site you are agreeing to our use of cookies. Find out more on our cookie page.×

Accelerometer

The accelerometer measures the acceleration (including the force of
gravity) applied to the device. This sensor is useful if your app is designed to handle
motion input from a user. For example, in a racing game, the user might control the
car's direction by tilting the device from side-to-side.

Acceleration values are reported in meters per second per second (m/s2).

When the device is lying on a flat surface in its natural orientation (for
example, the BlackBerry logo is right-side-up and facing the user), the following are true:

Pushing the device to the right results in a positive acceleration
value along the x axis.

Pushing the device away from the user results in a positive
acceleration value along the y axis.

Pushing the device directly off the flat surface and into the air
results in a positive acceleration along the z-axis. This acceleration includes the
acceleration caused by the movement off the surface (accelup), minus the force of gravity. That is, accelz = accelup - (-9.81 m/s2) = accelup + 9.81 m/s2. At rest, the acceleration along the z-axis of the device is 9.81
m/s2.

If you are developing a Cascades app using
QML or C++, you might want to configure the sensor to report only on certain types of
movements by using the accelerationMode property. Possible values are Gravity (only movements caused by gravity), User (only movements caused by the user), and Combined (the default value). For more information, see
QAccelerometer,QAccelerometerReading, and QAccelerometerFilter.

If you are developing an app using C, a BPS event with the code SENSOR_ACCELEROMETER_READING is generated when new
accelerometer values are available. You can call the function sensor_event_get_xyz() to retrieve the
acceleration values from the event.

The following code sample reads the accelerometer G-forces when the BlackBerry 10 device is tilted or moved. These forces allow the screen to be
aligned with the orientation of the device.

Ambient light sensor

If you are developing a Cascades app using
QML or C++, you can use the ambient light sensor to retrieve a constant representing the
current brightness of the external environment (dark, bright, sunny, and so on). This
sensor is commonly used to help save the device's battery power level by checking the
ambient light level and adjusting the backlighting of the device accordingly.

Azimuth, pitch, and roll

The azimuth, pitch, and roll values provide the following positioning
information about the device:

Azimuth

The heading of the device, which is the angle between the device's y-axis and
magnetic north.

Pitch

The rotation around the device's x axis

Roll

The rotation around the device's y axis

If you are developing a Cascades app using
QML or C++, the rotation sensor returns a
reading containing three angles, measured in degrees, that define the orientation of the
device in three-dimensional space. These angles are similar to yaw, pitch, and roll but
are defined using only right-hand rotation with axes as defined by the right-hand
Cartesian coordinate system. You can also use the Compass
sensor to find the device heading.

If you are developing an app using C, a BPS event with the code SENSOR_AZIMUTH_PITCH_ROLL_READING is generated when new
azimuth, pitch, and roll values are available. You can call the function sensor_event_get_apr() to retrieve the azimuth, pitch, and roll
values from the event. Pitch and roll values are reported in degrees.

The following code sample demonstrates how you can use the azimuth,
pitch, and roll sensor in your app:

Compass

If you are developing a Cascades app using
QML or C++, the compass sensor takes the 3D device orientation and turns it into a 2D
device heading (otherwise known as the azimuth). For more information, see QCompass,QCompassReading, and QCompassFilter.

The following code sample demonstrates how you can capture readings from
the compass sensor:

Gyroscope

The gyroscope returns readings that measure the velocity of the device
along three axes. Unlike the rotation reading, the gyroscope's readings represent the
current angular velocity rather than a fixed rotation.

If you are developing an app using C, a BPS event with the code SENSOR_GYROSCOPE_READING is generated when new gyroscope
values are available. You can call the function sensor_event_get_xyz() to retrieve the values
from the event. The measurements are in radians per second (rad/s), where
counterclockwise rotations are positive when looking from the positive end of the axis,
and negative otherwise.

The following code sample demonstrates how you can capture readings from
the gyroscope:

If you are developing an app using C, a BPS event is generated when the
holster sensor reports a new reading. You can determine if a BPS event was triggered by
the holster sensor by calling holster_get_domain(). When you determine that the event is from the
holster sensor, you can call holster_event_get_holster_status() to retrieve whether or not
the device is in a holster.

The following code sample demonstrates how you can capture readings from
the holster:

Infrared proximity sensor

The infrared proximity sensor can detect the proximity of a nearby object
by emitting infrared light and detecting how much of the light the object reflects back
to the device. However, there is no reliable way to turn reflectance values into
distances unless both the item that light is reflecting off and the ambient lighting
conditions are known. For example, a material like black felt absorbs a lot of the
inferred light, making the object appear farther away than it actually is.

If you are developing an app using C, a BPS event with the code SENSOR_LIGHT_READING is generated when a new illuminance
value is available. You can call the function sensor_event_get_illuminance() to retrieve the value of the
sensor reading from the event. The light sensor returns a value that is measured in lux
(lx), where 1 lux is equal to 1 lumen per square meter (1 lx = 1 lm/m2).

The following code sample demonstrates how you can capture readings from
the light sensor:

Linear acceleration

Linear acceleration is the acceleration of the device minus the
acceleration due to gravity. This value is calculated by combining inputs from several
device sensors, and the result is returned from the linear accelerometer sensor type
(SENSOR_TYPE_LINEAR_ACCEL). These values are in
meters per second per second (m/s2).

A BPS event with the code SENSOR_LINEAR_ACCEL_READING is generated when new linear acceleration
values are available. You can call the function sensor_event_get_xyz() to retrieve the linear
acceleration values from the event.

The following code sample demonstrates how you can use the linear
accelerometer sensor in your app:

Magnetometer

The magnetometer measures the strength and direction of magnetic fields
in three dimensions. Unlike the compass, readings are returned as magnetic flux density
values along three axes, in teslas. This sensor supports both raw magnetic flux values
or geomagnetic flux values, with raw magnetic flux values being the default. Unlike raw
magnetic flux values, geomagnetic flux values are processed to compensate for local
interference, and provide data based on the Earth's magnetic field only.

If you are developing an app using C, a BPS event with the code SENSOR_MAGNETOMETER_READING is generated when new
magnetometer values are available. You can call the function sensor_event_get_xyz() to retrieve the
magnetic field values from the event. The magnetometer sensor returns magnetic flux
density values in microteslas (µT). These values are processed to compensate for local
interference, and provide data based on the Earth's magnetic field.

The following code sample demonstrates how you can capture readings from
the magnetometer:

Orientation sensor

The orientation sensor reports on the orientation of the device. You can
detect which side of the device is pointing up, and whether the device is face up or
face down. Because this sensor operates below the UI level, it's not able to detect the
UI orientation. For information on handling app orientation, see Orientation.

Proximity sensor

The proximity sensor determines whether an object is close to the device
or not. Unlike the IR proximity sensor, which returns a raw reflectance value, the
proximity sensor returns a value that indicates whether an object is close or far away.
The proximity is still based on reflectance, but takes other factors into consideration
when determining the value.

The proximity sensor determines whether an object is close or far from the
top of the device. This sensor is most commonly used to determine when a person is
holding the device close to their head. For example, when a person is making/receiving a
call, any touch events that occur are likely the result of the screen brushing against
the user's head, and this unintentional input should be ignored. You can do this by
programming your app to ignore touch events when the proximity sensor reports that
something is close to the device.

The sensor_event_get_proximity()
function returns the distance in centimeters (cm) of the object that is closest to the
device. On some devices, the proximity sensor can't provide an accurate distance, and
returns either the range minimum value (0.0) to represent near or
the range maximum value (1.0) to represent far.

The following code sample demonstrates how you can capture readings from
the proximity sensor:

sensor_event_get_proximity_normalized() returns the
distance of the closest object to the device mapped to a range between 0.0 and
1.0 (near to far). The code sample below takes the value returned by this
function and uses it to determine whether to handle or ignore screen events.

Rotation sensor

The rotation sensor returns a reading containing three angles, measured
in degrees, that define the orientation of the device in three-dimensional space. These
angles are similar to yaw, pitch, and roll but are defined using only right-hand
rotation with axes as defined by the right-hand Cartesian coordinate system.

If you are developing an app using C, a BPS event with the code SENSOR_ROTATION_MATRIX_READING is generated when a new rotation matrix is
available. You can call the function sensor_event_get_rotation_matrix() to
retrieve the rotation matrix from the event. The rotation matrix sensor fuses sensor
data from different sources to create a rotation matrix based on the position of the
device. You can use this matrix to rotate screen items to match the position of the
device. For example, rotating text fields in an augmented reality app.

The following code sample demonstrates how you can capture readings from
the rotation sensor:

1. Download the tools

Before you start developing, you'll need to visit the Downloads tab. Here you'll find downloads for the BlackBerry 10 Native SDK, BlackBerry 10 Device Simulator, and some other useful tools.

2. Try the sample apps

Now featuring a filter control, the Sample apps tab allows you to search for samples by name or by feature.

Select either the Core or Cascades radio buttons to display the samples relevant to you.

3. Educate yourself

The Documentation tab contains tons of examples, tutorials, and best practices to guide you along the path towards building an awesome app.

You can access all the documentation that you need in the left-hand navigation.

4. Start developing

The Reference tab is where you'll find essential details about how to use our APIs.

You can use the left-hand navigation to choose how you would like to browse the reference: by module, by topic, or alphabetically. If you have an idea of what you are looking for, start typing it in the Filter box.