{"id":15198679,"url":"https://github.com/makio135/webserial","last_synced_at":"2025-10-28T11:30:25.265Z","repository":{"id":37196998,"uuid":"233594065","full_name":"MAKIO135/webserial","owner":"MAKIO135","description":"WebSerial","archived":false,"fork":false,"pushed_at":"2022-12-11T20:37:36.000Z","size":730,"stargazers_count":26,"open_issues_count":16,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-02-01T14:13:46.092Z","etag":null,"topics":["arduino","browser","electronjs","serial","websocket"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MAKIO135.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-01-13T12:48:18.000Z","updated_at":"2023-07-12T20:56:37.000Z","dependencies_parsed_at":"2023-01-27T06:45:39.175Z","dependency_job_id":null,"html_url":"https://github.com/MAKIO135/webserial","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MAKIO135%2Fwebserial","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MAKIO135%2Fwebserial/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MAKIO135%2Fwebserial/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MAKIO135%2Fwebserial/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MAKIO135","download_url":"https://codeload.github.com/MAKIO135/webserial/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238638121,"owners_count":19505536,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arduino","browser","electronjs","serial","websocket"],"created_at":"2024-09-28T01:24:12.458Z","updated_at":"2025-10-28T11:30:19.923Z","avatar_url":"https://github.com/MAKIO135.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WebSerial\n\n\u003e WebSerial is a minimal [Electron](https://electronjs.org/) application to bring Serial communication to Web browsers through websockets.  \n\u003e \n\u003e [@Makio135](https://twitter.com/makio135)\n\n![WbeSerial capture](https://i.imgur.com/WqXCIWo.png)\n\n- [Concept](#concept)\n- [How to configure your Serial device](##how-to-configure-your-serial-device)\n- [How to use WebSerial](#how-to-use-webserial)\n- [Documentation](#documentation)\n- [Acknowledgments](#acknowledgments)\n\n\n## Concept\n[Web MIDI](https://webaudio.github.io/web-midi-api/), [Web Bluetooth](https://webbluetoothcg.github.io/web-bluetooth/) and [Web USB](https://wicg.github.io/webusb/) are awesome ways to connect physical devices and microcontrollers to Web browsers and create rich interactive experiments.  \nBut, while these APIs are still in early stages, not widely supported or limited to a [very little set of devices](https://github.com/webusb/arduino#compatible-hardware) for now, WebSockets are way more accessible and cheap Arduinos or the likes can be found easily.  \n\n**WebSerial is a really simple way to connect your browser to any device with Serial communication and hack into physical web.**\n\n**WebSerial provides two ways communication between Serial devices and browsers**:  \nSerial data is forwarded to your page, and you can also use it to send data from your web page to your device.\n\nWebSerial uses [serialport](https://serialport.io/) to open a Serial connection, and runs an [express](https://expressjs.com/) / [socket.io](https://socket.io/) websocket server to communicate with your web page in realtime.  \n**Server runs on port 8135** by default but can be changed in WebSerial.\n\nFor references, see:\n- https://caniuse.com/#feat=midi\n- https://caniuse.com/#feat=web-bluetooth\n- https://caniuse.com/#feat=webusb\n- https://caniuse.com/#feat=mdn-api_websocket\n\n\n## How to configure your Serial device\n**WebSerial uses the `\\n` character as a delimiter to parse data.**  \nIn Arduino, this corresponds to use `Serial.println()`.  \n\n![](montage.png)\n\n```cpp\nvoid setup(){\n    Serial.begin(9600);\n}\n\nvoid loop() {\n    Serial.print(analogRead(A0));\n    Serial.print(',');\n    Serial.println(analogRead(A1));\n    delay(10);\n}\n```\n\n**WebSerial also appends a `\\n` character to your data, in order to parse it easily.**  \nCheck the [Read ASCII String](https://www.arduino.cc/en/Tutorial/ReadASCIIString) tutorial on Arduino's website.\n\u003cdetails\u003e\n\u003csummary\u003eClick here for some utility functions for parsing data in Arduino\u003c/summary\u003e\n\n```cpp\n#define MAX_CHARS 200\n\nString input;\n\nvoid setup() {\n    Serial.begin(9600);\n    input.reserve(MAX_CHARS);\n}\n\nvoid loop() {}\n\nvoid serialEvent() {\n    while (Serial.available()) {\n        readChar();\n    }\n}\n\nvoid readChar() {\n    char c = (char) Serial.read();\n    Serial.print(\"-\u003e\");\n    Serial.println(c);\n}\n\nvoid readString() {\n    char c = (char) Serial.read();\n\n    if (c == '\\n') {\n        Serial.println(\"-\u003e\" + input);\n        input = \"\";\n    }\n    else {\n        input += c;\n    }\n}\n\nvoid readInt() {\n    int i = Serial.parseInt();\n    Serial.print(\"-\u003e\");\n    Serial.println(i);\n}\n\nvoid readLong() {\n    char c = (char) Serial.read();\n\n    if (c == '\\n') {\n        char buffer[MAX_CHARS];\n        input.toCharArray(buffer, 20);\n        long l = atol(buffer);\n        Serial.print(\"-\u003e\");\n        Serial.println(l);\n        input = \"\";\n    }\n    else {\n        input += c;\n    }\n}\n```\n\u003c/details\u003e\n\n\n## How to use the WebSerial App\n- Download the [latest release](https://github.com/makio135/webserial/releases) for your OS.  \n- Start the WebSerial application.  \n- Connect your Serial device.  \n- Select the `port` and `baudrate` for your device, and click `connect`.  \n- On your web page, include the [`webserial.js` library](https://github.com/MAKIO135/webserial/tree/master/client), or use this one (served via github pages):\n    ```html\n    \u003cscript src=\"https://makio135.com/webserial/client/webserial.min.js\"\u003e\u003c/script\u003e\n    ```\nYou now have access to the `Webserial` Class, see [Documentation](#documentation) below 👇.\n\n\n## Documentation\nThe `Webserial` Class needs to be instanciated:\n```javascript\nconst serial = new WebSerial()\n```\nThe constructor can take an `options` Object to define the following properties:\n- `host`: The IP of the computer running the WebSerial app. String, default to `localhost`, optional.\n- `port`: The port of the websocket server. Number, default to `8135`, optional.\n- `log`: Additional logs in the console for debugging. Boolean, default to `false`, optional.\n\n```javascript\nconst serial = new WebSerial({\n    host: '192.168.0.14',\n    port: 8000,\n    log: true\n})\n```\n\nA `WebSerial` Instance exposes a few methods and properties:\n- `.on(eventName, callback)`, valid events are:\n    - `'connect'`: no argument is passed to the callback\n    - `'disconnect'`: no argument is passed to the callback\n    - `'data'`: callback takes one argument, the data received\n- `.write(dataString)`: method used to send data to the microcontrolller\n\n```html\n\u003cbody\u003e\n    \u003cscript src=\"js/webserial.min.js\"\u003e\u003c/script\u003e\n    \u003cscript\u003e\n        const serial = new WebSerial()\n        serial.on('connect', () =\u003e console.log('Serial connected'))\n        serial.on('disconnect', () =\u003e console.log('Serial disconnected'))\n        serial.on('data', data =\u003e console.log(`Data received: ${data}`))\n        document.body.addEventListener('click', () =\u003e serial.write('Hello WebSerial'))\n    \u003c/script\u003e\n\u003c/body\u003e\n```\n\nOr for use in a more direct mode:\n- `.isConnected`: state of the connection with Serial (Boolean)\n- `.data`: last data received from Serial (String)\n\n```html\n\u003c!-- Example using the p5js library (https://p5js.org/) --\u003e\n\u003cbody\u003e\n    \u003cscript src=\"js/webserial.min.js\"\u003e\u003c/script\u003e\n    \u003cscript src=\"https://cdn.jsdelivr.net/npm/p5@0.10.2/lib/p5.js\"\u003e\u003c/script\u003e\n\n    \u003cscript\u003e\n        let serial = new WebSerial()\n\n        function setup(){\n            createCanvas(windowWidth, windowHeight);\n            background(0)\n        }\n\n        function draw(){\n            if(serial.isConnected \u0026\u0026 serial.data) {\n                let [r, g] = serial.data.split(',').map(d =\u003e parseInt(d) / 4)\n                background(r, g, 127)\n            }\n        }\n\n        function mousePressed() {\n            serial.write(int(mouseX / width * 255))\n        }\n    \u003c/script\u003e\n\u003c/body\u003e\n```\n\n\n## Acknowledgments\nWebSerial would not be possible without these great projects: \n- [electron](https://electronjs.org/)\n- [electron-builder](https://www.electron.build/)\n- [serialport](https://serialport.io/)\n- [express](https://expressjs.com/)\n- [socket.io](https://socket.io/)  \n\n🙏🙏🙏\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmakio135%2Fwebserial","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmakio135%2Fwebserial","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmakio135%2Fwebserial/lists"}