Bondi logo

The Bondi sensor Module - Version 1.5

February 2010

Authors

© 2009-2010 OMTP Ltd. All rights reserved. OMTP and OMTP BONDI are registered trademarks of OMTP Ltd.

Abstract

Sensor API Sensors are classified by type. Sensor type names are defined Strings, and creation new type names must be centrally defined (by the owner of this API definition).

Table of Contents

Summary of Methods

Interface Method
SensorCapabilities
SensorCondition
Sensor DOMString getType()
DOMString getName()
SensorCapabilities getCapabilities()
PendingOperation read(SensorReadCallback successCallback, ErrorCallback errorCallback, DOMString condition)
PendingOperation read(SensorReadCallback successCallback, ErrorCallback errorCallback, SensorCondition condition)
long watch(SensorReadCallback listener, SensorCondition condition)
void clearWatch(long watch)
Accelerometer SensorCapabilities getCapabilities()
PendingOperation read(SensorReadCallback successCallback, ErrorCallback errorCallback, DOMString condition)
PendingOperation read(SensorReadCallback successCallback, ErrorCallback errorCallback, SensorCondition condition)
void watch(SensorReadCallback listener, SensorCondition condition)
void clearWatch(SensorReadCallback listener)
DOMString getName()
DOMString getType()
SensorManager Sensor getSensor(DOMString sensorType, Map params)
SensorArray getSensors()

1. Introduction

There is a Feature defined for each specific sensor type. as follows:

1.2. Features

This is the list of URIs used to declare this API's features, for use in bondi.requestFeature. For each URL, the list of functions covered is provided.

http://bondi.omtp.org/api/sensor/type

where type is a defined Sensor type.

2. Type Definitions

3. Interfaces

3.3. SensorCapabilities 

        interface SensorCapabilities {

        };

An abstract class representing the capabilities of a sensor.

This is expected to be subclasses for each specific sensor type.

3.4. SensorCondition 

        interface SensorCondition {

        };

An abstract class representing a set of conditions, triggers or thresholds associated with sensors.

This is expected to be subclassed for specific sensor types where it is not convenient to express relevant conditions as a DOMString.

3.5. Sensor 

        interface Sensor {
                const unsigned short SENSOR_TYPE_ACCELEROMETER       = 0; 
                const unsigned short SENSOR_TYPE_AMBIENT_TEMPERATURE = 1; 
                const unsigned short SENSOR_TYPE_ALTIMETER           = 2; 
                const unsigned short SENSOR_TYPE_AMBIENT_LIGHT       = 3; 

                DOMString getType();

                DOMString getName();

                SensorCapabilities getCapabilities();

                PendingOperation read(in SensorReadCallback successCallback,
                                      in ErrorCallback errorCallback,
                                      in DOMString condition);

                PendingOperation read(in SensorReadCallback successCallback,
                                      in ErrorCallback errorCallback,
                                      in SensorCondition condition);

                long watch(in SensorReadCallback listener,
                           in SensorCondition condition);

                void clearWatch(in long watch);
        };

The Sensor class is an abstract class that represents a general sensor. Specific sensor types do not necessarily extend this API, but will typically define specific types for sensor-specific aspects of the interface, such as - a sensor-specific value type representing the data returned when the sensor is read, extending SensorValue; - a sensor-specific value type representing the specific capabilities of the sensor, extending SensorCapabilities; - a sensor-specific condition type, representing specific conditions, triggers and thresholds for reading the sensor asynchronously, extending SensorCondition

Constants

unsigned short SENSOR_TYPE_ACCELEROMETER

Pre-defined Sensor types

unsigned short SENSOR_TYPE_AMBIENT_TEMPERATURE
unsigned short SENSOR_TYPE_ALTIMETER
unsigned short SENSOR_TYPE_AMBIENT_LIGHT

Methods

getType
Signature
DOMString getType();

Get the type of this Sensor This is one of the known sensor type strings

getName
Signature
DOMString getName();

Get the name of this Sensor For most sensors, the name is simply the type DOMString. However, if a device has multiple Sensors of the sale type, the name may be used to distinguish between specific sensors (eg two different attitude sensing devices, one for each half of a clamshell device)

getCapabilities
Signature
SensorCapabilities getCapabilities();

Get the capabilities of this Sensor. The object returned is of a specific subclass of SensorCapabilities appropriate to the type of sensor in question

