Generic Sensor API

W3C Candidate Recommendation Draft,

More details about this document
This version:
https://www.w3.org/TR/2023/CRD-generic-sensor-20230113/
Latest published version:
https://www.w3.org/TR/generic-sensor/
Editor's Draft:
https://w3c.github.io/sensors/
Previous Versions:
History:
https://www.w3.org/standards/history/generic-sensor
Feedback:
public-device-apis@w3.org with subject line “[generic-sensor] … message topic …” (archives)
Generic Sensor API Issues Repository
Implementation Report:
https://www.w3.org/wiki/DAS/Implementations
Editor:
Rick Waldron (Invited Expert, formerly on behalf of Bocoup and JS Foundation)
Former Editors:
Mikhail Pozdnyakov (Intel Corporation)
Alexander Shalamov (Intel Corporation)
Tobie Langel (Codespeaks, formerly on behalf of Intel Corporation)
Test Facilitator:
Wanming Lin (Intel Corporation)
Other:
Test suite, latest version history, previous version history

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.

Status of this document

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This document was published by the Devices and Sensors Working Group as a Candidate Recommendation Draft using the Recommendation track. This document is intended to become a W3C Recommendation.

If you wish to make comments regarding this document, please send them to public-device-apis@w3.org (subscribe, archives). When sending e-mail, please put the text “generic-sensor” in the subject, preferably like this: “[generic-sensor] …summary of comment…”. All comments are welcome.

Publication as a Candidate Recommendation does not imply endorsement by W3C and its Members. A Candidate Recommendation Draft integrates changes from the previous Candidate Recommendation that the Working Group intends to include in a subsequent Candidate Recommendation Snapshot. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

The entrance criteria for this document to enter the Proposed Recommendation stage is to have a minimum of two independent and interoperable user agents that implementation all the features of this specification, which will be determined by passing the user agent tests defined in the test suite developed by the Working Group. The Working Group will prepare an implementation report to track progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 2 November 2021 W3C Process Document.

Further implementation experience is being gathered for the permission request algorithm and specification clarifications informed by this experience are being discussed in GitHub issue #397. The group does not expect to advance this specification beyond CR until [PERMISSIONS-REQUEST] moves beyond incubation. This document is maintained and updated at any time. Some parts of this document are work in progress.

1. Introduction

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.

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 high-level 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 low-level APIs, and increase the pace at which new sensors can be exposed to the Web by simplifying the specification and implementation processes.

A comprehensive list of concrete sensors that are based on Generic Sensor API, applicable use cases, and code examples can be found in [GENERIC-SENSOR-USECASES] and [MOTION-SENSORS] explainer documents.

2. Scope

This section is non-normative.

The scope of this specification is currently limited to specifying primitives which enable exposing data from device sensors.

Exposing remote sensors or sensors found on personal area networks (e.g. Bluetooth) is out of scope. As work in these areas mature, it is possible that common, lower-level primitives be found, in which case this specification will be updated accordingly. This should have little to no effects on implementations, however.

This specification also does not currently expose a sensor discovery API. This is because the limited number of sensors currently available to user agents does not warrant such an API. Using feature detection, such as described in § 3 A note on Feature Detection of Hardware Features, is good enough for now. A subsequent version of this specification might specify such an API, and the current API has been designed with this in mind.

3. A note on Feature Detection of Hardware Features

This section is non-normative.

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:

This simple example illustrates how to check whether the User Agent exposes an interface for a particular sensor type. To handle errors in a robust manner, please refer to this example.
if (typeof Gyroscope === "function") {
    // run in circles...
}

if ("ProximitySensor" in window) {
    // watch out!
}

if (window.AmbientLightSensor) {
    // go dark...
}

// etc.

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 Sensor object,

  2. listening to errors emitted by it,

  3. handling all of the above graciously so that the user’s experience is enhanced by the possible usage of a sensor, not degraded by its absence.

The following snippet illustrates how an Accelerometer sensor can be created in a robust manner. Web application may choose different options for error handling, for example, show notification, choose different sensor type or fallback to other API.
let accelerometer = null;
try {
    accelerometer = new Accelerometer({ frequency: 10 });
    accelerometer.addEventListener('error', event => {
        // Handle runtime errors.
        if (event.error.name === 'NotAllowedError') {
            console.log('Permission to access sensor was denied.');
        } else if (event.error.name === 'NotReadableError' ) {
            console.log('Cannot connect to the sensor.');
        }
    });
    accelerometer.addEventListener('reading', () => reloadOnShake(accelerometer));
    accelerometer.start();
} catch (error) {
    // Handle construction errors.
    if (error.name === 'SecurityError') {
        console.log('Sensor construction was blocked by the Permissions Policy.');
    } else if (error.name === 'ReferenceError') {
        console.log('Sensor is not supported by the User Agent.');
    } else {
        throw error;
    }
}

4. Security and privacy considerations

The judgement on how to communicate to the user the known threats is up to the implementer. The implementation of the mitigations is mandatory, however.

Sensor readings are sensitive data and could become a subject of various attacks from malicious Web pages. Before discussing the mitigation strategies we briefly enumerate the main types of the sensor's privacy and security threats. The [MOBILESENSORS] categorizes main threats into location tracking, eavesdropping, keystroke monitoring, device fingerprinting, and user identification. This categorization is a good fit for this specification.

The risk of successful attack can increase when sensors 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 sensor readings as well as event firing rates offer the possibility of fingerprinting to identify users. User agents may reduce the risk by limiting event rates available to web application developers.

Minimizing the accuracy of a sensor’s readout generally decreases the risk of fingerprinting. User agents should not provide unnecessarily verbose readouts of sensors data. Each sensor type should be assessed individually.

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.

User agents should consider providing the user an indication of when the sensor is used and allowing the user to disable it. Additionally, user agents may consider allowing the user to verify past and current sensor use patterns.

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

Ability to detect a full working set of sensors on a device can form an identifier and could be used for fingerprinting.

A combination of selected sensors can potentially be used to form an out of band communication channel between devices.

Sensors can potentially be used in cross-device linking and tracking of a user.

4.1. Types of privacy and security threats

This section is non-normative.

4.1.1. Location Tracking

Under this type of threat, the attacks use sensor readings to locate the device without using GPS or any other location sensors. For example, accelerometer data can be used to infer the location of smartphones by using statistical models to obtain estimated trajectory, then map matching algorithms can be used to obtain predicted location points (within a 200-m radius)[MOBILESENSORS].

4.1.2. Eavesdropping

Recovering speech from gyroscope readings is an example of eavesdropping attack. See [GYROSPEECHRECOGNITION].

4.1.3. Keystroke Monitoring

Many user inputs can be inferred from sensor readings, this includes a wide range of attacks on user PINs, passwords, and lock patterns (and even touch actions such as click, scroll, and zoom) using motion sensors. These attacks normally train a machine learning algorithm to discover such information about the users. See [STEALINGPINSVIASENSORS].

4.1.4. Device Fingerprinting

Sensors can provide information that can uniquely identify the device using those sensors. Every concrete sensor model has minor manufacturing imperfections and differences that will be unique for this model. These manufacturing variations and imperfections can be used to fingerprint the device [ACCELPRINT] [MOBILESENSORS].

4.1.5. User Identifying

Sensor readings can be used to identify the user, for example via inferring individual walking patterns from smartphone or wearable device motion sensors' data.

4.2. Mitigation Strategies

This section is non-normative.

