# Sensor Use Cases

## W3C Note, 1 January 1970

This version:
  https://www.w3.org/TR/1970/NOTE-generic-sensor-usecases-19700101/
Latest published version:
  http://www.w3.org/TR/generic-sensor-usecases/
Editor's Draft:
  https://w3c.github.io/sensors/usecases
Version History:
  https://github.com/w3c/sensors/commits/gh-pages/index.bs
Feedback:
  public-device-apis@w3.org with subject line “`[generic-sensor-usecases] … message topic …`” (archives)
Editors:
  Rick Waldron (Bocoup, formerly on behalf of JS Foundation)
  Mikhail Pozdnyakov (Intel Corporation)
  Alexander Shalamov (Intel Corporation)
Former Editor:
  Tobie Langel (Codespeaks, formerly on behalf of Intel Corporation) tobie@codespeaks.com
Bug Reports:
  via the w3c/sensors repository on GitHub
Issue Tracking:
  Level 1 Issues

Copyright © 1970 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.

## Abstract

This document lists use cases for sensor data exposed to the Open Web Platform along with code examples of how Web developers ("authors" in spec speech) would listen to sensor data and use it within their application-level code.

## Status of this document

## 1. Introduction

The Generic Sensor API provides generic interfaces for accessing sensors. The purpose of this document is to collect use cases, requirements, references to applicable documents and concrete sensor specifications in order to provide input for Generic Sensor API improvements.

## 2. Use Cases and requirements

The use cases and requirements for the sensors differ from one application to another. In this section, sensors are grouped into categories that represent particular set of common use cases.

### 2.1. Environmental sensors

This group of sensors measure physical properties of the environment they are in. For example, sensors that measure barometric air pressure, humidity, ambient light, ambient air temperature, etc., belong to this group.

Environmental sensors might be used in applications like: home automation, accessibility, personal weather forecast, sport and fitness monitoring. Additional use cases and requirements can be found from corresponding environmental sensors that are based on Generic Sensor API:

- Ambient light sensor

- Proximity sensor

- Magnetometer

### 2.2. Inertial sensors

This group of sensors is based on inertia and relevant measuring concepts. Usually, inertial sensors are part of IMU (Inertial Measurements Unit) that measure acceleration using accelerometer and rotational rate using gyroscope. Magnetometer might be part of IMU and provide data to calculate heading reference and/or gyroscope drift correction.

Inertial sensors enable various use cases, such as: virtual and augmented reality, immersive gaming, activity recognition, sport and fitness monitoring, 3D scanning, indoor navigation and mapping. The motion sensors explainer has extensive list of use cases and references to applicable scientific papers.

The following inertial sensors are based on Generic Sensor API:

- Accelerometer

- Gyroscope

### 2.3. Fusion sensors

This group of sensors provide measurements that are 'fused together' by fusion algorithm. The fusion algorithms might require data from one or multiple sources. For example, the data provided by the relative orientation sensor can be fused from accelerometer or be a combination of accelerometer and gyroscope data. The most common use cases for fusion sensors can be found in the motion sensors explainer document.

The following fusion sensors are based on Generic Sensor API:

- Absolute orientation sensor

- Relative orientation sensor

- Linear acceleration sensor

- Gravity sensor

Note: The Magnetometer is often used to improve integrity of the data provided by accelerometer and/or gyroscope, as well as for establishing frame of reference based on Earth’s coordinate system.

### 2.4. Creating custom fusion sensors

The web applications might require data that is not provided by the UA. Generic Sensor API allows implementation of custom fusion sensors that may fulfill special use cases.

We might need to think about opening this as an improvement for Generic Sensor API. Interface that will take fusion algorithm and as a result, provide new sensor property and/or modify `onreading` behavior. This will enable implementation of various sensors, like: SimpleOrientation, FreeFall, Pedometer, Compass or simple trigger sensors.

In cases when web application requires additional functionality from the concrete sensor, extension of the base sensor interface might be the simplest solution.

In this example, we create a simple linear free fall detection sensor.

    class FreeFallSensor extends Accelerometer {
        set onreading(func) {
            super.onreading = () => {
                let isFalling = Math.hypot(super.x, super.y, super.z) < 0.5;
                if (this.inFreeFall_ != isFalling) {
                    this.inFreeFall_ =  isFalling;
                    func();
                }
            }
        }

        get inFreeFall() {
            return this.inFreeFall_;
        }
    }

When the web application requires measurements that are fused from multiple sensor sources, simple aggregation pattern may be used.

