Sensors

The Sensors object allows you to get access to system level sensors and attributes of the BlackBerry device.

The sensors object has various event listeners for sensors on the device.


Code Example:
<script type="text/javascript">

// Create a callback to handle each sensor
function compassCallback(sensor, data) {
    alert("Current azimuth: " + data.value);
}

// Start listening to the compass sensor with a delay feedback of 1000 microseconds 
blackberry.sensors.setOptions("devicecompass", { delay: 1000 });
   
// Start the event listener for the sensors callback
blackberry.event.addEventListener("devicecompass", compassCallback);
   
// Set the sensor to work in the background and use batching mode
blackberry.sensors.setOptions("devicecompass", { background: true, batching: true });

</script>


Learning Resources:

Sample - Using Sensors Sample that demonstrates how to use the BlackBerry Sensors API [BlackBerry on GitHub].

Supported Platform(s)

- BlackBerry 10
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
blackberry.sensors.setOptions           Y 
supportedSensors           Y 
blackberry.sensors.deviceaccelerometer           Y 
blackberry.sensors.deviceazimuthpitchroll           Y 
blackberry.sensors.devicecompass           Y 
blackberry.sensors.devicegravity           Y 
blackberry.sensors.devicegyroscope           Y 
blackberry.sensors.deviceholster           Y 
blackberry.sensors.devicelight           Y 
blackberry.sensors.devicelinearacceleration           Y 
blackberry.sensors.devicemagnetometer           Y 
blackberry.sensors.deviceorientation           Y 
blackberry.sensors.deviceproximity           Y 
blackberry.sensors.devicerotationmatrix           Y 

Configuration Document Settings

To use all of the API described for this object, you must ensure the following settings are in your configuration document:

You must declare the feature element(s) below in your configuration document:

Feature IDBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
<feature id="blackberry.sensors" />           Y 

Permission Elements (PlayBook and BlackBerry 10+)
This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application.



Properties

Functions

static void blackberry.sensors.setOptions (sensor : String, options : Object)


This function will set a sensor with the specifed options. Sensor options can be set before or after the sensor is active.

The supported object fields for 'options' are:


Supported Platforms
 - BlackBerry 10


Parameters
sensor The sensor to listen to.
options The options for the sensor being started.

delay: Time in µs (microseconds) to report back between sensor updates.
background: Allow sensor to send updates while the screen is off.
batching: When batching is enabled and supported by the hardware, sensors will report samples in hardware-specific batch sizes to conserve power.
queue: Enabling the queue creates a client-specific service side queue of events, this is useful to not miss any events.
reducedReporting: When reduced reporting is enabled, only a significant change between the last read event and the current unread event will cause an event to be delivered (useful for power saving).

Events

static void blackberry.sensors.deviceaccelerometer (data : Object)


Device accelerometer sensor.

This sensor returns accelerometer data. Returned as m/s/s (meters/second/second).


Supported Platforms
 - BlackBerry 10


Parameters
data The object containing the sensor data.

x: The x-axis value.
y: The y-axis value.
z: The z-axis value.

static void blackberry.sensors.deviceazimuthpitchroll (data : Object)


Device sensor azimuth pitch roll sensor.

This sensor returns a rotation matrix based on the orientation of the device.


Supported Platforms
 - BlackBerry 10


Parameters
data The object containing the sensor data.

azimuth: Azimuth from 0 -> 360 degrees from magnetic north.
pitch: Pitch from -180 to 180 degrees.
roll: Roll from -90 to 90 degrees.

static void blackberry.sensors.devicecompass (data : Object)


Device compass sensor.

This sensor returns directional information from the compass sensor.


Supported Platforms
 - BlackBerry 10


Parameters
data The object containing the sensor data.

value: Azimuth from 0 -> 360 degrees from magnetic north.
isFaceDown: 1 if face is down and compass heading is flipped, 0 otherwise.

static void blackberry.sensors.devicegravity (data : Object)


Device gravity sensor.

This sensor returns gravity information from the gravity sensor. Returned as m/s/s (meters/second/second).
Only the acceleration caused by gravity is reported. Movements of the device caused by the user have no effect other than changing the direction when the device is rotated.


Supported Platforms
 - BlackBerry 10


Parameters
data The object containing the sensor data.

x: The x-axis value.
y: The y-axis value.
z: The z-axis value.

static void blackberry.sensors.devicegyroscope (data : Object)


Device gyroscope sensor.

This sensor returns data from the gyroscope sensor. Returned as r/s (radians/second).


Supported Platforms
 - BlackBerry 10


Parameters
data The object containing the sensor data.

x: The x-axis value.
y: The y-axis value.
z: The z-axis value.
temperature: The temperature of the gyroscope sensor (in degrees Celsius).

static void blackberry.sensors.deviceholster (data : Object)


Device holster detection sensor.

This sensor returns the status of the holster sensor.


Supported Platforms
 - BlackBerry 10


Parameters
data The object containing the sensor data.

value: 1 if device is holstered, 0 otherwise.

static void blackberry.sensors.devicelight (data : Object)


Device light sensor.

This sensor returns brightness information from the light sensor.


Supported Platforms
 - BlackBerry 10


Parameters
data The object containing the sensor data.

value: Illuminance in lux.

static void blackberry.sensors.devicelinearacceleration (data : Object)


Device linear acceleration sensor.

This sensor returns linear acceleration data from the device accelerometer. Returned as m/s/s (meters/second/second).
Only the acceleration caused by the user moving the device is reported, the effect of gravity is canceled out.


Supported Platforms
 - BlackBerry 10


Parameters
data The object containing the sensor data.

x: The x-axis value.
y: The y-axis value.
z: The z-axis value.

static void blackberry.sensors.devicemagnetometer (data : Object)


Device magnetometer sensor.

This sensor returns values from the device's magnetometer. Returned as µT (micro Tesla).


Supported Platforms
 - BlackBerry 10


Parameters
data The object containing the sensor data.

x: The x-axis value.
y: The y-axis value.
z: The z-axis value.

static void blackberry.sensors.deviceorientation (data : Object)


Device orientation sensor.

This sensor returns device orientation information.
This relates to the physical device orientation.


Supported Platforms
 - BlackBerry 10


Parameters
data The object containing the sensor data.

screen: Screen rotation in degrees: 0, 90, 180 or 270.
face: String-based representation of device face.

static void blackberry.sensors.deviceproximity (data : Object)


Device proximity sensor.

This sensor returns data from the proximity sensor.


Supported Platforms
 - BlackBerry 10


Parameters
data The object containing the sensor data.

value: Discrete steps of distance or actual value in cm.
normalized: 0.0 -> 1.0 (close -> far), normalized unit-less signal from raw sensor.

static void blackberry.sensors.devicerotationmatrix (data : Object)


Device rotation matrix sensor.

This sensor returns a rotation matrix based on the orientation of the device.


Supported Platforms
 - BlackBerry 10


Parameters
data The object containing the sensor data.

matrix: Float array of data values representing the matrix.

Properties

static readonly void supportedSensors


Returns an array of the supported sensors on the current device.


Supported Platforms
 - BlackBerry 10

Documentation generated by JsDoc Toolkit 2.4.0 on Mon Feb 11 2013 14:51:10 GMT-0500 (EST)