-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathindex.html
795 lines (771 loc) · 43.3 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Web I2C API</title>
<script>
(function () {
var els = ['section', 'article', 'aside', 'nav', 'header', 'footer', 'time'];
for (var i=0; i<els.length; i++ ) {
document.createElement(els[i]);
}
})();
</script>
<link href="https://www.w3.org/community/src/css/spec/cg-draft.css" rel="stylesheet">
<style>
section, article, aside, nav, header, footer {
display: block;
}
p.subtitle {
font-size: 150%;
}
/* Note formatting taken from HTML5 spec */
.note {
border-left-style: solid;
border-left-width: 0.25em;
background: none repeat scroll 0 0 #E9FBE9;
border-color: #52E052;
}
.note em, .warning em, .note i, .warning i {
font-style: normal;
}
p.note, div.note {
padding: 0.5em 2em;
}
span.note {
padding: 0 2em;
}
.note p:first-child {
margin-top: 0;
}
.note p:last-child {
margin-bottom: 0;
}
p.note:before {
content: 'Note: ';
font-weight: bolder;
}
.open-issue {
border-left-style: solid;
border-left-width: 0.25em;
background: none repeat scroll 0 0 #fbfbe9;
border-color: #faf9a5;
}
.open-issue em, .warning em, .open-issue i, .warning i {
font-style: normal;
}
p.open-issue, div.open-issue {
padding: 0.5em 2em;
}
span.open-issue {
padding: 0 2em;
}
.open-issue p:first-child {
margin-top: 0;
}
.open-issue p:last-child {
margin-bottom: 0;
}
p.open-issue:before {
content: 'Open issue: ';
font-weight: bolder;
}
.non-normative {
border-left-style: solid;
border-left-width: 0.25em;
background: none repeat scroll 0 0 #E9FBE9;
border-color: #52E052;
}
p.non-normative:before {
content: 'Non-normative: ';
font-weight: bolder;
}
p.non-normative, div.non-normative {
padding: 0.5em 2em;
}
/* Pre.idl formatting taken from HTML5 spec */
pre.idl {
border: solid thin #d3d3d3;
background: #FCFCFC;
color: black;
padding: 0.5em 1em;
position: relative;
}
pre.idl :link, pre.idl :visited {
color: inherit;
background: transparent;
}
pre.idl::before {
content: "IDL";
font: bold small sans-serif;
padding: 0.5em;
background: white;
position: absolute;
top: 0;
margin: -1px 0 0 -4em;
width: 1.5em;
border: thin solid;
border-radius: 0 0 0 0.5em
}
/* .example idl formatting taken from HTML5 nightly spec */
.example {
display: block;
color: #222222;
background: #FCFCFC;
border-left-style: solid;
border-color: #c0c0c0;
border-left-width: 0.25em;
margin-left: 1em;
padding-left: 1em;
padding-bottom: 0.5em;
}
.algorithm li {
margin-bottom: 0.5em;
}
.interface dd, .parameters dt {
margin-bottom: 0.5em;
}
code {
color: orangered;
}
dt, dfn {
font-weight: bold;
font-style: normal;
}
</style>
</head>
<body>
<header class="head">
<!--begin-logo-->
<p><a href="http://www.w3.org/"><img alt="W3C" src="https://www.w3.org/Icons/w3c_home" width="72" height="48"></a></p>
<!--end-logo-->
<h1>Web I2C API</h1>
<p class="subtitle">Draft Report
<time datetime="2016-01-25">25 January 2016</time>
</p>
<dl>
<dt>This Version:</dt>
<dd><a href="#">http://</a></dd>
<dt>Latest Published Version</dt>
<dd><a href="#">http://</a></dd>
<dt>Previous Version:</dt>
<dd>None.</dd>
<dt>Editors: </dt>
<dd><a href="mailto:[email protected]">Futomi Hatano</a> (<span lang="ja">
<ruby>羽田野
<rp>(</rp>
<rt>はたの</rt>
<rp>)</rp>
</ruby>
<ruby>太巳
<rp>(</rp>
<rt>ふとみ</rt>
<rp>)</rp>
</ruby>
</span>), Newphoria</dd>
<dd><a href="twitter:@masap">Masashi Honma</a> (<span lang="ja">
<ruby>本間
<rp>(</rp>
<rt>ほんま</rt>
<rp>)</rp>
</ruby>
<ruby>雅史
<rp>(</rp>
<rt>まさし</rt>
<rp>)</rp>
</ruby>
</span>), プログラマ</dd>
<dd><a href="mailto:[email protected]">Satoru Takagi</a> (<span lang="ja">
<ruby>高木
<rp>(</rp>
<rt>たかぎ</rt>
<rp>)</rp>
</ruby>
<ruby>悟
<rp>(</rp>
<rt>さとる</rt>
<rp>)</rp>
</ruby>
</span>), KDDI </dd>
</dl>
<p class="copyright"> <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © 2015-2016 the Contributors to the Web I2C API Specification,
published by the <a href="http://www.w3.org/community/browserobo/">Browsers and Robotics Community Group</a> under the <a href="https://www.w3.org/community/about/agreements/final/">W3C Community
Final Specification Agreement (FSA)</a>. A human-readable <a href="http://www.w3.org/community/about/agreements/fsa-deed/">summary</a> is
available. </p>
<hr>
</header>
<section>
<h2 class="no-num no-toc" id="abstract">Abstract</h2>
<p>This specification defines an API to enable web applications to access I2C (Inter-Integrated Circuit) interfaces as masters embedded in the underlying device.</p>
</section>
<section>
<h2 class="no-num no-toc" id="sotd">Status of this document</h2>
<p>This specification was published by the <a href="http://www.w3.org/community/browserobo/">Browsers and Robotics Community Group</a>. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the <a href="http://www.w3.org/community/about/agreements/cla/">W3C Community Contributor License Agreement (CLA)</a> there is a limited opt-out and other conditions apply. Learn more about <a href="http://www.w3.org/community/">W3C Community and Business Groups</a>.</p>
</section>
<nav>
<h2 class="no-num no-toc" id="toc">Table of Contents</h2>
<ol class="toc">
<li><a href="#introduction"><span class="secno">1 </span> Introduction</a></li>
<li><a href="#conformance"><span class="secno">2 </span> Conformance</a></li>
<li><a href="#terminology"><span class="secno">3 </span> Terminology</a></li>
<li><a href="#example"><span class="secno">4 </span> Example</a>
<!--
<ol class="toc">
<li><a href="#example-bunch"><span class="secno">4.1 </span>Bunch of Data Getting and Sending</a></li>
<ol>
<li><a href="#example-bunch-get"><span class="secno">4.1.1 </span>Getting Bunch of Data</a></li>
<li><a href="#example-bunch-send"><span class="secno">4.1.2 </span>Sending Bunch of Data</a></li>
</ol>
<li><a href="#example-stream"><span class="secno">4.2 </span>Getting and Sending Data by Stream</a></li>
<ol>
<li>[TBD]</li>
</ol>
<li><a href="#example-diagnostics"><span class="secno">4.3 </span>Getting diagnostics of I2C Bus</a></li>
<ol>
<li><a href="#example-listing-i2c-ports"><span class="secno">4.3.1 </span> Listing I2C ports</a></li>
<li><a href="#example-listing-i2c-slaves"><span class="secno">4.3.2 </span> Listing I2C slaves</a></li>
</ol>
<li><a href="#example-activating-a-I2C-port-and-read-the-value"><span class="secno">4.4 </span> Activating a I2C port and read the value</a></li>
<li><a href="#example-listening-to-changes-of-a-I2C-port-value"><span class="secno">4.5 </span> Listening to changes of a I2C port value</a></li>
<li><a href="#example-listening-to-changes-of-multiple-I2C-port-values"><span class="secno">4.6 </span> Listening to changes of multiple I2C port values</a></li>
<li><a href="#example-writing-a-value-to-a-I2C-port"><span class="secno">4.7 </span> Writing a value to the a I2C port</a></li>
</ol>
-->
</li>
<li><a href="#interfaces"><span class="secno">5 </span> Interfaces</a>
<!--
<ol class="toc">
<li><a href="#navigator-I2C"><span class="secno">5.1 </span> The <code>requestI2CAccess</code> method</a></li>
<li><a href="#I2CAccess-interface"><span class="secno">5.2 </span> The <code>I2CAccess</code> interface</a></li>
<li><a href="#I2CPortMap-interface"><span class="secno">5.3 </span> The <code>I2CPortMap</code> interface</a></li>
<li><a href="#I2CPort-interface"><span class="secno">5.4 </span> The <code>I2CPort</code> interface</a></li>
<li><a href="#I2CChangeEvent-interface"><span class="secno">5.5 </span> The <code>I2CChangeEvent</code> interface</a></li>
<li><a href="#I2CChangeEventInit-interface"><span class="secno">5.6 </span> The <code>I2CChangeEventInit</code> interface</a></li>
</ol>
-->
</li>
<li><a href="#security-considerations"><span class="secno">6 </span> Security considerations</a></li>
<li><a class="no-num" href="#references">References</a></li>
</ol>
</nav>
<section>
<h2 id="introduction"><span class="secno">1 </span> Introduction</h2>
<p><i>This section is non-normative.</i></p>
<p>The Web I2C API provides interfaces that web applications can access devices via I2C interfaces embedded in the underlying devices. </p>
<p>Using this API, web applications can communicate various devices connected via I2C interfaced, watch hardware interrupts, and so on.</p>
<p>This API is intended to be used under the mechanism which maintains the safety of the device by which this API operates and users using it. Note that this API is <em>not</em> intended to be used by web applications running on a general web browser without such considerations. As a mechanism for such consideration, there may be packaged applications having Privileged Contexts running on a browser runtime or web applications running on a browser in some kind of dedicated devices. <a href="#biblio-powerful-features">[POWERFUL FEATURES]</a></p>
</section>
<section>
<h2 id="conformance"><span class="secno">2 </span> Conformance</h2>
<p>As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.</p>
<p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this document. <a href="#refsRFC2119">[RFC2119]</a></p>
</section>
<section>
<h2 id="terminology"><span class="secno">3 </span> Terminology</h2>
<!-- <p>The <dfn id="EventTarget"><code>EventTarget</code></dfn>, <dfn id="Event"><code>Event</code></dfn>, and <dfn id="EventInit"><code>EventInit</code></dfn> interfaces are defined in the Web IDL specification. <a href="#refsDOM4">[DOM4]</a></p>-->
<p>The <dfn id="DOMExceptions"><code>DOMExceptions</code></dfn> interfaces is defined in the Web IDL specification. <a href="#refsWEBIDL">[WEBIDL]</a></p>
<p>The <dfn id="Promise"><code>Promise</code></dfn> is defined in ECMA-262 6th Edition. <a href="#refsES6">[ES6]</a></p>
</section>
<section>
<h2 id="example"><span class="secno">4 </span> Example </h2>
<p><i>This section is non-normative.</i></p>
<p>The following examples show common I2C usage in JavaScript. The variable <var>I2C</var> is a <a href="#I2CAccess"><code>I2CAccess</code></a> object in the examples blow.</p>
<section>
<h3 id="example-getting-access"><span class="secno">4.1 </span> Getting Access to the I2C</h3>
<p>This example shows how to request access to the set of I2C interfaces on the underlying system.</p>
<pre class="example">var I2C = null; // global I2CAccess object
navigator.requestI2CAccess().then(
function(I2CAccess) {
console.log("I2C ready!");
I2C = I2CAccess; // store in the global
},
function(error) {
console.log("Failed to get I2C access: " + error.message);
}
);</pre>
</section>
<section>
<h3 id="example-listing-I2C-ports"><span class="secno">4.2 </span> Listing I2C ports</h3>
<p>This example shows how to list the I2C ports available on the underlying operating system.</p>
<pre class="example">
// get a I2CPortMap object
var ports = I2C.ports;
// show the detailed information for each port
ports.values(function(port) {
console.log("* Port " + port.portNumber);
console.log(" - Port name : " + port.portName);
console.log(" - PIN name : " + port.pinName);
});</pre>
</section>
<section>
<h3 id="example-getting-a-I2C-port"><span class="secno">4.3 </span> Getting a I2C port</h3>
<p>This example shows how to get a I2C port.</p>
<pre class="example">var port = null; // global I2CPort object
// get the I2CPort object representing the I2C port named "I2C18".
port = ports.get(2);
<!--
I2C.open((ports.get(2)).portNumber).then(
function(I2CPort) {
port = I2CPort; // store in the global
},
function(error) {
console.log("Failed to get I2C port: " + error.message);
}
);--></pre>
</section>
<section>
<h3 id="example-listing-I2C-slaves"><span class="secno">4.4 </span> Listing I2C slaves</h3>
<p>This example shows how to list the I2C slave devices connected on the specific I2C port.</p>
<pre>[TBD]</pre>
</section>
<section>
<h3 id="example-getting-a-slave"><span class="secno">4.5 </span> Getting a slave device</h3>
<p>This example shows how to get a I2C slave device.</p>
<pre class="example">
var slaveDevice = null;
// Getting a slave device representing the slave address 0x40.
var slaveAddress = 0x40;
port.open(slaveAddress).then(
function(I2CSlave) {
slaveDevice = I2CSlave; // store in global
},
function(error) {
console.log("Failed to get a I2C slave device: " + error.message);
}
);</pre>
</section>
<section>
<h3 id="example-read-the-value"><span class="secno">4.6 </span> Reading the value</h3>
<p>This example shows how to read a value of a specified register(0x10) on a I2C slave device.</p>
<pre class="example">
// read the eight bits value from a specified registar (0x10)
var readRegistar = 0x10;
window.setInterval(function() {
slaveDevice.read8(readRegistar).then(readSuccess, I2CError);
}, 1000);
// the value successfully read
function readSuccess(value) {
console.log(slaveAddress + ":" + readRegistar + ": " + value);
}
// Show an error
function I2CError(error) {
console.log("Error: " + error.message + "(" + slaveAddress + ")");
}</pre>
</section>
<section>
<h3 id="example-listening-to-changes-of-a-I2C-slave"><span class="secno">4.7 </span> Listening to changes of a spefific I2C slave device</h3>
<p>This example shows how to listen to changes of a I2C slave values. In this example, the exported I2C port will be unexported in 60 seconds.</p>
<pre class="example">[TBD]
</pre>
</section>
<section>
<h3 id="example-writing-a-value-to-a-I2C-port"><span class="secno">4.8 </span> Writing a value</h3>
<p>This example shows how to write a eight bits value of a specified register(0x11) on a I2C slave device. This example writes 0 or 1 one after the other to the I2C port 0x10 at a second interval.</p>
<pre class="example">
// register number to write
var writeRegistar = 0x11;
// the value to be written
var v = 0;
writeValue();
function writeValue(){
v = v ? 0 : 1;
slaveDevice.write8(writeRegistar, v).then(writeSuccess, I2CError);
}
// the value successfully written
function writeSuccess(value) {
console.log(slaveDevice.address + " : " + reg + " was set to " + value);
window.setTimeout(writeValue, 1000);
}
// Show an error
function I2CError(error) {
console.log("Error: " + error.message + "(" + slaveDevice.address + ")");
}</pre>
</section>
</section>
<section>
<h2 id="interfaces"><span class="secno">5 </span> Interfaces </h2>
<section>
<p class="open-issue"> Although many functions return Promise, the some may be things sufficient by just returning an instance. </p>
<p class="open-issue">The policy of arbitration when two or more apps call these API is needed.</p>
<p class="open-issue">There are requests to treat also as streaming devices. Examination which enables it to use <a href="https://streams.spec.whatwg.org/">Streams</a> is needed. </p>
<h3 id="navigator-I2C"><span class="secno">5.1 </span> The <code>requestI2CAccess()</code> method</h3>
<pre class="idl">partial interface Navigator {
<a href="#Promise">Promise</a><<a href="#I2CAccess">I2CAccess</a>> <a href="#requestI2CAccess">requestI2CAccess</a> ();
};</pre>
<p>The <dfn id="requestI2CAccess"><code>requestI2CAccess()</code></dfn> method must be visible on the <a href="http://www.w3.org/TR/html5/webappapis.html#navigator"><code>Navigator</code></a> object if the script's global object is the <a href="http://www.w3.org/TR/html5/browsers.html#window"><code>Window</code></a> object, or on the <a href="http://www.w3.org/TR/workers/#workernavigator"><code>WorkerNavigator</code></a> object if the script's global object is the <a href="http://www.w3.org/TR/workers/#workerutils"><code>WorkerUtils</code></a>. <a href="#refsHTML5">[HTML5]</a> <a href="#refsWEBWORKERS">[WEBWORKERS]</a></p>
<p>The <a href="#requestI2CAccess"><code>requestI2CAccess()</code></a> method is used to get a <a href="#I2CAccess"><code>I2CAccess</code></a> object. The <a href="#requestI2CAccess"><code>requestI2CAccess()</code></a> method is invoked, the user agent must run the steps as follows:</p>
<p class="open-issue">Is it proper that it belongs to Navigator instead of <a href="https://w3c.github.io/sensors/">Generic Sensors API</a> belongs to Window.</p>
<ol>
<li>
<p>Let <var>promise</var> be a new <a href="#Promise"><code>Promise</code></a> object and <var>resolver</var> be its associated resolver.</p>
</li>
<li>
<p>Return <var>promise</var> and run the following steps asynchronously.</p>
</li>
<li>
<p>If the underlying operating system does not support I2C access, then jump to the step labeled <i>failure</i> below.</p>
</li>
<li>
<p>Create a <a href="#I2CPortMap"><code>I2CPortMap</code></a> object, then let <var>map</var> be the newly created <a href="#I2CPortMap"><code>I2CPortMap</code></a>.</p>
</li>
<li>
<p>Find all of the I2C ports available on the underlying operating system, then add it to the <var>map</var>.</p>
<p class="open-issue">How can the UA find the I2C ports available on the underlying operating system?</p>
</li>
<li>
<p>Create a <a href="#I2CAccess"><code>I2CAccess</code></a> object, then set the <a href="#ports"><code>ports</code></a> attribute to the <var>map</var>.</p>
</li>
<li>
<p>Let <var>access</var> to be the newly created <a href="#MIDIAccess"><code>I2CAccess</code></a> at the previous step.</p>
</li>
<li>
<p><strong>success</strong>: Call <var>resolver</var>'s <code>accept(<var>value</var>)</code> method with <var>access</var> as <var>value</var> argument. Abort these steps.</p>
</li>
<li>
<p><strong>failure</strong>: Let <var>error</var> be a new <a href="#DOMExceptions"><code>DOMExceptions</code></a>. This must be of type "<code>NotSupportedError</code>". Then call <var>resolver</var>'s <code>reject(<var>value</var>)</code> method with <var>error</var> as <var>value</var> argument.</p>
</li>
</ol>
</section>
<section>
<h3 id="I2CAccess-interface"><span class="secno">5.2 </span> The <code>I2CAccess</code> interface</h3>
<pre class="idl">interface <dfn id="I2CAccess">I2CAccess</dfn> {
readonly attribute <a href="#I2CPortMap">I2CPortMap</a> <a href="#ports">ports</a>;
<!-- <a href="#Promise">Promise</a><<a href="#I2CPort">I2CPort</a>> <a href="#open">open</a>(unsigned short I2CAddress);-->
<!-- <a href="#Promise">Promise</a> <a href="#unexportAll">unexportAll</a>();-->
<!--
attribute EventHandler <a href="#onchange-I2Caccess">onchange</a>;-->
};</pre>
<p>The <dfn id="ports"><code>ports</code></dfn> attribute must return the <a href="#I2CPortMap"><code>I2CPortMap</code></a> object representing all of the I2C ports available on the underlying operating system.</p>
<!--
<p>The <dfn id="open"><code>open()</code></dfn> method is used to get <a href="#I2CPort"><code>I2CPort</code></a> object. When the <a href="#open"><code>open()</code></a> method is invoked, the I2C port number must be passed as the first argument. Otherwise, the <a href="#get"><code>open()</code></a> method must return the <a href="#I2CPort"><code>I2CPort</code></a> corresponding to the specified port number.</p>
<ol>
<li>
<p>Let <var>promise</var> be a new <a href="#Promise"><code>Promise</code></a> object and <var>resolver</var> be its associated resolver.</p>
</li>
<li>
<p>Return <var>promise</var> and run the following steps asynchronously.</p>
</li>
<li>
<p>If the first argument is not specified, or it is not valid as a port number, or it does not represent any I2C port available on the underlying operating system, then jump to the step labeled <i>failure</i> below.</p>
</li>
<li>
<p>Create a <a href="#I2CPort"><code>I2CPort</code></a> object, then let <var>map</var> be the newly created <a href="#I2CPort"><code>I2CPort</code></a>.</p>
</li>
<li>
<p><strong>success</strong>: Call <var>resolver</var>'s <code>accept(<var>value</var>)</code> method with <var>access</var> as <var>value</var> argument. Abort these steps.</p>
</li>
<li>
<p><strong>failure</strong>: Let <var>error</var> be a new <a href="#DOMExceptions"><code>DOMExceptions</code></a>. This must be of type "<code>NotSupportedError</code>". Then call <var>resolver</var>'s <code>reject(<var>value</var>)</code> method with <var>error</var> as <var>value</var> argument.</p>
</li>
</ol>
<p>The <dfn id="unexportAll"><code>unexportAll()</code></dfn> method is used to release all of the I2C ports exported by this API. The <a href="#unexportAll"><code>unexportAll()</code></a> method is invoked, the user agent must run the steps as follows:</p>
<ol>
<li>
<p>Let <var>promise</var> be a new <a href="#Promise"><code>Promise</code></a> object and <var>resolver</var> be its associated resolver.</p>
</li>
<li>
<p>Return <var>promise</var> and run the following steps asynchronously.</p>
</li>
<li>
<p>Let <var>list</var> be the list of the <a href="#I2CPort"><code>I2CPort</code></a> object whose <a href="#exported"><code>exported</code></a> attribute is true.</p>
</li>
<li>
<p>For each of the <a href="#I2CPort"><code>I2CPort</code></a> object in the <var>list</var>, release (unexport) the related I2C port, then set the <a href="#exported"><code>exported</code></a> attribute to false.</p>
</li>
<li>
<p>Wait until the previous step for all of the <a href="#I2CPort"><code>I2CPort</code></a> in the <var>list</var> finishes.</p>
</li>
<li>
<p>If all of the exported I2C port are released successfully, jump to the step labeled <i>success</i> below. Otherwise, jump to the step labeled <i>failure</i> below.</p>
</li>
<li>
<p><strong>success</strong>: Call <var>resolver</var>'s <code>accept()</code> method without any argument. Abort these steps.</p>
</li>
<li>
<p><strong>failure</strong>: Let <var>error</var> be a new <a href="#DOMExceptions"><code>DOMExceptions</code></a>. This must be of type "<code>OperationError</code>". Then call <var>resolver</var>'s <code>reject(<var>value</var>)</code> method with <var>error</var> as <var>value</var> argument.</p>
</li>
</ol>
-->
<!--
<p>The <dfn id="onchange-I2Caccess"><code>onchange</code></dfn> attribute is a event handler invoked when the value of one of the exported I2C ports changes (i.e. the value changes from 1 to 0 or from 0 to 1). Whenever the event handler is to be invoked, the user agent must run the following steps:</p>
<ol>
<li>
<p>Let <var>port</var> be the <a href="#I2CPort"><code>I2CPort</code></a> object.</p>
</li>
<li>
<p>Let <var>port value</var> be the value of the I2C port corresponding to the <a href="#I2CPort"><code>I2CPort</code></a>.</p>
</li>
<li>
<p>Let <var>event</var> be a newly constructed <a href="#I2CChangeEvent"><code>I2CChangeEvent</code></a>, with the <a href="#value"><code>value</code></a> attribute set to the <var>port value</var>, and the <a href="#port"><code>port</code></a> attribute set to the <var>port</var>.</p>
</li>
<li>
<p>Fire an event named <code>change</code> at the <a href="#I2CAccess-interface"><code>I2CAccess</code></a> object<a href="#I2CPort"><code></code></a>, using the <var>event</var> as the event object.</p>
</li>
</ol>
<p class="note">Before the <code>change</code> event is fired on the <a href="#I2CAccess-interface"><code>I2CAccess</code></a> object, another <code>change</code> event is fired on the <a href="#I2CPort"><code>I2CPort</code></a> object. Therefore, the event handler set on the <a href="#I2CAccess-interface"><code>I2CAccess</code></a> is invoked after the event handler set on the <a href="#I2CPort"><code>I2CPort</code></a> object is invoked.</p>
-->
</section>
<section>
<h3 id="I2CPortMap-interface"><span class="secno">5.3 </span> The <code>I2CPortMap</code> interface</h3>
<pre class="idl">interface <dfn id="I2CPortMap">I2CPortMap</dfn> {
attribute readonly unsigned short <a href="#size">size</a>;
function <a href="#keys">keys</a> (void function (<var>portNumber</var>));
function <a href="#values">values</a> (void function (<var>I2CPort</var>));
<a href="#I2CPort">I2CPort</a> get(portNumber);
<a href="#I2CPort">I2CPort</a> getByName(portName);
<!-- <a href="#I2CPort">I2CPort</a> <a href="#get">get</a> (unsigned short <var>key</var>);-->
};</pre>
<p>The <dfn id="size"><code>size</code></dfn> attributes is the number of I2C ports available on the underlying operating system at the current time.</p>
<p>The <dfn id="keys"><code>keys()</code></dfn> method is an iterator for keys. The <dfn id="values"><code>values()</code></dfn> method is an iterator for values.</p>
<p>The <dfn id="get"><code>get()</code></dfn> method returnes a <a href="#I2CPort"><code>I2CPort</code></a> object corresponding to <var>portNumber</var>.</p>
<p>The <dfn id="getByName"><code>getByName()</code></dfn> method returnes a <a href="#I2CPort"><code>I2CPort</code></a> object corresponding to <var>portName</var>.</p>
<!-- <p>The <dfn id="get"><code>get()</code></dfn> method is a getter for a <a href="#I2CPort"><code>I2CPort</code></a>. When the <a href="#get"><code>get()</code></a> method is invoked, the I2C port number must be passed as the first argument. If the first argument is not specified, or it is not valid as a port number, or it does not represent any I2C port available on the underlying operating system, the <a href="#get"><code>get()</code></a> method must return null. Otherwise, the <a href="#get"><code>get()</code></a> method must return the <a href="#I2CPort"><code>I2CPort</code></a> corresponding to the specified port number.</p>
<p>This interface is used to represent all the currently available I2C ports as a MapClass-like interface. This interface also act as an associative array:</p>
<pre class="example">// Iterate for values
ports.keys( function( portNumber ) {
var port = ports.get(portNumber);
console.log(port.pinName + ", " + port.portNumber);
});
// or you could express as:
ports.values( function( port ) {
console.log(port.pinName + ", " + port.portNumber);
});
// or you could express as:
for (port in ports) {
console.log(port.pinName + ", " + port.portNumber);
}</pre>
-->
</section>
<section>
<h3 id="I2CPort-interface"><span class="secno">5.4 </span> The <code>I2CPort</code> interface</h3>
<pre class="idl">interface <dfn id="I2CAccess">I2CPort</dfn> {
<!-- readonly attribute <a href="#I2CSlaveDeviceMap">I2CSlaveDeviceMap</a> <a href="#slaves">slaves</a>;-->
<a href="#Promise">Promise</a><<a href="#I2CSlaveDevice">I2CSlaveDevice</a>> <a href="#open">open</a>(unsigned short I2CSlaveAddress);
readonly attribute unsigned short portNumber;
<!--
<a href="#Promise">Promise</a> <a href="#unexportAll">unexportAll</a>();
attribute EventHandler <a href="#onchange-I2Caccess">onchange</a>;
<a href="#Promise">Promise</a> <a href="#close">close</a>();-->
};</pre>
<!--<p>The <dfn id="ports"><code>slaves</code></dfn> attribute must return the <a href="#I2CSlaveDeviceMap"><code>I2CSlaveDeviceMap</code></a> object representing all of the I2C slave devices available on the underlying operating system.</p>-->
<p>The <dfn id="open"><code>open()</code></dfn> method is used to get <a href="#I2CSlaveDevice"><code>I2CSlaveDevice</code></a> object. When the <a href="#open"><code>open()</code></a> method is invoked, the address number must be passed as the first argument. Otherwise, the <a href="#open"><code>open()</code></a> method must return the <a href="#I2CSlaveDevice"><code>I2CSlaveDevice</code></a> corresponding to the specified address.</p>
<ol>
<li>
<p>Let <var>promise</var> be a new <a href="#Promise"><code>Promise</code></a> object and <var>resolver</var> be its associated resolver.</p>
</li>
<li>
<p>Return <var>promise</var> and run the following steps asynchronously.</p>
</li>
<li>
<p>If the first argument is not specified, or it is not valid as a port number, or it does not represent any I2C slave device available on the underlying I2C port, then jump to the step labeled <i>failure</i> below.</p>
</li>
<li>
<p>Create a <a href="#I2CSlaveDevice"><code>I2CSlaveDevice</code></a> object, then let <var>map</var> be the newly created <a href="#I2CSlaveDevice"><code>I2CSlaveDevice</code></a>.</p>
</li>
<li>
<p><strong>success</strong>: Call <var>resolver</var>'s <code>accept(<var>value</var>)</code> method with <var>access</var> as <var>value</var> argument. Abort these steps.</p>
</li>
<li>
<p><strong>failure</strong>: Let <var>error</var> be a new <a href="#DOMExceptions"><code>DOMExceptions</code></a>. This must be of type "<code>NotSupportedError</code>" or "<code>OperationError</code>". Then call <var>resolver</var>'s <code>reject(<var>value</var>)</code> method with <var>error</var> as <var>value</var> argument.</p>
</li>
</ol>
</section>
<section>
<h3 id="I2CSlaveDevice-interface"><span class="secno">5.5 </span> The <code>I2CSlaveDevice</code> interface</h3>
<p class="open-issue">I2CSlaveDevice object may be useful to applications programmers. On the other hand, probably there is no concept of slavedevice in the library on linux etc. which will serve as a base of webI2C. The realizability of an implementation should be checked. </p>
<pre class="idl">
interface <dfn id="I2CSlaveDevice">I2CSlaveDevice</dfn> {
readonly attribute unsigned short <a href="#slaveAddress">slaveAddress</a>;
<!-- <a href="#Promise">Promise</a> <a href="#close">close</a>();-->
<a href="#Promise">Promise</a> <a href="#read8">read8</a>(unsigned short registerNumber);
<a href="#Promise">Promise</a> <a href="#read16">read16</a>(unsigned short registerNumber);
<a href="#Promise">Promise</a> <a href="#write8">write8</a>(unsigned short registerNumber, octet <var>value</var>);
<a href="#Promise">Promise</a> <a href="#write16">write16</a>(unsigned short registerNumber, unsigned short <var>value</var>);
<!--
attribute EventHandler <a href="#onchange-I2Cport">onchange</a>;-->
};</pre>
<p>The <a href="#I2CSlaveDevice"><code>I2CSlaveDevice</code></a> interface represents a I2C slave device assigned to a I2C interface address.</p>
<p>The <dfn id="slaveAddress"><code>slaveAddress</code></dfn> attribute must return the I2C address number assigned to the <a href="#I2CSlaveDevice"><code>I2CSlaveDevice</code></a> object.</p>
<!--
<p>The <dfn id="export"><code>export()</code></dfn> method
activate the related I2C port. When the <a href="#export"><code>export()</code></a> method is invoked, the user agent must run the steps as follows:</p>
<ol>
<li>
<p>Let <var>promise</var> be a new <a href="#Promise"><code>Promise</code></a> object and <var>resolver</var> be its associated resolver.</p>
</li>
<li>
<p>Return <var>promise</var> and run the following steps asynchronously.</p>
</li>
<li>
<p>If the value of the <a href="#exported"><code>exported</code></a> attribute is true, jump to the step labeled <i>success</i> below.</p>
</li>
<li>
<p>Let <var>direction</var> be the value of the first argument passed to the method.</p>
</li>
<li>
<p>If <var>direction</var> is neither "<code>in</code>" nor "<code>out</code>", jump to the step labeled <i>failure</i> below.</p>
</li>
<li>
<p>Activate the related I2C port in the specified direction mode ("<code>in</code>" or "<code>out</code>"). If succeeded, set the <a href="#exported"><code>exported</code></a> attribute to true, then jump to the step labeled <i>success</i> below. Otherwise, jump to the step labeled <i>failure</i> below.</p>
</li>
<li>
<p><strong>success</strong>: Call <var>resolver</var>'s <code>accept()</code> method without any argument. Abort these steps.</p>
</li>
<li>
<p><strong>failure</strong>: Let <var>error</var> be a new <a href="#DOMExceptions"><code>DOMExceptions</code></a>. This must be of type "<code>InvalidAccessError</code>" if <var>direction</var> was invalid (i.e. neither "<code>in</code>" nor "<code>out</code>"), "<code>SecurityError</code>" if this operation was denied by the operating system because of some kind of security reason, "<code>OperationError</code>" if this operation was failed because of any reasons other than security reason. Then call <var>resolver</var>'s <code>reject(<var>value</var>)</code> method with <var>error</var> as <var>value</var> argument.</p>
</li>
</ol>
<p>The <dfn id="unexport"><code>unexport()</code></dfn> method deactivates the related I2C port. When the <a href="#unexport"><code>unexport()</code></a> method is invoked, the user agent must run the steps as follows:</p>
<ol>
<li>
<p>Let <var>promise</var> be a new <a href="#Promise"><code>Promise</code></a> object and <var>resolver</var> be its associated resolver.</p>
</li>
<li>
<p>Return <var>promise</var> and run the following steps asynchronously.</p>
</li>
<li>
<p>If the value of the <a href="#exported"><code>exported</code></a> attribute is <em>not</em> true, jump to the step labeled <i>success</i> below.</p>
</li>
<li>
<p>Deactivate the related I2C port. If succeeded, set the <a href="#exported"><code>exported</code></a> attribute to false, then jump to the step labeled <i>success</i> below. Otherwise, jump to the step labeled <i>failure</i> below.</p>
</li>
<li>
<p><strong>success</strong>: Call <var>resolver</var>'s <code>accept()</code> method without any argument. Abort these steps.</p>
</li>
<li>
<p><strong>failure</strong>: Let <var>error</var> be a new <a href="#DOMExceptions"><code>DOMExceptions</code></a>. This must be of type "<code>OperationError</code>". Then call <var>resolver</var>'s <code>reject(<var>value</var>)</code> method with <var>error</var> as <var>value</var> argument.</p>
</li>
</ol>
-->
<p>The <dfn id="read8"><code>read8()</code></dfn> method reads the value from the related I2C port. When the <a href="#read8"><code>read8()</code></a> method is invoked, the user agent must run the steps as follows:</p>
<ol>
<li>
<p>Let <var>promise</var> be a new <a href="#Promise"><code>Promise</code></a> object and <var>resolver</var> be its associated resolver.</p>
</li>
<li>
<p>Return <var>promise</var> and run the following steps asynchronously.</p>
</li>
<!--
<li>
<p>If the value of the <a href="#exported"><code>exported</code></a> attribute is <em>not</em> true, jump to the step labeled <i>failure</i> below.</p>
</li>
<li>
<p>If the value of the <a href="#direction"><code>direction</code></a> attribute is <em>not</em> "<code>in</code>", jump to the step labeled <i>failure</i> below.</p>
</li>
-->
<li>
<p>Read the value of the assigned register of I2C slave device. If succeeded, let <var>regiser value</var> be the value. Otherwise, jump to the step labeled <i>failure</i> below.</p>
</li>
<li>
<p><strong>success</strong>: Call <var>resolver</var>'s <code>accept(<var>value</var>)</code> method with <var>regiser value</var> as <var>value</var> argument. Abort these steps.</p>
</li>
<li>
<p><strong>failure</strong>: Let <var>error</var> be a new <a href="#DOMExceptions"><code>DOMExceptions</code></a>. This must be of type "<code>InvalidAccessError</code>" or "<code>OperatioError</code>".</p>
</li>
</ol>
<p>The <dfn id="write8"><code>write8()</code></dfn> method writes the value passed as the first argument to the related I2C port. The value must be <a href="http://www.w3.org/TR/WebIDL/#idl-octet">octet</a>. When the <a href="#write8"><code>write8()</code></a> method is invoked, the user agent must run the steps as follows:</p>
<ol>
<li>
<p>Let <var>promise</var> be a new <a href="#Promise"><code>Promise</code></a> object and <var>resolver</var> be its associated resolver.</p>
</li>
<li>
<p>Return <var>promise</var> and run the following steps asynchronously.</p>
</li>
<li>
<p>Let <var>value</var> be the value of the first argument passed to this method.</p>
</li>
<li>
<p>If <var>value</var> is out of octet, jump to the step labeled <i>failure</i> below.</p>
</li>
<li>
<p>write <var>value</var> to the assigned register. If succeeded, jump to the step labeled <i>success</i> below. Otherwise, jump to the step labeled <i>failure</i> below.</p>
<p class="open-issue">In I2C, is the confirmation of having failed possible?</p>
</li>
<li>
<p><strong>success</strong>: Call <var>resolver</var>'s <code>accept(<var>value</var>)</code> method with <var>value</var> as <var>value</var> argument. Abort these steps.</p>
</li>
<li>
<p><strong>failure</strong>: Let <var>error</var> be a new <a href="#DOMExceptions"><code>DOMExceptions</code></a>. This must be of type "<code>InvalidAccessError</code>" or "<code>OperatioError</code>".</p>
</li>
</ol>
<!--
<p>The <dfn id="onchange-I2Cport"><code>onchange</code></dfn> attribute is a event handler invoked when the value of the I2C port corresponding to the <a href="#I2CPort"><code>I2CPort</code></a> object changes (i.e. the value changes from 1 to 0 or from 0 to 1). Whenever the event handler is to be invoked, the user agent must run the following steps:</p>
<ol>
<li>
<p>Let <var>port</var> be the <a href="#I2CPort"><code>I2CPort</code></a> object.</p>
</li>
<li>
<p>Let <var>port value</var> be the value of the I2C port corresponding to the <a href="#I2CPort"><code>I2CPort</code></a>.</p>
</li>
<li>
<p>Let <var>event</var> be a newly constructed <a href="#I2CChangeEvent"><code>I2CChangeEvent</code></a>, with the <a href="#value"><code>value</code></a> attribute set to <var>port value</var>, and the <a href="#port"><code>port</code></a> attribute set to <var>port</var>.</p>
</li>
<li>
<p>Fire an event named <code>change</code> at the <a href="#I2CPort"><code>I2CPort</code></a> object, using the <var>event</var> as the event object.</p>
</li>
</ol>
<p class="note">After the <code>change</code> event is fired on the <a href="#I2CPort"><code>I2CPort</code></a> <a href="#I2C-interface"></a> object, another <code>change</code> event will be fired on the <a href="#I2CAccess-interface"><code>I2CAccess</code></a> object. Therefore, the event handler set on the <a href="#I2C-interface"></a> <a href="#I2CPort"><code>I2CPort</code></a> is invoked before the event handler set on the <a href="#I2CAccess-interface"><code>I2CAccess</code></a> object is invoked.</p>
-->
<p>The <dfn id="read16"><code>read16()</code></dfn> and the <dfn id="write16"><code>write16()</code></dfn> are reading and writing methods for 16 bits. Each processing follows <a href="#read8"><code>read8()</code></a> and <a href="#write8"><code>write8()</code></a> except bits length.</p>
<p class="open-issue">Why is there read* write*? What is byte order?</p>
</section>
<!--
<section>
<h3 id="I2CChangeEvent-interface"><span class="secno">5.5 </span> The <code>I2CChangeEvent</code> interface</h3>
<p>When a value of a I2C port changes, if the <a href="#onchange-I2Cport"><code>onchange</code></a> of the <a href="#I2CPort"><code>I2CPort</code></a> object is set to a function, the <a href="#I2CChangeEvent"><code>I2CChangeEvent</code></a> object is passed to the event handler function as the first argument . If the <a href="#onchange-I2Caccess"><code>onchange</code></a> attribute of </p>
<pre class="idl">[Constructor(DOMString <var>type</var>, optional <a href="#I2CChangeEventInit">I2CChangeEventInit</a> <var>eventInitDict</var>)]
interface <dfn id="I2CChangeEvent">I2CChangeEvent</dfn> : <a href="#Event">Event</a> {
readonly attribute unsign short <a href="#value">value</a>;
readonly attribute <a href="#I2CPort">I2CPort</a> <a href="#port">port</a>;
};</pre>
<p>The <dfn id="value"><code>value</code></dfn> attribute must return the value of the I2C port corresponding to the <a href="#I2CPort"><code>I2CPort</code></a> object where the <code>change</code> event was fired..</p>
<p>The <dfn id="port"><code>port</code></dfn> attribute must return the <a href="#I2CPort"><code>I2CPort</code></a> object where the <code>change</code> event was fired.</p>
</section>
<section>
<h3 id="I2CChangeEventInit-interface"><span class="secno">5.6 </span> The <code>I2CChangeEventInit</code> interface</h3>
<pre class="idl">dictionary <dfn id="MIDIMessageEventInit">MIDIMessageEventInit</dfn> : EventInit {
unsign short value;
<a href="#I2CPort">I2CPort</a> port;
};</pre>
<p>The <code>value</code> attribute is a value of the related I2C port.</p>
</section>
-->
<p class="open-issue">We want Events in each slave devices. However, since I2C slave devices are various and unspecified, further investigation for designing general-purpose model is needed. </p>
</section>
<section>
<h2 id="security-considerations"><span class="secno">6 </span> Security considerations</h2>
<p><i>TBD</i></p>
<p>See <a href="https://w3c.github.io/sensors/#security-and-privacy-considerations">Security and privacy considerations</a> on <a href="#generic-sensor-api">[Generic Sensor API]</a>
</section>
<section>
<h2 class="no-num" id="references">References</h2>
<dl>
<dt id="refsDOM4">[DOM4]</dt>
<dd><cite><a href="http://www.w3.org/TR/dom/">DOM4</a></cite>,
Anne van Kesteren, Aryeh Gregor, Ms2ger, Alex Russell, Robin Berjon. W3C.</dd>
<dt id="refsES6">[ES6]</dt>
<dd><cite><a href="http://people.mozilla.org/~jorendorff/es6-draft.html">ECMA-262 6th Edition</a></cite>. Ecma International.</dd>
<dt id="refsHTML5">[HTML5]</dt>
<dd><cite><a href="http://www.w3.org/TR/html5/">HTML5</a></cite>, Robin Berjon, Travis Leithead, Erika Doyle Navara, Edward O'Connor, Silvia Pfeiffer, Ian Hickson. W3C.</dd>
<dt id="refsRFC2119">[RFC2119]</dt>
<dd><cite><a href="http://tools.ietf.org/html/rfc2119">Key words for use in RFCs to Indicate Requirement Levels</a></cite>, S. Bradner. IETF.</dd>
<dt id="refsWEBIDL">[WEBIDL]</dt>
<dd><cite><!-- <a href="http://www.w3.org/TR/WebIDL/"> --><a href="http://heycam.github.io/webidl/">Web IDL</a></cite>, Cameron McCormack. W3C.</dd>
<dt id="refsWEBWORKERS">[WEBWORKERS]</dt>
<dd><cite><a href="http://www.w3.org/TR/workers/">Web Workers</a></cite>, Ian Hickson. W3C.</dd>
<dt id="refsStreams">[STREAMS]</dt>
<dd><cite><a href="http://www.w3.org/TR/streams-api/">Streams API</a></cite>, Feras Moussa, Takeshi Yoshino. W3C.</dd>
<dt id="biblio-powerful-features"><a class="self-link" href="#biblio-powerful-features"></a>[POWERFUL-FEATURES]</dt>
<dd>Mike West; Yan Zhu. <a href="http://www.w3.org/TR/powerful-features/">Privileged Contexts</a>. 24 April 2015. WD. URL: <a href="http://www.w3.org/TR/powerful-features/">http://www.w3.org/TR/powerful-features/</a></dd>
<dt id="generic-sensor-api">[Generic Sensor API]</dt>
<dd><cite><a href="https://w3c.github.io/sensors/">Generic Sensor API</a></cite>, Tobie Langel. Rick Waldron. W3C.</dd>
</dl>
</section>
<section>
<h2 id="acknowledgements">Acknowledgements</h2>
<p>
We would like to sincerely thank <a href="https://lists.w3.org/Archives/Public/public-wot-ig/2015Oct/0042.html">Rick Waldron</a>, Much participants in a MozOpenHard project
to acknowledge their contributions to this work.
</p></section>
</body>
</html>