dap commit: added sensor api spec

changeset:   73:69178436f4d4
tag:         tip
user:        dtran
date:        Fri Mar 09 15:25:58 2012 -0800
files:       sensor-api/Overview.html
description:
added sensor api spec


diff -r 8e76d4410fe6 -r 69178436f4d4 sensor-api/Overview.html
--- /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>

Received on Monday, 12 March 2012 03:01:47 UTC