This section gives a high-level presentation of some of the mitigation strategies specified in the normative sections of this specification.

4.2.1. Secure Context

Sensor readings are explicitly flagged by the Secure Contexts specification [POWERFUL-FEATURES] as a high-value target for network attackers. Thus all interfaces defined by this specification or extension specifications are only available within a secure context.

4.2.2. Permissions Policy

To avoid the privacy risk of sharing sensor readings with contexts unfamiliar to the user, sensor readings are only available for the documents which are allowed to use the policy-controlled features for the given sensor type. See [PERMISSIONS-POLICY] for more details.

4.2.3. Focused Area

Sensor readings are only available for active documents whose origin is same origin-domain with the currently focused area document.

This is done in order to mitigate the risk of a skimming attack against the browsing context containing an element which has gained focus, for example when the user carries out an in-game purchase using a third party payment service from within an iframe.

4.2.4. Visibility State

Sensor readings are only available for the active documents whose visibility state is "visible".

4.2.5. Permissions API

Access to sensor readings are controlled by the Permissions API [PERMISSIONS].

4.3. Mitigation strategies applied on a case by case basis

Each sensor type will need to be assessed individually, taking into account the use cases it enables and its particular threat profile. While some of the below mitigation strategies are effective for certain sensors, they might also hinder or altogether prevent certain use cases.

Note: These mitigation strategies can be applied constantly or temporarily, for example when the user is carrying out specific actions, when other APIs which are known to amplify the level of the threat are in use, etc.

4.3.1. Limit maximum sampling frequency

User agents may mitigate certain threats by limiting the maximum sampling frequency. What upper limit to choose depends on the sensor type, the kind of threats the user agent is trying to protect against, the expected resources of the attacker, etc.

Limiting the maximum sampling frequency prevents use cases which rely on low latency or high data density.

4.3.2. Stop the sensor altogether

This is obviously a last-resort solution, but it can be extremely effective if it’s temporal, for example to prevent password skimming attempts when the user is entering credentials on a different origin ([rfc6454]) or in a different application.

4.3.3. Limit number of delivered readings

An alternative to limiting the maximum sampling frequency is to limit the number of sensor readings delivered to Web application developer, regardless of what frequency the sensor is polled at. This allows use cases which have low latency requirement to increase sampling frequency without increasing the amount of data provided.

Discarding intermediary readings prevents certain use cases, such as those relying on certain kinds of filters.

4.3.4. Reduce accuracy

Reducing the accuracy of sensor readings or sensor reading timestamps might also help mitigate certain threats, thus user agents should not provide unnecessarily verbose readouts of sensors data.

Implementations of concrete sensors may define a threshold check algorithm so that new readings that do not differ enough from the latest readings are discarded.

Implementations of concrete sensors may define a reading quantization algorithm to reduce the accuracy of the sensor readings received from a device sensor.

Note: these two mitigation measures often complement each other. An implementation that only executes the threshold check algorithm might expose readings that are too precise, while an implementation that only rounds readings up may provide attackers with information about more precise readings when raw readings are rounded to different values.

Note: Inaccuracies will further increase for operations carried out on the sensor readings, or time deltas calculated from the timestamps. So, this mitigation strategy can affect certain use cases.

Note: while adding random bias to sensor readings has similar effects, it shouldn’t be used in practice as it is easy to filter out the added noise.

4.3.5. Keep the user informed about API use

User agents may choose to keep the user informed about current and past use of the API.

Note: this does not imply keeping a log of the actual sensor readings which would have issues of its own.

5. Concepts

5.1. Sensors

The term device sensor refers to a device’s underlying physical sensor instance.

A device sensor measures a physical quantities and provides a corresponding sensor reading which is a source of information about the environment.

Each sensor reading is composed of the values of the physical quantity measured by the device sensor at time tn which is called the reading timestamp.

If the device sensor performs a spatial measurement (e.g. acceleration, angular velocity), it must be resolved in a local coordinate system that represents a reference frame for the device sensor's sensor readings. A device sensor that provides such sensor readings is referred to as spatial sensor.

A spatial sensor can be uniaxial, biaxial, or triaxial, depending on the number of orthogonal axes in which it can perform simultaneous measurements.

Scalar physical quantities (e.g. temperature) do not require a local coordinate system for resolution.

The local coordinate system normally used in a mobile device is a Cartesian coordinate system, which is defined relative to the device’s screen, so that X and Y axes are parallel to the screen dimentions and Z axis is perpendicular to the screen surface.

The term platform sensor refers to platform interfaces, with which the user agent interacts to obtain sensor readings for a single sensor type originated from one or more device sensors.

Platform sensor can be defined by the underlying platform (e.g. in a native sensors framework) or by the user agent, if it has a direct access to device sensor.

From the implementation perspective platform sensor can be treated as a software proxy for the corresponding device sensor. It is possible to have multiple platform sensors simultaneously interacting with the same device sensor if the underlying platform suppports it.

In simple cases, a platform sensor corresponds to a single device sensor, but if the provided sensor readings are a product of sensor fusion performed in software, the platform sensor corresponds to a set of device sensors involved in the sensor fusion process.

Discrepancies between a sensor reading and the corresponding physical quantity being measured are corrected through calibration that can happen at manufacturing time. Some sensors can require dynamic calibration to compensate unknown discrepancies.

Note: platform sensors created through sensor fusion are sometimes called virtual or synthetic sensors. However, the specification doesn’t make any practical distinction between them.

5.2. Sensor Types

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

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

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

Sensors named after their readings, regardless of the implementation, are said to be high-level 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. High-level sensors are generally the fruits of applying algorithms to low-level sensors—for example, a pedometer can be built using only the output of a gyroscope—or of sensor fusion.

That said, the distinction between high-level and low-level 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 low-level for most common purposes, even though it is the product of the sensor fusion 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 high-level sensor type.

Because the distinction is somewhat blurry, extensions to this specification (see § 10 Extensibility) are encouraged to provide domain-specific definitions of high-level and low-level sensors for the given sensor types they are targeting.

Sensor readings from different sensor types can be combined together through a process called sensor fusion. This process provides higher-level or more accurate data (often at the cost of increased latency). For example, the readings of a triaxial magnetometer needs to be combined with the readings of an accelerometer to provide a correct bearing.

Smart sensors and sensor hubs have built-in compute resources which allow them to carry out calibration and sensor fusion at the hardware level, freeing up CPU resources and lowering battery consumption in the process.

Sensor fusion can also be carried out in software if it cannot be performed at the hardware level or if an application-specific fusion algorithm is required.

5.3. Default sensor

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

Most of devices deployed today do not carry more than one device sensor providing sensor readings of the same type. The use cases which require a set of similar device sensors are rare and generally limited to specific sensor types, such as multiple accelerometers in 2-in-1 laptops.

The API therefore makes it easy to interact with the device’s default (and often unique) sensor for each type simply by instantiating the corresponding Sensor subclass.

Indeed, without specific information identifying a particular sensor of a given type, the default sensor is chosen by the user agent.

If the underlying platform provides an interface to find the default sensor, the user agent must choose the sensor offered by the platform, otherwise the user agent itself defines which of the sensors present on the device is the default sensor.

Listening to the default accelerometer changes:
let sensor = new Accelerometer({ frequency: 30 });

sensor.onreading = () => { ... }
sensor.start();

