index.bs

<pre class="metadata">
Title: Generic Sensor API
Status: ED
ED: https://w3c.github.io/sensors/
Shortname: generic-sensor
TR: http://www.w3.org/TR/generic-sensor/
Editor: Tobie Langel 78102, Intel Corporation, tobie@sensors.codespeaks.com
Editor: Rick Waldron, jQuery Foundation
Group: dap
Abstract:
  This specification defines a framework for exposing sensor data
  to the Open Web Platform in a consistent way.
  It does so by defining a blueprint for writing
  specifications of concrete sensors along with an abstract Sensor interface
  that can be extended to accommodate different sensor types.
Version History: https://github.com/w3c/sensors/commits/gh-pages/index.bs
!Bug Reports: <a href="https://www.github.com/w3c/sensors/issues/new">via the w3c/sensors repository on GitHub</a>
Indent: 2
Repository: w3c/sensors
Markup Shorthands: markdown on
Inline Github Issues: true
Boilerplate: omit issues-index, omit conformance
</pre>
<pre class="anchors">
urlPrefix: https://dom.spec.whatwg.org; spec: DOM
  type: dfn
    text: fire an event; url: concept-event-fire
  type: interface
    text: EventTarget; url: interface-eventtarget
urlPrefix: https://html.spec.whatwg.org/multipage/; spec: HTML
  type: dfn
    urlPrefix: webappapis.html
      text: incumbent settings object
      text: event handlers
      text: event handler event type
      text: queue a task
      text: event loop
    urlPrefix: infrastructure.html
      text: in parallel
    urlPrefix: browsers.html
      text: top-level browsing context
  type: interface
    urlPrefix: webappapis.html
      text: EventHandler
urlPrefix: http://w3c.github.io/hr-time/; spec: hr-time-2
  type: interface
    text: DOMHighResTimeStamp; url: dom-domhighrestimestamp
  type: dfn
    text: time origin
urlPrefix: https://w3c.github.io/webappsec/specs/powerfulfeatures/; spec: powerful-features
  type: dfn
    text: secure context
urlPrefix: https://heycam.github.io/webidl/; spec: WebIDL
  type: dfn
    text: throw; url: dfn-throw
</pre>