read
Signature
PendingOperation read(in SensorReadCallback successCallback, in ErrorCallback errorCallback, in DOMString condition);

Read the current value of the Sensor asynchronously. If no condition is specified, this will return the current reading of the sensor as soon as it is available. If a condition is specified, the operation will complete once the condition is satisfied. The condition DOMString is optional and specifies sensor-specific condition(s), in a sensor-specific syntax.

Parameters
  • successCallback:
  • errorCallback:
  • condition:
read
Signature
PendingOperation read(in SensorReadCallback successCallback, in ErrorCallback errorCallback, in SensorCondition condition);

Read the current value of the Sensor asynchronously. If no condition is specified, this will return the current reading of the sensor as soon as it is available. If a condition is specified, the operation will complete once the condition is satisfied. The Condition object is optional and specifies sensor-specific condition(s), in a sensor-specific subtype of SensorCondition.

Parameters
  • successCallback:
  • errorCallback:
  • condition:
watch
Signature
long watch(in SensorReadCallback listener, in SensorCondition condition);

Watch this sensor and listen for changes in value. This method is supported only for discrete sensors, or continuous sensors that support Conditions with thresholds that ensure a minimum distance or time delay between readings Each successfully read value that satisfies the condition results in the listener being called.

The Condition object is optional and specifies sensor-specific condition(s), in a sensor-specific subtype of SensorCondition. This is intended to be used in situations where sensor-specific conditions are not easily specified as a DOMString.

Multiple listeners may be active at any time.

Parameters
  • listener:
  • condition:
clearWatch
Signature
void clearWatch(in long watch);

Clear a previously registered watch

Parameters
  • watch:

3.8. Accelerometer 

        interface Accelerometer : Sensor {

                SensorCapabilities getCapabilities();
                
                PendingOperation read(in SensorReadCallback successCallback,
                                      in ErrorCallback errorCallback,
                                      in DOMString condition);

                PendingOperation read(in SensorReadCallback successCallback,
                                      in ErrorCallback errorCallback,
                                      in SensorCondition condition);

                void watch(in SensorReadCallback listener,
                           in SensorCondition condition)
                        raises(GenericError);

                void clearWatch(in SensorReadCallback listener)
                        raises(GenericError);

                DOMString getName();

                DOMString getType();
        };

A class representing an accelerometer measuring acceleration on up to 3 axes.

Methods

getCapabilities
Signature
SensorCapabilities getCapabilities();

Returns AccelerometerCapabilities

read
Signature
PendingOperation read(in SensorReadCallback successCallback, in ErrorCallback errorCallback, in DOMString condition);

Conditions are not supported for Accelerometer

Parameters
  • successCallback:
  • errorCallback:
  • condition:
read
Signature
PendingOperation read(in SensorReadCallback successCallback, in ErrorCallback errorCallback, in SensorCondition condition);

Conditions are not supported for Accelerometer

Parameters
  • successCallback:
  • errorCallback:
  • condition:
watch
Signature
void watch(in SensorReadCallback listener, in SensorCondition condition);

Watching accelerometer is not supported

Parameters
  • listener:
  • condition:
Exceptions
  • GenericError:
clearWatch
Signature
void clearWatch(in SensorReadCallback listener);

Watching accelerometer is not supported

Parameters
  • listener:
Exceptions
  • GenericError:
getName
Signature
DOMString getName();
getType
Signature
DOMString getType();

3.9. SensorManager 

        interface SensorManager {
                Sensor getSensor(in DOMString sensorType,
                                 in Map params);

                SensorArray getSensors();
        };

The top-level class that provides access to the sensors on a device.

Methods

getSensor
Signature
Sensor getSensor(in DOMString sensorType, in Map params);

Obtain an instance of a Sensor of specified type.

For most sensor types, there is at most one sensor available, and the params argument is ignored.

However, if there are multiple sensors of a given type, the params argument may be used to select a specific sensor.

A SensorManager at least supports "name" as a parameter, which will select from available sensors based on the name of the particular sensor.

Other parameters may be supported, and may be specific to a sensor type.

This is associated with Feature: http://bondi.omtp.org/api/sensor/sensorType

Parameters
  • sensorType:
  • params:
getSensors
Signature
SensorArray getSensors();

Return an array of all available Sensors.

This is associated with Feature: http://bondi.omtp.org/api/sensor