Note: extension to this specification may choose not to define a default sensor when doing so wouldn’t make sense. For example, it does not make sense to explicitly define a default sensor for geolocation sensor type as the implementation of its interface can use multiple backends.

In cases where multiple device sensors corresponding to the same type may coexist on the same device, specification extension will have to define ways to uniquely identify each one.

For example checking the pressure of the left rear tire:
var sensor = new DirectTirePressureSensor({ position: "rear", side: "left" });
sensor.onreading = _ => console.log(sensor.pressure);
sensor.start();

5.4. Sampling Frequency and Reporting Frequency

For the purpose of this specification, sampling frequency for a platform sensor is defined as a frequency at which the user agent obtains sensor readings from the underlying platform.

The user agent can request the underlying platform to deliver readings at a certain rate which is called requested sampling frequency.

The sampling frequency is equal to the requested sampling frequency if the underlying platform can support it.

The sampling frequency differs from the requested sampling frequency in the following cases:

The reporting frequency for a concrete Sensor object is defined as a frequency at which the "reading" event is fired at this object.

A Sensor object cannot access new readings at a higher rate than the user agent obtains them from the underlying platform, therefore the reporting frequency can never exceed the sampling frequency for the given sensor type.

5.5. Conditions to expose sensor readings

The user agent can expose sensor readings to a given document if and only if all of the following are true:

Note: In addition to the conditions above, it is important to note that Sensor subclasses invoke the check sensor policy-controlled features operation in their constructors, and § 7.1.7 Sensor.start() invokes request sensor access. Together, these checks correspond to the mitigation strategies described in § 4.2 Mitigation Strategies.

Note: In order to release hardware resources, the user agent can request underlying platform sensor to suspend notifications about newly available readings until it can expose sensor readings.

6. Model

6.1. Sensor Type

A sensor type has one or more associated extension sensor interfaces.

A sensor type has a set of associated sensors.

A sensor type may have a default sensor.

A sensor type has a nonempty set of associated names referred to as sensor permission names.

Note: multiple sensor types may share the same name.

A sensor type has a permission revocation algorithm.

To invoke the generic sensor permission revocation algorithm with name permission_name, run the following steps:

  1. For each sensor_type whose permission names contains permission_name:

    1. For each sensor in sensor_type’s set of associated sensors,

      1. Invoke revoke sensor permission with sensor as argument.

A sensor type has a permission request algorithm.

A sensor type has a nonempty set of associated policy-controlled feature tokens referred to as sensor feature names.

A sensor type may have an associated threshold check algorithm, which takes as arguments two separate sensor readings and determines if they differ enough to cause a platform sensor's latest reading map to be updated.

A sensor type may have an associated reading quantization algorithm, which takes a sensor reading and returns a less accurate sensor reading.

6.2. Sensor

The current browsing context's platform sensor must have:

Note: User agents can share the latest reading map and the activated sensor objects set between different contexts only if the origins of these contexts' active documents are same origin-domain.

Any time a new sensor reading for a platform sensor is obtained and if the user agent can expose sensor readings to the current browsing context's active document, the user agent invokes update latest reading with the platform sensor and the sensor reading as arguments.

The latest reading map contains an entry whose key is "timestamp" and whose value is a high resolution timestamp that estimates the reading timestamp expressed in milliseconds since the time origin.

Note: The accuracy of the reading timestamp estimate depends on the underlying platform interfaces that expose it.

The latest reading["timestamp"] is initially set to null, unless the latest reading map caches a previous reading.

The other entries of the latest reading map hold the values of the different quantities measured by the platform sensor. The keys of these entries must match the attribute identifier defined by the sensor type's associated extension sensor interface. The return value of the attribute getter is easily obtained by invoking get value from latest reading with the object implementing the extension sensor interface and the attribute identifier as arguments.

The value of all latest reading entries is initially set to null.

A platform sensor has an associated requested sampling frequency which is initially null.

For a non-empty set of activated sensor objects the requested sampling frequency is equal to the optimal sampling frequency, which is estimated by the user agent by taking into account the provided frequencies of activated Sensors and the sampling frequency bounds defined by the underlying platform.

Note: For example, the user agent may estimate optimal sampling frequency as a Least Common Denominator (LCD) for a set of provided frequencies capped by sampling frequency bounds defined by the underlying platform.

This example illustrates a possible implementation of the described Model.

In the diagram below several activated Sensor objects from two different browsing contexts interact with a single device sensor.

Generic Sensor Model

The Sensor object in "idle" state is not among the platform sensor's activated sensor objects and thus it does not interact with the device sensor.

In this example there is a platform sensor instance per browsing context.

The latest reading map is shared between Sensor objects from the same context and is updated at a rate equal to the requested sampling frequency of the corresponding platform sensor.

7. API

7.1. The Sensor Interface

Sensor

In only one current engine.

FirefoxNoneSafariNoneChrome67+
Opera?Edge79+
Edge (Legacy)?IENone
Firefox for Android?iOS Safari?Chrome for Android?Android WebView?Samsung Internet?Opera Mobile?
[SecureContext, Exposed=(DedicatedWorker, Window)]
interface Sensor : EventTarget {
  readonly attribute boolean activated;
  readonly attribute boolean hasReading;
  readonly attribute DOMHighResTimeStamp? timestamp;
  undefined start();
  undefined stop();
  attribute EventHandler onreading;
  attribute EventHandler onactivate;
  attribute EventHandler onerror;
};

dictionary SensorOptions {
  double frequency;
};

A Sensor object has an associated platform sensor.

The task source for the tasks mentioned in this specification is the sensor task source.

In the following example, firstly, we check whether the user agent has permission to access sensor readings, then we construct accelerometer sensor and add event listeners to get events for platform sensor activation, error conditions and notifications about newly available sensor readings. The example measures and logs maximum total acceleration of a device hosting the platform sensor.

The event handler event types for the corresponding Sensor Interface's event handler attributes are defined in Event handlers section.

navigator.permissions.query({ name: 'accelerometer' }).then(result => {
    if (result.state === 'denied') {
        console.log('Permission to use accelerometer sensor is denied.');
        return;
    }

    let acl = new Accelerometer({frequency: 30});
    let max_magnitude = 0;
    acl.addEventListener('activate', () => console.log('Ready to measure.'));
    acl.addEventListener('error', error => console.log(`Error: ${error.name}`));
    acl.addEventListener('reading', () => {
        let magnitude = Math.hypot(acl.x, acl.y, acl.z);
        if (magnitude > max_magnitude) {
            max_magnitude = magnitude;
            console.log(`Max magnitude: ${max_magnitude} m/s2`);
        }
    });
    acl.start();
});

7.1.1. Sensor lifecycle

Sensor lifecycle idle idle activating activating idle->activating start() start() activating->idle onerror activated activated activating->activated activated->idle stop() / onerror start start->idle construct

Note: the nodes in the diagram above represent the states of a Sensor object and they should not be confused with the possible states of the underlying platform sensor or device sensor.

7.1.2. Sensor garbage collection

A Sensor object whose [[state]] is "activating" must not be garbage collected if there are any event listeners registered for "activated" events, "reading" events, or "error" events.

A Sensor object whose [[state]] is "activated" must not be garbage collected if there are any event listeners registered for "reading" events, or "error" events.

When a Sensor object whose [[state]] is "activated" or "activating" is garbage collected, the user agent must invoke deactivate a sensor object with this object as argument.

7.1.3. Sensor internal slots

Instances of Sensor are created with the internal slots described in the following table:

