├── .npmignore ├── .gitignore ├── tsconfig.json ├── .github └── workflows │ ├── npm_publish.yml │ └── node.js.yml ├── README.md ├── .eslintrc.cjs ├── CONTRIBUTING.md ├── package.json ├── LICENSE └── serial.ts /.npmignore: -------------------------------------------------------------------------------- 1 | node_modules/ 2 | package-lock.json 3 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | dist/ 2 | node_modules/ 3 | package-lock.json 4 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "module": "es2015", 4 | "lib": ["es2017"], 5 | "outDir": "./dist/", 6 | "sourceMap": true, 7 | "noImplicitAny": true, 8 | "strictNullChecks": true, 9 | "target": "es2017", 10 | "declaration": true 11 | } 12 | } 13 | -------------------------------------------------------------------------------- /.github/workflows/npm_publish.yml: -------------------------------------------------------------------------------- 1 | # This workflow will do a clean install of node dependencies, build the source code and publish the code to the web-serial-polyfill npm package 2 | # For more information see: https://github.com/marketplace/actions/npm-publish 3 | 4 | name: NPM publish 5 | 6 | on: 7 | push: 8 | branches: [ main ] 9 | 10 | jobs: 11 | build: 12 | 13 | runs-on: ubuntu-latest 14 | 15 | steps: 16 | - uses: actions/checkout@v2 17 | - uses: actions/setup-node@v1 18 | with: 19 | node-version: '18' 20 | - run: npm install 21 | - run: npm run build 22 | - uses: JS-DevTools/npm-publish@v1 23 | with: 24 | token: ${{ secrets.NPM_TOKEN }} 25 | -------------------------------------------------------------------------------- /.github/workflows/node.js.yml: -------------------------------------------------------------------------------- 1 | # This workflow will do a clean install of node dependencies, build the source code and run tests across different versions of node 2 | # For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions 3 | 4 | name: Node.js CI 5 | 6 | on: 7 | push: 8 | branches: [ main ] 9 | pull_request: 10 | branches: [ main ] 11 | 12 | jobs: 13 | build: 14 | 15 | runs-on: ubuntu-latest 16 | 17 | strategy: 18 | matrix: 19 | node-version: [14.x, 16.x, 18.x] 20 | # See supported Node.js release schedule at https://nodejs.org/en/about/releases/ 21 | 22 | steps: 23 | - uses: actions/checkout@v2 24 | - name: Use Node.js ${{ matrix.node-version }} 25 | uses: actions/setup-node@v1 26 | with: 27 | node-version: ${{ matrix.node-version }} 28 | - run: npm install 29 | - run: npm run build 30 | - run: npm run lint 31 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Serial API Polyfill 2 | 3 | An implementation of the [Web Serial API](https://wicg.github.io/serial) on top 4 | of the [WebUSB API](https://wicg.github.io/webusb) for use with USB-to-serial 5 | adapters. Use of this library is limited to hardware and platforms where the 6 | device is accessible via the WebUSB API because it has not been claimed by a 7 | built-in device driver. This project was used to prototype the design of 8 | the Web Serial API and remains useful for platforms (such as Android) which 9 | support the WebUSB API but do not support the Web Serial API. 10 | 11 | This is also available as an npm package 12 | [here](https://www.npmjs.com/package/web-serial-polyfill) for convenience. 13 | 14 | A demo of this library is provided as part of the 15 | [serial terminal demo](https://github.com/GoogleChromeLabs/serial-terminal) 16 | and can be activated by clicking the 17 | "[Switch to API polyfill](https://googlechromelabs.github.io/serial-terminal/?polyfill)" 18 | link. 19 | -------------------------------------------------------------------------------- /.eslintrc.cjs: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2019 Google LLC 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the 5 | * "License"); you may not use this file except in 6 | * compliance with the License. You may obtain a copy of 7 | * the License at 8 | * 9 | * https://www.apache.org/licenses/LICENSE-2.0 10 | * 11 | * Unless required by applicable law or agreed to in 12 | * writing, software distributed under the License is 13 | * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES 14 | * OR CONDITIONS OF ANY KIND, either express or implied. 15 | * See the License for the specific language governing 16 | * permissions and limitations under the License. 17 | */ 18 | 19 | module.exports = { 20 | "extends": [ 21 | "eslint:recommended", 22 | "plugin:@typescript-eslint/eslint-recommended", 23 | "plugin:@typescript-eslint/recommended", 24 | "google" 25 | ], 26 | "env": { 27 | "browser": true, 28 | "es6": true 29 | }, 30 | "parser": "@typescript-eslint/parser", 31 | "plugins": ["@typescript-eslint"], 32 | } 33 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # How to Contribute 2 | 3 | We'd love to accept your patches and contributions to this project. There are 4 | just a few small guidelines you need to follow. 5 | 6 | ## Contributor License Agreement 7 | 8 | Contributions to this project must be accompanied by a Contributor License 9 | Agreement. You (or your employer) retain the copyright to your contribution; 10 | this simply gives us permission to use and redistribute your contributions as 11 | part of the project. Head over to to see 12 | your current agreements on file or to sign a new one. 13 | 14 | You generally only need to submit a CLA once, so if you've already submitted one 15 | (even if it was for a different project), you probably don't need to do it 16 | again. 17 | 18 | ## Code reviews 19 | 20 | All submissions, including submissions by project members, require review. We 21 | use GitHub pull requests for this purpose. Consult 22 | [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more 23 | information on using pull requests. 24 | 25 | ## Community Guidelines 26 | 27 | This project follows [Google's Open Source Community 28 | Guidelines](https://opensource.google.com/conduct/). 29 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "web-serial-polyfill", 3 | "version": "1.0.15", 4 | "description": "An implementation of the [Serial API](https://wicg.github.io/serial) on top of the [WebUSB API](https://wicg.github.io/webusb) for use with USB-to-serial adapters. Use of this library is limited to hardware and platforms where the device is accessible via the WebUSB API because it has not been claimed by a built-in device driver. This project will be used to prototype the design of the Serial API.", 5 | "type": "module", 6 | "main": "./dist/serial.js", 7 | "types": "./dist/serial.d.ts", 8 | "scripts": { 9 | "lint": "eslint serial.ts", 10 | "build": "tsc -d", 11 | "prepublish": "tsc -d" 12 | }, 13 | "repository": { 14 | "type": "git", 15 | "url": "https://github.com/google/web-serial-polyfill.git" 16 | }, 17 | "author": "James C Hollyer", 18 | "license": "Apache", 19 | "devDependencies": { 20 | "@types/w3c-web-serial": "^1.0.3", 21 | "@types/w3c-web-usb": "^1.0.6", 22 | "@types/web": "^0.0.71", 23 | "@typescript-eslint/eslint-plugin": "^5.33.0", 24 | "@typescript-eslint/parser": "^5.33.0", 25 | "eslint": "^8.21.0", 26 | "eslint-config-google": "^0.14.0", 27 | "typescript": "^4.7.4" 28 | } 29 | } 30 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | 2 | Apache License 3 | Version 2.0, January 2004 4 | http://www.apache.org/licenses/ 5 | 6 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 7 | 8 | 1. Definitions. 9 | 10 | "License" shall mean the terms and conditions for use, reproduction, 11 | and distribution as defined by Sections 1 through 9 of this document. 12 | 13 | "Licensor" shall mean the copyright owner or entity authorized by 14 | the copyright owner that is granting the License. 15 | 16 | "Legal Entity" shall mean the union of the acting entity and all 17 | other entities that control, are controlled by, or are under common 18 | control with that entity. For the purposes of this definition, 19 | "control" means (i) the power, direct or indirect, to cause the 20 | direction or management of such entity, whether by contract or 21 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 22 | outstanding shares, or (iii) beneficial ownership of such entity. 23 | 24 | "You" (or "Your") shall mean an individual or Legal Entity 25 | exercising permissions granted by this License. 26 | 27 | "Source" form shall mean the preferred form for making modifications, 28 | including but not limited to software source code, documentation 29 | source, and configuration files. 30 | 31 | "Object" form shall mean any form resulting from mechanical 32 | transformation or translation of a Source form, including but 33 | not limited to compiled object code, generated documentation, 34 | and conversions to other media types. 35 | 36 | "Work" shall mean the work of authorship, whether in Source or 37 | Object form, made available under the License, as indicated by a 38 | copyright notice that is included in or attached to the work 39 | (an example is provided in the Appendix below). 40 | 41 | "Derivative Works" shall mean any work, whether in Source or Object 42 | form, that is based on (or derived from) the Work and for which the 43 | editorial revisions, annotations, elaborations, or other modifications 44 | represent, as a whole, an original work of authorship. For the purposes 45 | of this License, Derivative Works shall not include works that remain 46 | separable from, or merely link (or bind by name) to the interfaces of, 47 | the Work and Derivative Works thereof. 48 | 49 | "Contribution" shall mean any work of authorship, including 50 | the original version of the Work and any modifications or additions 51 | to that Work or Derivative Works thereof, that is intentionally 52 | submitted to Licensor for inclusion in the Work by the copyright owner 53 | or by an individual or Legal Entity authorized to submit on behalf of 54 | the copyright owner. For the purposes of this definition, "submitted" 55 | means any form of electronic, verbal, or written communication sent 56 | to the Licensor or its representatives, including but not limited to 57 | communication on electronic mailing lists, source code control systems, 58 | and issue tracking systems that are managed by, or on behalf of, the 59 | Licensor for the purpose of discussing and improving the Work, but 60 | excluding communication that is conspicuously marked or otherwise 61 | designated in writing by the copyright owner as "Not a Contribution." 62 | 63 | "Contributor" shall mean Licensor and any individual or Legal Entity 64 | on behalf of whom a Contribution has been received by Licensor and 65 | subsequently incorporated within the Work. 66 | 67 | 2. Grant of Copyright License. Subject to the terms and conditions of 68 | this License, each Contributor hereby grants to You a perpetual, 69 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 70 | copyright license to reproduce, prepare Derivative Works of, 71 | publicly display, publicly perform, sublicense, and distribute the 72 | Work and such Derivative Works in Source or Object form. 73 | 74 | 3. Grant of Patent License. Subject to the terms and conditions of 75 | this License, each Contributor hereby grants to You a perpetual, 76 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 77 | (except as stated in this section) patent license to make, have made, 78 | use, offer to sell, sell, import, and otherwise transfer the Work, 79 | where such license applies only to those patent claims licensable 80 | by such Contributor that are necessarily infringed by their 81 | Contribution(s) alone or by combination of their Contribution(s) 82 | with the Work to which such Contribution(s) was submitted. If You 83 | institute patent litigation against any entity (including a 84 | cross-claim or counterclaim in a lawsuit) alleging that the Work 85 | or a Contribution incorporated within the Work constitutes direct 86 | or contributory patent infringement, then any patent licenses 87 | granted to You under this License for that Work shall terminate 88 | as of the date such litigation is filed. 89 | 90 | 4. Redistribution. You may reproduce and distribute copies of the 91 | Work or Derivative Works thereof in any medium, with or without 92 | modifications, and in Source or Object form, provided that You 93 | meet the following conditions: 94 | 95 | (a) You must give any other recipients of the Work or 96 | Derivative Works a copy of this License; and 97 | 98 | (b) You must cause any modified files to carry prominent notices 99 | stating that You changed the files; and 100 | 101 | (c) You must retain, in the Source form of any Derivative Works 102 | that You distribute, all copyright, patent, trademark, and 103 | attribution notices from the Source form of the Work, 104 | excluding those notices that do not pertain to any part of 105 | the Derivative Works; and 106 | 107 | (d) If the Work includes a "NOTICE" text file as part of its 108 | distribution, then any Derivative Works that You distribute must 109 | include a readable copy of the attribution notices contained 110 | within such NOTICE file, excluding those notices that do not 111 | pertain to any part of the Derivative Works, in at least one 112 | of the following places: within a NOTICE text file distributed 113 | as part of the Derivative Works; within the Source form or 114 | documentation, if provided along with the Derivative Works; or, 115 | within a display generated by the Derivative Works, if and 116 | wherever such third-party notices normally appear. The contents 117 | of the NOTICE file are for informational purposes only and 118 | do not modify the License. You may add Your own attribution 119 | notices within Derivative Works that You distribute, alongside 120 | or as an addendum to the NOTICE text from the Work, provided 121 | that such additional attribution notices cannot be construed 122 | as modifying the License. 123 | 124 | You may add Your own copyright statement to Your modifications and 125 | may provide additional or different license terms and conditions 126 | for use, reproduction, or distribution of Your modifications, or 127 | for any such Derivative Works as a whole, provided Your use, 128 | reproduction, and distribution of the Work otherwise complies with 129 | the conditions stated in this License. 130 | 131 | 5. Submission of Contributions. Unless You explicitly state otherwise, 132 | any Contribution intentionally submitted for inclusion in the Work 133 | by You to the Licensor shall be under the terms and conditions of 134 | this License, without any additional terms or conditions. 135 | Notwithstanding the above, nothing herein shall supersede or modify 136 | the terms of any separate license agreement you may have executed 137 | with Licensor regarding such Contributions. 138 | 139 | 6. Trademarks. This License does not grant permission to use the trade 140 | names, trademarks, service marks, or product names of the Licensor, 141 | except as required for reasonable and customary use in describing the 142 | origin of the Work and reproducing the content of the NOTICE file. 143 | 144 | 7. Disclaimer of Warranty. Unless required by applicable law or 145 | agreed to in writing, Licensor provides the Work (and each 146 | Contributor provides its Contributions) on an "AS IS" BASIS, 147 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 148 | implied, including, without limitation, any warranties or conditions 149 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 150 | PARTICULAR PURPOSE. You are solely responsible for determining the 151 | appropriateness of using or redistributing the Work and assume any 152 | risks associated with Your exercise of permissions under this License. 153 | 154 | 8. Limitation of Liability. In no event and under no legal theory, 155 | whether in tort (including negligence), contract, or otherwise, 156 | unless required by applicable law (such as deliberate and grossly 157 | negligent acts) or agreed to in writing, shall any Contributor be 158 | liable to You for damages, including any direct, indirect, special, 159 | incidental, or consequential damages of any character arising as a 160 | result of this License or out of the use or inability to use the 161 | Work (including but not limited to damages for loss of goodwill, 162 | work stoppage, computer failure or malfunction, or any and all 163 | other commercial damages or losses), even if such Contributor 164 | has been advised of the possibility of such damages. 165 | 166 | 9. Accepting Warranty or Additional Liability. While redistributing 167 | the Work or Derivative Works thereof, You may choose to offer, 168 | and charge a fee for, acceptance of support, warranty, indemnity, 169 | or other liability obligations and/or rights consistent with this 170 | License. However, in accepting such obligations, You may act only 171 | on Your own behalf and on Your sole responsibility, not on behalf 172 | of any other Contributor, and only if You agree to indemnify, 173 | defend, and hold each Contributor harmless for any liability 174 | incurred by, or claims asserted against, such Contributor by reason 175 | of your accepting any such warranty or additional liability. 176 | 177 | END OF TERMS AND CONDITIONS 178 | 179 | APPENDIX: How to apply the Apache License to your work. 180 | 181 | To apply the Apache License to your work, attach the following 182 | boilerplate notice, with the fields enclosed by brackets "[]" 183 | replaced with your own identifying information. (Don't include 184 | the brackets!) The text should be enclosed in the appropriate 185 | comment syntax for the file format. We also recommend that a 186 | file or class name and description of purpose be included on the 187 | same "printed page" as the copyright notice for easier 188 | identification within third-party archives. 189 | 190 | Copyright [yyyy] [name of copyright owner] 191 | 192 | Licensed under the Apache License, Version 2.0 (the "License"); 193 | you may not use this file except in compliance with the License. 194 | You may obtain a copy of the License at 195 | 196 | http://www.apache.org/licenses/LICENSE-2.0 197 | 198 | Unless required by applicable law or agreed to in writing, software 199 | distributed under the License is distributed on an "AS IS" BASIS, 200 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 201 | See the License for the specific language governing permissions and 202 | limitations under the License. 203 | -------------------------------------------------------------------------------- /serial.ts: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2019 Google LLC 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the 5 | * "License"); you may not use this file except in 6 | * compliance with the License. You may obtain a copy of 7 | * the License at 8 | * 9 | * https://www.apache.org/licenses/LICENSE-2.0 10 | * 11 | * Unless required by applicable law or agreed to in 12 | * writing, software distributed under the License is 13 | * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES 14 | * OR CONDITIONS OF ANY KIND, either express or implied. 15 | * See the License for the specific language governing 16 | * permissions and limitations under the License. 17 | */ 18 | 'use strict'; 19 | 20 | export enum SerialPolyfillProtocol { 21 | UsbCdcAcm, // eslint-disable-line no-unused-vars 22 | } 23 | 24 | export interface SerialPolyfillOptions { 25 | protocol?: SerialPolyfillProtocol; 26 | usbControlInterfaceClass?: number; 27 | usbTransferInterfaceClass?: number; 28 | } 29 | 30 | const kSetLineCoding = 0x20; 31 | const kSetControlLineState = 0x22; 32 | const kSendBreak = 0x23; 33 | 34 | const kDefaultBufferSize = 255; 35 | const kDefaultDataBits = 8; 36 | const kDefaultParity = 'none'; 37 | const kDefaultStopBits = 1; 38 | 39 | const kAcceptableDataBits = [16, 8, 7, 6, 5]; 40 | const kAcceptableStopBits = [1, 2]; 41 | const kAcceptableParity = ['none', 'even', 'odd']; 42 | 43 | const kParityIndexMapping: ParityType[] = 44 | ['none', 'odd', 'even']; 45 | const kStopBitsIndexMapping = [1, 1.5, 2]; 46 | 47 | const kDefaultPolyfillOptions = { 48 | protocol: SerialPolyfillProtocol.UsbCdcAcm, 49 | usbControlInterfaceClass: 2, 50 | usbTransferInterfaceClass: 10, 51 | }; 52 | 53 | /** 54 | * Utility function to get the interface implementing a desired class. 55 | * @param {USBDevice} device The USB device. 56 | * @param {number} classCode The desired interface class. 57 | * @return {USBInterface} The first interface found that implements the desired 58 | * class. 59 | * @throws TypeError if no interface is found. 60 | */ 61 | function findInterface(device: USBDevice, classCode: number): USBInterface { 62 | const configuration = device.configurations[0]; 63 | for (const iface of configuration.interfaces) { 64 | const alternate = iface.alternates[0]; 65 | if (alternate.interfaceClass === classCode) { 66 | return iface; 67 | } 68 | } 69 | throw new TypeError(`Unable to find interface with class ${classCode}.`); 70 | } 71 | 72 | /** 73 | * Utility function to get an endpoint with a particular direction. 74 | * @param {USBInterface} iface The interface to search. 75 | * @param {USBDirection} direction The desired transfer direction. 76 | * @return {USBEndpoint} The first endpoint with the desired transfer direction. 77 | * @throws TypeError if no endpoint is found. 78 | */ 79 | function findEndpoint(iface: USBInterface, direction: USBDirection): 80 | USBEndpoint { 81 | const alternate = iface.alternates[0]; 82 | for (const endpoint of alternate.endpoints) { 83 | if (endpoint.direction == direction) { 84 | return endpoint; 85 | } 86 | } 87 | throw new TypeError(`Interface ${iface.interfaceNumber} does not have an ` + 88 | `${direction} endpoint.`); 89 | } 90 | 91 | /** 92 | * Implementation of the underlying source API[1] which reads data from a USB 93 | * endpoint. This can be used to construct a ReadableStream. 94 | * 95 | * [1]: https://streams.spec.whatwg.org/#underlying-source-api 96 | */ 97 | class UsbEndpointUnderlyingSource implements UnderlyingByteSource { 98 | private device_: USBDevice; 99 | private endpoint_: USBEndpoint; 100 | private onError_: () => void; 101 | 102 | type: 'bytes'; 103 | 104 | /** 105 | * Constructs a new UnderlyingSource that will pull data from the specified 106 | * endpoint on the given USB device. 107 | * 108 | * @param {USBDevice} device 109 | * @param {USBEndpoint} endpoint 110 | * @param {function} onError function to be called on error 111 | */ 112 | constructor(device: USBDevice, endpoint: USBEndpoint, onError: () => void) { 113 | this.type = 'bytes'; 114 | this.device_ = device; 115 | this.endpoint_ = endpoint; 116 | this.onError_ = onError; 117 | } 118 | 119 | /** 120 | * Reads a chunk of data from the device. 121 | * 122 | * @param {ReadableByteStreamController} controller 123 | */ 124 | pull(controller: ReadableByteStreamController): void { 125 | (async (): Promise => { 126 | let chunkSize; 127 | if (controller.desiredSize) { 128 | const d = controller.desiredSize / this.endpoint_.packetSize; 129 | chunkSize = Math.ceil(d) * this.endpoint_.packetSize; 130 | } else { 131 | chunkSize = this.endpoint_.packetSize; 132 | } 133 | 134 | try { 135 | const result = await this.device_.transferIn( 136 | this.endpoint_.endpointNumber, chunkSize); 137 | if (result.status != 'ok') { 138 | controller.error(`USB error: ${result.status}`); 139 | this.onError_(); 140 | } 141 | if (result.data?.buffer) { 142 | const chunk = new Uint8Array( 143 | result.data.buffer, result.data.byteOffset, 144 | result.data.byteLength); 145 | controller.enqueue(chunk); 146 | } 147 | } catch (error) { 148 | controller.error(error.toString()); 149 | this.onError_(); 150 | } 151 | })(); 152 | } 153 | } 154 | 155 | /** 156 | * Implementation of the underlying sink API[2] which writes data to a USB 157 | * endpoint. This can be used to construct a WritableStream. 158 | * 159 | * [2]: https://streams.spec.whatwg.org/#underlying-sink-api 160 | */ 161 | class UsbEndpointUnderlyingSink implements UnderlyingSink { 162 | private device_: USBDevice; 163 | private endpoint_: USBEndpoint; 164 | private onError_: () => void; 165 | 166 | /** 167 | * Constructs a new UnderlyingSink that will write data to the specified 168 | * endpoint on the given USB device. 169 | * 170 | * @param {USBDevice} device 171 | * @param {USBEndpoint} endpoint 172 | * @param {function} onError function to be called on error 173 | */ 174 | constructor(device: USBDevice, endpoint: USBEndpoint, onError: () => void) { 175 | this.device_ = device; 176 | this.endpoint_ = endpoint; 177 | this.onError_ = onError; 178 | } 179 | 180 | /** 181 | * Writes a chunk to the device. 182 | * 183 | * @param {Uint8Array} chunk 184 | * @param {WritableStreamDefaultController} controller 185 | */ 186 | async write( 187 | chunk: Uint8Array, 188 | controller: WritableStreamDefaultController): Promise { 189 | try { 190 | const result = 191 | await this.device_.transferOut(this.endpoint_.endpointNumber, chunk); 192 | if (result.status != 'ok') { 193 | controller.error(result.status); 194 | this.onError_(); 195 | } 196 | } catch (error) { 197 | controller.error(error.toString()); 198 | this.onError_(); 199 | } 200 | } 201 | } 202 | 203 | /** a class used to control serial devices over WebUSB */ 204 | export class SerialPort { 205 | private polyfillOptions_: SerialPolyfillOptions; 206 | private device_: USBDevice; 207 | private controlInterface_: USBInterface; 208 | private transferInterface_: USBInterface; 209 | private inEndpoint_: USBEndpoint; 210 | private outEndpoint_: USBEndpoint; 211 | 212 | private serialOptions_: SerialOptions; 213 | private readable_: ReadableStream | null; 214 | private writable_: WritableStream | null; 215 | private outputSignals_: SerialOutputSignals; 216 | 217 | /** 218 | * constructor taking a WebUSB device that creates a SerialPort instance. 219 | * @param {USBDevice} device A device acquired from the WebUSB API 220 | * @param {SerialPolyfillOptions} polyfillOptions Optional options to 221 | * configure the polyfill. 222 | */ 223 | public constructor( 224 | device: USBDevice, 225 | polyfillOptions?: SerialPolyfillOptions) { 226 | this.polyfillOptions_ = {...kDefaultPolyfillOptions, ...polyfillOptions}; 227 | this.outputSignals_ = { 228 | dataTerminalReady: false, 229 | requestToSend: false, 230 | break: false, 231 | }; 232 | 233 | this.device_ = device; 234 | this.controlInterface_ = findInterface( 235 | this.device_, 236 | this.polyfillOptions_.usbControlInterfaceClass as number); 237 | this.transferInterface_ = findInterface( 238 | this.device_, 239 | this.polyfillOptions_.usbTransferInterfaceClass as number); 240 | this.inEndpoint_ = findEndpoint(this.transferInterface_, 'in'); 241 | this.outEndpoint_ = findEndpoint(this.transferInterface_, 'out'); 242 | } 243 | 244 | /** 245 | * Getter for the readable attribute. Constructs a new ReadableStream as 246 | * necessary. 247 | * @return {ReadableStream} the current readable stream 248 | */ 249 | public get readable(): ReadableStream | null { 250 | if (!this.readable_ && this.device_.opened) { 251 | this.readable_ = new ReadableStream( 252 | new UsbEndpointUnderlyingSource( 253 | this.device_, this.inEndpoint_, () => { 254 | this.readable_ = null; 255 | }), 256 | { 257 | highWaterMark: this.serialOptions_.bufferSize ?? kDefaultBufferSize, 258 | }); 259 | } 260 | return this.readable_; 261 | } 262 | 263 | /** 264 | * Getter for the writable attribute. Constructs a new WritableStream as 265 | * necessary. 266 | * @return {WritableStream} the current writable stream 267 | */ 268 | public get writable(): WritableStream | null { 269 | if (!this.writable_ && this.device_.opened) { 270 | this.writable_ = new WritableStream( 271 | new UsbEndpointUnderlyingSink( 272 | this.device_, this.outEndpoint_, () => { 273 | this.writable_ = null; 274 | }), 275 | new ByteLengthQueuingStrategy({ 276 | highWaterMark: this.serialOptions_.bufferSize ?? kDefaultBufferSize, 277 | })); 278 | } 279 | return this.writable_; 280 | } 281 | 282 | /** 283 | * a function that opens the device and claims all interfaces needed to 284 | * control and communicate to and from the serial device 285 | * @param {SerialOptions} options Object containing serial options 286 | * @return {Promise} A promise that will resolve when device is ready 287 | * for communication 288 | */ 289 | public async open(options: SerialOptions): Promise { 290 | this.serialOptions_ = options; 291 | this.validateOptions(); 292 | 293 | try { 294 | await this.device_.open(); 295 | if (this.device_.configuration === null) { 296 | await this.device_.selectConfiguration(1); 297 | } 298 | 299 | await this.device_.claimInterface(this.controlInterface_.interfaceNumber); 300 | if (this.controlInterface_ !== this.transferInterface_) { 301 | await this.device_.claimInterface( 302 | this.transferInterface_.interfaceNumber); 303 | } 304 | 305 | await this.setLineCoding(); 306 | await this.setSignals({dataTerminalReady: true}); 307 | } catch (error) { 308 | if (this.device_.opened) { 309 | await this.device_.close(); 310 | } 311 | throw new Error('Error setting up device: ' + error.toString()); 312 | } 313 | } 314 | 315 | /** 316 | * Closes the port. 317 | * 318 | * @return {Promise} A promise that will resolve when the port is 319 | * closed. 320 | */ 321 | public async close(): Promise { 322 | const promises = []; 323 | if (this.readable_) { 324 | promises.push(this.readable_.cancel()); 325 | } 326 | if (this.writable_) { 327 | promises.push(this.writable_.abort()); 328 | } 329 | await Promise.all(promises); 330 | this.readable_ = null; 331 | this.writable_ = null; 332 | if (this.device_.opened) { 333 | await this.setSignals({dataTerminalReady: false, requestToSend: false}); 334 | await this.device_.close(); 335 | } 336 | } 337 | 338 | /** 339 | * Forgets the port. 340 | * 341 | * @return {Promise} A promise that will resolve when the port is 342 | * forgotten. 343 | */ 344 | public async forget(): Promise { 345 | return this.device_.forget(); 346 | } 347 | 348 | /** 349 | * A function that returns properties of the device. 350 | * @return {SerialPortInfo} Device properties. 351 | */ 352 | public getInfo(): SerialPortInfo { 353 | return { 354 | usbVendorId: this.device_.vendorId, 355 | usbProductId: this.device_.productId, 356 | }; 357 | } 358 | 359 | /** 360 | * A function used to change the serial settings of the device 361 | * @param {object} options the object which carries serial settings data 362 | * @return {Promise} A promise that will resolve when the options are 363 | * set 364 | */ 365 | public reconfigure(options: SerialOptions): Promise { 366 | this.serialOptions_ = {...this.serialOptions_, ...options}; 367 | this.validateOptions(); 368 | return this.setLineCoding(); 369 | } 370 | 371 | /** 372 | * Sets control signal state for the port. 373 | * @param {SerialOutputSignals} signals The signals to enable or disable. 374 | * @return {Promise} a promise that is resolved when the signal state 375 | * has been changed. 376 | */ 377 | public async setSignals(signals: SerialOutputSignals): Promise { 378 | this.outputSignals_ = {...this.outputSignals_, ...signals}; 379 | 380 | if (signals.dataTerminalReady !== undefined || 381 | signals.requestToSend !== undefined) { 382 | // The Set_Control_Line_State command expects a bitmap containing the 383 | // values of all output signals that should be enabled or disabled. 384 | // 385 | // Ref: USB CDC specification version 1.1 §6.2.14. 386 | const value = (this.outputSignals_.dataTerminalReady ? 1 << 0 : 0) | 387 | (this.outputSignals_.requestToSend ? 1 << 1 : 0); 388 | 389 | await this.device_.controlTransferOut({ 390 | 'requestType': 'class', 391 | 'recipient': 'interface', 392 | 'request': kSetControlLineState, 393 | 'value': value, 394 | 'index': this.controlInterface_.interfaceNumber, 395 | }); 396 | } 397 | 398 | if (signals.break !== undefined) { 399 | // The SendBreak command expects to be given a duration for how long the 400 | // break signal should be asserted. Passing 0xFFFF enables the signal 401 | // until 0x0000 is send. 402 | // 403 | // Ref: USB CDC specification version 1.1 §6.2.15. 404 | const value = this.outputSignals_.break ? 0xFFFF : 0x0000; 405 | 406 | await this.device_.controlTransferOut({ 407 | 'requestType': 'class', 408 | 'recipient': 'interface', 409 | 'request': kSendBreak, 410 | 'value': value, 411 | 'index': this.controlInterface_.interfaceNumber, 412 | }); 413 | } 414 | } 415 | 416 | /** 417 | * Checks the serial options for validity and throws an error if it is 418 | * not valid 419 | */ 420 | private validateOptions(): void { 421 | if (!this.isValidBaudRate(this.serialOptions_.baudRate)) { 422 | throw new RangeError('invalid Baud Rate ' + this.serialOptions_.baudRate); 423 | } 424 | 425 | if (!this.isValidDataBits(this.serialOptions_.dataBits)) { 426 | throw new RangeError('invalid dataBits ' + this.serialOptions_.dataBits); 427 | } 428 | 429 | if (!this.isValidStopBits(this.serialOptions_.stopBits)) { 430 | throw new RangeError('invalid stopBits ' + this.serialOptions_.stopBits); 431 | } 432 | 433 | if (!this.isValidParity(this.serialOptions_.parity)) { 434 | throw new RangeError('invalid parity ' + this.serialOptions_.parity); 435 | } 436 | } 437 | 438 | /** 439 | * Checks the baud rate for validity 440 | * @param {number} baudRate the baud rate to check 441 | * @return {boolean} A boolean that reflects whether the baud rate is valid 442 | */ 443 | private isValidBaudRate(baudRate: number): boolean { 444 | return baudRate % 1 === 0; 445 | } 446 | 447 | /** 448 | * Checks the data bits for validity 449 | * @param {number} dataBits the data bits to check 450 | * @return {boolean} A boolean that reflects whether the data bits setting is 451 | * valid 452 | */ 453 | private isValidDataBits(dataBits: number | undefined): boolean { 454 | if (typeof dataBits === 'undefined') { 455 | return true; 456 | } 457 | return kAcceptableDataBits.includes(dataBits); 458 | } 459 | 460 | /** 461 | * Checks the stop bits for validity 462 | * @param {number} stopBits the stop bits to check 463 | * @return {boolean} A boolean that reflects whether the stop bits setting is 464 | * valid 465 | */ 466 | private isValidStopBits(stopBits: number | undefined): boolean { 467 | if (typeof stopBits === 'undefined') { 468 | return true; 469 | } 470 | return kAcceptableStopBits.includes(stopBits); 471 | } 472 | 473 | /** 474 | * Checks the parity for validity 475 | * @param {string} parity the parity to check 476 | * @return {boolean} A boolean that reflects whether the parity is valid 477 | */ 478 | private isValidParity(parity: ParityType | undefined): boolean { 479 | if (typeof parity === 'undefined') { 480 | return true; 481 | } 482 | return kAcceptableParity.includes(parity); 483 | } 484 | 485 | /** 486 | * sends the options alog the control interface to set them on the device 487 | * @return {Promise} a promise that will resolve when the options are set 488 | */ 489 | private async setLineCoding(): Promise { 490 | // Ref: USB CDC specification version 1.1 §6.2.12. 491 | const buffer = new ArrayBuffer(7); 492 | const view = new DataView(buffer); 493 | view.setUint32(0, this.serialOptions_.baudRate, true); 494 | view.setUint8( 495 | 4, kStopBitsIndexMapping.indexOf( 496 | this.serialOptions_.stopBits ?? kDefaultStopBits)); 497 | view.setUint8( 498 | 5, kParityIndexMapping.indexOf( 499 | this.serialOptions_.parity ?? kDefaultParity)); 500 | view.setUint8(6, this.serialOptions_.dataBits ?? kDefaultDataBits); 501 | 502 | const result = await this.device_.controlTransferOut({ 503 | 'requestType': 'class', 504 | 'recipient': 'interface', 505 | 'request': kSetLineCoding, 506 | 'value': 0x00, 507 | 'index': this.controlInterface_.interfaceNumber, 508 | }, buffer); 509 | if (result.status != 'ok') { 510 | throw new DOMException('NetworkError', 'Failed to set line coding.'); 511 | } 512 | } 513 | } 514 | 515 | /** implementation of the global navigator.serial object */ 516 | class Serial { 517 | /** 518 | * Requests permission to access a new port. 519 | * 520 | * @param {SerialPortRequestOptions} options 521 | * @param {SerialPolyfillOptions} polyfillOptions 522 | * @return {Promise} 523 | */ 524 | async requestPort( 525 | options?: SerialPortRequestOptions, 526 | polyfillOptions?: SerialPolyfillOptions): Promise { 527 | polyfillOptions = {...kDefaultPolyfillOptions, ...polyfillOptions}; 528 | 529 | const usbFilters: USBDeviceFilter[] = []; 530 | if (options && options.filters) { 531 | for (const filter of options.filters) { 532 | const usbFilter: USBDeviceFilter = { 533 | classCode: polyfillOptions.usbControlInterfaceClass, 534 | }; 535 | if (filter.usbVendorId !== undefined) { 536 | usbFilter.vendorId = filter.usbVendorId; 537 | } 538 | if (filter.usbProductId !== undefined) { 539 | usbFilter.productId = filter.usbProductId; 540 | } 541 | usbFilters.push(usbFilter); 542 | } 543 | } 544 | 545 | if (usbFilters.length === 0) { 546 | usbFilters.push({ 547 | classCode: polyfillOptions.usbControlInterfaceClass, 548 | }); 549 | } 550 | 551 | const device = await navigator.usb.requestDevice({'filters': usbFilters}); 552 | const port = new SerialPort(device, polyfillOptions); 553 | return port; 554 | } 555 | 556 | /** 557 | * Get the set of currently available ports. 558 | * 559 | * @param {SerialPolyfillOptions} polyfillOptions Polyfill configuration that 560 | * should be applied to these ports. 561 | * @return {Promise} a promise that is resolved with a list of 562 | * ports. 563 | */ 564 | async getPorts(polyfillOptions?: SerialPolyfillOptions): 565 | Promise { 566 | polyfillOptions = {...kDefaultPolyfillOptions, ...polyfillOptions}; 567 | 568 | const devices = await navigator.usb.getDevices(); 569 | const ports: SerialPort[] = []; 570 | devices.forEach((device) => { 571 | try { 572 | const port = new SerialPort(device, polyfillOptions); 573 | ports.push(port); 574 | } catch (e) { 575 | // Skip unrecognized port. 576 | } 577 | }); 578 | return ports; 579 | } 580 | } 581 | 582 | /* an object to be used for starting the serial workflow */ 583 | export const serial = new Serial(); 584 | --------------------------------------------------------------------------------