loginov-rocks / web-bluetooth-terminal Goto Github PK

View Code? Open in Web Editor NEW

233.0 14.0 78.0 2.04 MB

Progressive Web Application for serial communication with your own Bluetooth Low Energy (Smart) devices

Home Page: https://loginov-rocks.github.io/Web-Bluetooth-Terminal/

License: MIT License

HTML 11.12% JavaScript 69.04% CSS 7.13% C++ 3.61% SCSS 9.09%

pwa serial communication bluetooth bluetooth-low-energy bluetooth-smart ble iot arduino terminal

web-bluetooth-terminal's Introduction

Web Bluetooth Terminal

https://loginov-rocks.github.io/Web-Bluetooth-Terminal — try it out, see how it works on YouTube, read tutorial on Medium (English) or on Habr (Russian).

Web Bluetooth Terminal is a website that can connect with the remote devices which support Bluetooth Low Energy (also called Bluetooth Smart) and exchange data bidirectionally. It can be installed on your homescreen as an application and work offline.

Killer feature: the application establishes serial communication over BLE that is not provided by the specification, but needed if you want to make your own BLE IoT devices using affordable bluetooth modules.

The application utilises BLE service (0xFFE0) and characteristic (0xFFE1) available in low cost BLE modules based for example on CC2541 chip, such as HM-10, JDY-08, AT-09, CC41-A and other. Also, it bypasses 20 bytes limit specific for GATT characteristics by keeping incoming messages in a buffer and waiting for the end of line characters.

Check Bluetooth Low Energy (Smart) device and How to use this app as a base for my own project? sections for a quick start and to find out how to make your own project. Also, I've made MeArm Controller as a showcase project.

Features

Accessible via browser — just go to the website and you'll get the full featured application, it is not needed to install anything.

Cross-platform — as long as the app is accessible via browser, you can use it with the desktop or with the smart phone browser.

Installable — if you don't want to remember the website address, you can add it to the homescreen.

Works offline after installation on your homescreen, since it is a Progressive Web Application.

And... it have auto scrolling! Enabled by default, but you can scroll the terminal to the top on more than a half of the terminal window height to disable it. Scroll to the bottom to enable it again. Rocket science!

Requirements

Browser

One of browsers which supports Web Bluetooth API by default (Chrome Platform Status, Can I use):

Chrome for desktop 56+
Chrome for Android 56+
Opera 43+
Opera for Android 43+

All this browsers support other necessary features, such as ES6 classes and PWA capabilities (Web App Manifest and Service Workers), so I don't pay attention to it here.

Bluetooth Low Energy (Smart) device

Different BLE devices implement their own services and characteristics to communicate with, but you can build your own simple 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 bridge sketch.

Pay attention to what voltage level your BLE module consumes, since it can vary from device to device! Read specifications, you may need to connect your BLE module to the 3.3V pin and use voltage level shifter between TX and RX pins.

Open Serial Monitor in Arduino IDE, switch baudrate to 9600 and line endings to Both NL & CR. Next, launch the Web Bluetooth Terminal and connect to your module. Now you're able to make a small talk between the Terminal and the Serial Monitor!

BLE module configuration

When a BLE module is waiting for connection it can be configured with AT commands. So if you have troubles trying to make BLE module work as expected you can use following commands, but again, read specifications! Here are some commands I use with CC41-A module:

AT+DEFAULT — resets the module to the defaults;
AT+RESET — resets the module softly;
AT+ROLE — gets the module working mode;
AT+ROLE0 — makes the module to work in slave mode, waiting for connection from other devices;
AT+NAME — gets the module name;
AT+NAMESimon — sets the module name to Simon;
AT+PIN — gets the module pin (password);
AT+PIN123456 — sets the module pin to 123456;
AT+UUID — gets the module service UUID;
AT+CHAR — gets the module characteristic UUID.

Commands can be case insensitive and may need to be terminated with CR (\r) and LF (\n).

How to use this app as a base for my own project?

You can fork this repository and implement features specific to your needs. Don't forget that application should be accessible via HTTPS protocol to enable Web Bluetooth API feature, so you can use GitHub Pages switching the source to the master branch of your repository.

To use development capabilities, you'll need Node.js, npm especially. Install it, clone the repository and install npm dependencies:

git clone https://github.com/loginov-rocks/Web-Bluetooth-Terminal.git
cd Web-Bluetooth-Terminal
npm install

Global install

Alternatively, you can delegate repository cloning to the package itself. Just install it globally:

npm install -g web-bluetooth-terminal

