- From: Dzung Tran via cvs-syncmail <cvsmail@w3.org>
- Date: Fri, 11 Nov 2011 17:13:06 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/system-info
In directory hutz:/tmp/cvs-serv19417/system-info
Modified Files:
Sensors.html
Log Message:
Updated with f2f and from workgroup
Index: Sensors.html
===================================================================
RCS file: /sources/public/2009/dap/system-info/Sensors.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- Sensors.html 7 Oct 2011 14:22:54 -0000 1.5
+++ Sensors.html 11 Nov 2011 17:13:04 -0000 1.6
@@ -11,14 +11,14 @@
var respecConfig = {
specStatus: "ED",
shortName: "sensor",
- publishDate: "2011-10-07",
+ publishDate: "2011-11-10",
//previousPublishDate: "2011-06-02",
previousMaturity: "WD",
- edDraftURI: "http://dev.w3.org/2009/dap/sensors.html",
+ edDraftURI: "http://dev.w3.org/2009/dap/Sensors.html",
// lcEnd: "2009-08-05",
editors: [
{name: "Dzung D Tran", company: "Intel"},
- {name: "Jose Manuel Cantera Fonseca", company: "Telefonica - WAC"}
+ {name: "José Manuel Cantera Fonseca", company: "Telefónica"}
],
inlineCSS: true,
noIDLIn: true,
@@ -38,10 +38,7 @@
</head>
<body>
<section id='abstract'>
- This specification defines a generic API for getting access to information provided by the physical sensors available on a hosting device.
- </section>
- <section class='introductory'>
- <h2>Introduction</h2>
+ This specification defines a generic API for getting access to information provided by sensors available from a hosting device.
</section>
<!--***************************************Sensors***********************************************-->
@@ -49,16 +46,16 @@
<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
- physical sensors available on the hosting device. The information provided through this API is
+ 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.
- Nonetheless, the API is extensible, allowing to integrate vendor specific sensors if necessary .</p>
+ Nonetheless, the API is extensible, allowing to integrate vendor or external specific sensors if necessary .</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 sensorConnection = new navigator.sensor.Connection('Temperature');
- sensorConnection.addEventListener('sensordata', function(e) {
+ var sensorCnx = new SensorConnection('Temperature');
+ sensorCnx.addEventListener('sensordata', function(e) {
if(e.data > 20.0) {
window.console.log('Temperature is too high!!!!');
}
@@ -67,6 +64,22 @@
var watchOptions = { interval: (15 * 60 * 1000) };
session.startWatch(watchOptions);
</pre>
+
+ <p>The following code snippet illustrates how to discover all sensors available from the device:</p>
+ <pre class="example sh_javascript_dom">
+ var sensorReq = navigator.findSensors();
+
+ 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>
@@ -87,53 +100,110 @@
<section>
<h2>Security and Privacy Considerations</h2>
- <p class="note">To be defined</p>
+ <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>
- <h2>SensorManager</h3>
-
- <div class="issue">
- This interface is still under discussion. The intention is to have basic support for discovery in the API.
- </div>
-
- <p>
- The SensorManager object is an event target that MUST be used to request a list of sensors that are available on the
- hosting 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>
+<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='interface SensorManager : EventTarget' class='idl'>
- <dt>Sensor[] listSensors(optional DOMString type)</dt>
- <dd>
- When invoked the user agent MUST run a <em>listSensors process</em> that will call platform native sensor interfaces
- to fill a list of <code>Sensor</code> objects that will contain sensors metadata.
- If the argument <code>type</code> is set, only sensors of the specified <code>type</code> MUST be returned. Otherwise it MUST
- be returned the entire list obtained initially.
- </dd>
-
- <dt>attribute Function? onsensoravailable</dt>
+ <dl title='[NoInterfaceObject] interface SensorManager' class='idl'>
+ <dt>SensorRequest findSensors(optional DOMString type)</dt>
<dd>
- Allows to set an event handler that will be invoked when a new sensor is available
+ <p>When invoked the user agent MUST immediately return a <a>SensorRequest</a> instance (with done flag set to false), 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 <code>Sensor</code> objects that will contain metadata about the sensors hosted by the device.
+ If the argument <code>type</code> is set, only sensors of the specified <code>type</code> MUST be obtained. </p>
+ <p>If user permissions are not ok the process must finish and an error event on the request with error code <code>PERMISSION_DENIED</code> MUST be fired.
+ <p>
+ Once the <em>listSensors process</em> finishes without error, an event is fired on the request, the done flag is set to true and the information becomes available through
+ the properties of the <a>SensorRequest</a> instance. If an error occurs while performing the operation,
+ the <a>readyState</a> is changed to <code>done</code>, the <a>error</a> is set to the code of the error, and a event with type error is fired at the request.</p>
+
+ <p>User Agents MAY run additional processes to discover remote sensors available in the current context.</p>
</dd>
- </dl>
+ </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 Sensor[] result</dt>
+ <dd>
+ When the done flag is true, getting this property MUST return list of sensors discovered.
+ This is undefined when the request resulted in an error. When the done flag is false, getting this property 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>
+
+ </dd>
+ <dt>readonly attribute SensorError error</dt>
+ <dd>
+ When the <a title="request done">done</a> flag is true, getting this property MUST return the error of
+ the request. This is null when no error occurred. When the <a title="request done">done</a> flag is false, getting this property
+ 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 <a title="request done">done</a> flag was set to false.</dd>
+ </dl>
+ </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 done flag is false.</li>
+ <li><code>done</code>. If the done flag is true. </li>
+ </ul>
+ </dd>
+ <dt>attribute Function onsuccess</dt>
+ <dd>
+ The event handler for the success event
+ </dd>
+ <dt>attribute Function onerror</dt>
+ <dd>
+ The event handler for the error event
+ </dd>
+ </dl>
+
+ </section>
</section>
<section>
- <h2>Sensor</h2>
+ <h2>Sensor Metadata</h2>
+ <section>
+ <h3><a>Sensor</a></h3>
The <code>Sensor</code> object contains different attributes that provide sensor metadata.
- <dl title='dictionary Sensor' class='idl'>
+ <dl title='[NoInterfaceObject] interface Sensor' class='idl'>
<dt>readonly attribute float? resolution</dt>
<dd>
It must return the sensor's resolution of the sensor in the sensor's unit or <code>null</code>
if this parameter is not known to the implementation.
</dd>
- <dt>readonly attribute int? minDelay</dt>
+ <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 int? range</dt>
+ <dt>readonly attribute short? range</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>
@@ -154,16 +224,24 @@
It must return a string that identifies the vendor of the sensor. <code>null</code> if this data is not available.
</dd>
</dl>
+ </section>
</section>
-
+
+ <section>
+ <h2>Sensor Data</h2>
<section>
- <h2>SensorConnection Interface</h2>
+ <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,optional DOMString name)] interface SensorConnection : EventTarget' class='idl'>
- <dt>readonly attribute Sensor sensor</dt>
+ <dl title='[Constructor(DOMString type),Constructor(SensorOptions options)] interface SensorConnection : EventTarget' class='idl'>
+ <dt>readonly attribute Sensor sensor </dt>
<dd>
- Represents the sensor type that is currently connected to this event target.
+ 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>
@@ -171,20 +249,27 @@
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 SensorError? error</dt>
+ <dd>The code attribute of a SensorError object must return the code for the error. 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? oncalibrationneeded</dt>
+ <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>
@@ -210,8 +295,10 @@
<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.</li>
+ <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>
@@ -232,46 +319,86 @@
<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.</li>
+ 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(DOMString type,optional DOMString name)]</dt>
- <dd>Constructs a new SensorConnection. 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 the parameter <code>name</code> is not defined
- then <var>_sensor</var> MUST correspond to the default sensor of the specified type.
- Otherwise <var>_sensor</var> MUST be assigned to a sensor of the specified type and whose identifier
- is equal to the name passed as parameter. </li>
- <li>Check if the sensor identified by <var>_sensor</var> is available and ready to be connected</li>
- <li>If the sensor is available instantiate a <code>SensorConnection</code> object and set its status to 'open'. </li>
- <li>If the sensor is not available raise an instantiation exception (tbd). </li>
- </ol>
+
+ <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' with error code to <code>PERMISSION_DENIED</code>.
+ </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>
- <h2>SensorWatchOptions Interface</h2>
- <dl title='interface SensorWatchOptions : Object' class='idl'>
+ <h3><a>SensorWatchOptions Interface</a></h3>
+ <dl title='dictionary SensorWatchOptions' class='idl'>
<dt>attribute double threshold</dt>
<dd>
- TBD
+ This attribute only applies to sensors that provide single value readings. It indicates that a data event MUST only be raised when
+ the sensor reaches a value below the specified threshold.
+ <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.
+ 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>
- <h2>SensorDataEvent Interface</h2>
+
+ <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">Once the spec progress 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>
@@ -290,8 +417,6 @@
<dt>readonly attribute double timestamp</dt>
<dd>
The time in nanosecond at which the sensor data was read.
- This value is relative to the timestamp of the first sample that was acquired for
- this sensor.
</dd>
<dt>readonly attribute DOMString reason</dt>
<dd>It is a string that denotes the reason for this data. The only admissible values for this attribute are:
@@ -313,10 +438,12 @@
</dd>
</dl>
- <p class="note">A section describing all the events defined by the API will be added for next draft. </p>
+ <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 Data Implementation Requirements</h2>
@@ -334,24 +461,20 @@
<tr><td>Temperature</td><td>double</td><td>degree Celsius (ºC)</td></tr>
<tr><td>AmbientLight</td><td>double</td><td>Lux</td></tr>
<tr><td>AmbientNoise</td><td>double</td><td>dbA</td></tr>
- <tr><td>MagneticField</td><td>double</td><td>micro-Tesla (uTesla)</td></tr>
+ <tr><td>MagneticField</td><td>MagneticFieldData</td><td>micro-Tesla (uTesla)</td></tr>
<tr><td>Proximity</td><td>double</td><td>centimetres (cm)</td></tr>
<tr><td>AtmPressure</td><td>double</td><td>kiloPascal (kP)</td></tr>
- <tr><td>Accelerometer</td><td>DeviceAcceleration</td><td>meters/second^2 (m/s2)</td></tr>
- <tr><td>Gyroscope</td><td>DeviceRotationRate</td><td>radians/second</td></tr>
- <tr><td>Orientation</td><td>DeviceOrientation</td><td>radians</td></tr>
+ <tr><td>RelHumidity</td><td>double</td><td></td></tr>
+ <tr><td>Accelerometer</td><td>AccelerationData</td><td>meters/second^2 (m/s2)</td></tr>
+ <tr><td>Gyroscope</td><td>RotationData</td><td>radians/second</td></tr>
+ <tr><td>Orientation</td><td>OrientationData</td><td>radians</td></tr>
</tbody>
</table>
-
- <div class="issue">
- The WG (together with Geoloc) is still discussing whether Accelerometer, Gyroscope and Orientation data are going to be exposed through
- the Sensor API.
- </div>
</p>
</section>
- <section><h4>The DeviceAcceleration interface</h4>
- <dl title='interface DeviceAcceleration' class='idl'>
+ <section><h4>The AccelerationData interface</h4>
+ <dl title='interface AccelerationData' class='idl'>
<dt>readonly attribute double x</dt>
<dd>
</dd>
@@ -381,8 +504,8 @@
</dl>
</section>
- <section><h4>The DeviceRotationRate interface</h4>
- <dl title='interface DeviceRotationRate' class='idl'>
+ <section><h4>The RotationData interface</h4>
+ <dl title='interface RotationData' class='idl'>
<dt>readonly attribute double x</dt>
<dd>
Angular speed around the x-axis
@@ -398,8 +521,8 @@
</dl>
</section>
- <section><h4>The DeviceOrientation interface</h4>
- <dl title='interface DeviceOrientation' class='idl'>
+ <section><h4>The OrientationData interface</h4>
+ <dl title='interface OrientationData' class='idl'>
<dt>readonly attribute double alpha</dt>
<dd>
</dd>
@@ -411,13 +534,34 @@
</dd>
</dl>
</section>
-</section>
+ </section>
+<section>
+ <h2>Errors</h2>
+
+ <section>
+ <h3>Sensor Error</h3>
+ <dl title='dictionary SensorError' class='idl'>
+ <dt>readonly attribute DOMString message</dt>
+ <dd>
+ Error message
+ </dd>
+ <dt>readonly attribute unsigned short code</dt>
+ <dd>
+ Error code
+ </dd>
+ <dt>const unsigned short PERMISSION_DENIED = -100</dt>
+ <dd>
+ The user has not given permission
+ </dd>
+ </dl>
+ </section>
+</section>
<section class='appendix'>
<h2>Acknowledgements</h2>
<p>
- WAC Ipanema Device APIs Lightweight Participation WG
+ WAC Ipanema Device APIs Lightweight Participation WG, in particular Bryan Sullivan, Balaji N.V., and Kaushik Das.
</p>
</section>
</body>
Received on Friday, 11 November 2011 17:13:10 UTC