Sensors

The Sensors object allows you to access system-level sensors and attributes on a BlackBerry device.

Since: BlackBerry WebWorks 2.0

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

Installation:

To use this API in your project, add the sensors plugin:

webworks plugin add com.blackberry.sensors

Example:

<script type="text/javascript">

function compassCallback(data) {
     console.log("Current azimuth: " + data.value);
}

blackberry.sensors.setOptions("devicecompass", { delay: 1000000 });
document.addEventListener("devicecompass", compassCallback);
blackberry.sensors.setOptions("devicecompass", { background: true, batching: true });
</script>
            

Learning Resources:

Sensors sample app The Sensors sample app demonstrates how to use the BlackBerry Sensors API [BlackBerry on GitHub].

Functions:
void setOptions()
Properties:
String[] supportedSensors

setOptions()

This function sets a sensor with the specifed options. Sensor options can be set at any time and apply whenever the sensor is active.

Synopsis:

void blackberry.sensors.setOptions(sensor, options)

Parameters:

sensor {Object}

The sensor to set options on.

options {Object}

The options to set on the sensor.

delay {String}

Time in ┬Ás (microseconds) to report back between sensor updates.

background {Boolean}

Allow the sensor to send updates while the screen is off.

batching {Boolean}

When batching is enabled and supported by the hardware, sensors will report samples in hardware-specific batch sizes to conserve power.

queue {Boolean}

Enabling the queue creates a client-specific service-side queue of events, this is useful to not miss any events.

reducedReporting {Boolean}

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

deviceaccelerometer

This sensor returns accelerometer data.

Synopsis:

deviceaccelerometer

Parameters:

data {Object}

The object containing the sensor data.

x {Float}

The x-axis value.

y {Float}

The y-axis value.

z {Float}

The z-axis value.

deviceazimuthpitchroll

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

Synopsis:

deviceazimuthpitchroll

Parameters:

data {Object}

The object containing the sensor data.

azimuth {Float}

Azimuth from 0 -> 360 degrees from magnetic north.

pitch {Float}

Pitch from -180 to 180 degrees.

roll {Float}

Roll from -90 to 90 degrees.

devicecompass

This sensor returns compass data.

Synopsis:

devicecompass

Parameters:

data {Object}

The object containing the sensor data.

data.value {Float}

Azimuth from 0 -> 360 degrees from magnetic north.

data.isFaceDown {Number}

1 if face is down and compass heading is flipped, 0 otherwise.

devicegravity

The sensor returns gravity data as m/s/s (meters/second/second).

Synopsis:

devicegravity

Parameters:

data {Object}

The object containing the sensor data.

x {Float}

The x-axis value.

y {Float}

The y-axis value.

z {Float}

The z-axis value.

devicegyroscope

This sensor returns gyroscope data.

Synopsis:

devicegyroscope

Parameters:

data {Object}

The object containing the sensor data.

x {Float}

The x-axis value.

y {Float}

The y-axis value.

z {Float}

The z-axis value.

temperature {Float}

The temperature of the gyroscope sensor (in degrees Celsius).

deviceholster

This sensor returns the status of the holster sensor.

Synopsis:

deviceholster

Parameters:

data {Object}

The object containing the sensor data.

value {Number}

1 if device is holstered, 0 otherwise.

devicelight

This sensor returns brightness information from the light sensor.

Synopsis:

devicelight

Parameters:

data {Object}

The object containing the sensor data.

value {Float}

Illuminance in lux.

devicelinearacceleration

This sensor returns linear acceleration data from the device accelerometer. Returned as m/s/s (meters/second/second).

Synopsis:

devicelinearacceleration

Parameters:

data {Object}

The object containing the sensor data.

x {Float}

The x-axis value.

y {Float}

The y-axis value.

z {Float}

The z-axis value.

devicemagnetometer

This sensor returns magnetometer data.

Synopsis:

devicemagnetometer

Parameters:

data {Object}

The object containing the sensor data.

x {Float}

The x-axis value.

y {Float}

The y-axis value.

z {Float}

The z-axis value.

deviceorientation

This sensor returns device orientation information.

Synopsis:

deviceorientation

Parameters:

data {Object}

The object containing the sensor data.

screen {Number}

Screen rotation in degrees: 0, 90, 180 or 270.

face {String}

String-based representation of the device orientation.

deviceproximity

This sensor returns proximity data.

Synopsis:

deviceproximity

Parameters:

data {Object}

The object containing the sensor data.

value {Number}

Discrete steps of distance or actual value in cm.

normalized {Float}

0.0 -> 1.0 (close -> far), normalized unit-less signal from raw sensor.

devicerotationmatrix

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

Synopsis:

devicerotationmatrix

Parameters:

data {Object}

The object containing the sensor data.

[m11, m12, m13, m21, m22, m23, m31, m32, m33] {Number}

The rotation matrix that converts a vector in the device frame to a vector in the world frame. The 3x3 rotation matrix is flattened to a 1x9 matrix in row order.

supportedSensors

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

Synopsis:

read-only
String[] blackberry.sensors.supportedSensors

In BlackBerry 10 WebWorks SDK 2.0.0.71 and earlier, the supportedSensors property was (incorrectly) provided as a JSON object instead of as an array of strings. If you used the following workaround, you need to remove it: JSON.parse(blackberry.sensors.supportedSensors).

Last modified: 2014-09-29



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

comments powered by Disqus