Having this package installed globally, you can use the following command to clone the repository into your current directory:

web-bluetooth-terminal

Or you can specify directory name to clone into as an argument:

web-bluetooth-terminal MyProject

This command checks out the same version as you have installed globally. So if a new version is released, you can update package with the following command:

npm update -g web-bluetooth-terminal

Npm scripts

After installing npm dependencies, you can use some simple scripts that can be helpful:

npm run build copies used vendors files and generates css/style.css;
npm run js:vendor copies used vendors JavaScript files into the js directory;
npm run lint lints JavaScript files;
npm run styles generates css/style.css from SCSS sources placed in the scss directory;
npm run styles:vendor copies used vendors stylesheets into the css directory;
npm run watch:styles watches for changes made to the files placed in the scss directory and runs npm run styles command.

BluetoothTerminal.js API

Also, you can install bluetooth-terminal package or directly download the file containing BluetoothTerminal class written in ES6 and use it as you want. Here is a simple code snippet that can be helpful for a quick start:

// Obtain configured instance.
let terminal = new BluetoothTerminal();

// Override `receive` method to handle incoming data as you want.
terminal.receive = function(data) {
  alert(data);
};

// Request the device for connection and get its name after successful connection.
terminal.connect().then(() => {
  alert(terminal.getDeviceName() + ' is connected!');
});

// Send something to the connected device.
terminal.send('Simon says: Hello, world!');

// Disconnect from the connected device.
terminal.disconnect();

Contribution

Please use the dev branch and feel free to contribute!

Reference

Gists

web-bluetooth-terminal's People

Contributors

Stargazers

Watchers

Forkers

emlyon ardelean-calin josschne danzenti sudiptochy m-reimer boikonur nickarthur georgeredinger mobilizeit radioeng korzak jonbattista rcunhaescarcel nicodinh rcotrina94 kpatel122 ryans-picobrew taprik davidka portalsinc bobbyjohansen nazosnare the-code-chef fastboatster dryerzinia steven-kang sangeethjayaprakash erkkimon gavinying vtt-info jackycnhk deftio chenhuayou kabbi georgievarkey chge workshop512 interesting-useful-stuff felixcollins mattthelwell netforces nangolijude trokhymbutko robot4fun chiyul marktekfan elyas207 clairemca lntek lhaeger af970 jasonwarta copyleft243 bastelpichi rfdougherty vinhlin curlyz jackeychens johninwi danvinn

web-bluetooth-terminal's Issues

Close then Reopen fails

Finally back to using your code and web page example, find that if I connect, send some data, then disconnect, wait a bit, then reconnect to the same device, data will not be sent after the second connect. It fails in your web page terminal example as well as my code which uses your same JS. I have to refresh the screen on your web terminal as well as refresh my page with my code to make the connection and sends work again. It seems like something is not cleared on disconnect that should be cleared, and it takes a refresh to make it work. Please take a look at this. Thank you for your help.

Separators

Could you please change your code to have a binary mode. I do not think it is reasonable to force separators on the user in many cases. For example, I have an application with an HM-10 that sends live binary data back and forth to an arduino. I would prefer not to hack apart your code. Maybe you could just send all data immediately to the requester like the serialport library using some sort of flag like binarymode or something like that? This way you could keep your code the way it is for old users, and add a binary mode for people like me :)

I also commented on the issue of your promises chain not working correctly for signalling the end of sends. Please look into it.

Thank you so much, Jack

ESP32 Gatt Error

Hello,
I have tried to connect my ESP32 and receive a GATT error message.
Has anyone else had this issue?

Requesting bluetooth device...
"ESP32" bluetooth device selected
Connecting to GATT server...
GATT server connected
Getting service...
Service found
Getting characteristic...
CharacteristicTx found
CharacteristicRx found
Starting notifications...
NotSupportedError: GATT Error Unknown.

ESC/POS bluetooth printer

Can this library connect to a ESC/POS bluetooth printer and can print?

Feature request: Nordic UART/BBC micro:bit support

Hello,
the BBC micro:bit (microbit.org) uses the Nordic UART service https://lancaster-university.github.io/microbit-docs/ble/uart-service/ - it would be awesome if this app supported micro:bit. This would also allow trivial support for other Arm MBED boards https://os.mbed.com/teams/Bluetooth-Low-Energy/wiki/UART-access-over-BLE

There's a program for testing with the micro:bit here https://makecode.microbit.org/_8gyHC3Aq8Yxu

bluetooth module serial question

Hello,

