Sensor API

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

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

mailto:jmcf@tid.es

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

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 { readonly attribute DOMString type; // Vocabulary to be defined ("Acceleration", "AmbientLight") readonly attribute DOMString name; // ("Accelerometer", "Compass", "Thermometer") // 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);