--- a/sensor-api/Overview.html Mon Apr 09 22:35:19 2012 -0700
+++ b/sensor-api/Overview.html Tue May 08 20:58:05 2012 -0700
@@ -11,14 +11,14 @@
var respecConfig = {
specStatus: "ED",
shortName: "sensor",
- publishDate: "2012-04-09",
+ publishDate: "2012-05-08",
//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"}
+ // {name: "José Manuel Cantera Fonseca", company: "Telefónica"}
],
inlineCSS: true,
noIDLIn: true,
@@ -38,29 +38,24 @@
</head>
<body>
<section id='abstract'>
- This specification defines an API for getting access to information provided by sensors available from a hosting device.
+ This specification defines several new DOM events that provide information about the physical sensors of 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. </p>
+ <p>This specification provides several new DOM events that allow application code to obtain information given by the various
+ sensors available on a hosting device. The information provided through this DOM event is
+ raw sensor data. The specification is aimed at covering well-known sensors that are commonly found in devices. </p>
+ <p>There will be a DOM event for each of the sensor type which supplies the physical raw sensor data for that sensor type.
+ </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">
TDB
</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">
- TBD
- </pre>
-
</section>
</section>
@@ -77,210 +72,75 @@
</section>
<section>
+ <h2>Scope</h2>
+ <p>This section is non-normative</p>
+ <p>This specification is limited to provide DOM events for retrieving raw sensor information for physical sensors of a hosting device.
+ The scope of this specification does not include providing utilities to manipulate this data, such as sensor fusing or tranformation libraries.
+ Nor does it include direct control of these sensors.</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="sensormanager">
- <h2>Sensor Manager</h2>
- <section>
- <div class='idl' title='Navigator implements SensorManager'></div>
- </section>
-
+<section id='Description'>
+ <h2>Description</h2>
<section>
- <h3><a>SensorManager</a></h3>
- This is an asynchronous API that returns without blocking the calling thread. This interface provides interfaces to applications for making sensor requests.
-
- <dl title='[NoInterfaceObject] interface SensorManager' class='idl'>
- <dt>void cancelWatchpoint(<a>SensorRequest</a> request)</dt>
- <dd>
- When this method is called the user agent MUST check the argument <code>request</code> versus its current pending requests
- and do the following:
- <ol>
- <li>If the current request is other than <code>WatchPoint</code> an ILLEGAL_STATE exception MUST be thrown.</li>
- <li>If the current request is <code>WatchPoint</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 then return.</li>
- <li>If the invocation fails then an exception MUST be thrown.</li>
- </ol>
- </ol>
- </dd>
- <dt>void connectSensor(<a>SensorRequest</a> request, SensorSuccessCallback onSuccess, optional callback onFailure)</dt>
- <dd>
- <p>When invoked the user agent asks the user if the sensor data should be granted to the requesting application.
- UAs may provide arrangements for users to save their response, but must always allow the user to change any saved
- permission.</p>
- <p>If user permissions are not ok, the request must finish and an error event must be fired.
- Otherwise the request uses the <a>SensorRequest</a> instance data to invoke the platform native interfaces to start
- monitoring sensor values in accordance with the parameters specified as part of <a>SensorRequest</a> argument.
- It then returns immediately and subsequently, the <code>onSuccess</code> event is fired on the request
- when the information becomes available through the properties of the <a>SensorData</a> instance. If an error occurs
- while performing the operation, the <code>onFailure</code> event is fired and the error is set to the error string.</p>
- </dd>
- </dl>
- </section>
- <section>
- <h3>SensorSuccessCallback</h3>
- The success callback passed to <a>connectSensor</a> must provide the signature:
- <dl title='[NoInterfaceObject] interface SensorSuccessCallback' class='idl'>
- <dt>void onSuccess(<a>SensorData</a> data)</dt>
- <dd>
- The <code>onSuccess</code> callback is raised with an <a>SensorData</a> object when there is sensor data available.
- </dd>
- </dl>
- </section>
+ <h3><a>Sensor DOM Events</a></h3>
+ User agents implementing this specification must provide a new DOM event for each of the sensor types as specified in section 6. The sensor will turn on when
+ the listener is added and turn off when the last event is removed. The corresponding event must be fire on the <code>window</code> object when there is a change
+ in the sensor data. Registration for, and firing of the event must follow the usual behavior of DOM Events. If the UA does not support the sensor of interest
+ then the event will not be fired.
+ <p>User agents must also accept an event handler for addEventListener with the following interface:</p>
- <section>
- <h3>SensorFailureCallback</h3>
- The failure callback passed to <a>connectSensor</a> must provide the signature:
- <dl title='[NoInterfaceObject] interface SensorFailureCallback' class='idl'>
- <dt>void onFailure(DOMString error)</dt>
- <dd>
- The <code>onFailure</code> callback is raised with a error string when an error occurs during the <a>connectSensor</a> process.
- UAs should provide the following error strings:
- <ol>
- <li>"sensor not available"</li>
- <li>"sensor not responding"</li>
- <li>"invalid parameters"</li>
- </ol>
- </dd>
- </dl>
- </section>
-
+ The event handler passed to <code>addEventListener</code> must provide the signature:
+ <dl title='[NoInterfaceObject] interface SensorCallback' class='idl'>
+ <dt>void ondata(double value, double min, double max)</dt>
+ <dd>
+ The <code>ondata</code> callback is raised when there is sensor data to report.
+ The <code>value</code> is the sensor data as specified in section 6. The <code>min</code> is the minimum value in the range the sensor detects,
+ if available. If not available, a value of zero must be returned.
+ The <code>max</code> is maximum value in the range the sensor detects, if available.
+ If not available, a value of zero must be returned.
+ </dd>
+ </dl>
+ </section>
</section>
-<section id="sensorrequest">
- <h2>Sensor Request</h2>
- <section>
- <div class='idl' title='SensorManager implements SensorRequest'></div>
- </section>
-
- <section>
- <h3><a>SensorRequest</a></h3>
- This interface provides means to specify the current request sensor of interest.
-
- <dl title='[NoInterfaceObject] interface SensorRequest' class='idl'>
- <dt>readonly attribute <a>DOMString</a> action</dt>
- <dd>
- Represents the action for the request. The string must not be empty, or the constructor must throw an exception.
- The string must be one of:
- <ol>
- <li>"OneTime"</li>
- <li>"WatchPoint"</li>
- </ol>
- <p>If the action is <code>OneTime</code>, there is a single response returned to the callback and the connection to the sensor is
- cancelled automatically. If the action is <code>WatchPoint</code>, then repeated data samples are sent to the callback until
- <code>cancelWatchpoint</code> is called or the page unloads.</p>
- </dd>
- <dt>readonly attribute <a>DOMString</a> type</dt>
- <dd>
- Represents the sensor type of the request. The string must not be empty, or the constructor must throw an exception.
- The type MUST be one of the types specified in section <a>Sensor Type Definitions</a>
- </dd>
- <dt>attribute double threshold[]</dt>
- <dd>
- It indicates that a data event MUST only be raised when the sensor value crosses any of the threshold values in the
- array (in either direction).
- </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>
-
-<section id="sensordata">
- <h2>Sensor Data</h2>
- <section>
- <h3><a>SensorData</a></h3>
- This interface provides means to access the sensor data for the current request sensor of interest. This object will be returned
- in the <code>onSuccess</code> callback of the connectSensor interface.
-
- <dl title='[NoInterfaceObject] interface SensorData' class='idl'>
- <dt>readonly attribute <a>DOMString</a> action</dt>
- <dd>
- Same as in <a>SensorManager</a> request.
- </dd>
- <dt>readonly attribute <a>DOMString</a> type</dt>
- <dd>
- Same as in <a>SensorManager</a> request.
- </dd>
- <dt>readonly attribute double accuracy</dt>
- <dd>
- Accuracy of measurement in term of data type specified below section, if available.
- If not available, a value of zero must be returned
- </dd>
- <dt>readonly attribute double minInRange</dt>
- <dd>
- Minimal value in the range the sensor detects, if available.
- If not available, a value of zero must be returned.
- </dd>
- <dt>readonly attribute double maxInRange</dt>
- <dd>
- Maximum value in the range the sensor detects, if available.
- If not available, a value of zero must be returned
- </dd>
- <dt>readonly attribute double timestamp</dt>
- <dd>
- Time in nanoseconds when the sensor was read, if available.
- If not available, a value of zero must be returned
- </dd>
- <dt>readonly attribute DOMString name</dt>
- <dd>
- Friendly name of the sensor, if available.
- If not available, an empty string must be returned
- </dd>
- <dt>readonly attribute double values[]</dt>
- <dd>
- Sensor data values as specified in the section below.
- </dd>
- </dl>
- </section>
-</section>
-
-<section id="datatypes">
- <h2><a>Sensor Type Definitions</a></h2>
- This section specifies 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. UAs may choose which sensors they wish to support.
- <p>For the sensor types defined here, an implementation MUST set the specific type of the <code>SensorRequest.type</code>
- attribute in accordance with the following table:
+<section id='datatypes'>
+ <h2>DOM Sensor Events and Related Data Formats</h2>
+ <p>This section specifies a base set of DOM sensor events and related data formats. If the UA supports these sensor types, it MUST use
+ this data format definition. UAs may choose which sensors they wish to support. A UA MUST fire the DOM Sensor Event for sensors it
+ supports in accordance with the following table::</p>
<table class="simple">
<thead>
<tr>
+ <th>DOM Sensor Event</th>
<th>Sensor Type</th>
- <th>Description</th>
<th>Data Type</th>
<th>Units</th></tr>
</thead>
<tbody>
- <tr><td>AmbientTemperature</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>DevMagneticField</td><td>A magnetic field sensor</td><td>array of three doubles</td><td>micro-Tesla (uTesla)</td></tr>
- <tr><td>DevProximity</td><td>A proximity sensor</td><td>double</td><td>centimetres (cm)</td></tr>
+ <tr><td>devicetemperature</td><td>A ambient temperature sensor</td><td>double</td><td>degree Celsius (ºC)</td></tr>
+ <tr><td>devicepressure</td><td>A pressure sensor</td><td>double</td><td>kiloPascal (kP)</td></tr>
+ <tr><td>devicehumidity</td><td>A releative humidity sensor</td><td>double</td><td>percentage</td></tr>
+ <tr><td>devicelight</td><td>A light sensor</td><td>double</td><td>Lux</td></tr>
+ <tr><td>devicenoise</td><td>A ambient noise sensor</td><td>double</td><td>dbA</td></tr>
+ <tr><td>deviceproximity</td><td>A proximity sensor</td><td>double</td><td>centimetres (cm)</td></tr>
</tbody>
</table>
</p>
- </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>
+ <p>WAC Ipanema Device APIs Lightweight Participation WG, in particular Bryan Sullivan, Balaji N.V., and Kaushik Das.</p>
+ <p>Mozilla's <a href="http://dougturner.wordpress.com/2012/03/26/device-light-sensor/">Device Proximity and Light Sensor APIs</a>, in particular Doug Turner</p>
+ <p>José Manuel Cantera Fonseca from Telefónica as one of the original contributors and editors to this specification.</p>
+ <p>Marcos Caceres from W3C, Wayne Carr and Sakari Poussa from Tizen</p>
</section>
</body>
</html>