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 
blackberry.sensors.setOptions("devicecompass", { delay : 1000 });
   
// Start the event listener for the sensors callback
blackberry.event.addEventListener("devicecompass", compassCallback);
   
</script>

Supported Platform(s)

- BlackBerry 10

View Supported Platform Table

API	BB5.0	BB6.0	BB7.0	PB1.0	PB2.0	BB10	Ripple
blackberry.sensors.setOptions						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 ID	BB5.0	BB6.0	BB7.0	PB1.0	PB2.0	BB10	Ripple
<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.

Functions

void	blackberry.sensors.setOptions

Events

void	blackberry.sensors.deviceaccelerometer
void	blackberry.sensors.deviceazimuthpitchroll
void	blackberry.sensors.devicecompass
void	blackberry.sensors.devicegravity
void	blackberry.sensors.devicegyroscope
void	blackberry.sensors.deviceholster
void	blackberry.sensors.devicelight
void	blackberry.sensors.devicelinearacceleration
void	blackberry.sensors.devicemagnetometer
void	blackberry.sensors.deviceorientation
void	blackberry.sensors.deviceproximity
void	blackberry.sensors.devicerotationmatrix

Functions

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

This method will start a sensor with the specifed options and begin returning it to the added event listener.

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

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.

Documentation generated by JsDoc Toolkit 2.4.0 on Sun Dec 30 2012 18:15:43 GMT-0500 (EST)