usecases.bs

<pre class="metadata">
Title: Sensor Use Cases
Status: ED
Level: 1
ED: https://w3c.github.io/sensors/
Shortname: generic-sensor-use
TR: http://www.w3.org/TR/generic-sensor/
Editor: Tobie Langel 78102, Intel Corporation, tobie@sensors.codespeaks.com
Group: dap
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.
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
!Issue Tracking: <a href="https://github.com/w3c/sensors/milestones/Level%201">Level 1 Issues</a>
Boilerplate: omit issues-index, omit conformance
</pre>

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

Sensor data is increasingly used in Web application development, especially on mobile devices where new sensors are added regularly. Exposing those to the Web has so far been both slow-paced and ad-hoc. The goal of the Generic Sensor API is to promote consistency across sensor APIs and increase the pace at which they can be Web applications by simplifying both the specification and implementation processes.

There are plenty of different kinds of sensors cattering to plenty more use cases with various performance requirements. The purpose of this document is to describe the minimum number of use cases in order to build an exhaustive list of all requirements with which to inform the design of a Generic Sensor API.


Note: Some of the examples and use cases in this document rely on sensors that have already been specified by this or other Working Groups. While the editor feels these would be great candidates for building atop the Generic Sensor API, their inclusion in this document does not imply that the relevant Working Groups have given their agreement to do so or a planning to.


Use Cases {#usecases}
=====================

Displaying the position of the user on a map in real time {#display-realtime}
---------------------

In this use case, the user's location is positioned on a map in real time using the device's default geolocation sensor. The users' position is represented on the map by a circle the size of which depends on the accuracy of the data provided by the geolocation sensor. When no signal is available, the circle is greyed-out.

An <a href="https://w3c.github.io/sensors/examples/realtime-positioning/index.html"> example</a>(best-viewed with a device equipped with a geolocation sensor). Its <a href="https://github.com/w3c/sensors/tree/gh-pages/examples/cached-data">source code</a> can be found in the same repository as this document.

<!--
    TODO Add screenshots
-->

Using the current Geolocation API [[!geolocation-API]], the application code to tap into the sensor looks like this:

<div class="example">
<pre highlight="js">
  function onsuccess(position) {
      var coords = [position.coords.latitude, position.coords.longitude];
      updateMap(null, coords, position.coords.accuracy);
  }

  function onerror(e) {
      updateMap(e);
  }

  navigator.geolocation.watchPosition(onsuccess, onerror, {
      enableHighAccuracy: true,
      maximumAge: 0,
      timeout: Infinity
  });
</pre>
</div>


Using the proposed Generic Sensor API, application level code looks like this:

<div class="example">
<pre highlight="js">
  var sensor = new GeolocationSensor({ accuracy: "low" });
  sensor.start();
  sensor.onchange = function(event) {
      var coords = [event.reading.latitude, event.reading.longitude];
      updateMap(null, coords, event.reading.accuracy);
  };
  sensor.onerror = function(event) {
      updateMap(event.error);
  };
  sensor.onstatechange = function(e) {
      console.log("STATE:", this.state)
  };
</pre>
</div>


###  Further improvements ### {#improvements}

It is worth noting that the current syntax of the Geolocation API doesn't allow for a number of performance optimizations that require awareness of domain constraints and/or application-level code.

In our particular example application, the frequency at which the Gelocation API must be queried and its precision requirements vary greatly depending on the zoom factor of the map and the speed at which the user is driving.

The more zoomed out we are, the lower our accuracy and frequency requirments become.

The faster the user is moving (for example if they are driving a car), the higher the frequency requirements (as per the <a href="https://en.wikipedia.org/wiki/Nyquist%E2%80%93Shannon_sampling_theorem"> Nyquist–Shannon sampling theorem </a>).


### Requirements ### {#requirements}



Relying on cached data in a battery- or CPU-contrained environment {#caching}
-----------------


Head-tracking {#head-tracking}
---------------


Turn by turn navigation {#turn-navigation}
------------------


Pedometer {#pedometer}
--------------

Issue(12):


Promimity sensors {#proximity}
-------------


Security and Privacy Considerations {#security-and-privacy}
===================================

There are no specific security and privacy considerations
beyond those described in the Generic Sensor API [[!GENERIC-SENSOR]].