Skip to content

Commit

Permalink
Fixes for review comments
Browse files Browse the repository at this point in the history
  • Loading branch information
Alexander Shalamov committed Sep 20, 2017
1 parent 1a7b767 commit 26ff704
Show file tree
Hide file tree
Showing 2 changed files with 45 additions and 26 deletions.
26 changes: 12 additions & 14 deletions index.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1570,26 +1570,24 @@ for each [=sensor types=]:

<h3 id="permission-api">Extending the Permission API</h3>

{{Sensor}} interface for concrete [=sensor=] must protect it's [=sensor reading|reading=]
by associated {{PermissionName}} or more complex {{PermissionDescriptor}}.
[=Low-level=] {{Sensor|sensor}} may use it's interface name as a {{PermissionName}}, for instance
"gyroscope" or "accelerometer". [=sensor fusion|Fusion sensors=] must
[=request permission to use|request permission to use=] sensors used as a source of fusion.
An implementation of the {{Sensor}} interface for each [=sensor type=] must protect its
[=sensor reading|reading=] by associated {{PermissionName}} or {{PermissionDescriptor}}.
A [=Low-level=] {{Sensor|sensor}} may use its interface name as a {{PermissionName}},
for instance, "gyroscope" or "accelerometer". [=sensor fusion|Fusion sensors=] must
[=request permission to use|request permission to access=] each of the sensors that are
used as a source of fusion.

Even though, it might be difficult to reconstruct [=low-level=] [=sensor readings=] from
fused data, some of the original information might be inferred. For example, it is easy to
deduce user's orientation in space if absolute or geomagnetic orientation sensors are used,
therefore, those sensors must [=request permission to use|request permission to use=]
"magnetometer" as it provides information about orientation of device in relation to Earth's
therefore, these sensors must [=request permission to use|request permission to use=]
magnetometer as it provides information about orientation of device in relation to Earth's
magnetic field. In contrast, relative orientation sensor does not expose such information, thus,
does not need to [=request permission to use|request permission to use=] "magnetometer".
it does not need to [=request permission to use|request permission to use=] magnetometer.

In order to provide fine grained control over the sensor's data,
{{PermissionDescriptor|permission descriptors}} may be used. For example, descriptor can contain
settings for accuracy or [=sampling frequency=].

Here is an example of {{PermissionDescriptor}} for a possible extension of the Permission API for
accelerometer sensor.
{{PermissionDescriptor|Permission descriptors}} can also be used to set maximum allowed limits
for accuracy or [=sampling frequency=]. An example for a possible extension of the Permission API
for accelerometer sensor is given below.

