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