- From: Dzung Tran via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 28 Sep 2011 14:08:04 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/system-info
In directory hutz:/tmp/cvs-serv1176/system-info
Modified Files:
Sensors.html
Log Message:
latest
Index: Sensors.html
===================================================================
RCS file: /sources/public/2009/dap/system-info/Sensors.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- Sensors.html 1 Sep 2011 17:56:01 -0000 1.2
+++ Sensors.html 28 Sep 2011 14:08:02 -0000 1.3
@@ -1,34 +1,37 @@
<!DOCTYPE html>
<html>
<head>
- <title>The Sensors API</title>
+ <title>Sensor API Specification</title>
<meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
- <script src='../ReSpec.js/js/simple-node.js' class='remove'></script>
- <script src='../ReSpec.js/js/shortcut.js' class='remove'></script>
- <script src='../ReSpec.js/js/respec.js' class='remove'></script>
- <script src='../ReSpec.js/bibref/biblio.js' class='remove'></script>
+ <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: "WD",
- shortName: "sensors-api",
- editors: [
+ specStatus: "ED",
+ shortName: "sensor",
+ publishDate: "2011-09-27",
+ //previousPublishDate: "2011-06-02",
+ previousMaturity: "WD",
+ 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: "WAC Ipanema Editor"}
- ],
- publishDate: "2011-07-28",
- //previousPublishDate: "2010-07-20",
- previousMaturity: "ED",
- edDraftURI: "http://dev.w3.org/2009/dap/system-info/Sensors/",
- // lcEnd: "2009-08-05",
+ {name: "Jose Manuel Cantera Fonseca", company: "Telefonica - WAC"}
+ ],
+ 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>
- <script src='../common/config.js' class='remove'></script>
</head>
<body>
<section id='abstract'>
- This specification defines an Application Programming Interface
- (<acronym title="Application Programming Interface">API</acronym>)
- that provides scripted access to the sensors information associated with the hosting device.
+ This specification defines a generic API for getting access to information provided by the physical sensors on a hosting device.
</section>
<section class='introductory'>
<h2>Introduction</h2>
@@ -36,223 +39,283 @@
<!--***************************************Sensors***********************************************-->
<section>
- <h2>Sensors</h2>
+ <h2>Introduction</h2>
<p>This section is non-normative</p>
- <p>This specification is a sensor API provided by the User Agent to expose various sensor data from hosting device to application code.
- This specification will cover the well-known sensors that are commonly found in
- devices. The information provided by the API is raw sensor data. The specification also provides a
- mechanism for extending the API to cover for vendor specific sensors such as providing additional sensor types as vocabulary.</p>
- <p>The API is designed to enable both "one-shot" requests and repeated updates. The Sensors API in
- this specification is based on the W3C [[GEOLOCATION-API]], WAC [[WAC-ORIENTATION-API]], WAC [[WAC-SENSOR-API]] and
- Google Android's Sensor API.</p>
- <section>
- <h3>Requirements</h3>
- <ul>
- <li>A conforming implementation MUST provide a method to retrieve one-shot sensor information.</li>
- <li>A conforming implementation MUST allow an application to register to receive
- updates when the hosting device sensor changes.</li>
- <li>A conforming implementation MUST allow an application to stop receiving such updates.</li>
- <li>A conforming implementation SHOULD be agnostic to the underlying sources of information.</li>
- </ul>
- </section>
+ <p>This specification defines an API that allows application code to obtain information given by the various
+ physical sensors of the 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>
+
<section>
- <p>The following code extracts illustrate how to obtain basic sensor information:</p>
- <code>
- code examples go here.....
- </code>
+ <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 SensorConnection('sensor:Temperature');
+ sensorConnection.addEventListener('sensordata', function(e) {
+ if(e.data > 20.0) {
+ window.console.log('Temperature is too high!!!!');
+ }
+ } );
+
+ var watchOptions = { interval: (15 * 60 * 1000) };
+ session.startWatch(watchOptions);
+ </pre>
</section>
- <h2>API Definition</h2>
- <h3>Sensor</h3>
- The SensorManager object can be used by scripts to programmatically determine the sensor information for a specified type associated with the
- hosting device. The sensor information is acquired by calling platform native sensor interfaces, creating a Sensor object, and
- populating that object with appropriate data accordingly.
- <dl title='interface SensorManager : Object' class='idl'>
- <dt>void getSensor ( in SensorCallback successCallback, in DOMString type,
- [Optional] in SensorErrorCallback errorCallback,
- [Optional] in SensorOptions options)</dt>
+ </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>To be defined</p>
+</section>
+
+</section>
+ <section>
+ <h2>SensorConnection Interface</h2>
+ 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 uri)] interface SensorConnection : EventTarget' class='idl'>
+ <dt>readonly attribute DOMString sensorType</dt>
+ <dd>
+ Represents the sensor type that is currently connected to this event target.
+ </dd>
+ <dt>readonly attribute DOMString sensorURI</dt>
+ <dd>
+ Represents the sensor URI that corresponds to this event target.
+ </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>open</code>. All the infrastructure to get sensor data is ready.</li>
+ <li><code>watching</code>. The sensor is under monitoring.</li>
+ <li><code>error</code>. An error has occured</li>
+ </ul>
+ </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>void read()</dt>
<dd>
- The <code>GetSensor()</code> function takes two, three or four arguments.
- When called, it must immediately return and then asynchronously acquire a new <code>
- Sensor</code> object that contains the sensor information of the hosting device for the specified
- sensor <code>type</code>. If successful, this method must invoke its associated
- <code>successCallback</code> argument with a <code>Sensor</code> object as an argument. If the
- attempt fails, and the method was invoked with a non-null <code>errorCallback</code> argument,
- this method must invoke the <code>errorCallback</code> with a <code>SensorError</code> object as
- an argument.
+ 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>reason</code> field equal to 'read'</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>long watchSensor ( in SensorCallback successCallback, in DOMString type, in int interval,
- [Optional] in SensorErrorCallback errorCallback,
- [Optional] in SensorOptions options)</dt>
+
+ <dt>void startWatch(in SensorWatchOptions watchOptions)</dt>
<dd>
- The <code>watchSensor()</code> function takes three, four or five arguments. When
- called, it must immediately return and then asynchronously start a watch process to acquire a
- new <code>Sensor</code> object that contains the sensor information of the hosting device for the specified
- sensor <code>type</code> at the rate specified as <code>interval</code>. If successful, invoke the associated
- <code>successCallback</code> with an <code>Sensor</code> object as the argument. If the
- attempt fails, and the method was invoked with a non-null <code>errorCallback</code>
- argument, this method must invoke the <code>errorCallback</code> with a <code>
- SensorError</code> object as an argument.
- <p/>This method returns an long value that uniquely identifies the watch process. When
- the <code>clearWatch()</code> method is called with this identifier, the watch process MUST
- stop acquiring any new sensor data and must cease invoking any callbacks.
+ <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.</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>reason</code> field equal to 'watch'
+ </ul>
</dd>
-
- <dt>void clearWatch ( in long watchId )</dt>
+
+ <dt>void endWatch()</dt>
<dd>
- When this method is called, the implementation MUST stop calling the <code>successCallback
- </code> and <code>errorCallback</code> associated with the <code>watchId</code>.
+ 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.</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>
-
- <section>
- <h3>SensorCallback</h3>
- <dl title='[Callback=FunctionOnly, NoInterfaceObject] interface SensorCallback : Object' class='idl'>
- <dt>void handleEvent(in Sensor sensor)</dt>
- <dd>
- This function MUST be called whenever the implementation successfully retrieves sensor information as a result to a
- prior call to either <code>GetSensor()</code> or <code>watchSensor()</code>. If an implementation is able to
- retrieve sensor information, but the information does not meet the criteria specified in the <code>SensorOptions</code> argument,
- this method SHOULD NOT be called.
+ <dl>
+ <dt>[Constructor(DOMString uri)]</dt>
+ <dd>Constructs a new SensorConnection. When invoked the user agent MUST run the following steps:
+ <ol>
+ <li>De-Reference the URI to a sensor identifier recognized by the target platform. </li>
+ <li>Check if the corresponding identified sensor is available on the device</li>
+ <li>If the sensor is available instantiate a SensorConnection object and set its status to 'open'. </li>
+ <li>If the sensor is not available raise an exception (tbd). </li>
+ </ol>
</dd>
- </dl>
- </section>
- <section>
- <h3>SensorErrorCallback</h3>
- <dl title='[Callback=FunctionOnly, NoInterfaceObject] interface SensorErrorCallback : Object' class='idl'>
- <dt>void handleEvent(in SensorError error)</dt>
+ </dl>
+
+ </section>
+
+<section>
+ <h2>SensorWatchOptions Interface</h2>
+ <dl title='interface SensorWatchOptions : Object' class='idl'>
+ <dt>attribute double threshold</dt>
<dd>
- This function MUST be called whenever the implementation is unable to retrieve sensor information as a result to a prior call to
- either <code>GetSensor()</code> or <code>watchSensor()</code>. If an implementation is able to retrieve sensor information,
- but the information does not meet the criteria specified in the <code>SensorOptions</code> argument, this method SHOULD be called.
+ TBD
</dd>
- </dl>
- </section>
- <section>
- <h3>type</h3>
- The sensor type to obtain sensor information from the hosting device. The current vocabulary includes:
- <ul>
- <li>MagneticField</li>
- <li>Gyroscope</li>
- <li>AmbientLight</li>
- <li>Proximity</li>
- </ul>
- <h3>interval</h3>
- The <code>sampleInterval</code> attribute specifies in milliseconds how often
- the implementation SHOULD check to see if the sensor information has changed. While the
- specification allows the caller to sample at very small intervals, on many
- implementations, this may be wasteful because the battery device may update its
- level information at a frequency significantly below the <code>sampleInterval</code>.
- On implementations that are event driven, this value MAY be ignored. The caller
- should be aware that setting a value too small can adversely affect the battery life.
- The implementation should clamp this value that is at least 20 milliseconds.
- <p>
- If the interval is set to zero, then the implementation SHOULD return sensor information only when there is a change
- since the last acquisition.
- </p>
-
- <h3>Sensor</h3>
- The Sensor object allows an implementation to provide sensor information of the hosting device. How this information is obtained is
- beyond the scope of this specification.
- <dl title='interface Sensor : Object' class='idl'>
- <dt>readonly attribute int accuracy</dt>
+ <dt>attribute double interval</dt>
<dd>
- <ul>
- <li>SENSOR_STATUS_ACCURACY_HIGH - This sensor is reporting data with maximum accuracy</li>
- <li>SENSOR_STATUS_ACCURACY_MEDIUM - This sensor is reporting data with average accuracy, calibration with the environment may
- improve readings</li>
- <li>SENSOR_STATUS_ACCURACY_LOW - This sensor is reporting data with low level of accuracy, calibration with the environment is needed</li>
- <li>SENSOR_STATUS_ACCURACY_UNRELIABLE - This sensor is reporting data that can't be trusted, calibration is needed or the environment
- doesn't allow readings</li>
- </ul>
+ 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>
- <dt>readonly attribute long timestamp</dt>
- <dd>
- The time in nanosecond at which the sensor data was read
+ </dl>
+</section>
+
+ <section>
+ <h2>SensorDataEvent Interface</h2>
+ <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 float[] values</dt>
- <dd>
- The raw sensor data as specified by sensor type
- <ul>
- <li>MagneticField: All values are in micro-Tesla (uT)
- values[0]: ambient magnetic field in X
- values[1]: ambient magnetic field in Y
- values[2]: ambient magnetic field in Z
- </li>
- <li>Gyroscope: All values are in radians/second
- values[0]: Angular speed around the x-axis
- values[1]: Angular speed around the y-axis
- values[2]: Angular speed around the z-axis
- </li>
- <li>AmbientLight: values[0]: Ambient light level in SI lux units </li>
- <li>Proximity: values[0]: Proximity sensor distance measured in centimeters </li>
- </ul>
+ <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:
+ <ul>
+ <li><code>read</code>. The event was raised due to a read operation</li>
+ <li><code>watch</code>. The event was raised due to a watch operation</li>
+ </ul>
</dd>
- <dt>readonly attribute DOMString type</dt>
- <dd>
- Specifies the sensor type for this Sensor object
+ <dt>void initSensorDataEvent(in DOMString type,
+ in boolean bubbles,
+ in boolean cancelable,
+ in DOMString reason,
+ in any data)
+ </dt>
+ <dd>
+ Initializes a <a>SensorDataEvent</a> created through the <code>DocumentEvent</code> interface.
+ </dd>
+ </dl>
+
+ </section>
+
+<section id="datatypes">
+ <h2>Sensor Data Implementation Requirements</h2>
+
+ <section>
+ <h3>Summary</h3>
+ <p>An implementation MUST set the specific data type of the <code>SensorDataEvent.data</code> attribute in accordance with the following table:
+ <table class="simple">
+ <thead>
+ <tr>
+ <th>Sensor Type</th>
+ <th>Data Type</th>
+ <th>Units</th></tr>
+ </thead>
+ <tbody>
+ <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>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>
+ </tbody>
+ </table>
+ </p>
+ </section>
+
+ <section><h4>The DeviceAcceleration interface</h4>
+ <dl title='interface DeviceAcceleration' class='idl'>
+ <dt>readonly attribute double x</dt>
+ <dd>
</dd>
- </dl>
- </section>
- <section>
- <h3>SensorOptions</h3>
- <dl title='[Callback, NoInterfaceObject] interface SensorOptions : Object' class='idl'>
- <dt>readonly attribute boolean enableHighAccuracy</dt>
+ <dt>readonly attribute double y</dt>
<dd>
- The <code>enableHighAccuracy</code> attribute provides a hint that the application would
- like to receive the best possible results. This may result in slower response times or
- increased power consumption. The user might also deny this capability, or the device might
- not be able to provide more accurate results than if the flag was not specified.
</dd>
- <dt>readonly attribute long timeout</dt>
+ <dt>readonly attribute double z</dt>
<dd>
- The <code>timeout</code> attribute denotes the maximum length of time (expressed in milliseconds) that is allowed to
- pass from the call to <code>GetSensor()</code> or <code>watchSensor()</code> until the corresponding
- <code>successCallback</code> is invoked. If the implementation is unable to successfully acquire a new <code>Sensor</code>
- before the given <code>timeout</code> elapses, and no other errors have occurred in this interval, then the
- corresponding <code>errorCallback</code> MUST be invoked with a <code>SensorError</code> object whose <code>code</code>
- attribute is set to <code>TIMEOUT</code>.
</dd>
- </dl>
- </section>
- <section>
- <h3>SensorError</h3>
- <dl title='interface SensorError : Object' class='idl'>
- <dt>readonly attribute unsigned short UNKNOWN_ERROR</dt>
- <dd>
- The acquisition process failed due to an error not covered by the definition of any other error code in this interface.
+ </dl>
+ </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 unsigned short PERMISSION_DENIED</dt>
+ <dt>readonly attribute double y</dt>
<dd>
- The acquisition process failed because the application origin does not have permission to use this <abbr title="Application Programming Interface">API</abbr>.
+ ambient magnetic field in Y
</dd>
- <dt>readonly attribute unsigned short UNAVAILALBE</dt>
+ <dt>readonly attribute double z</dt>
<dd>
- The acquisition process could not be determined. The implementation reported an internal error that caused the process to fail entirely.
+ ambient magnetic field in Z
</dd>
- <dt>readonly attribute unsigned short TIMEOUT</dt>
+ </dl>
+ </section>
+
+ <section><h4>The DeviceRotationRate interface</h4>
+ <dl title='interface DeviceRotationRate' class='idl'>
+ <dt>readonly attribute double x</dt>
+ <dd>
+ Angular speed around the x-axis
+ </dd>
+ <dt>readonly attribute double y</dt>
<dd>
- The specified maximum length of time has elapsed before the acquisition could successfully acquire a new <code>Sensor</code> object.
+ Angular speed around the y-axis
</dd>
- <dt>readonly attribute unsigned short INVALID_VALUE</dt>
+ <dt>readonly attribute double z</dt>
<dd>
- The acquisition process failed because one or more of the values in the parameters of the <code>GetSensor()</code> or <code>watchSensor()</code>.
+ Angular speed around the z-axis
</dd>
- <dt>readonly attribute unsigned short code</dt>
+ </dl>
+ </section>
+
+ <section><h4>The DeviceOrientation interface</h4>
+ <dl title='interface DeviceOrientation' class='idl'>
+ <dt>readonly attribute double alpha</dt>
+ <dd>
+ </dd>
+ <dt>readonly attribute double beta</dt>
<dd>
- The <code>code</code> attribute SHOULD contain one of the errors defined in this specification. An implementation MAY define additional error codes, but MUST NOT use the numeric values defined here.
</dd>
- <dt>readonly attribute DOMString message</dt>
+ <dt>readonly attribute double gamma</dt>
<dd>
- The <code>message</code> attribute must return an error message describing the details of the error encountered. This attribute is primarily intended for debugging and developers should not use it directly in their application user interface.
</dd>
- </dl>
- </section>
+ </dl>
</section>
-
+</section>
+
+
<section class='appendix'>
<h2>Acknowledgements</h2>
<p>
+ WAC Ipanema Device APIs Lightweight Participation WG
</p>
</section>
</body>
Received on Wednesday, 28 September 2011 14:08:14 UTC