Internal Slot Description (non-normative)
[[state]] The current state of the Sensor object which is one of "idle", "activating", or "activated". It is initially "idle".
[[frequency]] A double representing frequency in Hz that is used to calculate the requested sampling frequency for the associated platform sensor and to define the upper bound of the reporting frequency for this Sensor object.

This slot holds the provided SensorOptions.frequency value. It is initially unset.

[[lastEventFiredAt]] The high resolution timestamp of the latest sensor reading that was sent to observers of the Sensor object, expressed in milliseconds that passed since the time origin. It is initially null.
[[pendingReadingNotification]] A boolean which indicates whether the observers need to be notified after a new sensor reading was reported. It is initially false.

7.1.4. Sensor.activated

Sensor/activated

In only one current engine.

FirefoxNoneSafariNoneChrome67+
Opera?Edge79+
Edge (Legacy)?IENone
Firefox for Android?iOS Safari?Chrome for Android?Android WebView?Samsung Internet?Opera Mobile?

The activated getter steps are:

  1. If this.[[state]] is "activated", return true.

  2. Otherwise, return false.

7.1.5. Sensor.hasReading

Sensor/hasReading

In only one current engine.

FirefoxNoneSafariNoneChrome67+
Opera?Edge79+
Edge (Legacy)?IENone
Firefox for Android?iOS Safari?Chrome for Android?Android WebView?Samsung Internet?Opera Mobile?

The hasReading getter steps are:

  1. Let timestamp be the result of invoking get value from latest reading with this and "timestamp" as arguments.

  2. If timestamp is not null, return true.

  3. Otherwise, return false.

7.1.6. Sensor.timestamp

Sensor/timestamp

In only one current engine.

FirefoxNoneSafariNoneChrome67+
Opera?Edge79+
Edge (Legacy)?IENone
Firefox for Android?iOS Safari?Chrome for Android?Android WebView?Samsung Internet?Opera Mobile?

The timestamp getter steps are to return the result of invoking get value from latest reading with this and "timestamp" as arguments.

It represents a reading timestamp.

7.1.7. Sensor.start()

Sensor/start

In only one current engine.

FirefoxNoneSafariNoneChrome67+
Opera?Edge79+
Edge (Legacy)?IENone
Firefox for Android?iOS Safari?Chrome for Android?Android WebView?Samsung Internet?Opera Mobile?

The start() method steps are:

  1. If this.[[state]] is either "activating" or "activated", then return.

  2. Set this.[[state]] to "activating".

  3. Run these sub-steps in parallel:

    1. Let permissionState be the result of invoking request sensor access with this as argument.

    2. If permissionState is "denied", then:

      1. Let e be the result of creating a "NotAllowedError" DOMException.

      2. Queue a task to run notify error with this and e as arguments.

      3. Return.

    3. Let connected be the result of invoking connect to sensor with this as argument.

    4. If connected is false, then

      1. Let e be the result of creating a "NotReadableError" DOMException.

      2. Queue a task to run notify error with this and e as arguments.

      3. Return.

    5. Invoke activate a sensor object with this as argument.

7.1.8. Sensor.stop()

Sensor/stop

In only one current engine.

FirefoxNoneSafariNoneChrome67+
Opera?Edge79+
Edge (Legacy)?IENone
Firefox for Android?iOS Safari?Chrome for Android?Android WebView?Samsung Internet?Opera Mobile?

The stop() method steps are:

  1. If this.[[state]] is "idle", then return.

  2. Set this.[[state]] to "idle".

  3. Run these sub-steps in parallel:

    1. Invoke deactivate a sensor object with this as argument.

7.1.9. Sensor.onreading

Sensor/reading_event

In only one current engine.

FirefoxNoneSafariNoneChrome67+
Opera?Edge79+
Edge (Legacy)?IENone
Firefox for Android?iOS Safari?Chrome for Android?Android WebView?Samsung Internet?Opera Mobile?

onreading is an EventHandler which is called to notify that new reading is available.

7.1.10. Sensor.onactivate

Sensor/activate_event

In only one current engine.

FirefoxNoneSafariNoneChrome67+
Opera?Edge79+
Edge (Legacy)?IENone
Firefox for Android?iOS Safari?Chrome for Android?Android WebView?Samsung Internet?Opera Mobile?

onactivate is an EventHandler which is called when this.[[state]] transitions from "activating" to "activated".

7.1.11. Sensor.onerror

Sensor/error_event

In only one current engine.

FirefoxNoneSafariNoneChrome67+
Opera?Edge79+
Edge (Legacy)?IENone
Firefox for Android?iOS Safari?Chrome for Android?Android WebView?Samsung Internet?Opera Mobile?

onerror is an EventHandler which is called whenever an exception cannot be handled synchronously.

7.1.12. Event handlers

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

event handler event handler event type
onreading reading
onactivate activate
onerror error

7.2. The SensorErrorEvent Interface

SensorErrorEvent

In only one current engine.

FirefoxNoneSafariNoneChrome67+
Opera?Edge79+
Edge (Legacy)?IENone
Firefox for Android?iOS Safari?Chrome for Android?Android WebView?Samsung Internet?Opera Mobile?

SensorErrorEvent/SensorErrorEvent

In only one current engine.

FirefoxNoneSafariNoneChrome67+
Opera?Edge79+
Edge (Legacy)?IENone
Firefox for Android?iOS Safari?Chrome for Android?Android WebView?Samsung Internet?Opera Mobile?
[SecureContext, Exposed=(DedicatedWorker, Window)]
interface SensorErrorEvent : Event {
  constructor(DOMString type, SensorErrorEventInit errorEventInitDict);
  readonly attribute DOMException error;
};

dictionary SensorErrorEventInit : EventInit {
  required DOMException error;
};

SensorErrorEvent instances are constructed by following the steps described in Event's constructor.

SensorErrorEvent/error

In only one current engine.

FirefoxNoneSafariNoneChrome67+
Opera?Edge79+
Edge (Legacy)?IENone
Firefox for Android?iOS Safari?Chrome for Android?Android WebView?Samsung Internet?Opera Mobile?

The error attribute must return the value it was initialized to. It represents the DOMException object passed to SensorErrorEventInit.

8. Abstract Operations

8.1. Initialize a sensor object

input

sensor_instance, a Sensor object.

options, a SensorOptions dictionary instance.

output

None

  1. For each keyvalue of options

    1. If the associated supported sensor options does not contain key

      1. Throw "NotSupportedError" DOMException.

  2. If options["frequency"] exists, then

    1. Set sensor_instance.[[frequency]] to options["frequency"].

    Note: there is not guarantee that the requested options["frequency"] can be respected. The actual sampling frequency can be calculated using Sensor timestamp attributes.

8.2. Check sensor policy-controlled features

input

sensor_type, a sensor type.

output

True if all of the associated sensor feature names are allowed to use, false otherwise.

  1. Let feature_names be the sensor_type’s associated sensor feature names.

  2. For each feature_name of feature_names,

    1. If active document is not allowed to use the policy-controlled feature named feature_name, then:

      1. Return false.

  3. Return true.

8.3. Connect to sensor

input

sensor_instance, a Sensor object.

output

True if sensor instance was associated with a platform sensor, false otherwise.

  1. Let type be the sensor type of sensor_instance.

  2. If the device has a single device sensor which can provide readings for type, then

    1. Associate sensor_instance with a platform sensor corresponding to this device sensor.

    2. Return true.

  3. If the device has multiple device sensors which can provide readings for type, then

    1. If type has an associated default sensor, then

      1. Associate sensor_instance with a platform sensor corresponding to default sensor.

      2. Return true.

  4. Return false.