<pre class=example>
dictionary AccelerometerPermissionDescriptor : PermissionDescriptor {
Expand Down
45 changes: 33 additions & 12 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1183,9 +1183,8 @@
background-attachment: fixed;
}
</style>
<meta content="Bikeshed version 6e949445d0006e32e94031287e7088aa812092a0" name="generator">
<meta content="Bikeshed version df778ba2d9793f77f64705dbba65d0c50f68e0d9" name="generator">
<link href="https://www.w3.org/TR/generic-sensor/" rel="canonical">
<meta content="a271b771f69cb3be985187585eb39f4467226e1c" name="document-revision">
<style>
emu-val {
font-weight: bold;
Expand Down Expand Up @@ -1459,7 +1458,7 @@
<div class="head">
<p data-fill-with="logo"><a class="logo" href="https://www.w3.org/"> <img alt="W3C" height="48" src="https://www.w3.org/StyleSheets/TR/2016/logos/W3C" width="72"> </a> </p>
<h1 class="p-name no-ref" id="title">Generic Sensor API</h1>
<h2 class="no-num no-toc no-ref heading settled" id="subtitle"><span class="content">Editor’s Draft, <time class="dt-updated" datetime="2017-09-18">18 September 2017</time></span></h2>
<h2 class="no-num no-toc no-ref heading settled" id="subtitle"><span class="content">Editor’s Draft, <time class="dt-updated" datetime="2017-09-20">20 September 2017</time></span></h2>
<div data-fill-with="spec-metadata">
<dl>
<dt>This version:
Expand All @@ -1470,15 +1469,15 @@ <h2 class="no-num no-toc no-ref heading settled" id="subtitle"><span class="cont
<dd><a href="https://www.w3.org/TR/2017/WD-generic-sensor-20170530/" rel="prev">https://www.w3.org/TR/2017/WD-generic-sensor-20170530/</a>
<dt>Feedback:
<dd><span><a href="mailto:public-device-apis@w3.org?subject=%5Bgeneric-sensor%5D%20YOUR%20TOPIC%20HERE">public-device-apis@w3.org</a> with subject line “<kbd>[generic-sensor] <i data-lt="">… message topic …</i></kbd>” (<a href="https://lists.w3.org/Archives/Public/public-device-apis/" rel="discussion">archives</a>)</span>
<dd><span><a href="https://github.com/w3c/sensors">GitHub</a> (<a href="https://github.com/w3c/sensors/issues/new">new issue</a>, <a href="https://github.com/w3c/sensors/milestone/2">level 1 issues</a>, <a href="https://github.com/w3c/sensors/issues">all issues</a>)</span>
<dd><a href="https://github.com/w3c/sensors">GitHub</a> (<a href="https://github.com/w3c/sensors/issues/new">new issue</a>, <a href="https://github.com/w3c/sensors/milestone/2">level 1 issues</a>, <a href="https://github.com/w3c/sensors/issues">all issues</a>)
<dt class="editor">Editors:
<dd class="editor p-author h-card vcard" data-editor-id="50572"><span class="p-name fn">Rick Waldron</span> (<span class="p-org org">JS Foundation</span>)
<dd class="editor p-author h-card vcard" data-editor-id="78325"><a class="p-name fn u-url url" href="https://intel.com/">Mikhail Pozdnyakov</a> (<span class="p-org org">Intel Corporation</span>)
<dd class="editor p-author h-card vcard" data-editor-id="78335"><a class="p-name fn u-url url" href="https://intel.com/">Alexander Shalamov</a> (<span class="p-org org">Intel Corporation</span>)
<dt class="editor">Former Editor:
<dd class="editor p-author h-card vcard" data-editor-id="60809"><a class="p-name fn u-url url" href="http://tobie.me">Tobie Langel</a> (<span class="p-org org">Codespeaks, formerly on behalf of Intel Corporation</span>) <a class="u-email email" href="mailto:tobie@codespeaks.com">tobie@codespeaks.com</a>
<dt>Other:
<dd><span><a href="https://github.com/w3c/web-platform-tests/tree/master/generic-sensor">Test suite</a>, <a href="https://github.com/w3c/sensors/commits/master/index.bs">latest version history</a>, <a href="https://github.com/w3c/sensors/commits/gh-pages/index.bs">previous version history</a></span>
<dd><a href="https://github.com/w3c/web-platform-tests/tree/master/generic-sensor">Test suite</a>, <a href="https://github.com/w3c/sensors/commits/master/index.bs">latest version history</a>, <a href="https://github.com/w3c/sensors/commits/gh-pages/index.bs">previous version history</a>
</dl>
</div>
<div data-fill-with="warning"></div>
Expand Down Expand Up @@ -1732,7 +1731,7 @@ <h2 class="heading settled" data-level="3" id="background"><span class="secno">3
<div class="example" id="example-fdd94e11">
<a class="self-link" href="#example-fdd94e11"></a> For example checking the pressure of the left rear tire:
<pre class="highlight"><span class="kd">var</span> sensor <span class="o">=</span> <span class="k">new</span> DirectTirePressureSensor<span class="p">({</span> position<span class="o">:</span> <span class="s2">"rear"</span><span class="p">,</span> side<span class="o">:</span> <span class="s2">"left"</span> <span class="p">});</span>
sensor<span class="p">.</span>onreading <span class="o">=</span> _ <span class="o">=></span> console<span class="p">.</span>log<span class="p">(</span>sensor<span class="p">.</span>pressure<span class="p">);</span>
sensor<span class="p">.</span>onreading <span class="o">=</span> _ <span class="p">=></span> console<span class="p">.</span>log<span class="p">(</span>sensor<span class="p">.</span>pressure<span class="p">);</span>
sensor<span class="p">.</span>start<span class="p">();</span>
</pre>
</div>
Expand Down Expand Up @@ -1796,8 +1795,8 @@ <h2 class="heading settled" data-level="4" id="feature-detection"><span class="s
<pre class="highlight"><span class="k">try</span> <span class="p">{</span> <span class="c1">// No need to feature detect thanks to try..catch block.</span>
<span class="c1"></span> <span class="kd">var</span> sensor <span class="o">=</span> <span class="k">new</span> GeolocationSensor<span class="p">();</span>
sensor<span class="p">.</span>start<span class="p">();</span>
sensor<span class="p">.</span>onerror <span class="o">=</span> error <span class="o">=></span> gracefullyDegrade<span class="p">(</span>error<span class="p">);</span>
sensor<span class="p">.</span>onreading <span class="o">=</span> _ <span class="o">=></span> updatePosition<span class="p">(</span>sensor<span class="p">.</span>latitude<span class="p">,</span> sensor<span class="p">.</span>longitude<span class="p">);</span>
sensor<span class="p">.</span>onerror <span class="o">=</span> error <span class="p">=></span> gracefullyDegrade<span class="p">(</span>error<span class="p">);</span>
sensor<span class="p">.</span>onreading <span class="o">=</span> _ <span class="p">=></span> updatePosition<span class="p">(</span>sensor<span class="p">.</span>latitude<span class="p">,</span> sensor<span class="p">.</span>longitude<span class="p">);</span>
<span class="p">}</span> <span class="k">catch</span><span class="p">(</span>error<span class="p">)</span> <span class="p">{</span>
gracefullyDegrade<span class="p">(</span>error<span class="p">);</span>
<span class="p">}</span>
Expand Down Expand Up @@ -2142,9 +2141,9 @@ <h3 class="heading settled" data-level="8.1" id="the-sensor-interface"><span cla
<p>The <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/webappapis.html#event-handler-event-type" id="ref-for-event-handler-event-type">event handler event types</a> for the corresponding <a href="#the-sensor-interface"> Sensor Interface</a>'s <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/webappapis.html#event-handlers" id="ref-for-event-handlers">event handler</a> attributes are defined in <a href="#event-handlers">Event handlers</a> section.</p>
<pre class="highlight"><span class="kd">let</span> acl <span class="o">=</span> <span class="k">new</span> Accelerometer<span class="p">({</span>frequency<span class="o">:</span> <span class="mi">30</span><span class="p">});</span>
<span class="kd">let</span> max_magnitude <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
acl<span class="p">.</span>addEventListener<span class="p">(</span><span class="s1">'activate'</span><span class="p">,</span> <span class="p">()</span> <span class="o">=></span> console<span class="p">.</span>log<span class="p">(</span><span class="s1">'Ready to measure.'</span><span class="p">));</span>
acl<span class="p">.</span>addEventListener<span class="p">(</span><span class="s1">'error'</span><span class="p">,</span> error <span class="o">=></span> console<span class="p">.</span>log<span class="p">(</span><span class="s1">'Error: '</span> <span class="o">+</span> error<span class="p">.</span>name<span class="p">));</span>
acl<span class="p">.</span>addEventListener<span class="p">(</span><span class="s1">'reading'</span><span class="p">,</span> <span class="p">()</span> <span class="o">=></span> <span class="p">{</span>
acl<span class="p">.</span>addEventListener<span class="p">(</span><span class="s1">'activate'</span><span class="p">,</span> <span class="p">()</span> <span class="p">=></span> console<span class="p">.</span>log<span class="p">(</span><span class="s1">'Ready to measure.'</span><span class="p">));</span>
acl<span class="p">.</span>addEventListener<span class="p">(</span><span class="s1">'error'</span><span class="p">,</span> error <span class="p">=></span> console<span class="p">.</span>log<span class="p">(</span><span class="s1">'Error: '</span> <span class="o">+</span> error<span class="p">.</span>name<span class="p">));</span>
acl<span class="p">.</span>addEventListener<span class="p">(</span><span class="s1">'reading'</span><span class="p">,</span> <span class="p">()</span> <span class="p">=></span> <span class="p">{</span>
<span class="kd">let</span> magnitude <span class="o">=</span> Math<span class="p">.</span>hypot<span class="p">(</span>acl<span class="p">.</span>x<span class="p">,</span> acl<span class="p">.</span>y<span class="p">,</span> acl<span class="p">.</span>z<span class="p">);</span>
<span class="k">if</span> <span class="p">(</span>magnitude <span class="o">></span> max_magnitude<span class="p">)</span> <span class="p">{</span>
max_magnitude <span class="o">=</span> magnitude<span class="p">;</span>
Expand Down Expand Up @@ -2972,7 +2971,24 @@ <h3 class="heading settled" data-level="10.6" id="definition-reqs"><span class="
<p>A set of <a data-link-type="dfn" href="#identifying-parameters" id="ref-for-identifying-parameters②">identifying parameters</a>. TODO: replace that by an abstract operation.</p>
</ul>
<h3 class="heading settled" data-level="10.7" id="permission-api"><span class="secno">10.7. </span><span class="content">Extending the Permission API</span><a class="self-link" href="#permission-api"></a></h3>
<p>Provide guidance on how to extend the Permission API <a data-link-type="biblio" href="#biblio-permissions">[PERMISSIONS]</a> for each <a data-link-type="dfn" href="#sensor-type" id="ref-for-sensor-type③⑥">sensor types</a>.</p>
<p>An implementation of the <code class="idl"><a data-link-type="idl" href="#sensor" id="ref-for-sensor③⓪">Sensor</a></code> interface for each <a data-link-type="dfn" href="#sensor-type" id="ref-for-sensor-type③⑥">sensor type</a> must protect its <a data-link-type="dfn" href="#sensor-readings" id="ref-for-sensor-readings④⑦">reading</a> by associated <code class="idl"><a data-link-type="idl" href="https://w3c.github.io/permissions/#enumdef-permissionname" id="ref-for-enumdef-permissionname⑥">PermissionName</a></code> or <code class="idl"><a data-link-type="idl" href="https://w3c.github.io/permissions/#dictdef-permissiondescriptor" id="ref-for-dictdef-permissiondescriptor①">PermissionDescriptor</a></code>.
A <a data-link-type="dfn" href="#low-level" id="ref-for-low-level①③">Low-level</a> <code class="idl"><a data-link-type="idl" href="#sensor" id="ref-for-sensor③①">sensor</a></code> may use its interface name as a <code class="idl"><a data-link-type="idl" href="https://w3c.github.io/permissions/#enumdef-permissionname" id="ref-for-enumdef-permissionname⑦">PermissionName</a></code>,
for instance, "gyroscope" or "accelerometer". <a data-link-type="dfn" href="#sensor-fusion" id="ref-for-sensor-fusion⑦">Fusion sensors</a> must <a data-link-type="dfn" href="https://w3c.github.io/permissions/#request-permission-to-use" id="ref-for-request-permission-to-use①">request permission to access</a> each of the sensors that are
used as a source of fusion.</p>
<p>Even though, it might be difficult to reconstruct <a data-link-type="dfn" href="#low-level" id="ref-for-low-level①④">low-level</a> <a data-link-type="dfn" href="#sensor-readings" id="ref-for-sensor-readings④⑧">sensor readings</a> from
fused data, some of the original information might be inferred. For example, it is easy to
deduce user’s orientation in space if absolute or geomagnetic orientation sensors are used,
therefore, these sensors must <a data-link-type="dfn" href="https://w3c.github.io/permissions/#request-permission-to-use" id="ref-for-request-permission-to-use②">request permission to use</a> magnetometer as it provides information about orientation of device in relation to Earth’s
magnetic field. In contrast, relative orientation sensor does not expose such information, thus,
it does not need to <a data-link-type="dfn" href="https://w3c.github.io/permissions/#request-permission-to-use" id="ref-for-request-permission-to-use③">request permission to use</a> magnetometer.</p>
<p><code class="idl"><a data-link-type="idl" href="https://w3c.github.io/permissions/#dictdef-permissiondescriptor" id="ref-for-dictdef-permissiondescriptor②">Permission descriptors</a></code> can also be used to set maximum allowed limits
for accuracy or <a data-link-type="dfn" href="#sampling-frequency" id="ref-for-sampling-frequency⑥">sampling frequency</a>. An example for a possible extension of the Permission API
for accelerometer sensor is given below.</p>
<pre class="example" id="example-6d08453b"><a class="self-link" href="#example-6d08453b"></a>dictionary AccelerometerPermissionDescriptor : PermissionDescriptor {
boolean highAccuracy = false;
boolean highFrequency = false;
};
</pre>
<h3 class="heading settled" data-level="10.8" id="example-webidl"><span class="secno">10.8. </span><span class="content">Example WebIDL</span><a class="self-link" href="#example-webidl"></a></h3>
<p>Here’s example WebIDL for a possible extension of this specification
for proximity <a data-link-type="dfn" href="#concept-sensor" id="ref-for-concept-sensor⑤①">sensors</a>.</p>
Expand Down Expand Up @@ -3549,6 +3565,7 @@ <h2 class="no-num no-ref heading settled" id="idl-index"><span class="content">I
<li><a href="#ref-for-sensor-readings④③">10.2. Naming</a> <a href="#ref-for-sensor-readings④④">(2)</a>
<li><a href="#ref-for-sensor-readings④⑤">10.3. Unit</a>
<li><a href="#ref-for-sensor-readings④⑥">10.6. Definition Requirements</a>
<li><a href="#ref-for-sensor-readings④⑦">10.7. Extending the Permission API</a> <a href="#ref-for-sensor-readings④⑧">(2)</a>
</ul>
</aside>
<aside class="dfn-panel" data-for="low-level">
Expand All @@ -3559,6 +3576,7 @@ <h2 class="no-num no-ref heading settled" id="idl-index"><span class="content">I
<li><a href="#ref-for-low-level⑧">10. Extensibility</a>
<li><a href="#ref-for-low-level⑨">10.2. Naming</a>
<li><a href="#ref-for-low-level①⓪">10.4. Exposing High-Level vs. Low-Level Sensors</a> <a href="#ref-for-low-level①①">(2)</a> <a href="#ref-for-low-level①②">(3)</a>
<li><a href="#ref-for-low-level①③">10.7. Extending the Permission API</a> <a href="#ref-for-low-level①④">(2)</a>
</ul>
</aside>
<aside class="dfn-panel" data-for="high-level">
Expand All @@ -3576,6 +3594,7 @@ <h2 class="no-num no-ref heading settled" id="idl-index"><span class="content">I
<ul>
<li><a href="#ref-for-sensor-fusion">6.1. Sensors</a> <a href="#ref-for-sensor-fusion①">(2)</a>
<li><a href="#ref-for-sensor-fusion②">6.2. Sensor Types</a> <a href="#ref-for-sensor-fusion③">(2)</a> <a href="#ref-for-sensor-fusion④">(3)</a> <a href="#ref-for-sensor-fusion⑤">(4)</a> <a href="#ref-for-sensor-fusion⑥">(5)</a>
<li><a href="#ref-for-sensor-fusion⑦">10.7. Extending the Permission API</a>
</ul>
</aside>
<aside class="dfn-panel" data-for="smart-sensors">
Expand Down Expand Up @@ -3625,6 +3644,7 @@ <h2 class="no-num no-ref heading settled" id="idl-index"><span class="content">I
<li><a href="#ref-for-sampling-frequency②">5.3.3. Limit number of delivered readings</a>
<li><a href="#ref-for-sampling-frequency③">7.2. Sensor</a> <a href="#ref-for-sampling-frequency④">(2)</a>
<li><a href="#ref-for-sampling-frequency⑤">8.1.2. Sensor internal slots</a>
<li><a href="#ref-for-sampling-frequency⑥">10.7. Extending the Permission API</a>
</ul>
</aside>
<aside class="dfn-panel" data-for="sensor-type">
Expand Down Expand Up @@ -3757,6 +3777,7 @@ <h2 class="no-num no-ref heading settled" id="idl-index"><span class="content">I
<li><a href="#ref-for-sensor②⑤">10.2. Naming</a> <a href="#ref-for-sensor②⑥">(2)</a> <a href="#ref-for-sensor②⑦">(3)</a>
<li><a href="#ref-for-sensor②⑧">10.5. When is Enabling Multiple Sensors of the Same Type Not the Right Choice?</a>
<li><a href="#ref-for-sensor②⑨">10.6. Definition Requirements</a>
<li><a href="#ref-for-sensor③⓪">10.7. Extending the Permission API</a> <a href="#ref-for-sensor③①">(2)</a>
</ul>
</aside>
<aside class="dfn-panel" data-for="dom-sensor-activated">
Expand Down

0 comments on commit 26ff704

Please sign in to comment.