This section is non-normative
This specification defines an API that allows application code to obtain information given by the various sensors available on a hosting device. The information provided through this API is raw sensor data. The specification is aimed at covering well-known sensors that are commonly found in devices. Nonetheless, the API is extensible, allowing to integrate vendor or external specific sensors if necessary .
The following code snippet illustrates how to monitor sensor data, for instance the ambient temperature:
var sensorCnx = new SensorConnection('Temperature'); sensorCnx.addEventListener('sensordata', function(e) { if(e.data > 20.0) { window.console.log('Temperature is too high!!!!'); } } ); var watchOptions = { interval: (15 * 60 * 1000) }; sensorCnx.startWatch(watchOptions);
The following code snippet illustrates how to list all sensors hosted on the device:
var sensorReq = navigator.sensors.list(); sensorReq.onsuccess = function() { for(var count = 0; count < this.result.length; count++) { window.console.log("Sensor Found: " + this.result[count].type); } } sensorReq.onerror = function() { window.console.error(this.error.code); }
The following example shows how to connect to a default accelerometer sensor hosted on the device
var accel = navigator.sensors.Accelerometer; accel.onsensordata = function(e) { window.console.log("Accelerometer data: " + e.data.x + ", " + e.data.y) } accel.startWatch(1000);
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.
A conforming implementation is required to implement all fields defined in this specification.
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.
This interface allows applications to know what sensors are available from the device. The sensor information is acquired by calling platform native sensor interfaces, creating a list of Sensor objects, and populating that object with appropriate data accordingly.
This is an asynchronous API that returns without blocking the calling thread.
When invoked the user agent MUST immediately return a SensorRequest instance (with done flag set to false), which
does not initially contain any information about the result of the operation. If the user permissions are ok then the UA MUST
queue a new listSensors process that will call platform native sensor interfaces
to fill a list of SensorInfo
with the type of sensors hosted by the device.
If user permissions are not ok the process must finish and an error event on the request
with error code PERMISSION_DENIED
MUST be fired.
Once the listSensors process finishes without error, an event is fired on the request, the done flag is set to true and the information becomes available through
the properties of the SensorRequest instance. If an error occurs while performing the operation,
the readyState is changed to done
, the error is set to the code of the error, and a event with type error is fired at the request.
InvalidStateError
.
DOMException
of type InvalidStateError.
processing
. If the done flag is false.done
. If the done flag is true. This interface defines the minimum information about a sensor hosted on a device.
Sensor
object contains different attributes that provide sensor metadata.
null
if this parameter is not known to the implementation.
null
must be returned if this parameter is not known to the implementation.
null
if it is not known.
null
if this parameter is not available
null
if this data is not available.
new
. The object has been instantiated but a connection to the sensor has not been established yet. open
. All the infrastructure to get sensor data is ready.watching
. The sensor is under monitoring.disconnected
. The connection with the sensor has been lost.error
. An error has occuredopen
or watching
an ILLEGAL_STATE exception MUST be thrown. data
field equal to the values read from the sensor.reason
field equal to 'read'When called the user agent MUST run the following steps:
open
an ILLEGAL_STATE exception MUST be thrownopen
then run the following sub-steps: watching
value. Queue a task to fire a simple event named
statuschange
at the SensorConnectionEverytime the platform monitoring mechanism notifies of a new sensor value the user agent MUST queue a task to fire a SensorDataEvent with:
data
field equal to the values read from the sensorreason
field equal to 'watch'
watching
an ILLEGAL_STATE exception MUST be thrown.watching
then the following substeps MUST be done:
open
value
and the control MUST be returned to the caller. Finally, Queue a task to fire a simple event named
statuschange
at the SensorConnection. id
is not defined
then _sensor MUST correspond to the default sensor type specified by the type
member.
Otherwise _sensor MUST be assigned to a sensor of the specified type
and whose identifier
is equal to the id
member. SensorConnection
object and set its status to 'open'. Once the user gives permission set status to 'open'.
If the user does not give permission set status to 'error' with error code to PERMISSION_DENIED
.
Implementations MAY support other connection options as part of the SensorOptions interface
These constructors must be visible when the script's global object is either a Window
object
or an object implementing the WorkerUtils
interface.
This attribute is likely to be revisited to support these use cases:
- Low and high thresholds
- Ranges [10,20] (10,20] ....
- Thresholds that apply to the different data components of a sensor, for instance x,y,z in the case of accelerometer.
interval
attribute represents the monitorization interval at which data SHOULD be obtained
from the underlying sensor hardware and must be expressed in milliseconds. The caller
should be aware that setting a value too small can adversely affect the battery life. If the interval is
set to zero, then the implementation MUST return sensor data only when there is a change since the last acquisition.
Once the spec progress this section will be changed to comply with the DOM4 Event interfaces
high
- This sensor is reporting data with maximum accuracymedium
- This sensor is reporting data with average accuracy, calibration with the environment may improve readingslow
This sensor is reporting data with low level of accuracy, calibration with the environment is neededunreliable
- This sensor is reporting data that can't be trusted, calibration is needed. read
. The event was raised due to a read operationwatch
. The event was raised due to a watch operationDocumentEvent
interface.
A section describing all the events defined by the API might be added for next draft.
An implementation MUST set the specific data type of the SensorDataEvent.data
attribute in accordance with the following table:
Sensor Type | Data Type | Units |
---|---|---|
Temperature | double | degree Celsius (ºC) |
AmbientLight | double | Lux |
AmbientNoise | double | dbA |
MagneticField | MagneticFieldData | micro-Tesla (uTesla) |
Proximity | double | centimetres (cm) |
AtmPressure | double | kiloPascal (kP) |
RelHumidity | double | |
Accelerometer | AccelerationData | meters/second^2 (m/s2) |
Gyroscope | RotationData | radians/second |
Orientation | OrientationData | radians |
WAC Ipanema Device APIs Lightweight Participation WG, in particular Bryan Sullivan, Balaji N.V., and Kaushik Das.