8.4. Activate a sensor object

input

sensor_instance, a Sensor object.

output

None

  1. Let sensor be the platform sensor associated with sensor_instance.

  2. Append sensor_instance to sensor’s set of activated sensor objects.

  3. Invoke set sensor settings with sensor as argument.

  4. Queue a task to run notify activated state with sensor_instance as an argument.

8.5. Deactivate a sensor object

input

sensor_instance, a Sensor object.

output

None

  1. Remove all tasks associated with sensor_instance from the task queue associated with sensor task source.

  2. Let sensor be the platform sensor associated with sensor_instance.

  3. If sensor’s set of activated sensor objects contains sensor_instance,

    1. Remove sensor_instance from sensor’s set of activated sensor objects.

    2. Invoke set sensor settings with sensor as argument.

    3. Set sensor_instance.[[pendingReadingNotification]] to false.

    4. Set sensor_instance.[[lastEventFiredAt]] to null.

8.6. Revoke sensor permission

input

sensor, a platform sensor.

output

None

  1. Let activated_sensors be sensor’s associated set of activated sensor objects.

  2. For each s of activated_sensors,

    1. Invoke deactivate a sensor object with s as argument.

    2. Let e be the result of creating a "NotAllowedError" DOMException.

    3. Queue a task to run notify error with s and e as arguments.

8.7. Set sensor settings

input

sensor, a platform sensor.

output

None

  1. If sensor’s set of activated sensor objects is empty,

    1. Set requested sampling frequency to null.

    2. For each keyvalue of latest reading.

      1. Set latest reading[key] to null.

    3. Update the user-agent-specific way in which sensor readings are obtained from sensor to no longer provide readings.

    4. Return.

  2. Set requested sampling frequency to optimal sampling frequency.

8.8. Update latest reading

input

sensor, a platform sensor.

reading, a sensor reading.

output

None

  1. Let type be sensor’s associated sensor type.

  2. If type’s threshold check algorithm is defined, then:

    1. Let result be the result of invoking type’s threshold check algorithm with reading and latest reading.

    2. If result is false, then abort these steps.

  3. For each keyvalue of latest reading.

    1. Set latest reading[key] to the corresponding value of reading.

  4. Let activated_sensors be sensor’s associated set of activated sensor objects.

  5. Run these sub-steps in parallel:

    1. For each s in activated_sensors,

      1. Invoke report latest reading updated with s as an argument.

8.9. Find the reporting frequency of a sensor object

input

sensor_instance, a Sensor object.

output

reporting frequency in Hz.

  1. Let frequency be null.

  2. Let f be sensor_instance.[[frequency]].

    1. if f is set,

      1. set frequency to f capped by the upper and lower sampling frequency bounds for the associated platform sensor.

    2. Otherwise,

      1. user agent can assign frequency to an appropriate value.

  3. return frequency.

8.10. Report latest reading updated

input

sensor_instance, a Sensor object.

output

None

  1. If sensor_instance.[[pendingReadingNotification]] is true,

    1. Return.

  2. Set sensor_instance.[[pendingReadingNotification]] to true.

  3. Let lastReportedTimestamp be the value of sensor_instance.[[lastEventFiredAt]].

  4. If lastReportedTimestamp is not set

    1. Queue a task to run notify new reading with sensor_instance as an argument.

    2. Return.

  5. Let reportingFrequency be result of invoking Find the reporting frequency of a sensor object.

  6. If reportingFrequency is null

    1. Queue a task to run notify new reading with sensor_instance as an argument.

    2. Return.

  7. Let reportingInterval be the result of 1 / reportingFrequency.

  8. Let timestampDelta be the result of latest reading["timestamp"] - lastReportedTimestamp.

  9. If timestampDelta is greater than or equal to reportingInterval

    1. Queue a task to run notify new reading with sensor_instance as an argument.

    2. Return.

  10. Let deferUpdateTime be the result of reportingInterval - timestampDelta.

  11. Spin the event loop for a period of time equal to deferUpdateTime.

  12. If sensor_instance.[[pendingReadingNotification]] is true,

    1. Queue a task to run notify new reading with sensor_instance as an argument.

8.11. Notify new reading

input

sensor_instance, a Sensor object.

output

None

  1. Set sensor_instance.[[pendingReadingNotification]] to false.

  2. Set sensor_instance.[[lastEventFiredAt]] to latest reading["timestamp"].

  3. Fire an event named "reading" at sensor_instance.

8.12. Notify activated state

input

sensor_instance, a Sensor object.

output

None

  1. Set sensor_instance.[[state]] to "activated".

  2. Fire an event named "activate" at sensor_instance.

  3. Let sensor be the platform sensor associated with sensor_instance.

  4. If sensor’s latest reading["timestamp"] is not null,

    1. Queue a task to run notify new reading with sensor_instance as an argument.

8.13. Notify error

input

sensor_instance, a Sensor object.

error, a DOMException.

output

None

  1. Set sensor_instance.[[state]] to "idle".

  2. Fire an event named "error" at sensor_instance using SensorErrorEvent with its error attribute initialized to error.

8.14. Get value from latest reading

input

sensor_instance, a Sensor object.

key, a string representing the name of the value.

output

A sensor reading value or null.

  1. If sensor_instance.[[state]] is "activated",

    1. Let readings be the latest reading of sensor_instance’s related platform sensor.

    2. Let type be sensor_instance’s associated platform sensor's associated sensor type.

    3. If type’s reading quantization algorithm is defined, then:

      1. Set readings to the result of invoking type’s reading quantization algorithm with readings.

    4. If the extension specification defines a local coordinate system for sensor_instance,

      1. Remap (see [COORDINATES-TRANSFORMATION]) readings values to the local coordinate system.

    5. Return readings[key].

  2. Otherwise, return null.

8.15. Request sensor access

input

sensor_instance, a Sensor object.

output

A permission state.

  1. Let sensor be the platform sensor associated with sensor_instance.

  2. Let sensor_permissions be sensor’s associated set of permission names.

  3. For each permission_name in sensor_permissions,

    1. Let state be the result of requesting permission to use permission_name.

    2. If state is "denied"

      1. Return "denied".

  4. Return "granted".

9. Automation

The Generic Sensor API and its extension specifications pose a challenge to test authors, as fully exercising those interfaces requires physical hardware devices that respond in predictable ways. To address this challenge this document defines a number of extension commands to the [WEBDRIVER2] specification for controlling mock sensor on the host that the user agent is running on. With these extension commands, devices with particular properties can be created and their responses to requests are well defined.

9.1. Mock Sensors

A mock sensor simulates the behavior of a platform sensor in controlled ways.

A mock sensor reports a corresponding mock sensor reading, which is a source of mocking information about the environment, to the Sensor objects.

The current browsing context's mock sensor has an associated mock sensor reading map.

The mock sensor reading map contains an entry whose key is "timestamp" and whose value is a high resolution timestamp that estimates the time mock sensor reading sent to observers of the Sensor object, expressed in milliseconds since the time origin.

The other entries of the mock sensor reading map whose keys must match the dictionary members identifier defined by the mock sensor type's MockSensorReadingValues and whose initial values are implementation-dependent.

Note: The user agent must provide the mock sensor reading that are initially exposed to the Sensor objects.

