├── tidyconfig.txt ├── styles └── spec.css ├── README.md ├── .gitignore ├── CONTRIBUTING.md ├── LICENSE ├── respecConfig.js ├── index.html └── images └── logo_serial.svg /tidyconfig.txt: -------------------------------------------------------------------------------- 1 | char-encoding: utf8 2 | indent: yes 3 | wrap: 80 4 | tidy-mark: no 5 | -------------------------------------------------------------------------------- /styles/spec.css: -------------------------------------------------------------------------------- 1 | #speclogo{ 2 | position: absolute; 3 | right: 2em; 4 | top: 4em; 5 | } -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Serial API 2 | 3 | [Serial ports API](http://whatwg.github.io/serial/) for the platform. 4 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | lib-cov 2 | *.seed 3 | *.log 4 | *.csv 5 | *.dat 6 | *.out 7 | *.pid 8 | *.gz 9 | 10 | pids 11 | logs 12 | results 13 | 14 | npm-debug.log 15 | node_modules 16 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | For significant contributions (i.e., non-editorial changes to the API), 2 | we require you to become a member of the 3 | [Web of Sensors CG](http://www.w3.org/community/sensorweb/). This helps 4 | keep the spec royalty free and gives us some patent protection! 5 | 6 | This spec is written using [ReSpec](http://w3.org/respec/). For 7 | configuration options, etc. please see the [ReSpec 8 | refeference](www.w3.org/respec/ref.html). 9 | 10 | Please make sure you run [HTML5 Tidy](http://w3c.github.io/tidy-html5/) 11 | before sending a Pull Request: 12 | 13 | ```Bash 14 | tidy -config tidyconfig.txt -o index.html index.html 15 | ``` 16 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | This is free and unencumbered software released into the public domain. 2 | 3 | Anyone is free to copy, modify, publish, use, compile, sell, or 4 | distribute this software, either in source code form or as a compiled 5 | binary, for any purpose, commercial or non-commercial, and by any 6 | means. 7 | 8 | In jurisdictions that recognize copyright laws, the author or authors 9 | of this software dedicate any and all copyright interest in the 10 | software to the public domain. We make this dedication for the benefit 11 | of the public at large and to the detriment of our heirs and 12 | successors. We intend this dedication to be an overt act of 13 | relinquishment in perpetuity of all present and future rights to this 14 | software under copyright law. 15 | 16 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 17 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 18 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 19 | IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR 20 | OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 21 | ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 22 | OTHER DEALINGS IN THE SOFTWARE. 23 | 24 | For more information, please refer to 25 | -------------------------------------------------------------------------------- /respecConfig.js: -------------------------------------------------------------------------------- 1 | var respecConfig = { 2 | // disable auto generation of tables by ReSpec 3 | noLegacyStyle: true, 4 | format: "markdown", 5 | 6 | // specification status (e.g. WD, LCWD, WG-NOTE, etc.). If in doubt use ED. 7 | specStatus: "unofficial", 8 | 9 | // the specification's short name, as in http://www.w3.org/TR/short-name/ 10 | shortName: "serial", 11 | 12 | // if your specification has a subtitle that goes below the main 13 | // formal title, define it here 14 | subtitle: "Living document", 15 | 16 | // if you wish the publication date to be other than the last modification, set this 17 | // publishDate: "2009-08-06", 18 | 19 | // if the specification's copyright date is a range of years, specify 20 | // the start date here: 21 | // copyrightStart: "2005" 22 | 23 | // if there is a previously published draft, uncomment this and set its YYYY-MM-DD date 24 | // and its maturity status 25 | // previousPublishDate: "1977-03-15", 26 | // previousMaturity: "WD", 27 | 28 | // if there a publicly available Editor's Draft, this is the link 29 | // edDraftURI: "http://berjon.com/", 30 | 31 | // if this is a LCWD, uncomment and set the end of its review period 32 | // lcEnd: "2009-08-05", 33 | 34 | // editors, add as many as you like 35 | // only "name" is required 36 | editors: [ 37 | { 38 | name: "See contributors on GH", 39 | url: "https://github.com/whatwg/serial/graphs/contributors" 40 | }, 41 | ], 42 | 43 | // name of the WG 44 | wg: "A Web of Sensors Community Group / WHATWG Joint", 45 | 46 | // URI of the public WG page 47 | wgURI: "http://www.w3.org/community/sensorweb/", 48 | 49 | // name (without the @w3c.org) of the public mailing to which comments are due 50 | wgPublicList: "public-sensorweb", 51 | 52 | // URI of the patent status for this WG, for Rec-track documents 53 | // !!!! IMPORTANT !!!! 54 | // This is important for Rec-track documents, do not copy a patent URI from a random 55 | // document unless you know what you're doing. If in doubt ask your friendly neighbourhood 56 | // Team Contact. 57 | wgPatentURI: "", 58 | // !!!! IMPORTANT !!!! MAKE THE ABOVE BLINK IN YOUR HEAD 59 | otherLinks: [{ 60 | key: "Repository", 61 | data: [ 62 | { 63 | href: "https://github.com/whatwg/serial" 64 | }, 65 | { 66 | value: "issues", 67 | href: "https://github.com/whatwg/serial/issues" 68 | }, 69 | { 70 | value: "Commit History.", 71 | href: "https://github.com/ResponsiveImagesCG/ri-usecases/commits/gh-pages" 72 | }] 73 | }], 74 | localBiblio: { 75 | STREAMS: { 76 | "authors": ["Domenic Denicola"], 77 | "href": "https://github.com/whatwg/streams", 78 | "title": "Streams API", 79 | "status": "unofficial", 80 | "publisher": "WHATWG", 81 | } 82 | }, 83 | additionalCopyrightHolders: "CC0 To the extent possible under law, the editor has waived all copyright and related or neighboring rights to this work. In addition, as of 25 October 2013, the editor has made this specification available under the Open Web Foundation Agreement Version 1.0, which is available at http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-0.", 84 | }; 85 | -------------------------------------------------------------------------------- /index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | Serial API 4 | 5 | 6 | 7 | 8 | 9 | 10 |
11 | The Serial API provides a way for websites to read and write from a 12 | serial device through script. Such an API would bridge the web and the 13 | physical world, by allowing documents to communicate with devices such 14 | as microcontrollers, 3D printers, and other serial devices. 15 |
16 | 17 |
18 | This is a work in progress. All [contributions](https://github.com/whatwg/serial) 19 | welcome. 20 |
21 | 22 | ## Usage example 23 | This example shows how to find the first "Arduino" device and set it up for use. 24 | 25 | 
 26 | // Request the list of ports from the user
 27 | SerialPort.requestList().then(ports => {
 28 |   // Pick the first matching port
 29 |   var serial,
 30 |       kind = "Arduino"
 31 |       arduinos = ports.filter(port => port.manufacturer.contains(kind));
 32 | 
 33 |   if (arduinos.length) {
 34 |      serial = new SerialPort(arduinos[0].path);
 35 |      serial.in.read(readData)
 36 |   }
 37 | 
 38 |   function readData(){
 39 |     while(let data = yield serial.read()) {
 40 |       console.log(data);
 41 |     }
 42 |   }
 43 | })
 44 | .catch(console.error);
 45 |
46 | 47 | ## `SerialPort` interface 48 |
49 |
50 | static Promise requestList() 51 |
52 |
53 | readonly attribute ReadableStream in 54 |
55 |
56 | readonly attribute WritableStream out 57 |
58 |
59 | readonly attribute DOMString path 60 |
61 |
62 | readonly attribute unsigned long bufferSize 63 |
64 |
65 | 66 | The `ReadableStream` and `WritableStream` interfaces are 67 | defined in [[!STREAMS]]. 68 | 69 | ## `SerialPortDetails` dictionary 70 |
71 |
72 | DOMString comName 73 |
74 |
75 | DOMString path 76 |
77 |
78 | DOMString pnpId 79 |
80 |
81 | DOMString manufacturer 82 |
83 |
84 | DOMString locationID 85 |
86 |
87 | DOMString vendorID 88 |
89 |
90 | DOMString productId 91 |
92 |
93 | DOMString serialNumber 94 |
95 |
96 | 97 | ## `SerialOptions` dictionary 98 |
99 |
100 | long baudrate = 9600 101 |
102 |
103 | One of 115200, 57600, 38400, 19200, 9600, 4800, 2400, 1800, 1200, 104 | 600, 300, 200, 150, 134, 110, 75, or 50. 105 |
106 |
107 | octet databits = 8 108 |
109 |
110 | One of 8, 7, 6, or 5. 111 |
112 |
113 | octet stopbits = 1 114 |
115 |
116 | One of 1 or 2. 117 |
118 |
119 | ParityType parity = 'none' 120 |
121 |
122 | The parity type. 123 |
124 |
125 | long buffersize = 255 126 |
127 |
128 | boolean rtscts = false 129 |
130 |
131 | boolean xon = false 132 |
133 |
134 | boolean xoff = false 135 |
136 |
137 | boolean xany = false 138 |
139 |
140 | 141 | ## `ParityType` enum 142 |
143 |
144 | none 145 |
146 |
147 | even 148 |
149 |
150 | mark 151 |
152 |
153 | odd 154 |
155 |
156 | space 157 |
158 |
159 | 160 | ## Security Considerations 161 | User agents must not grant Web sites access to any serial ports without 162 | the express permission of the user. A conforming implementation of this 163 | specification must provide a means for user to control which serial 164 | ports the API can access, as well as a means for the end-user to be 165 | able to revoke all access to serial ports. 166 | 167 | ## Use cases and requirements 168 | 169 | ### Hardware disconnection 170 | Some devices allow users to manually reset the connection between the user 171 | agent and the physical device (e.g., by pushing a button). One example 172 | device is the Arduino. Another example is the user abruptly disconnecting 173 | one device from another, thus severing the communication channel. 174 | 175 | As such, it is a requirement that the API gracefully handle abrupt 176 | disconnection caused by a reset or other event. When such disconnections 177 | occur, the API must make it possible for the developer to be notified of such 178 | disconnections. When possible, the API should provide details about the 179 | disconnection (e.g., reason, time, etc.). 180 | 181 | ### Baud rates 182 | Traditionally, serial devices have operated at 183 | [baud rates](http://en.wikipedia.org/wiki/Baud) 184 | of between 50 and 115,200 bps. 185 | 186 | However, modern USB serial devices are able to operate at significantly higher 187 | baud rates than legacy hardware. For example, the 188 | [bioloid servos](http://support.robotis.com/en/techsupport_eng.htm#product/dynamixel/ax_series/dxl_ax_actuator.htm) 189 | operate at 1 Mbit (1,000,000 bps). Other USB-to-serial chips are able to 190 | operate at 3 MBit (3,000,000bps). 191 | 192 | Additionally, other serial devices have standardized baud rates that 193 | are not in the commonly accepted value for baud rates. For example, 194 | [MIDI](http://en.wikipedia.org/wiki/MIDI) uses a baud rate of 31,250 bps, 195 | while a [DMX512 controller](http://en.wikipedia.org/wiki/DMX512) 196 | transmits data at 250kbps. 197 | 198 | As such, it is a requirement that the Serial API does not limit the 199 | baud rates to a traditional range. Instead, the API must allow a 200 | developer to specify any rate so long as the value is an unsigned number. 201 | If there is a baud rate that is common for a large range of hardware that 202 | will make use of this API, the API should provide a default baud rate value. 203 | 204 | Given the above requirement, it is possible to create software to wrap the 205 | Serial API to restrict the possible baud rates used for communicating with some 206 | particular hardware. For example, a JavaScript library that communicates with 207 | a MIDI device could automatically set the baud rate to 31,250 bps without 208 | needing to bother the developer to specify the value. 209 | 210 | 211 | 212 |
213 | ## Acknowledgements 214 | ... coming soon... 215 |
216 | 217 | -------------------------------------------------------------------------------- /images/logo_serial.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | WHATWG Serial API logo 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | --------------------------------------------------------------------------------