This specification defines several new DOM events that provide information about the physical sensors of a hosting device.

The Device APIs Working Group decided to put this general Sensor API specification on hold and work on each sensor separately (see e.g. the Device Proximity).

Introduction

This section is non-normative

This specification provides several new DOM events that allow application code to obtain information given by the various sensors available on a hosting device. The information provided through this DOM event is raw sensor data. The specification is aimed at covering well-known sensors that are commonly found in devices.

There will be a DOM event for each of the sensor type which supplies the physical raw sensor data for that sensor type.

The following code snippet illustrates how to monitor sensor data, for instance the ambient temperature:

        TDB
		

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

Implementations that use ECMAScript to implement the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]], as this specification uses that specification and terminology.

Scope

This section is non-normative

This specification is limited to provide DOM events for retrieving raw sensor information for physical sensors of a hosting device. The scope of this specification does not include providing utilities to manipulate this data, such as sensor fusing or tranformation libraries. Nor does it include direct control of these sensors.

Security and Privacy Considerations

A conforming implementation of this specification MUST provide a mechanism that protects the user's privacy and this mechanism should ensure that no sensitive information is made available through this API without the user's express permission. User agents MUST acquire permission through a user interface, unless they have prearranged trust relationships with users.

Description

Sensor DOM Events

User agents implementing this specification must provide a new DOM event for each of the sensor types as specified in section 6. The sensor will turn on when the listener is added and turn off when the last event is removed. The corresponding event must be fire on the window object when there is a change in the sensor data. Registration for, and firing of the event must follow the usual behavior of DOM Events. If the UA does not support the sensor of interest then the event will not be fired.

User agents must also accept an event handler for addEventListener with the following interface:

The event handler passed to addEventListener must provide the signature:
void ondata(double value, double min, double max)
The ondata callback is raised when there is sensor data to report. The value is the sensor data as specified in section 6. The min is the minimum value in the range the sensor detects, if available. If not available, a value of zero must be returned. The max is maximum value in the range the sensor detects, if available. If not available, a value of zero must be returned.

DOM Sensor Events and Related Data Formats

This section specifies a base set of DOM sensor events and related data formats. If the UA supports these sensor types, it MUST use this data format definition. UAs may choose which sensors they wish to support. A UA MUST fire the DOM Sensor Event for sensors it supports in accordance with the following table::

DOM Sensor Event Sensor Type Data Type Units
devicetemperatureA ambient temperature sensordoubledegree Celsius (ºC)
devicepressureA pressure sensordoublekiloPascal (kP)
devicehumidityA releative humidity sensordoublepercentage
devicelightA light sensordoubleLux
devicenoiseA ambient noise sensordoubledbA
deviceproximityA proximity sensordoublecentimetres (cm)

Acknowledgements

WAC Ipanema Device APIs Lightweight Participation WG, in particular Bryan Sullivan, Balaji N.V., and Kaushik Das.

Mozilla's Device Proximity and Light Sensor APIs, in particular Doug Turner

José Manuel Cantera Fonseca from Telefónica as one of the original contributors and editors to this specification.

Marcos Caceres from W3C, Wayne Carr and Sakari Poussa from Tizen