- From: Dzung Tran via cvs-syncmail <cvsmail@w3.org>
- Date: Fri, 07 Oct 2011 14:22:56 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/system-info
In directory hutz:/tmp/cvs-serv14885/system-info
Modified Files:
Sensors.html
Log Message:
minor changes included:
- added the vendor attribute and added a few notes for clarification.
- changed the accuracy attribute to be a DOMString as the trend is to use string values for enumerations, instead of integers.
- added the disconnected state to the list of possible states.
- emoved the URI from the constructor to follow the suggestions from the last conf call.
Index: Sensors.html
===================================================================
RCS file: /sources/public/2009/dap/system-info/Sensors.html,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5
--- Sensors.html 6 Oct 2011 03:23:49 -0000 1.4
+++ Sensors.html 7 Oct 2011 14:22:54 -0000 1.5
@@ -11,7 +11,7 @@
var respecConfig = {
specStatus: "ED",
shortName: "sensor",
- publishDate: "2011-09-27",
+ publishDate: "2011-10-07",
//previousPublishDate: "2011-06-02",
previousMaturity: "WD",
edDraftURI: "http://dev.w3.org/2009/dap/sensors.html",
@@ -28,10 +28,17 @@
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 the physical sensors on a hosting device.
+ 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>
@@ -42,14 +49,15 @@
<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 of the hosting device. The information provided through this API is
+ physical sensors available on 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>
+ 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 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');
+ var sensorConnection = new navigator.sensor.Connection('Temperature');
sensorConnection.addEventListener('sensordata', function(e) {
if(e.data > 20.0) {
window.console.log('Temperature is too high!!!!');
@@ -79,60 +87,72 @@
<section>
<h2>Security and Privacy Considerations</h2>
- <p>To be defined</p>
+ <p class="note">To be defined</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.
+ Sensor objects, and populating that object with appropriate data accordingly. </p>
+
<dl title='interface SensorManager : EventTarget' class='idl'>
- <dt>Sensor[] listSensors(in optional DOMString type)</dt>
+ <dt>Sensor[] listSensors(optional DOMString type)</dt>
<dd>
- The <code>listSensors()</code> function optionally takes one argument as the sensor <code>type</code>.
- When called, the user agent calls platform native sensor interfaces and fill a list of <code>Sensor</code>
- objects that contain the sensors information. If the argument <code>type</code> is set, only sensors of
- the specified <code>type</code> are returned.
+ 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>
<dd>
- Allows to set an event handler that will be invoked when new sensors are available
+ Allows to set an event handler that will be invoked when a new sensor is available
</dd>
</dl>
</section>
<section>
<h2>Sensor</h2>
- The Sensor object allows an implementation to provide sensor information of the hosting device. The sensor information is acquired by
- calling platform sensor interfaces.
- <dl title='interface Sensor : Object' class='idl'>
- <dt>readonly attribute float resolution</dt>
+ The <code>Sensor</code> object contains different attributes that provide sensor metadata.
+ <dl title='dictionary Sensor' class='idl'>
+ <dt>readonly attribute float? resolution</dt>
<dd>
- Specifies the resolution of the sensor in the sensor's unit
+ 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 delay</dt>
+ <dt>readonly attribute int? minDelay</dt>
<dd>
- Specifies the minimum delay allowed between two events in microsecond or zero if this sensor
- only returns a value when the data it's measuring changes
+ 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 int? range</dt>
<dd>
- Specifies the maximum range of the sensor in the sensor's unit
+ 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 DOMString name</dt>
<dd>
- Specifies the sensor name for this Sensor object
+ It must return an identifier for the sensor.
</dd>
<dt>readonly attribute DOMString type</dt>
<dd>
- Specifies the sensor type for this Sensor object
+ It must return the sensor type. See table below for a list sensor types defined by this specification
</dd>
- <dt>readonly attribute float power</dt>
+ <dt>readonly attribute float? power</dt>
<dd>
- Specifies the power in mA used by this sensor while in use
+ It must return the power in mA used by this sensor while in use. <code>null</code> if this parameter is not available
</dd>
+ <dt>readonly attribute DOMString? vendor</dt>
+ <dd>
+ It must return a string that identifies the vendor of the sensor. <code>null</code> if this data is not available.
+ </dd>
</dl>
</section>
@@ -140,15 +160,12 @@
<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>
+ <dl title='[Constructor(DOMString type,optional DOMString name)] interface SensorConnection : EventTarget' class='idl'>
+ <dt>readonly attribute Sensor sensor</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
@@ -156,6 +173,7 @@
<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>disconnected</code>. The connection with the sensor has been lost.</li>
<li><code>error</code>. An error has occured</li>
</ul>
</dd>
@@ -165,7 +183,10 @@
<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? oncalibrationneeded</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:
@@ -182,7 +203,7 @@
</ol>
</dd>
- <dt>void startWatch(in SensorWatchOptions watchOptions)</dt>
+ <dt>void startWatch(SensorWatchOptions watchOptions)</dt>
<dd>
<p>When called the user agent MUST run the following steps:
<ol>
@@ -218,13 +239,16 @@
</dd>
</dl>
<dl>
- <dt>[Constructor(DOMString uri)]</dt>
+ <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>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>
+ <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>
</dd>
</dl>
@@ -248,23 +272,25 @@
<section>
<h2>SensorDataEvent Interface</h2>
+ <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>
<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 int accuracy</dt>
- <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>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 mayimprove 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 environmentdoesn't allow readings</li>
+ <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. This value is relative to the timestamp of the first sample that was acquired for
+ 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>
@@ -278,12 +304,16 @@
in boolean bubbles,
in boolean cancelable,
in DOMString reason,
+ 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 will be added for next draft. </p>
</section>
@@ -312,6 +342,11 @@
<tr><td>Orientation</td><td>DeviceOrientation</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>
Received on Friday, 7 October 2011 14:23:03 UTC