{"id":15293223,"url":"https://github.com/loginov-rocks/web-bluetooth-terminal","last_synced_at":"2025-04-05T05:03:15.124Z","repository":{"id":44379310,"uuid":"103553238","full_name":"loginov-rocks/Web-Bluetooth-Terminal","owner":"loginov-rocks","description":"Progressive Web Application for serial communication with your own Bluetooth Low Energy (Smart) devices","archived":false,"fork":false,"pushed_at":"2024-08-14T04:36:51.000Z","size":2091,"stargazers_count":246,"open_issues_count":3,"forks_count":79,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-04-05T05:03:05.248Z","etag":null,"topics":["arduino","ble","bluetooth","bluetooth-low-energy","bluetooth-smart","communication","iot","physical-web","pwa","serial","terminal"],"latest_commit_sha":null,"homepage":"https://loginov-rocks.github.io/Web-Bluetooth-Terminal/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/loginov-rocks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-14T16:02:13.000Z","updated_at":"2025-03-21T03:27:57.000Z","dependencies_parsed_at":"2024-08-24T05:01:39.729Z","dependency_job_id":"79bc295f-713f-4af4-9ee1-5c7435a9a1b4","html_url":"https://github.com/loginov-rocks/Web-Bluetooth-Terminal","commit_stats":{"total_commits":91,"total_committers":4,"mean_commits":22.75,"dds":0.2637362637362637,"last_synced_commit":"31448e135d86aa7a3c4e50d9b3ec6c8457dc5891"},"previous_names":["1oginov/web-bluetooth-terminal"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loginov-rocks%2FWeb-Bluetooth-Terminal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loginov-rocks%2FWeb-Bluetooth-Terminal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loginov-rocks%2FWeb-Bluetooth-Terminal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loginov-rocks%2FWeb-Bluetooth-Terminal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/loginov-rocks","download_url":"https://codeload.github.com/loginov-rocks/Web-Bluetooth-Terminal/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247289409,"owners_count":20914464,"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","ble","bluetooth","bluetooth-low-energy","bluetooth-smart","communication","iot","physical-web","pwa","serial","terminal"],"created_at":"2024-09-30T16:45:07.282Z","updated_at":"2025-04-05T05:03:15.095Z","avatar_url":"https://github.com/loginov-rocks.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Web Bluetooth Terminal\n\n[![NpmVersion](https://img.shields.io/npm/v/web-bluetooth-terminal.svg)](https://www.npmjs.com/package/web-bluetooth-terminal)\n[![dependencies Status](https://david-dm.org/loginov-rocks/Web-Bluetooth-Terminal/status.svg)](https://david-dm.org/loginov-rocks/Web-Bluetooth-Terminal)\n[![devDependencies Status](https://david-dm.org/loginov-rocks/Web-Bluetooth-Terminal/dev-status.svg)](https://david-dm.org/loginov-rocks/Web-Bluetooth-Terminal?type=dev)\n\n![Favicon](https://raw.githubusercontent.com/loginov-rocks/Web-Bluetooth-Terminal/master/icons/favicon-16x16.png)\n[https://loginov-rocks.github.io/Web-Bluetooth-Terminal](https://loginov-rocks.github.io/Web-Bluetooth-Terminal/) — try\nit out, see how it works on [YouTube](https://www.youtube.com/watch?v=BNXN_931W_M), read tutorial on\n[Medium](https://medium.com/@loginov_rocks/how-to-make-a-web-app-for-your-own-bluetooth-low-energy-device-arduino-2af8d16fdbe8)\n(English) or on [Habr](https://habr.com/post/339146/) (Russian).\n\nWeb Bluetooth Terminal is a website that can **connect** with the remote devices which support **Bluetooth Low Energy**\n(also called Bluetooth Smart) and **exchange data bidirectionally**. It can be installed on your homescreen as an\napplication and work offline.\n\n**Killer feature:** the application establishes **serial communication** over BLE that is not provided by the\nspecification, but needed if you want to make your own BLE IoT devices using affordable bluetooth modules.\n\n![Teaser](https://raw.githubusercontent.com/loginov-rocks/Web-Bluetooth-Terminal/master/misc/Teaser.png)\n\nThe application utilises BLE service (`0xFFE0`) and characteristic (`0xFFE1`) available in low cost BLE modules based\nfor example on CC2541 chip, such as HM-10, JDY-08, AT-09, CC41-A and other. Also, it bypasses 20 bytes limit specific\nfor GATT characteristics by keeping incoming messages in a buffer and waiting for the end of line characters.\n\nCheck [Bluetooth Low Energy (Smart) device](#bluetooth-low-energy-smart-device) and\n[How to use this app as a base for my own project?](#how-to-use-this-app-as-a-base-for-my-own-project)\nsections for a quick start and to find out how to make your own project. Also, I've made\n[MeArm Controller](https://github.com/loginov-rocks/MeArm-Controller) as a showcase project.\n\n## Features\n\n**Accessible via browser** — just go to the [website](https://loginov-rocks.github.io/Web-Bluetooth-Terminal/) and\nyou'll get the full featured application, it is not needed to install anything.\n\n**Cross-platform** — as long as the app is accessible via browser, you can use it with the desktop or with the smart\nphone [browser](#browser).\n\n**Installable** — if you don't want to remember the website address, you can add it to the homescreen.\n\n**Works offline** after installation on your homescreen, since it is a Progressive Web Application.\n\nAnd... it have **auto scrolling!** Enabled by default, but you can scroll the terminal to the top on more than a half of\nthe terminal window height to disable it. Scroll to the bottom to enable it again. Rocket science!\n\n## Requirements\n\n### Browser\n\nOne of browsers which supports Web Bluetooth API by default\n([Chrome Platform Status](https://www.chromestatus.com/feature/5264933985976320),\n[Can I use](https://caniuse.com/#feat=web-bluetooth)):\n\n1. Chrome for desktop 56+\n2. Chrome for Android 56+\n3. Opera 43+\n4. Opera for Android 43+\n\nAll this browsers support other necessary features, such as [ES6 classes](https://caniuse.com/#feat=es6-class) and PWA\ncapabilities ([Web App Manifest](https://caniuse.com/#feat=web-app-manifest) and\n[Service Workers](https://caniuse.com/#feat=serviceworkers)), so I don't pay attention to it here.\n\n### Bluetooth Low Energy (Smart) device\n\nDifferent BLE devices implement their own services and characteristics to communicate with, but you can build your own\nsimple device: you just need a BLE module (e.g. HM-10, JDY-08, AT-09, CC41-A) and an Arduino Uno. Wire it and upload the\n[bridge sketch](https://raw.githubusercontent.com/loginov-rocks/Web-Bluetooth-Terminal/master/misc/Arduino-Bridge/Arduino-Bridge.ino).\n\nPay attention to what voltage level your BLE module consumes, since it can vary from device to device! Read\nspecifications, you may need to connect your BLE module to the `3.3V` pin and use voltage level shifter between `TX` and\n`RX` pins.\n\n![Arduino Uno to BLE module wiring scheme](https://raw.githubusercontent.com/loginov-rocks/Web-Bluetooth-Terminal/master/misc/Arduino-Bridge/Scheme.png)\n\nOpen Serial Monitor in Arduino IDE, switch baudrate to `9600` and line endings to `Both NL \u0026 CR`. Next, launch the\n[Web Bluetooth Terminal](https://loginov-rocks.github.io/Web-Bluetooth-Terminal/) and connect to your module. Now you're\nable to make a small talk between the Terminal and the Serial Monitor!\n\n#### BLE module configuration\n\nWhen a BLE module is waiting for connection it can be configured with `AT` commands. So if you have troubles trying to\nmake BLE module work as expected you can use following commands, but again, read specifications! Here are some commands\nI use with CC41-A module:\n\n* `AT+DEFAULT` — resets the module to the defaults;\n* `AT+RESET` — resets the module softly;\n* `AT+ROLE` — gets the module working mode;\n* `AT+ROLE0` — makes the module to work in slave mode, waiting for connection from other devices;\n* `AT+NAME` — gets the module name;\n* `AT+NAMESimon` — sets the module name to `Simon`;\n* `AT+PIN` — gets the module pin (password);\n* `AT+PIN123456` — sets the module pin to `123456`;\n* `AT+UUID` — gets the module service UUID;\n* `AT+CHAR` — gets the module characteristic UUID.\n\nCommands can be case insensitive and may need to be terminated with `CR` (`\\r`) and `LF` (`\\n`).\n\n## How to use this app as a base for my own project?\n\nYou can fork this repository and implement features specific to your needs. Don't forget that application should be\naccessible via HTTPS protocol to enable Web Bluetooth API feature, so you can use\n[GitHub Pages](https://pages.github.com/) switching the source to the `master` branch of your repository.\n\nTo use development capabilities, you'll need [Node.js](https://nodejs.org/), [npm](https://www.npmjs.com/) especially.\nInstall it, clone the repository and install `npm` dependencies:\n\n```sh\ngit clone https://github.com/loginov-rocks/Web-Bluetooth-Terminal.git\ncd Web-Bluetooth-Terminal\nnpm install\n```\n\n### Global install\n\nAlternatively, you can delegate repository cloning to the package itself. Just install it globally:\n\n```sh\nnpm install -g web-bluetooth-terminal\n```\n\nHaving this package installed globally, you can use the following command to clone the repository into your current\ndirectory:\n\n```sh\nweb-bluetooth-terminal\n```\n\nOr you can specify directory name to clone into as an argument:\n\n```sh\nweb-bluetooth-terminal MyProject\n```\n\nThis command checks out the same version as you have installed globally. So if a new version is released, you can update\npackage with the following command:\n\n```sh\nnpm update -g web-bluetooth-terminal\n```\n\n### Npm scripts\n\nAfter installing `npm` dependencies, you can use some simple scripts that can be helpful:\n\n* `npm run build` copies used vendors files and generates `css/style.css`;\n* `npm run js:vendor` copies used vendors JavaScript files into the `js` directory;\n* `npm run lint` lints JavaScript files;\n* `npm run styles` generates `css/style.css` from SCSS sources placed in the `scss` directory;\n* `npm run styles:vendor` copies used vendors stylesheets into the `css` directory;\n* `npm run watch:styles` watches for changes made to the files placed in the `scss` directory and runs `npm run styles`\ncommand.\n\n### BluetoothTerminal.js API\n\nAlso, you can install [bluetooth-terminal](https://github.com/loginov-rocks/bluetooth-terminal) package or\n[directly download the file](https://raw.githubusercontent.com/loginov-rocks/bluetooth-terminal/master/src/BluetoothTerminal.js)\ncontaining `BluetoothTerminal` class written in ES6 and use it as you want. Here is a simple code snippet that can be\nhelpful for a quick start:\n\n```js\n// Obtain configured instance.\nlet terminal = new BluetoothTerminal();\n\n// Override `receive` method to handle incoming data as you want.\nterminal.receive = function(data) {\n  alert(data);\n};\n\n// Request the device for connection and get its name after successful connection.\nterminal.connect().then(() =\u003e {\n  alert(terminal.getDeviceName() + ' is connected!');\n});\n\n// Send something to the connected device.\nterminal.send('Simon says: Hello, world!');\n\n// Disconnect from the connected device.\nterminal.disconnect();\n```\n\n## Contribution\n\nPlease use the [dev](https://github.com/loginov-rocks/Web-Bluetooth-Terminal/tree/dev) branch and feel free to contribute!\n\n## Reference\n\n1. [Web Bluetooth Specification](https://webbluetoothcg.github.io/web-bluetooth/)\n2. [Web Bluetooth Samples](https://googlechrome.github.io/samples/web-bluetooth/)\n3. [Interact with Bluetooth devices on the Web](https://developers.google.com/web/updates/2015/07/interact-with-ble-devices-on-the-web/)\n4. [Progressive Web Apps](https://developers.google.com/web/progressive-web-apps/)\n5. [Service Worker Toolbox](https://github.com/GoogleChromeLabs/sw-toolbox/)\n\n## Gists\n\n1. https://gist.github.com/loginov-rocks/8aeb19f207b1da53eaa553faa7aa8a51\n2. https://gist.github.com/loginov-rocks/c0709f22540c01cf532ec0d311f059e2\n3. https://gist.github.com/loginov-rocks/0e4ff696195863e99853b126aca8ecb1\n4. https://gist.github.com/loginov-rocks/ad98c6a48394d48c3252d7694ffb5e57\n5. https://gist.github.com/loginov-rocks/1156e4581ec9f68a20cc6acb1cd6e52a\n6. https://gist.github.com/loginov-rocks/26d9714acbfbcb723c79bb8e23128e3c\n7. https://gist.github.com/loginov-rocks/f918a2b11b98d20808a12a8c923e74bc\n8. https://gist.github.com/loginov-rocks/d23a840d2c38b88ed3f55f2be62bf7ba\n9. https://gist.github.com/loginov-rocks/4cf8d0d720dafcf52781748d5c975452\n10. https://gist.github.com/loginov-rocks/fa0478f085410d1f59ede2f653af0e5c\n11. https://gist.github.com/loginov-rocks/44c7a144a1548ab08426bc675854d183\n12. https://gist.github.com/loginov-rocks/e03b1dd9e038eaf4eb65413d97a34678\n13. https://gist.github.com/loginov-rocks/b39e4e5c6d0c95b404172ad04baf8b28\n14. https://gist.github.com/loginov-rocks/140ee65772f87ab775cb94cae850eb3a\n15. https://gist.github.com/loginov-rocks/b060cecbe50f09f40e2c29f6e3b7dc67\n16. https://gist.github.com/loginov-rocks/c88f7eed3bfaa8685b594a2e19813a43\n17. https://gist.github.com/loginov-rocks/58a1b7428f9a3bbc71a49ef36bea6e34\n18. https://gist.github.com/loginov-rocks/49e208008b95da9c8de985c15f383dd8\n19. https://gist.github.com/loginov-rocks/8451dcae975e746e3283c7190a75441e\n20. https://gist.github.com/loginov-rocks/f0bd2c16640c9493e19df8262afeb995\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floginov-rocks%2Fweb-bluetooth-terminal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Floginov-rocks%2Fweb-bluetooth-terminal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floginov-rocks%2Fweb-bluetooth-terminal/lists"}