A mock sensor has an associated requested sampling frequency. Its default value is implementation-dependent but must be set within a mock sensor's associated sampling frequency bounds.

A mock sensor has an associated sampling frequency with supported bounds. The default values of supported bounds are implementation-dependent.

A mock sensor must report the mock sensor reading at the rate of its requested sampling frequency if the user agent can expose sensor readings to the current browsing context's active document.

Note: The mock sensor defined in this specification is not intended be used by non-testing-related web content. The UA MAY choose to expose mock sensor interface only when a runtime or compile-time flag has been set.

9.1.1. MockSensorConfiguration dictionary

dictionary MockSensorConfiguration {
  required MockSensorType mockSensorType;
  boolean connected = true;
  double? maxSamplingFrequency;
  double? minSamplingFrequency;
};

The MockSensorConfiguration dictionary is used to create a mock sensor.

mockSensorType member

A MockSensorType that is used to set mock sensor type.

connected member

A boolean that indicates a mock sensor's connection flag which is used for switching the connection between Sensor object and mock sensor. When set to false the user agent must force the result of invoking connect to sensor with mock sensor's associated Sensor object as argument to false, otherwise true.

maxSamplingFrequency member

A double representing frequency in Hz that is used to set maximum supported sampling frequency for the associated mock sensor.

minSamplingFrequency member

A double representing frequency in Hz that is used to set minimum supported sampling frequency for the associated mock sensor.

9.1.2. MockSensor dictionary

dictionary MockSensor {
  double maxSamplingFrequency;
  double minSamplingFrequency;
  double requestedSamplingFrequency;
};

The MockSensor dictionary provides information about a mock sensor.

maxSamplingFrequency member

A double representing frequency in Hz that indicates the maximum supported sampling frequency of the associated mock sensor.

minSamplingFrequency member

A double representing frequency in Hz that indicates the minimum supported sampling frequency of the associated mock sensor.

requestedSamplingFrequency member

A double representing frequency in Hz that indicates the requested sampling frequency of the associated mock sensor.

A serialized mock sensor is a JSON Object where a mock sensor's fields listed in the MockSensor dictionary are mapped using the JSON Key and the associated field’s value from the available mock sensor in current browsing context.

9.1.3. Mock sensor type

A mock sensor type is equivalent to a sensor type's associated Sensor subclass.

enum MockSensorType {
  "ambient-light",
  "accelerometer",
  "linear-acceleration",
  "gravity",
  "gyroscope",
  "magnetometer",
  "uncalibrated-magnetometer",
  "absolute-orientation",
  "relative-orientation",
  "geolocation",
  "proximity",
};

Each enumeration value in the MockSensorType enum identifies a mock sensor type.

"ambient-light"

A mock sensor type associated with the usage of the AmbientLightSensor interface.

"accelerometer"

A mock sensor type associated with the usage of the Accelerometer interface.

"linear-acceleration"

A mock sensor type associated with the usage of the LinearAccelerationSensor interface.

"gravity"

A mock sensor type associated with the usage of the GravitySensor interface.

"gyroscope"

A mock sensor type associated with the usage of the Gyroscope interface.

"magnetometer"

A mock sensor type associated with the usage of the Magnetometer interface.

"uncalibrated-magnetometer"

A mock sensor type associated with the usage of the UncalibratedMagnetometer interface.

"absolute-orientation"

A mock sensor type associated with the usage of the AbsoluteOrientationSensor interface.

"relative-orientation"

A mock sensor type associated with the usage of the RelativeOrientationSensor interface.

"geolocation"

A mock sensor type associated with the usage of the GeolocationSensor interface.

"proximity"

A mock sensor type associated with the usage of the ProximitySensor interface.

Each mock sensor type has a mock sensor reading values dictionary:

Mock Sensor Reading Values dictionary

MockSensorReadingValues dictionary represents a user-specified mock sensor reading used for updating a mock sensor reading. Its members must match the attribute identifier defined by the sensor type's associated extension sensor interface. Each mock sensor type has a specific MockSensorReadingValues, which is defined in each extension specifications.

dictionary MockSensorReadingValues {
};

9.2. Extension Commands

9.2.1. Create mock sensor

HTTP Method URI Template
POST /session/{session id}/sensor

The create mock sensor extension command creates a new mock sensor.

The remote end steps are:

  1. Let configuration be the configuration parameter, converted to an IDL value of type MockSensorConfiguration. If this throws an exception, return an invalid argument error.

  2. Let type be the configuration.mockSensorType. If the current browsing context already has this type of mock sensor, return a mock sensor already created error.

  3. If the current browsing context is no longer open, return a no such window error.

  4. Handle any user prompts, and return its value if it is an error.

  5. Run these sub-steps in parallel to create a mock sensor in the current browsing context:

    1. Let mock be a new mock sensor.

    2. Set mock’s mock sensor type to type.

    3. Let connected be the configuration.connected, set mock’s associated connection flag to connected.

    4. If configuration.maxSamplingFrequency exists, then:

      1. Set mock’s maximum supported sampling frequency to configuration.maxSamplingFrequency.

    5. If configuration.minSamplingFrequency exists, then:

      1. Set mock’s minimum supported sampling frequency to configuration.minSamplingFrequency.

    6. Let sensor_instance be a type of Sensor object, set sensor_instance’s associated platform sensor to mock.

  6. Return success with data null.

To create an "ambient-light" mock sensor in the current browsing context of the session with ID 23, the local end would POST to /session/23/sensor with the body:
{
  "mockSensorType": "ambient-light",
  "maxSamplingFrequency": 60,
  "minSamplingFrequency": 5
}

Be aware that only one mock sensor of a given mock sensor type can be created in current browsing context, otherwise a mock sensor already created error will be thrown.

9.2.2. Get mock sensor

HTTP Method URI Template
GET /session/{session id}/sensor/{type}

The get mock sensor extension command retrieves information about a given type of mock sensor.

The remote end steps are:

  1. Let type be a url variable, converted to an IDL value of type MockSensorType. If this throws an exception, return an invalid argument error.

  2. If the current browsing context is no longer open, return a no such window error.

  3. Handle any user prompts, and return its value if it is an error.

  4. If type does not match a mock sensor type amongst all associated mock sensors of the current browsing context, return a no such mock sensor error.

  5. Return success with the serialized mock sensor as data.

9.2.3. Update mock sensor reading

HTTP Method URI Template
POST /session/{session id}/sensor/{type}

The update mock sensor reading extension command updates a given type of mock sensor's reading.

The remote end steps are:

  1. Let type be a url variable, converted to an IDL value of type MockSensorType. If this throws an exception, return an invalid argument error.

  2. If the current browsing context is no longer open, return a no such window error.

  3. Handle any user prompts, and return its value if it is an error.

  4. If type does not match a mock sensor type amongst all associated mock sensors of the current browsing context, return a no such mock sensor error.

  5. Let reading be the reading argument, converted to an IDL value of the type’s associated MockSensorReadingValues. If this throws an exception, return an invalid argument error.

  6. For each keyvalue of reading.

    1. Set mock sensor reading[key] to the corresponding value of reading.

  7. Return success with data null.

9.2.4. Delete mock sensor

HTTP Method URI Template
DELETE /session/{session id}/sensor/{type}

The delete mock sensor extension command deletes a given type of mock sensor.