Introduction {#intro}
=====================

Increasingly, sensor data is used in application development to
enable new use cases such as geolocation,
counting steps or head-tracking.
This is especially true on mobile devices where new sensors are added regularly.
It is also increasingly common in networked objects
which are part of the Internet of Things.

Exposing sensor data to the Web
has so far been both slow-paced and ad-hoc.
Few sensors are already exposed to the Web.
When they are, it is often in ways that limit their possible use cases
(for example by exposing abstractions that are too <a>high-level</a>
and which don't perform well enough).
APIs also vary greatly from one sensor to the next
which increases the cognitive burden of Web application developers
and slows development.

The goal of the Generic Sensor API is to
promote consistency across sensor APIs,
enable advanced use cases thanks to performant <a>low-level</a> APIs,
and increase the pace at which new sensors can be exposed to the Web
by simplifying the specification and implementation processes.

Terminology
===========

A <dfn>sensor</dfn> measures different physical quantities
and provide corresponding <dfn>output data</dfn>
which is a source of information about the user and their environment.

Known, <em>predictable</em> discrepancies between <a>sensor</a> <a>output data</a>
and the corresponding physical quantities being measured
are corrected through <dfn>calibration</dfn>,

Known but <em>unpredictable</em> discrepancies need to be addressed dynamically
through a process called <a>sensor fusion</a>.

Different <dfn>sensor types</dfn> measure different physical quantities
such as temperature, air pressure, heart-rate, or luminosity.

For the purpose of this specification we distinguish between
<a>high-level</a> and <a>low-level</a> sensor types.

<a>Sensor types</a> which are characterized by their implementation
are referred to as <dfn>low-level</dfn> sensors.
For example a Gyroscope is a <a>low-level</a> sensor type.

<a>Sensors</a> named after their <a>output data</a>,
regardless of the implementation,
are said to be <dfn>high-level</dfn> sensors.
For instance, geolocation sensors provide information about the user's location,
but the precise means by which this data is obtained
is purposefully left opaque
(it could come from a GPS chip, network cell triangulation,
wifi networks, etc. or any combination of the above)
and depends on various, implementation-specific heuristics.
<a>High-level</a> sensors are generally the fruits of
applying algorithms to <a>low-level</a> sensors--
for example, a pedometer can be built using only the output of a gyroscope--
or of <a>sensor fusion</a>.

That said, the distinction between
<a>high-level</a> and <a>low-level</a> sensor types
is somewhat arbitrary and the line between the two is often blurred.
For instance, a barometer, which measures air pressure,
would be considered <a>low-level</a> for most common purposes.
Even though it is the product of the <a>sensor fusion</a> of
resistive piezo-electric pressure and temperature sensors,
exposing the sensors that compose it would serve no practical purpose
(who cares about the temperature of a piezo-electric sensor?).
A pressure-altimeter would probably fall in the same category,
while a nondescript altimeter--
which could get its data from either a barometer or a GPS signal--
would clearly be categorized as a <a>high-level</a> sensor type.

Because the distinction is somewhat blurry,
extensions to this specification (see [[#extensibility]])
are encouraged to provide domain-specific definitions of
<a>high-level</a> and <a>low-level</a> sensors
for the given <a>sensor types</a> they are targeting.

The <a>output data</a> of sensors can be combined with
the output of other sensors
through a process called <dfn>sensor fusion</dfn>.
This process provides <a lt="high-level">higher-level</a> or
more accurate data (often at the cost of increased latency).
For example, the <a lt="output data">output</a> of a three-axis magnetometer
needs to be combined with the <a lt="output data">output</a> of an accelerometer
to provide a correct bearing.
<a>Sensor fusion</a> can be carried out at either
the hardware or software level.

Note: <a>sensors</a> created through <a>sensor fusion</a> are sometimes
called virtual or synthetic sensors.
However, the specification doesn't make any practical differences between them,
preferring instead to differentiate sensors as to whether they describe
the kind of <a>output data</a> produced--these are <a>high-level</a> sensors--
or how the sensor is implemented (<a>low-level</a> sensors).

TODO: add a section about reading from a <a>sensor</a> and
how this is exposed as an asynchronous operation.

An note on Feature Detection of Hardware Features {#feature-detection}
=================================================

<em>This section is non-normative.</em>

Feature detection is an established Web development best practice.
Resources on the topic are plentiful on and offline and
the purpose of this section is not to discuss it further,
but rather to put it in the context of detecting hardware-dependent features.

Consider the below feature detection examples:

<div class="example">
    <pre highlight="js">
        if (typeof Gyroscope === "function") {
            // run in circles...
        }
        
        if ("ProximitySensor" in window) {
            // watch out!
        }
        
        if (window.AmbientLightSensor) {
            // go dark...
        }
        
        // etc.
    </pre>
</div>

All of these tell you something about the presence
and possible characteristics of an API.
They do not tell you anything, however, about whether
that API is actually connected to a real hardware sensor,
whether that sensor works,
if its still connected,
or even whether the user is going to allow you to access it.
Note you can check the latter using the Permissions API [[permissions]].

In an ideal world, information about the underlying status
would be available upfront.
The problem with this is twofold.
First, getting this information out of the hardware is costly,
in both performance and battery time,
and would sit in the critical path.
Secondly, the status of the underlying hardware can evolve over time.
The user can revoke permission, the connection to the sensor be severed,
the operating system may decide to limit sensor usage below a certain battery threshold,
etc.

Therefore, an effective strategy is to combine feature detection,
which checks whether an API for the sought-after sensor actually exists,
and defensive programming which includes:

1.  checking for error thrown when instantiating a <a interface>Sensor</a> object,
2.  listening to errors emitted by it,
3.  setting an appropriate timeout for your particular use case,
4.  handling all of the above graciously so that the user's experienced is
    enhanced by the possible usage of a sensor, not degraded by its
    absence.

<div class="example">
    <pre highlight="js">
    	try { // No need to feature detect thanks to try..catch block.
    	    let sensor = new GeolocationSensor({
    	        timeout: 3 * 1000 // 3 seconds
    	    });
    	    sensor.onerror = error => gracefullyDegrade(error);
    	    sensor.onchange = data => updatePosition(data.coords);
    	} catch(error) {
    	    gracefullyDegrade(error);
    	}
    </pre>
</div>

Model
=====

<em>This section is non-normative</em>.

The Generic Sensor API is designed to make the most common use cases straightforward
while still enabling more complex use cases.

Most devices deployed today do not carry more than one
<a>sensor</a> of each <a lt="sensor types">type</a>.
This shouldn't come as a surprise since use cases for more than
a <a>sensor</a> of a given <a lt="sensor types">type</a> are rare
and generally limited to specific <a>sensor types</a> such as
proximity sensors.

The API therefore makes it easy to interact with
the device's default (and often unique) <a>sensor</a>
for each <a lt="sensor types">type</a>
simply by instantiating the corresponding <a interface>Sensor</a> subclass.

Indeed, without specific information identifying a particular <a>sensor</a>
of a given <a lt="sensor type">type</a>,
the default <a>sensor</a> is chosen.

<div class="example">
    Listening to geolocation changes:

    <pre highlight="js">
    let sensor = new GeolocationSensor({ accuracy: "high" });

    sensor.onchange = function(event) {
        var coords = [event.data.latitude, event.data.longitude];
        updateMap(null, coords, event.data.accuracy);
    };

    sensor.onerror = function(error) {
        updateMap(error);
    };
    </pre>
</div>

Similarly, getting a single <a>output data</a> sample
should be a simple process, and it is:

<div class="example">
    Geolocating the user:

    <pre highlight="js">
    GeolocationSensor.requestReading({ accuracy: "high" })
        .then(reading => { displayCoords(reading.coords); })
        .catch(err => console.log(err));
    </pre>
</div>

Note: extension to this specification may choose not to define a default sensor
when doing so wouldn't make sense.
For example, it might be difficult to agree on an obvious default <a>sensor</a> for
proximity <a>sensors</a>.

In cases where
multiple <a>sensors</a> of the same <a lt="sensor type">type</a>
may coexist on the same device,
specification extension will have to
define ways to uniquely identify each one.

<div class="example">
    For example checking the pressure of the left rear tire: 

    <pre highlight="js">
    DirectTirePressureSensor.requestReading({ position: "rear", side: "left" })
        .then(reading => { display(reading.pressure); })
        .catch(err => console.log(err));
    </pre>
</div>

API
===

## The Sensor Interface

A <dfn interface>Sensor</dfn> object has an associated <a>sensor</a>.

A <a interface>Sensor</a> object observes the changes in its associated <a>sensor</a>
at regular intervals and reports those values by firing DOM events.

<dfn>frequency</dfn> is measured in hertz (Hz).

TODO: define the following concepts

- <dfn>permission</dfn>
- <dfn>read steps</dfn>
- <dfn>identifying parameters</dfn>

<pre class="idl">
[Constructor(optional SensorOptions sensorOptions)]
interface Sensor : EventTarget {
  static Promise&lt;SensorReading&gt; requestReading(RequestReadingOptions requestReadingOptions);
  readonly attribute DOMString sensorId;
  attribute double? treshold;
  attribute double timeout; 
  readonly attribute SensorReading? reading;
  attribute EventHandler onerror;
  attribute EventHandler ondata;
  attribute EventHandler onchange;
  attribute EventHandler oncalibration;
};

dictionary SensorOptions {
  DOMString? sensorId;
  double? treshold;
  double? frequency;
  double? timeout;
};

dictionary RequestReadingOptions : SensorOptions {
  boolean? fromCache = false;
};

</pre>

### Sensor Constructor

The <a>Sensor()</a> constructor must run these steps:

1.  If the <a>incumbent settings object</a> is not a <a>secure context</a>, then:
    1.  <a>throw</a> a SecurityError.
1.  If sensorOptions.sensorId is specified, then:
    1.  If there is a <a>sensor</a> identified by sensorOptions.sensorId, then
        1.  let <var>sensor</var> be a new <a interface>Sensor</a> object.
        1.  associate <var>sensor</var> with that <a>sensor</a>
    1. Otherwise, <a>throw</a> a TypeError.
1.  Otherwise, if <a>identifying parameters</a> in sensorOptions are set, then:
    1.  If these <a>identifying parameters</a> allow a unique <a>sensor</a> to be identified, then:
        1.  let <var>sensor</var> be a new <a interface>Sensor</a> object.
        1.  associate <var>sensor</var> with that <a>sensor</a>
    1. Otherwise, <a>throw</a> a TypeError.
1.  Otherwise, if a default sensor exists for this <a>sensor type</a>:
    1.  let <var>sensor</var> be a new <a interface>Sensor</a> object.
    1.  associate that <a>sensor</a> with it.
1.  Otherwise, <a>throw</a> a TypeError.
1.  Set <var>sensor</var>'s reading attribute to `null`.
1.  return <var>sensor</var>.
1.  Run these sub-steps <a>in parallel</a>:
    1.  If <a>permission</a> is not granted,
        <a>queue a task</a> to <a>fire an event</a> named error on <var>sensor</var>,
        and terminate these sub-steps.
    1.  If cached <a>SensorReadings</a> are available,
        1.   let <var>latest_reading</var> be the most recent of those <a>SensorReadings</a>.
        2.   set the value of <var>sensor</var>'s reading attribute to <var>latest_reading</var>.
    1.  run the <a>read steps</a> for <var>sensor</var>.

### Sensor.sensorId

### Sensor.threshold

### Sensor.timeout

### Sensor.reading

The reading attribute of must always point to the latest <a>SensorReading</a>
whatever the <a>frequency</a> so that
the reading attribute of two instances of the same Sensor interface
associated with the same <a>sensor</a>
hold the same <a>SensorReading</a> during a single <a>event loop</a> turn.

### Sensor.onerror

### Sensor.ondata

### Sensor.onchange

### Sensor.oncalibration


### Event handlers

The following are the <a>event handlers</a> (and their corresponding <a>event handler event types</a>) that MUST be supported as attributes by the objects implementing the <a>Sensor</a> interface:

<table class="simple">
  <thead>
    <tr>
      <th>event handler</th>
      <th>event handler event type</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong><code>ondata</code></strong></td>
      <td><code>data</code></td>
    </tr>
    <tr>
      <td><strong><code>onchange</code></strong></td>
      <td><code>change</code></td>
    </tr>
    <tr>
      <td><strong><code>onerror</code></strong></td>
      <td><code>error</code></td>
    </tr>
    <tr>
      <td><strong><code>oncalibration</code></strong></td>
      <td><code>calibration</code></td>
    </tr>
  </tbody>
</table>

The SensorReading Interface
---------------------------

A <dfn>SensorReading</dfn> represents the state of a <a>sensor</a> at a given point in time.

<pre class="idl">
interface SensorReading {
  readonly attribute DOMHighResTimeStamp timeStamp;
  readonly attribute DOMString sensorId;
};
</pre>

### SensorReading.timeStamp

Returns a timestamp of the time
at which the <a>read steps</a> was carried out
expressed in milliseconds that passed since the <a>time origin</a>.

### SensorReading.sensorId

Returns the id of the sensor the reading is taken from.

Security and privacy considerations
===================================

Privacy risks can arise when <a>sensors</a> are used
with each other,
in combination with other functionality,
or when used over time,
specifically with the risk of correlation of data
and user identification through fingerprinting.
Web application developers using these JavaScript APIs should
consider how this information might be correlated with other information
and the privacy risks that might be created.
The potential risks of collection of such data over a longer period of time
should also be considered.

Variations in <a>output data</a>
as well as event firing rates
offer the possibility of fingerprinting to identify users.
Browser implementations may reduce the risk by
limiting event rates available to web application developers.

Note: do we really want this mitigation strategy?

If the same JavaScript code using the API can be
used simultaneously in different window contexts on the same device
it may be possible for that code to correlate the user across those two contexts,
creating unanticipated tracking mechanisms.

Browser implementations should consider providing the user
an indication of when the <a>sensor</a> is used
and allowing the user to disable it.

Web application developers that use <a>sensors</a> should
perform a privacy assessment of their application
taking all aspects of their application into consideration.

Browsing Context {#browsing-context}
----------------

Sensor <a>output data</a> should only be available in the
<a>top-level browsing context</a> to avoid the privacy risk of
sharing the information defined in this specification
(and specifications extending it)
with contexts unfamiliar to the user.
For example, a mobile device will only fire the event on
the active tab, and not on the background tabs or within iframes.

Secure Context {#secure-context}
--------------

Sensor <a>output data</a> is explicitly flagged by the
Secure Contexts specification [[powerful-features]]
as a high-value target for network attackers.
As such, sensor <a>output data</a> should only be available
within a <a>secure context</a>.

Obtaining Explicit User Permission {#permissioning}
----------------------------------

Issue(w3c/sensors#20):

Extensibility
=============

<em>This section is non-normative.</em>

Its purpose is to describe
how this specification can be extended to specify APIs for
different <a>sensor types</a>.

Extension specifications are encouraged to focus on a single <a>sensor type</a>,
exposing both <a lt="high-level">high</a> and <a lt="low-level">low</a> level
as appropriate.

Naming
------

<a interface>Sensor</a> interfaces for <a>low-level</a> sensors should be
named after their associated <a>sensor</a>.
So for example, the interface associated with a gyroscope
should be simply named `Gyroscope`.
<a interface>Sensor</a> interfaces for <a>high-level</a> sensors should be
named by combining the physical quantity the <a>sensor</a> measures
with the "Sensor" suffix.
For example, a <a>sensor</a> measuring
the distance at which an object is from it
may see its associated interface called `ProximitySensor`.

Attributes of the <a interface>SensorReading</a> subclass that
hold <a>output data</a>
should be named after the full name of this <a>output data</a>.
For example, the `TemperatureSensorReading` interface should hold
the value of the <a>sensor</a>'s <a>output data</a> in
a `temperature` attribute (and not a `value` or `temp` attribute).

Exposing High-Level vs. Low-Level Sensors {#high-vs-low-level}
-----------------------------------------

So far, specifications exposing sensors to the Web platform
have focused on <a>high-level</a> sensors APIs. [[geolocation-API]] [[orientation-event]]

This was a reasonable approach for a number of reasons.
Indeed, <a>high-level</a> sensors:

-   convey developer intent clearly,
-   do not require intimate knowledge of how the underlying hardware sensors functions,
-   are easy to use,
-   may enable the User Agent to make significant
    performance and battery life improvements,
-   help avoid certain privacy and security issues by
    decreasing the amount and type of information exposed.

However, an increasing number of use cases
such as virtual and augmented reality [[sensor-use-cases]]
require <a>low-level</a> access to sensors,
most notably for performance reasons.

Providing <a>low-level</a> access
enables Web application developers to leverage domain-specific constraints
and design more performant systems.

Following the precepts of the Extensible Web Manifesto [[EXTENNNNSIBLE]],
extension specifications should focus primarily on
exposing <a>low-level</a> sensor APIs, but should also expose
<a>high-level</a> APIs when they are clear benefits in doing so.

When is Enabling Multiple Sensors of the Same Type Not the Right Choice? {#multiple-sensors}
------------------------------------------------------------------------

TODO: provide guidance on when to:

- allow multiple sensors of the same type to be instantiated,
- create different interfaces that inherit from <a interface>Sensor</a>,
- add constructor parameters to tweak sensors settings (e.g. setting required accuracy).

Defining a default
------------------

TODO: provide guidance on how and when to set a default <a>sensor</a>.

Calibration {#calibration}
-----------

<a>Output data</a> emitted by <a interface>Sensor</a> objects
should always be <a lt="calibration">calibrated</a>.

Extending the Permission API {#permission-api}
----------------------------

Provide guidance on how to extend the Permission API [[permissions]]
for each <a>sensor types</a>.

Issue(w3c/sensors#22):

Example WebIDL
--------------

Here's example WebIDL for a possible extension of this specification
for proximity <a>sensors</a>.

<pre class=example highlight=WEBidl >
    [Constructor(optional ProximitySensorOptions proximitySensorOptions)]
    interface ProximitySensor : Sensor {
      readonly attribute ProximitySensorReading? reading;
    };

    interface ProximitySensorReading : SensorReading {
        readonly attribute unrestricted double distance;
    };

    dictionary ProximitySensorOptions : SensorOptions {
        double? min = -Infinity;
        double? max = Infinity;
        ProximitySensorPosition? position;
        ProximitySensorDirection? direction;
    };
    
    enum ProximitySensorPosition {
        "top-left",
        "top",
        "top-right",
        "middle-left",
        "middle",
        "middle-right",
        "bottom-left",
        "bottom",
        "bottom-right"
    };

    enum ProximitySensorDirection {
        "front",
        "rear",
        "left",
        "right",
        "top",
        "bottom"
    };
</pre>

Acknowledgements
================

The following people have greatly contributed to this specification through extensive discussions on GitHub:
Anssi Kostiainen,
Boris Smus,
Claes Nilsson,
Dave Raggett,
davidmarkclements,
Domenic Denicola,
Dominique Hazael-Massieux (via the HTML5Apps project),
Frederick Hirsch,
Francesco Iovine,
gmandyam,
Jafar Husain,
Johannes Hund,
Kris Kowal,
Marcos Caceres,
Mats Wichmann,
Matthew Podwysocki,
pablochacin,
Remy Sharp,
Rich Tibbett,
Rick Waldron,
Rijubrata Bhaumik,
robman,
Sean T. McBeth,
smaug----,
and
zenparsing.

We'd also like to thank
Anssi Kostiainen,
Erik Wilde,
and
Michael[tm] Smith
for their editorial input.

<h2 id="conformance" class="no-ref no-num">Conformance</h2>

<h3 id="conventions" class="no-ref no-num">Document conventions</h3>

    <p>Conformance requirements are expressed with a combination of
    descriptive assertions and RFC 2119 terminology. The key words "MUST",
    "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
    "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this
    document are to be interpreted as described in RFC 2119.
    However, for readability, these words do not appear in all uppercase
    letters in this specification.

    <p>All of the text of this specification is normative except sections
    explicitly marked as non-normative, examples, and notes. [[!RFC2119]]</p>

    <p>Examples in this specification are introduced with the words "for example"
    or are set apart from the normative text with <code>class="example"</code>,
    like this:

    <div class="example">
        <p>This is an example of an informative example.</p>
    </div>

    <p>Because this document doesn't itself define APIs for specific <a>sensor types</a>--
    that is the role of extensions to this specification--
    all examples are inevitably (wishful) fabrications.
    Although all of the <a>sensors</a> used a examples
    would be great candidates for building atop the Generic Sensor API,
    their inclusion in this document does not imply that the relevant Working Groups
    are planning to do so.

    <p>Informative notes begin with the word "Note" and are set apart from the
    normative text with <code>class="note"</code>, like this:

    <p class="note">Note, this is an informative note.</p>

<h3 id="conformant-algorithms" class="no-ref no-num">Conformant Algorithms</h3>

    <p>Requirements phrased in the imperative as part of algorithms (such as
    "strip any leading space characters" or "return false and abort these
    steps") are to be interpreted with the meaning of the key word ("must",
    "should", "may", etc) used in introducing the algorithm.</p>

    <p>Conformance requirements phrased as algorithms or specific steps can be
    implemented in any manner, so long as the end result is equivalent. In
    particular, the algorithms defined in this specification are intended to
    be easy to understand and are not intended to be performant. Implementers
    are encouraged to optimize.</p>

<h3 id="conformance-classes" class="no-ref no-num">Conformance Classes</h3>

    <p>A <dfn>conformant user agent</dfn> must implement all the requirements
    listed in this specification that are applicable to user agents.</p>