--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/sensor-api/Overview.html Fri Mar 09 15:25:58 2012 -0800
@@ -0,0 +1,498 @@
+<!DOCTYPE html>
+<html>
+ <head>
+ <title>Sensor API Specification</title>
+ <meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
+ <script src='http://dev.w3.org/2009/dap/ReSpec.js/js/respec.js' class='remove'></script>
+ <script src='http://dev.w3.org/2009/dap/ReSpec.js/js/sh_main.min.js' class='remove'></script>
+ <script src="http://dev.w3.org/2009/dap/ReSpec.js/js/lang/sh_javascript_dom.min.js" class='remove'></script>
+
+ <script class='remove'>
+ var respecConfig = {
+ specStatus: "ED",
+ shortName: "sensor",
+ publishDate: "2012-03-09",
+ //previousPublishDate: "2011-06-02",
+ previousMaturity: "WD",
+ edDraftURI: "http://dvcs.w3.org/hg/dap/raw-file/tip/sensor-api/Overview.html",
+ // lcEnd: "2009-08-05",
+ editors: [
+ {name: "Dzung D Tran", company: "Intel"},
+ {name: "José Manuel Cantera Fonseca", company: "Telefónica"}
+ ],
+ inlineCSS: true,
+ noIDLIn: true,
+ extraCSS: ["http://dev.w3.org/2009/dap/ReSpec.js/css/respec.css"],
+ wg: "Device APIs Working Group",
+ wgURI: "http://www.w3.org/2009/dap/",
+ wgPublicList: "public-device-apis"
+ };
+ </script>
+
+ <style>
+ .event {
+ font-family: monospace;
+ color: #459900;
+ }
+ </style>
+ </head>
+ <body>
+ <section id='abstract'>
+ This specification defines a generic API for getting access to information provided by sensors available from a hosting device.
+ </section>
+
+<!--***************************************Sensors***********************************************-->
+ <section>
+ <h2>Introduction</h2>
+ <p>This section is non-normative</p>
+ <p>This specification defines an API that allows application code to obtain information given by the various
+ sensors available on a hosting device. The information provided through this API is
+ raw sensor data. The specification is aimed at covering
+ well-known sensors that are commonly found in devices.
+ The API is extensible, allowing integration of vendor or external specific sensors.</p>
+
+ <section>
+ <p>The following code snippet illustrates how to monitor sensor data, for instance the ambient temperature:</p>
+ <pre class="example sh_javascript_dom">
+ var sensorCnx = new SensorConnection('Temperature');
+ sensorCnx.addEventListener('sensordata', function(e) {
+ if(e.data > 20.0) {
+ window.console.log('Temperature is too high!!!!');
+ }
+ } );
+
+ var watchOptions = { interval: (15 * 60 * 1000) };
+ sensorCnx.startWatch(watchOptions);
+ </pre>
+
+ <p>The following code snippet illustrates how to discover all sensors of type 'Temperature' that are available from the device:</p>
+ <pre class="example sh_javascript_dom">
+ var sensorReq = navigator.findSensors('Temperature');
+
+ sensorReq.onsuccess = function() {
+ for(var count = 0; count < this.result.length; count++) {
+ window.console.log("Discovered: " + this.result[count].name);
+ }
+ }
+
+ sensorReq.onerror = function() {
+ window.console.error(this.error.code);
+ }
+ </pre>
+
+ </section>
+ </section>
+
+<section id='conformance'>
+ <p>
+ This specification defines conformance criteria that apply to a single product: the
+ <dfn id="ua">user agent</dfn> that implements the interfaces that it contains.
+ </p>
+ <p>
+ Implementations that use ECMAScript to implement the APIs defined in this specification MUST implement
+ them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification
+ [[!WEBIDL]], as this specification uses that specification and terminology.
+ </p>
+ <p>
+ A conforming implementation is required to implement all fields defined in this specification.
+ </p>
+</section>
+
+<section>
+ <h2>Security and Privacy Considerations</h2>
+ <p>A conforming implementation of this specification MUST provide a mechanism that protects the user's privacy and this mechanism should ensure that
+ no sensitive information is made available through this API without the user's express permission. User agents MUST acquire permission through a user interface,
+ unless they have prearranged trust relationships with users. </p>
+</section>
+
+<section id="discovery">
+ <h2>Sensor Discovery</h2>
+ <section>
+ <div class='idl' title='Navigator implements SensorManager'></div>
+ </section>
+
+ <section>
+ <h3><a>SensorManager</a></h3>
+ This is an asynchronous API that returns without blocking the calling thread.
+ <p>
+ This interface allows applications to discover what sensors are available from the device.
+ The sensor information is acquired by calling platform native sensor interfaces, creating a list of
+ Sensor objects, and populating that object with appropriate data accordingly.
+ </p>
+
+ <dl title='[NoInterfaceObject] interface SensorManager' class='idl'>
+ <dt>SensorRequest findSensors(DOMString type)</dt>
+ <dd>
+ <p>When invoked the user agent MUST immediately return a <a>SensorRequest</a> instance with the <a>readyState</a> set
+ to <a>processing</a>, which does not initially contain any information about the result of the operation. If
+ the user permissions are ok then the UA MUST queue a new <em>listSensors process</em> that will call platform native
+ sensor interfaces to fill a list of <a>Sensor</a> objects that will contain metadata about the sensors hosted
+ by the device. The argument <a>type</a> MUST be set to the type of sensor to be searched for.
+ <p>If user permissions are not ok the process MUST finish and an error event on the request MUST be fired.
+ <p>
+ Once the <em>listSensors process</em> finishes without error, the <a>onSuccess</a> event is fired on the request and
+ the information becomes available through the properties of the <a>SensorRequest</a> instance. If an error occurs while
+ performing the operation, the <a>onError</a> event is fired and the <a>error</a> is set to the error code. If no matching
+ sensors are found, this is NOT reported as an error but just an empty list of sensors. In either
+ case the the <a>readyState</a> is set to <code>done</code> to indicate the discovery process has completed</p>
+ </dd>
+ </dl>
+ </section>
+
+ <section>
+ <h3><a>SensorRequest</a></h3>
+ This interface provides means to access results of asynchronous sensor discovery requests.
+
+ <dl title='[NoInterfaceObject] interface SensorRequest' class='idl'>
+ <dt>readonly attribute <a>DOMError</a> error</dt>
+ <dd>
+ When the readyState is done and an error exception has been raised, MUST return the error of
+ the request. This is null when no error occurred. When the readyState is processing,
+ MUST throw a <code>DOMException</code> of type <a>InvalidStateError</a>.
+ <dl class="getraises" title="DOMException">
+ <dt><a>InvalidStateError</a></dt>
+ <dd>Thrown when this attribute was read when the readyState is processing.</dd>
+ </dl>
+ </dd>
+ <dt>attribute Function onerror</dt>
+ <dd>
+ The event handler for the error event
+ </dd>
+ <dt>attribute Function onsuccess</dt>
+ <dd>
+ The event handler for the success event
+ </dd>
+ <dt>
+ readonly attribute DOMString readyState</dt>
+ </dt>
+ <dd>Represents the status of the request. It MUST be set to one of the following:
+ <ul>
+ <li><code>processing</code>. If the discovery process is still pending.</li>
+ <li><code>done</code>. If the discovery process is completed. </li>
+ </ul>
+ <dt>readonly attribute Sensor[] result</dt>
+ <dd>
+ When the <a>readyState</a> is done, MUST return list of sensors discovered.
+ This is undefined when the request resulted in an error. When the <a>readyState</a> is processing, MUST throw a <a><code>InvalidStateError</code></a>.
+ <dl class="getraises" title="DOMException">
+ <dt><a>InvalidStateError</a></dt>
+ <dd>Thrown when this attribute was read when the <a title="request done">done</a> flag was set to false.</dd>
+ </dl>
+ </dl>
+
+ </section>
+</section>
+
+<section>
+ <h2>Sensor Metadata</h2>
+ <section>
+ <h3><a>Sensor</a></h3>
+ The <code>Sensor</code> object contains different attributes that provide sensor metadata.
+ <dl title='[NoInterfaceObject] interface Sensor' class='idl'>
+ <dt>readonly attribute short? minDelay</dt>
+ <dd>
+ It MUST return the minimum delay allowed between two sensor data events in microseconds or zero if only sensor
+ data events are dispatched when there is a change in the measured magnitude.
+ <code>null</code> MUST be returned if this parameter is not known to the implementation.
+ </dd>
+ <dt>readonly attribute DOMString name</dt>
+ <dd>
+ It MUST return an unique identifier for the sensor.
+ </dd>
+ <dt>readonly attribute short? minRange</dt>
+ <dd>
+ It MUST return the minimum range of the sensor in the sensor's unit or <code>null</code> if it is not known.
+ </dd>
+ <dt>readonly attribute short? maxRange</dt>
+ <dd>
+ It MUST return the maximum range of the sensor in the sensor's unit or <code>null</code> if it is not known.
+ </dd>
+ <dt>readonly attribute float? resolution</dt>
+ <dd>
+ It MUST return the sensor's resolution of the sensor in unit of measurement or <code>null</code>
+ if this parameter is not known to the implementation.
+ </dd>
+ <dt>readonly attribute DOMString type</dt>
+ <dd>
+ It MUST return the sensor type. See table below for a list sensor types defined by this specification
+ </dd>
+ </dl>
+ </section>
+</section>
+
+ <section>
+ <h2>Sensor Data</h2>
+<section>
+ <h3>SensorConnection Interface</h3>
+ The SensorConnection object is an event target that MUST be used to request a connection to a sensor of a
+ specified type on the hosting device. The sensor connection is acquired by calling platform native sensor interfaces.
+ <dl title='[Constructor(DOMString type),Constructor(SensorOptions options)] interface SensorConnection : EventTarget' class='idl'>
+ <dt>readonly attribute Sensor sensor </dt>
+ <dd>
+ Represents the metadata of the sensor that is currently connected to this event target.
+
+ <dl class="getraises" title="DOMException">
+ <dt><a>InvalidStateError</a></dt>
+ <dd>Thrown when this attribute was read and the sensor connection was in the "new" state.</dd>
+ </dl>
+ </dd>
+
+ <dt>readonly attribute DOMString status</dt>
+ <dd>
+ Represents the current status of the event target. The status MUST be set to one of the
+ following:
+ <ul>
+ <li><code>new</code>. The object has been instantiated but a connection to the sensor has not been established yet. </li>
+ <li><code>open</code>. All the infrastructure to get sensor data is ready.</li>
+ <li><code>watching</code>. The sensor is under monitoring.</li>
+ <li><code>disconnected</code>. The connection with the sensor has been lost.</li>
+ <li><code>error</code>. An error has occured</li>
+ </ul>
+ </dd>
+
+ <dt>readonly attribute DOMError error</dt>
+ <dd>Represents the current error of the event target. This is null when no error occurred.</dd>
+
+ <dt>attribute Function? onerror</dt>
+ <dd>Allows to set an event handler that will be invoked when the sensor connection is in error</dd>
+
+ <dt>attribute Function? onsensordata</dt>
+ <dd>Allows to set an event handler that will be invoked when new sensor data is available</dd>
+
+ <dt>attribute Function? onstatuschange</dt>
+ <dd>Allows to set an event handler that will be invoked when connection status change</dd>
+
+ <dt>attribute Function? oncalibneed</dt>
+ <dd>Allows to set an event handler that will be invoked when the sensor needs calibration</dd>
+
+ <dt>void read()</dt>
+ <dd>
+ When invoked the user agent MUST run the following steps:
+ <ol>
+ <li>If the status is other than <code>open</code> or <code>watching</code> an ILLEGAL_STATE exception MUST be thrown. </li>
+ <li>Otherwise the user agent MUST queue a task <var>TRead</var> to perform a reading from the sensor and then return immediately. </li>
+ <li> Once <var>TRead</var> has finished successfully, the implementation MUST queue a task to fire a
+ <a>SensorDataEvent</a> with:
+ <ul>
+ <li><code>data</code> field equal to the values read from the sensor.</li>
+ <li><code>isWatchPoint</code> field equal to 'false'</li>
+ </ul>
+ <li>If <var>TRead</var> fails Queue a task to fire a simple event named error at the <a>SensorConnection</a>.</li>
+ </ol>
+ </dd>
+
+ <dt>void startWatch(SensorWatchOptions watchOptions)</dt>
+ <dd>
+ <p>When called the user agent MUST run the following steps:
+ <ol>
+ <li>If <a>status</a> is other than <code>open</code> an ILLEGAL_STATE exception MUST be thrown</li>
+ <li>If <a>status</a> is <code>open</code> then run the following sub-steps: </li>
+ <ol>
+ <li>Queue a task <var>TWatch</var> in charge of invoking the platform native interfaces to start monitoring sensor values
+ in accordance with the parameters specified as part of <a>SensorWatchOptions</a> argument. Then, return immediately to the caller. </li>
+ <li>If <var>TWatch</var> succeeds, the <a>status</a> attribute MUST be set to the <code>watching</code> value. Queue a task to fire a simple event named
+ <code>statuschange</code> at the <a>SensorConnection</a></li>
+ <li>If <var>TWatch</var> fails then Queue a task to fire a simple event named error at the <a>SensorConnection</a>.</li>
+ </ol>
+ </ol>
+ <p>Everytime the platform monitoring mechanism notifies of a new sensor value the user agent MUST queue a task to fire a
+ <a>SensorDataEvent</a> with:
+ <ul>
+ <li><code>data</code> field equal to the values read from the sensor</li>
+ <li><code>isWatchPoint</code> field equal to 'true'
+ </ul>
+ </dd>
+
+ <dt>void endWatch()</dt>
+ <dd>
+ When this method is called the user agent MUST run the following steps:
+ <ol>
+ <li>If status is other than <code>watching</code> an ILLEGAL_STATE exception MUST be thrown.</li>
+ <li>If status is <code>watching</code> then the following substeps MUST be done:
+ <ol>
+ <li>Invoke platform native interfaces to notify the end of the monitoring.</li>
+ <li>If the invocation succeeds, the <a>status</a> attribute MUST be set to the <code>open</code> value
+ and the control MUST be returned to the caller. Finally, Queue a task to fire a simple event named
+ <code>statuschange</code> at the <a>SensorConnection</a>. </li>
+ <li>If the invocation fails Queue a task to fire a simple event named error at the <a>SensorConnection</a>.</li>
+ </ol>
+ </ol>
+ </dd>
+ </dl>
+ <dl>
+
+ <dt>[Constructor(SensorOptions options)]</dt>
+ <dd>Constructs a new <a>SensorConnection</a>. when invoked the user agent MUST run the following steps:
+ <ol>
+ <li>Let <var>_sensor</var> be the target sensor to be connected to. If none of the dictionary members are defined then raise an instantiation exception. </li>
+ <li>If the dictionary member <code>name</code> is not defined
+ then <var>_sensor</var> MUST correspond to the default sensor type specified by the <code>type</code> member.
+ Otherwise <var>_sensor</var> MUST be assigned to a sensor of the specified <code>type</code> and whose identifier
+ is equal to the <code>name</code> member. </li>
+ <li>Check if the sensor identified by <var>_sensor</var> is available and ready to be connected</li>
+ <li>If the sensor exists, is available and user permissions are ok, then instantiate a <code>SensorConnection</code> object and set its status to 'open'. </li>
+ <li>If user permissions are needed then instantiate the SensorConnection object, set its status to 'new' and prompt the user in a user-agent-specific manner for permission.
+ <p>Once the user gives permission set status to 'open'. If the user does not give permission set status to 'error' and fire an error event.
+ </li>
+ <li>If the sensor is not available or does not exist raise an instantiation exception (tbd). </li>
+ </ol>
+ <p>Implementations MAY support other connection options as part of the <a>SensorOptions</a> interface</p>
+ </dd>
+
+ <dt>[Constructor(DOMString type)]</dt>
+ <dd>Constructs a new <a>SensorConnection</a> by passing a sensor type. This is a convenient function for the more general function described above.
+ </dd>
+
+ <p>These constructors MUST be visible when the script's global object is either a <code>Window</code> object
+ or an object implementing the <code>WorkerUtils</code> interface.</p>
+ </dl>
+
+</section>
+
+<section>
+ <h3><a>SensorWatchOptions Interface</a></h3>
+ <dl title='dictionary SensorWatchOptions' class='idl'>
+ <dt>attribute double threshold</dt>
+ <dd>
+ This attribute only applies to sensors that provide single value readings. It indicates that a data event MUST only be raised when the
+ sensor value crosses the specified threshold (in either direction).
+ <p class="issue">
+ This attribute is likely to be revisited to support these use cases:<br>
+
+ - Low and high thresholds<br>
+ - Ranges [10,20] (10,20] .... <br>
+ - Thresholds that apply to the different data components of a sensor, for instance x,y,z in the case of accelerometer.
+ </p>
+ </dd>
+ <dt>attribute double interval</dt>
+ <dd>
+ The <code>interval</code> attribute represents the monitorization interval at which data SHOULD be obtained
+ from the underlying sensor hardware and MUST be expressed in milliseconds. The caller
+ should be aware that setting a value too small can adversely affect the battery life. If the interval is
+ set to zero, then the implementation MUST return sensor data only when there is a change since the last acquisition.
+ </dd>
+ </dl>
+</section>
+
+<section>
+
+ <h3><a>SensorOptions</a> Interface</h3>
+ <dl title='dictionary SensorOptions' class='idl'>
+ <dt>attribute DOMString type</dt>
+ <dd>
+ Sensor type for which a connection is requested
+ </dd>
+ <dt>attribute DOMString name</dt>
+ <dd>
+ Sensor name for which a connection is requested
+ </dd>
+ </dl>
+</section>
+
+<section>
+ <h3><a>SensorDataEvent</a> Interface</h3>
+ <p class="note">This section will be changed to comply with the DOM4 Event interfaces</p>
+ <dl title='interface SensorDataEvent : Event' class='idl'>
+ <dt>readonly attribute any data</dt>
+ <dd>This attribute represents the raw data provided by the sensor. The specific type depends on the <a>type</a> of the sensor.
+ See <a href="datatypes"></a> for implementation requirements for this attribute depending on the type of sensor.
+ </dd>
+ <dt>readonly attribute DOMString accuracy</dt>
+ <dd>This attribute MUST return an enumerated value that gives an indication of the accuracy of the sensor data. The allowed values are:
+ <ul>
+ <li><code>high</code> - This sensor is reporting data with maximum accuracy</li>
+ <li><code>medium</code> - This sensor is reporting data with average accuracy, calibration with the environment may improve readings</li>
+ <li><code>low</code> This sensor is reporting data with low level of accuracy, calibration with the environment is needed</li>
+ <li><code>unreliable</code> - This sensor is reporting data that can't be trusted, calibration is needed. </li>
+ </ul>
+ </dd>
+ <dt>readonly attribute double timestamp</dt>
+ <dd>
+ The time in nanosecond at which the sensor data was read.
+ </dd>
+ <dt>readonly attribute boolean isWatchPoint</dt>
+ <dd>It is a boolean that denotes if this is a watch point. The only admissible values for this attribute are:
+ <ul>
+ <li><code>false</code>. The event was raised due to onetime read operation</li>
+ <li><code>true</code>. The event was raised due to a recurring watch operation</li>
+ </ul>
+ </dd>
+ <dt>void initSensorDataEvent(in DOMString type,
+ in boolean bubbles,
+ in boolean cancelable,
+ in boolean isWatchPoint,
+ in double timestamp,
+ in DOMString accuracy,
+ in any data)
+ </dt>
+ <dd>
+ Initializes a <a>SensorDataEvent</a> created through the <code>DocumentEvent</code> interface.
+ </dd>
+ </dl>
+
+ <p class="note">A section describing all the events defined by the API might be added for next draft. </p>
+
+</section>
+
+ </section>
+
+<section id="datatypes">
+ <h2>Sensor Type Definitions</h2>
+ This section specifies some base sensor types and related data formats.
+ <section>
+ <h3>Sensor Types and Related Data Formats</h3>
+ <p>This section specifies a base set of sensor types and related data formats. If the UA supports these sensor types, they MUST use
+ this data format definition. Any UA can also extend its support to other sensors that are
+ defined elsewhere outside of this specification. It is implementation dependent how to register and support new sensor types.</p>
+ <p>For the sensor types defined here, an implementation MUST set the specific type of the <code>SensorDataEvent.data</code>
+ and <code>SensorDataEvent.type</code> attributes in accordance with the following table:
+ <table class="simple">
+ <thead>
+ <tr>
+ <th>Sensor Type</th>
+ <th>Description</th>
+ <th>Data Type</th>
+ <th>Units</th></tr>
+ </thead>
+ <tbody>
+ <tr><td>Temperature</td><td>A ambient temperature sensor</td><td>double</td><td>degree Celsius (ºC)</td></tr>
+ <tr><td>AtmPressure</td><td>A pressure sensor</td><td>double</td><td>kiloPascal (kP)</td></tr>
+ <tr><td>RelHumidity</td><td>A releative humidity sensor</td><td>double</td><td>percentage</td></tr>
+ <tr><td>AmbientLight</td><td>A light sensor</td><td>double</td><td>Lux</td></tr>
+ <tr><td>AmbientNoise</td><td>A ambient noise sensor</td><td>double</td><td>dbA</td></tr>
+ <tr><td>MagneticField</td><td>A magnetic field sensor</td><td>MagneticFieldData</td><td>micro-Tesla (uTesla)</td></tr>
+ <tr><td>Proximity</td><td>A proximity sensor</td><td>double</td><td>centimetres (cm)</td></tr>
+ </tbody>
+ </table>
+ </p>
+ </section>
+
+ <section><h4>The MagneticFieldData interface</h4>
+ <dl title='interface MagneticFieldData' class='idl'>
+ <dt>readonly attribute double x</dt>
+ <dd>
+ ambient magnetic field in X
+ </dd>
+ <dt>readonly attribute double y</dt>
+ <dd>
+ ambient magnetic field in Y
+ </dd>
+ <dt>readonly attribute double z</dt>
+ <dd>
+ ambient magnetic field in Z
+ </dd>
+ </dl>
+ </section>
+
+ </section>
+
+<section>
+
+ <section class='appendix'>
+ <h2>Acknowledgements</h2>
+ <p>
+ WAC Ipanema Device APIs Lightweight Participation WG, in particular Bryan Sullivan, Balaji N.V., and Kaushik Das.
+ </p>
+ </section>
+ </body>
+</html>