The remote end steps are:

  1. Let type be a url variable.

  2. If MockSensorType does not contain type, return an invalid argument error.

  3. If the current browsing context is no longer open, return a no such window error.

  4. Handle any user prompts, and return its value if it is an error.

  5. If type does not match a mock sensor type amongst all associated mock sensors of the current browsing context, return a no such mock sensor error.

  6. Delete type of mock sensor in current browsing context.

  7. Return success with data null.

9.3. Handling errors

This section extends the WebDriver § 6.6 Errors section and defines extended WebDriver error codes specific for mock sensor in following table.

Error Code HTTP Status JSON Error Code Description
no such mock sensor 404 no such mock sensor no mock sensor matching the given type was found.
mock sensor already created 500 mock sensor already created command to create a mock sensor could not be satisfied because the given type of mock sensor is already existed.

10. Extensibility

This section is non-normative.

Note: This section and its subsections provide guidance to extension specification authors using normative language. From implementers' point of view, this section and its subsections are considered non-normative.

This section describes how this specification can be extended to specify APIs for different sensor types.

Such extension specifications are encouraged to focus on a single sensor type, exposing both high and low level as appropriate.

Extension specifications are encouraged to define whether a calibration process applies to sensor readings.

Extension specifications may explicitly define the local coordinate system for the associated sensor type or make it configurable per Sensor object.

For an up-to-date list of extension specifications, please refer to [GENERIC-SENSOR-USECASES] and [MOTION-SENSORS] documents.

10.1. Security and Privacy

Extension specifications are expected to:

10.2. Naming

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

Attributes of the Sensor subclass that hold sensor readings values should be named after the full name of these values. For example, the Thermometer interface should hold the sensor reading's value in a temperature attribute (and not a value or temp attribute). A good starting point for naming are the Quantities, Units, Dimensions and Data Types Ontologies [QUDT].

10.3. Unit

Extension specifications must specify the unit of sensor readings.

As per the Technical Architecture Group’s (TAG) API Design Principles [API-DESIGN-PRINCIPLES], all time measurement should be in milliseconds. All other units should be specified using, in order of preference, and with the exception of temperature (for which Celsius should be favored over Kelvin), the International System of Units (SI), SI derived units, and Non-SI units accepted for use with the SI, as described in the SI Brochure [SI].

10.4. Exposing High-Level vs. Low-Level Sensors

So far, specifications exposing sensors to the Web platform have focused on high-level sensors APIs. [GEOLOCATION-API] [ORIENTATION-EVENT]

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

However, an increasing number of use cases such as virtual and augmented reality require low-level access to sensors, most notably for performance reasons.

Providing low-level 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 low-level sensor APIs, but should also expose high-level APIs when they are clear benefits in doing so.

10.5. When is Enabling Multiple Sensors of the Same Type Not the Right Choice?

It is not advisable to construct multiple Sensor instances of the same sensor type with equal construction parameters, as it can lead to unnecessary hardware resources consumption.

In cases when multiple observers are interested in notifications of a newly available sensor reading, an event listener can be added on a single Sensor instance instead of creating multiple instances of the same sensor type and using simple onreading event handler.

Conversely, multiple Sensors of the same sensor type can be created when they are intended to be used with different settings, such as: requested sampling frequency, accuracy or other settings defined in extension specifications.

10.6. Definition Requirements

The following definitions must be specified for each sensor type in extension specifications:

An extension specification may specify the following definitions for each sensor types:

10.7. Automation

In order to enable user-agent automation and application testing, extension specifications are encouraged to:

10.8. Extending the Permission API

An implementation of the Sensor interface for each sensor type must protect its reading by associated name or PermissionDescriptor. A low-level sensor may use its interface name as a name, for instance, "gyroscope" or "accelerometer". Fusion sensors must request permission to access each of the sensors that are used as a source of fusion.

Even though it might be difficult to reconstruct low-level sensor readings from fused data, some of the original information might be inferred. For example, it is easy to deduce user’s orientation in space if absolute or geomagnetic orientation sensors are used, therefore, these sensors must request permission to use magnetometer as it provides information about orientation of device in relation to Earth’s magnetic field. In contrast, relative orientation sensor does not expose such information, thus, it does not need to request permission to use magnetometer.

Permission descriptors can also be used to set maximum allowed limits for accuracy or sampling frequency. An example for a possible extension of the Permission API for accelerometer sensor is given below.

dictionary AccelerometerPermissionDescriptor : PermissionDescriptor {
    boolean highAccuracy = false;
    boolean highFrequency = false;
};

10.9. Extending the Permissions Policy API

An implementation of the Sensor interface for each sensor type has one (if sensor fusion is not performed) or several policy-controlled features that control whether or not this implementation can be used in a document.

The features' default allowlist is 'self'.

Note: The default allowlist of 'self' allows Sensor interface implementation usage in same-origin nested frames but prevents third-party content from sensor readings access.

The sensor feature names set must contain policy-controlled feature tokens of every associated feature.

A low-level sensor may use its interface name as a policy-controlled feature token, for instance, "gyroscope" or "accelerometer". Unless the extension specification defines otherwise, the sensor feature names matches the same type-associated sensor permission names.

The accelerometer feature is selectively enabled for third-party origin by adding an allow attribute to the frame container element:
<iframe src="https://third-party.com" allow="accelerometer"/></iframe>
A sensor usage is disabled completely by specifying the permissions policy in an HTTP response header:
Permissions-Policy: accelerometer=()

Fusion sensors must use sensor feature names of the sensors that are used as a source of fusion.

Allow third-party origin to use accelerometer, magnetometer and gyroscope features that are required by the absolute orientation sensor.
<iframe src="https://third-party.com" allow="accelerometer; magnetometer; gyroscope"/>

10.10. Example WebIDL

Here’s an example WebIDL for a possible extension of this specification for proximity sensors.

[SecureContext, Exposed=Window]
interface ProximitySensor : Sensor {
    constructor(optional ProximitySensorOptions proximitySensorOptions = {});
    readonly attribute double? distance;
};

dictionary ProximitySensorOptions : SensorOptions {
    double min;
    double max;
    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"
};

11. Acknowledgements

First and foremost, I would like to thank Anssi Kostiainen for his continuous and dedicated support and input throughout the development of this specification, as well as Mikhail Pozdnyakov, Alexander Shalamov, Rijubrata Bhaumik, and Kenneth Rohde Christiansen for their invaluable implementation feedback, suggestions, and research that have helped inform the specification work.

Special thanks to Rick Waldron for driving the discussion around a generic sensor API design for the Web, sketching the original API on which this is based, providing implementation feedback from his work on Johnny-Five, and continuous input during the development of this specification.

Special thanks to Boris Smus, Tim Volodine, and Rich Tibbett for their initial work on exposing sensors to the web with consistency.

Thanks to Anne van Kesteren for his tireless help both in person and through IRC.

Thanks to Domenic Denicola and Jake Archibald for their help.

Thanks also to Frederick Hirsch and Dominique Hazaël-Massieux (via the HTML5Apps project) for both their administrative help and technical input.

Thanks to Tab Atkins for making Bikeshed and taking the time to explain its subtleties.

Thanks to Lukasz Olejnik and Maryam Mehrnezhad for their contributions around privacy and security.

