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-10-09
Got questions about leaving a comment? Get answers from our Disqus FAQ.
comments powered by Disqus