In this simplified example, we define `FusionSensor` class that aggregates multiple sources and provides fused data.

    class FusionSensor {
        constructor(sensors, algorithm) {
            this.sensors_ = sensors;
            this.algorithm_ = algorithm.bind(this);
        }

        start() {
            this.sensors_.map(sensor => sensor.start());
        }

        stop()  {
            this.sensors_.map(sensor => sensor.stop());
        }

        set onreading(func) {
            this.sensors_.map(sensor => {
                sensor.onreading = () => {
                    this.fusedReading_ = this.algorithm_(sensor, this.sensors_);
                    func();
                }
            });
        }

        get fusedReading() {
            return this.fusedReading_;
        }
    }

    // Stateful algorithm that finds brightest spot during calibration phase and uses
    // it as a fixed frame of reference to calculate relative orientation from brightest
    // light source.
    let custom_algo = (changed_source, all_sources) => { return new DOMMatrix(); }
    let source_sensors = [new Accelerometer(), new Gyroscope(), new AmbientLightSensor()];
    let sensor = new FusionSensor(source_sensors, custom_algo);
    sensor.onreading = () => { console.log(JSON.stringify(sensor.fusedReading)); }
    sensor.start();

### 2.5. Trigger sensors

This group of sensors may not need frequency. The HW will just fire interrupt to signal about the change. If trigger sensor functionality is provided by e.g., accelerometer, sensor would be operating in special low-power mode.

For the purpose of this document, trigger sensors group is characterised by the simplicity of the hardware, limited sensor configuration capabilities, special mode of operation or notification mechanism for the new sensor readings. For example, reed switch or hall effect sensors that will trigger hardware interrupt and provide one bit reading data (on / off).

The following list of sensors might be a good example of trigger sensors:

- Reed switch and hall effect sensors

- Significant motion, no motion, tap, flat, free fall, low-g and high-g sensors

- Laser or infrared switch sensors

## Index

https://w3c.github.io/accelerometer#acceleration Referenced in:

- 2.2. Inertial sensors

https://w3c.github.io/accelerometer#accelerometer-interface Referenced in:

- 2.2. Inertial sensors (2)
- 2.3. Fusion sensors (2) (3)
- 2.5. Trigger sensors

https://w3c.github.io/accelerometer#gravitysensor-interface Referenced in:

- 2.3. Fusion sensors

https://w3c.github.io/accelerometer#linearaccelerationsensor-interface Referenced in:

- 2.3. Fusion sensors

https://w3c.github.io/ambient-light#usecases-requirements Referenced in:

- 2.1. Environmental sensors

https://w3c.github.io/gyroscope#gyroscope-interface Referenced in:

- 2.2. Inertial sensors (2) (3)
- 2.3. Fusion sensors (2)

https://w3c.github.io/gyroscope#angular-velocity Referenced in:

- 2.2. Inertial sensors

https://w3c.github.io/magnetometer#magnetometer-interface Referenced in:

- 2.2. Inertial sensors
- 2.3. Fusion sensors

https://w3c.github.io/magnetometer#usecases-and-requirements Referenced in:

- 2.1. Environmental sensors

https://w3c.github.io/motion-sensors#usecases-and-requirements Referenced in:

- 2.2. Inertial sensors
- 2.3. Fusion sensors

https://w3c.github.io/orientation-sensor#absoluteorientationsensor-interface Referenced in:

- 2.3. Fusion sensors

https://w3c.github.io/orientation-sensor#relativeorientationsensor-interface Referenced in:

- 2.3. Fusion sensors

https://w3c.github.io/proximity#proximity-sensor-interface Referenced in:

- 2.1. Environmental sensors

### Terms defined by reference

- [accelerometer] defines the following terms:
  - acceleration
  - accelerometer
  - gravity sensor
  - linear acceleration sensor
- [ambient-light] defines the following terms:
  - ambient light sensor
- [gyroscope] defines the following terms:
  - gyroscope
  - rotational rate
- [magnetometer] defines the following terms:
  - magnetometer
  - magnetometer use cases
- [motion-sensors] defines the following terms:
  - motion sensors explainer
- [orientation-sensor] defines the following terms:
  - absolute orientation sensor
  - relative orientation sensor
- [proximity] defines the following terms:
  - proximity sensor

## References

### Normative References

[ACCELEROMETER]
  Anssi Kostiainen. Accelerometer. 7 March 2019. WD. URL: https://www.w3.org/TR/accelerometer/
[AMBIENT-LIGHT]
  Anssi Kostiainen. Ambient Light Sensor. 7 March 2019. WD. URL: https://www.w3.org/TR/ambient-light/
[GYROSCOPE]
  Anssi Kostiainen. Gyroscope. 7 March 2019. WD. URL: https://www.w3.org/TR/gyroscope/
[MAGNETOMETER]
  Anssi Kostiainen; Rijubrata Bhaumik. Magnetometer. 7 March 2019. WD. URL: https://www.w3.org/TR/magnetometer/
[MOTION-SENSORS]
  Kenneth Christiansen; Alexander Shalamov. Motion Sensors Explainer. 30 August 2017. NOTE. URL: https://www.w3.org/TR/motion-sensors/
[ORIENTATION-SENSOR]
  Kenneth Christiansen; Anssi Kostiainen. Orientation Sensor. 7 March 2019. WD. URL: https://www.w3.org/TR/orientation-sensor/
[PROXIMITY]
  Anssi Kostiainen; Rijubrata Bhaumik. Proximity Sensor. 5 March 2019. WD. URL: https://www.w3.org/TR/proximity/