The following people have greatly contributed to this specification through extensive discussions on GitHub: Anssi Kostiainen, Boris Smus, chaals, Claes Nilsson, Dave Raggett, David Mark Clements, Domenic Denicola, Dominique Hazaël-Massieux (via the HTML5Apps project), Francesco Iovine, Frederick Hirsch, gmandyam, Jafar Husain, Johannes Hund, Kris Kowal, Lukasz Olejnik, Marcos Caceres, Marijn Kruisselbrink, Mark Foltz, Mats Wichmann, Matthew Podwysocki, Olli Pettay, pablochacin, Remy Sharp, Rich Tibbett, Rick Waldron, Rijubrata Bhaumik, robman, Sean T. McBeth, Tab Atkins Jr., Virginie Galindo, zenparsing, and Zoltan Kis.

We’d also like to thank Anssi Kostiainen, Dominique Hazaël-Massieux, Erik Wilde, and Michael[tm] Smith for their editorial input.

Conformance

Document conventions

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.

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

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

This is an example of an informative example.

Because this document doesn’t itself define APIs for specific sensor typesthat is the role of extensions to this specification—all examples are inevitably (wishful) fabrications. Although all of the sensors 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.

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

Note, this is an informative note.

Conformant Algorithms

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

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.

Conformance Classes

A conformant user agent must implement all the requirements listed in this specification that are applicable to user agents.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[ACCELEROMETER]
Anssi Kostiainen. Accelerometer. URL: https://w3c.github.io/accelerometer/
[AMBIENT-LIGHT]
Anssi Kostiainen; Rijubrata Bhaumik. Ambient Light Sensor. URL: https://w3c.github.io/ambient-light/
[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[GEOLOCATION-SENSOR]
Anssi Kostiainen; Thomas Steiner; Marijn Kruisselbrink. Geolocation Sensor. URL: https://w3c.github.io/geolocation-sensor/
[GYROSCOPE]
Anssi Kostiainen. Gyroscope. URL: https://w3c.github.io/gyroscope/
[HR-TIME-3]
Yoav Weiss. High Resolution Time. URL: https://w3c.github.io/hr-time/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[MAGNETOMETER]
Anssi Kostiainen; Rijubrata Bhaumik. Magnetometer. URL: https://w3c.github.io/magnetometer/
[ORIENTATION-SENSOR]
Kenneth Christiansen; et al. Orientation Sensor. URL: https://w3c.github.io/orientation-sensor/
[PERMISSIONS]
Marcos Caceres; Mike Taylor. Permissions. URL: https://w3c.github.io/permissions/
[PERMISSIONS-POLICY]
Ian Clelland. Permissions Policy. URL: https://w3c.github.io/webappsec-permissions-policy/
[PERMISSIONS-REQUEST]
Requesting Permissions. cg-draft. URL: https://wicg.github.io/permissions-request/
[PROXIMITY]
Anssi Kostiainen; Rijubrata Bhaumik. Proximity Sensor. URL: https://w3c.github.io/proximity/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[WEBDRIVER2]
Simon Stewart; David Burns. WebDriver. URL: https://w3c.github.io/webdriver/
[WEBIDL]
Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/

Informative References

[ACCELPRINT]
Dey, Sanorita, et al.. AccelPrint: Imperfections of Accelerometers Make Smartphones Trackable. 2014. Informational. URL: http://synrg.csl.illinois.edu/papers/AccelPrint_NDSS14.pdf
[API-DESIGN-PRINCIPLES]
Sangwhan Moon. Web Platform Design Principles. URL: https://w3ctag.github.io/design-principles/
[COORDINATES-TRANSFORMATION]
George W. Collins, II. The Foundations of Celestial Mechanics. 2004. Informational. URL: http://ads.harvard.edu/books/1989fcm..book/Chapter2.pdf
[EXTENNNNSIBLE]
The Extensible Web Manifesto. 10 June 2013. URL: https://extensiblewebmanifesto.org/
[GENERIC-SENSOR-USECASES]
Rick Waldron, Mikhail Pozdnyakov, Alexander Shalamov. Sensor Use Cases. 2017. Note. URL: https://w3c.github.io/sensors/usecases
[GEOLOCATION-API]
Andrei Popescu. Geolocation API Specification 2nd Edition. URL: https://w3c.github.io/geolocation-api/
[GYROSPEECHRECOGNITION]
Michalevsky, Y., Boneh, D. and Nakibly, G.. Gyrophone: Recognizing Speech from Gyroscope Signals. 2014. Informational. URL: https://www.usenix.org/system/files/conference/usenixsecurity14/sec14-paper-michalevsky.pdf
[MOBILESENSORS]
Manish J. Gajjar. Mobile Sensors and Context-Aware Computing. 2017. Informational.
[MOTION-SENSORS]
Kenneth Christiansen; Alexander Shalamov. Motion Sensors Explainer. URL: https://w3c.github.io/motion-sensors/
[ORIENTATION-EVENT]
Rich Tibbett; et al. DeviceOrientation Event Specification. URL: https://w3c.github.io/deviceorientation/
[POWERFUL-FEATURES]
Mike West. Secure Contexts. URL: https://w3c.github.io/webappsec-secure-contexts/
[QUDT]
Ralph Hodgson; et al. QUDT - Quantities, Units, Dimensions and Data Types Ontologies. 18 March 2014. URL: http://www.qudt.org/
[RFC6454]
A. Barth. The Web Origin Concept. December 2011. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6454
[SECURITY-PRIVACY-QUESTIONNAIRE]
Theresa O'Connor; Peter Snyder. Self-Review Questionnaire: Security and Privacy. URL: https://w3ctag.github.io/security-questionnaire/
[SI]
SI Brochure: The International System of Units (SI), 8th edition. 2014. URL: http://www.bipm.org/en/publications/si-brochure/
[STEALINGPINSVIASENSORS]
Maryam Mehrnezhad, Ehsan Toreini, Siamak F. Shahandashti, Feng Hao. Stealing PINs via mobile sensors: actual risk versus user perception. 2017. Informational. URL: https://rd.springer.com/article/10.1007/s10207-017-0369-x?wt_mc=Internal.Event.1.SEM.ArticleAuthorOnlineFirst
[WEBDRIVER-BIDI]
WebDriver BiDi URL: https://w3c.github.io/webdriver-bidi/

IDL Index

[SecureContext, Exposed=(DedicatedWorker, Window)]
interface Sensor : EventTarget {
  readonly attribute boolean activated;
  readonly attribute boolean hasReading;
  readonly attribute DOMHighResTimeStamp? timestamp;
  undefined start();
  undefined stop();
  attribute EventHandler onreading;
  attribute EventHandler onactivate;
  attribute EventHandler onerror;
};

dictionary SensorOptions {
  double frequency;
};

[SecureContext, Exposed=(DedicatedWorker, Window)]
interface SensorErrorEvent : Event {
  constructor(DOMString type, SensorErrorEventInit errorEventInitDict);
  readonly attribute DOMException error;
};

dictionary SensorErrorEventInit : EventInit {
  required DOMException error;
};

dictionary MockSensorConfiguration {
  required MockSensorType mockSensorType;
  boolean connected = true;
  double? maxSamplingFrequency;
  double? minSamplingFrequency;
};

dictionary MockSensor {
  double maxSamplingFrequency;
  double minSamplingFrequency;
  double requestedSamplingFrequency;
};

enum MockSensorType {
  "ambient-light",
  "accelerometer",
  "linear-acceleration",
  "gravity",
  "gyroscope",
  "magnetometer",
  "uncalibrated-magnetometer",
  "absolute-orientation",
  "relative-orientation",
  "geolocation",
  "proximity",
};

dictionary MockSensorReadingValues {
};