great job, I am looking for something similar. Is this solution compatible with serial bluetooth modules like hc-04 and hc-12? Is it possible for hc-12 to communicate with ble devices?

Regards
Jernej

Will this work on iOS?

I tried this on Safari and Chrome on my iPhone X, but couldn't get it to work. Am I missing something?

ESP32 Support

I got really enthusiastic when I saw this library! But can't get it to work with my DOIT ESP32 Devkit V1. Seems like a great candidate because of it's inbuilt Bluetooth LE and Arduino IDE compatibility.

Can this library work with the ESP32? Or does it need changes?

I found this fork or Web-Bluetooth-Terminal, which supposedly adds ESP32 support. But it didn't work for me either.

I'm using this sketch from this tutorial on the ESP32 to enable Bluetooth LE. It uses the UART service UUID 6E400001-B5A3-F393-E0A9-E50E24DCCA9E and a characteristic of 6E400002-B5A3-F393-E0A9-E50E24DCCA9E for receiving data with "WRITE" and a characteristic of 6E400003-B5A3-F393-E0A9-E50E24DCCA9E used to send data with "NOTIFY". This also matches the UUID and characteristic in the Web Bluetooth Terminal fork by kpatel122. So I had a good feeling about it 😝

I can connect to the ESP32 with Adafruit Bluefruit LE Connect for OS X. It connects to the ESP32 just fine, logs the received data and I can send values to it as well, which shows up in the Arduino Serial Monitor. So far so good.

But then trying to connect with Web Bluetooth Terminal in the latest Google Chrome, it won't list any devices. Same with the fork. I tried using the underlying BluetoothTerminal.js API directly in this JSitor snippet, but it doesn't list any device in the permission dialog either. It just says: "No compatible devices found."

Looking in chrome://bluetooth-internals it shows me the following info for the ESP32:

ESP32: UNSUPPORTED_DEVICE
Name: ESP32
Address: 30:AE:A4:40:50:7E
GATT Connected: Not Connected
Latest RSSI:Unknown
Services: Unknown

If I enable the Experimental Web Platform features in chrome://flags (which I just did for testing, because I can't expect users of my web app to do this), I can send an receive data from the chrome://bluetooth-internals page, but the ESP32 still won't show up in Web Bluetooth Terminal, not in the fork and not in my JSitor snippet.

Is this a dead end? Would be great to know what can be done to get this working with the ESP32.

Promise at Send

The promise returned by the send command should be at the end when all the data has been sent. The promise returned only is the first chunk I believe. I use this to set a flag that tells me I cant send anymore data until the previous data is complete, and this bombs since data collides. Please fix. Thx.

Реализация загрузчика для Atmel

На уровне идеи - если прикрутить к этому восхотительному приложению реализацию какого-нибудь относительно стандартного протокола загрузчика (типа того протокола, что реализует, например, avrprog), то получится ещё отличная возможность обновлять прошивку в девайсах по блутусу. Ну это так, мечты :) Спасибо за приложение, пригодится!

your github.io site is down?

I demo your software at your github.io site, but it appears to be down. Please fix. JD69

HC-05/06 compatibility

The HC-05 and HC-06 Bluetooth V2.0 modules (FW VERSION:2.0-20100601) will fail when writing to Characteristic 0xFFE1 with this error:
"NotSupportedError: GATT operation failed for unknown reason"

Instead these modules require Characteristic 0xFFE2 for writing/transmitting.

When I get my hands on a HM-10 or AT-09 I will try to make the BluetoothTerminal class compatible with both module families.

Action required: Greenkeeper could not be activated 🚨

🚨 You need to enable Continuous Integration on all branches of this repository. 🚨

To enable Greenkeeper, you need to make sure that a commit status is reported on all branches. This is required by Greenkeeper because we are using your CI build statuses to figure out when to notify you about breaking changes.

Since we did not receive a CI status on the greenkeeper/initial branch, we assume that you still need to configure it.

If you have already set up a CI for this repository, you might need to check your configuration. Make sure it will run on all new branches. If you don’t want it to run on every branch, you can whitelist branches starting with greenkeeper/.

We recommend using Travis CI, but Greenkeeper will work with every other CI service as well.

Once you have installed CI on this repository, you’ll need to re-trigger Greenkeeper’s initial Pull Request. To do this, please delete the greenkeeper/initial branch in this repository, and then remove and re-add this repository to the Greenkeeper integration’s white list on Github. You'll find this list on your repo or organization’s settings page, under Installed GitHub Apps.

Windows Support

Its not working with windows