Sensor API

Goals

Proposal for a new Sensor API. A generic API to retrieve values from sensors.

The Sensor API allows to retrieve values from sensors available from the device. It is intended to be compatible with existing concrete Web APIs that provide values from device sensors (http://dev.w3.org/geo/api/spec-source-orientation.html).

Author: José Manuel Cantera (Telefónica I+D)

mailto:jmcf@tid.es

Status

First draft provided

Proposed API

interface SensorManager : EventTarget {

    // Creates a new session to interact with a sensor
    SensorSession newSession(in DOMString sensorName,in optional SensorSessionOptions options) raises SensorNotFound;
    // The list of open sessions
    attribute sequence<SensorSession> openSessions;
    sequence<Sensor> listSensors(); // List the available sensors on the device
    attribute Function onSensorAvailable;

}; interface Sensor : EventTarget {

 // Vocabulary to be defined ("Acceleration", "AmbientLight")

readonly attribute DOMString type; // ("Accelerometer", "Compass", "Thermometer") readonly attribute DOMString name; // Another method to retrieve capabilities?? }; interface SensorSession : EventTarget {

    readonly attribute Sensor sensor;
    // Allows to watch (monitor) for the sensor 
    void watch(in SensorWatchOptions options);
    // Finish monitoring session
    void endWatch();
    // Reads the value of a sensor
    void read();
    // Close the session with the sensor (endWatch is called if necessary)
    void close();
    readonly attribute DOMString status; // ("watching", "closed", ...)
    attribute Function onSensorData;
    attribute Function onError;

}; interface SensorData {

    readonly attribute any value;

}; // New DOM Event 'sensordata' interface SensorDataEvent : Event {

    readonly attribute SensorData data;
    void initSensorDataEvent(in DOMString type,
                               in boolean bubbles,
                               in boolean cancelable,
                               in SensorData data);

}; interface SensorWatchOptions {

    attribute  any highThreshold; // High threshold. If the sensor value is higher a data event will be raised
    attribute  any lowThreshold;  // Low threshold. If the sensor value is lower a data event will be raised
    attribute double relativeThreshold; // Notify only when a relative change in the magnitude meausured by the sensor occurs 
    attribute double interval; // Interval at which values will be provided by the sensor (milliseconds)

};

Example of use

var accelerometer = navigator.sensor.newSession('Accelerometer') session.onSensorData = function(e) {

  window.console.log('New accelerometer data');
  window.console.log('Acceleration along the x axis: ' + e.value.x);

} var watchOptions = { interval = 1.0 } // Every one millisecond session.watch(watchOptions);