- From: Dzung Tran via cvs-syncmail <cvsmail@w3.org>
- Date: Mon, 29 Aug 2011 20:09:09 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/system-info
In directory hutz:/tmp/cvs-serv29293/system-info
Added Files:
Sensors.html
Log Message:
First stab at sensors from system-info
--- NEW FILE: Sensors.html ---
<!DOCTYPE html>
<html>
<head>
<title>The Sensors API</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 class='remove'>
var respecConfig = {
specStatus: "WD",
shortName: "sensors-api",
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",
};
</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.
</section>
<section class='introductory'>
<h2>Introduction</h2>
</section>
<!--***************************************Sensors***********************************************-->
<section>
<h2>Sensors</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.</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>
<section>
<p>The following code extracts illustrate how to obtain basic sensor information:</p>
<code>
code examples go here.....
</code>
</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 int type,
[Optional] in SensorErrorCallback errorCallback,
[Optional] in SensorOptions options)</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.
</dd>
<dt>long watchSensor ( in SensorCallback successCallback, in int type, in int interval,
[Optional] in SensorErrorCallback errorCallback,
[Optional] in SensorOptions options)</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.
</dd>
<dt>void clearWatch ( in long watchId )</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>.
</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.
</dd>
</dl>
</section>
<section>
<h3>SensorErrorCallback</h3>
<dl title='[Callback=FunctionOnly, NoInterfaceObject] interface SensorErrorCallback : Object' class='idl'>
<dt>void handleEvent(in SensorError error)</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.
</dd>
</dl>
</section>
<section>
<h3>type</h3>
The sensor type to obtain sensor information from the hosting device. Vendor specific type MUST starts from SENSOR_TYPE_VENDOR_START.
<ul>
<li>SENSOR_TYPE_MAGNETIC_FIELD: Ambient magnetic field sensor</li>
<li>SENSOR_TYPE_GYROSCOPE: Gyroscope sensor</li>
<li>SENSOR_TYPE_AMBIENT_LIGHT: Ambient light sensor</li>
<li>SENSOR_TYPE_PROXIMITY: Proximity sensor</li>
<li>SENSOR_TYPE_VENDOR_START: Vendor specific sensor type start with this type constant</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>
<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>
</dd>
<dt>readonly attribute long timestamp</dt>
<dd>
The time in nanosecond at which the sensor data was read
</dd>
<dt>readonly attribute float[] values</dt>
<dd>
The raw sensor data as specified by sensor type
<ul>
<li>SENSOR_TYPE_MAGNETIC_FIELD: 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>SENSOR_TYPE_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>SENSOR_TYPE_AMBIENT_LIGHT: values[0]: Ambient light level in SI lux units </li>
<li>SENSOR_TYPE_PROXIMITY: values[0]: Proximity sensor distance measured in centimeters </li>
</ul>
</dd>
<dt>readonly attribute int type</dt>
<dd>
Specifies the sensor type for this Sensor object
</dd>
</dl>
</section>
<section>
<h3>SensorOptions</h3>
<dl title='[Callback, NoInterfaceObject] interface SensorOptions : Object' class='idl'>
<dt>readonly attribute boolean enableHighAccuracy</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>
<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.
</dd>
<dt>readonly attribute unsigned short PERMISSION_DENIED</dt>
<dd>
The acquisition process failed because the application origin does not have permission to use this <abbr title="Application Programming Interface">API</abbr>.
</dd>
<dt>readonly attribute unsigned short UNAVAILALBE</dt>
<dd>
The acquisition process could not be determined. The implementation reported an internal error that caused the process to fail entirely.
</dd>
<dt>readonly attribute unsigned short TIMEOUT</dt>
<dd>
The specified maximum length of time has elapsed before the acquisition could successfully acquire a new <code>Sensor</code> object.
</dd>
<dt>readonly attribute unsigned short INVALID_VALUE</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>.
</dd>
<dt>readonly attribute unsigned short code</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>
<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>
</section>
<section class='appendix'>
<h2>Acknowledgements</h2>
<p>
</p>
</section>
</body>
</html>
Received on Monday, 29 August 2011 20:09:12 UTC