@alexgyver/ble 1.0.0

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AlexGyver
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# BLE.js
+Обёртка на Web Bluetooth API
+- Автоматическое переподключение
+- Буферизация отправки
+- Буферизация приёма, разделение текста по разделителю
+
+> npm i @alexgyver/ble
+
+## Дока
+```js
+constructor(params = {});
+config(params = {});
+// eol: /\r?\n/
+// serviceUUID: '0000ffe0-0000-1000-8000-00805f9b34fb'
+// charxUUID: '0000ffe1-0000-1000-8000-00805f9b34fb'
+// auto_open: false
+// max_tx: 20
+// reconnect: 1000
+
+onbin(b);
+ontext(t);
+
+onopen():
+onclose():
+onchange(s):
+onselect(name);
+onerror(e);
+
+static supported();
+opened();
+selected();
+getName();
+
+select();
+open();
+close();
+
+sendBin(data);
+sendText(text);
+```

package/ble.js

@@ -0,0 +1,171 @@
+import { sleep, ShiftBuffer, StreamSplitter } from "@alexgyver/utils";
+
+export default class BLEJS {
+    static State = {
+        Closed: 'closed',
+        Opening: 'opening',
+        Open: 'open',
+        Closing: 'closing',
+    };
+
+    //#region handlers
+    onbin = null;
+    ontext = null;
+
+    onopen() { }
+    onclose() { }
+    onchange(s) { }
+    onselect(name) { }
+    onerror(e) { }
+
+    //#region constructor
+    constructor(params = {}) {
+        const def = {
+            eol: /\r?\n/,
+            serviceUUID: '0000ffe0-0000-1000-8000-00805f9b34fb',
+            charxUUID: '0000ffe1-0000-1000-8000-00805f9b34fb',
+            auto_open: false,
+            max_tx: 20,
+            reconnect: 1000,
+        };
+        this.cfg = { ...def, ...params };
+
+        this.splitter = new StreamSplitter(this.cfg.eol);
+        this.splitter.ontext = (t) => this.ontext(t);
+    }
+
+    //#region methods
+    config(params = {}) {
+        this.cfg = { ...this.cfg, ...params };
+        this.splitter.eol = this.cfg.eol;
+    }
+
+    static supported() {
+        return 'bluetooth' in navigator;
+    }
+
+    opened() {
+        return this._state === BLEJS.State.Open;
+    }
+
+    selected() {
+        return !!this._device;
+    }
+
+    getName() {
+        return this._device ? this._device.name : null;
+    }
+
+    async select() {
+        try {
+            await this.close();
+            if (this._device) this._device.removeEventListener('gattserverdisconnected', this._disconnect_h);
+            this._device = await navigator.bluetooth.requestDevice({
+                filters: [{ services: [this.cfg.serviceUUID] }],
+                optionalServices: [this.cfg.serviceUUID]
+            });
+            this._device.addEventListener("gattserverdisconnected", this._disconnect_h);
+        } catch (e) {
+            this._error(e);
+            this._device = null;
+        }
+        this.onselect(this.getName());
+        if (this.cfg.auto_open) this.open();
+        return this.selected();
+    }
+
+    async open() {
+        if (!this._device) return;
+        if (this.opened()) return;
+
+        if (this.cfg.reconnect) this.retry = true;
+        await this._open();
+    }
+
+    async _open() {
+        if (this._state != BLEJS.State.Closed) return;
+
+        this._change(BLEJS.State.Opening);
+        try {
+            const server = await this._device.gatt.connect();
+            const service = await server.getPrimaryService(this.cfg.serviceUUID);
+            this._charx = await service.getCharacteristic(this.cfg.charxUUID);
+            await this._charx.startNotifications();
+            this._charx.addEventListener("characteristicvaluechanged", this._data_h);
+            this._buffer.clear();
+            this._change(BLEJS.State.Open);
+        } catch (e) {
+            this._error(e);
+            this._change(BLEJS.State.Closed);
+            if (this.retry) sleep(this.cfg.reconnect).then(() => this._open());
+        }
+    }
+
+    async close() {
+        this.retry = false;
+        if (this.opened()) await this._close();
+    }
+
+    async _close() {
+        this._change(BLEJS.State.Closing);
+        try { this._device.gatt.disconnect(); }
+        catch (e) { this._error(e); }
+    }
+
+    async sendText(text) {
+        await this.sendBin((new TextEncoder()).encode(text));
+    }
+
+    async sendBin(data) {
+        this._buffer.push(data);
+        this._send();
+    }
+
+    //#region private    
+    _device = null;
+    _charx = null;
+    _state = BLEJS.State.Closed;
+    _buffer = new ShiftBuffer();
+    _decoder = new TextDecoder();
+
+    async _disconnect(e) {
+        this._change(BLEJS.State.Closed);
+        if (this._charx) this._charx.removeEventListener('characteristicvaluechanged', this._data_h);
+        this._charx = null;
+        if (this.retry) sleep(this.cfg.reconnect).then(() => this._open());
+        await sleep(50);
+    }
+    _disconnect_h = this._disconnect.bind(this);
+
+    _data(e) {
+        const dv = e.target.value;
+        const value = new Uint8Array(dv.buffer, dv.byteOffset, dv.byteLength);
+        if (this.onbin) this.onbin(value);
+        if (this.ontext) this.splitter.write(this._decoder.decode(value, { stream: true }));
+    }
+    _data_h = this._data.bind(this);
+
+    async _send() {
+        if (this._busy) return;
+        this._busy = true;
+        while (this._buffer.length && this._charx) {
+            let d = this._buffer.shift(this.cfg.max_tx);
+            try {
+                if (d.length) await this._charx.writeValueWithoutResponse(d);
+            } catch (e) { }
+        }
+        this._busy = false;
+    }
+
+    _error(e) {
+        this.onerror('[BLE] ' + e);
+    }
+    _change(s) {
+        this._state = s;
+        this.onchange(s);
+        switch (s) {
+            case BLEJS.State.Open: this.onopen(); break;
+            case BLEJS.State.Closed: this.onclose(); break;
+        }
+    }
+}

package/ble.min.js

@@ -0,0 +1 @@
+const t=t=>new Promise(e=>setTimeout(e,t));class e{ontext=null;constructor(t=/\r?\n/,e=!1){this.eol=t,this.skip=e}reset(){this._buf=""}write(t){if(!this.ontext)return;if(!this.eol)return void this.ontext(t);this._buf+=t;let e=this._buf.split(this.eol);1!=e.length&&(e[e.length-1].length?this._buf=e.pop():(this._buf="",e.pop()),this.skip&&(e.shift(),this.skip=!1),e.forEach(t=>this.ontext(t)))}_buf=""}class s{constructor(){this.chunks=[],this.length=0}clear(){this.chunks=[],this.length=0}push(t){return!(!t||0===t.length||(this.chunks.push(t),this.length+=t.length,0))}shift(t){if(!this.length||!t)return new Uint8Array(0);t>this.length&&(t=this.length);const e=new Uint8Array(t);let s=0;for(;s<t&&this.chunks.length>0;){const i=this.chunks[0];if(!i||0===i.length){this.chunks.shift();continue}const h=Math.min(i.length,t-s);e.set(i.subarray(0,h),s),s+=h,h===i.length?this.chunks.shift():this.chunks[0]=i.subarray(h),this.length-=h}return e}shiftAll(){return this.shift(this.length)}}class i{static State={Closed:"closed",Opening:"opening",Open:"open",Closing:"closing"};onbin=null;ontext=null;onopen(){}onclose(){}onchange(t){}onselect(t){}onerror(t){}constructor(t={}){this.cfg={eol:/\r?\n/,serviceUUID:"0000ffe0-0000-1000-8000-00805f9b34fb",charxUUID:"0000ffe1-0000-1000-8000-00805f9b34fb",auto_open:!1,max_tx:20,reconnect:1e3,...t},this.splitter=new e(this.cfg.eol),this.splitter.ontext=t=>this.ontext(t)}config(t={}){this.cfg={...this.cfg,...t},this.splitter.eol=this.cfg.eol}static supported(){return"bluetooth"in navigator}opened(){return this._state===i.State.Open}selected(){return!!this._device}getName(){return this._device?this._device.name:null}async select(){try{await this.close(),this._device&&this._device.removeEventListener("gattserverdisconnected",this._disconnect_h),this._device=await navigator.bluetooth.requestDevice({filters:[{services:[this.cfg.serviceUUID]}],optionalServices:[this.cfg.serviceUUID]}),this._device.addEventListener("gattserverdisconnected",this._disconnect_h)}catch(t){this._error(t),this._device=null}return this.onselect(this.getName()),this.cfg.auto_open&&this.open(),this.selected()}async open(){this._device&&(this.opened()||(this.cfg.reconnect&&(this.retry=!0),await this._open()))}async _open(){if(this._state==i.State.Closed){this._change(i.State.Opening);try{const t=await this._device.gatt.connect(),e=await t.getPrimaryService(this.cfg.serviceUUID);this._charx=await e.getCharacteristic(this.cfg.charxUUID),await this._charx.startNotifications(),this._charx.addEventListener("characteristicvaluechanged",this._data_h),this._buffer.clear(),this._change(i.State.Open)}catch(e){this._error(e),this._change(i.State.Closed),this.retry&&t(this.cfg.reconnect).then(()=>this._open())}}}async close(){this.retry=!1,this.opened()&&await this._close()}async _close(){this._change(i.State.Closing);try{this._device.gatt.disconnect()}catch(t){this._error(t)}}async sendText(t){await this.sendBin((new TextEncoder).encode(t))}async sendBin(t){this._buffer.push(t),this._send()}_device=null;_charx=null;_state=i.State.Closed;_buffer=new s;_decoder=new TextDecoder;async _disconnect(e){this._change(i.State.Closed),this._charx&&this._charx.removeEventListener("characteristicvaluechanged",this._data_h),this._charx=null,this.retry&&t(this.cfg.reconnect).then(()=>this._open()),await t(50)}_disconnect_h=this._disconnect.bind(this);_data(t){const e=t.target.value,s=new Uint8Array(e.buffer,e.byteOffset,e.byteLength);this.onbin&&this.onbin(s),this.ontext&&this.splitter.write(this._decoder.decode(s,{stream:!0}))}_data_h=this._data.bind(this);async _send(){if(!this._busy){for(this._busy=!0;this._buffer.length&&this._charx;){let t=this._buffer.shift(this.cfg.max_tx);try{t.length&&await this._charx.writeValueWithoutResponse(t)}catch(t){}}this._busy=!1}}_error(t){this.onerror("[BLE] "+t)}_change(t){switch(this._state=t,this.onchange(t),t){case i.State.Open:this.onopen();break;case i.State.Closed:this.onclose()}}}export{i as default};

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@alexgyver/ble",
+  "version": "1.0.0",
+  "description": "Web BLE Serial",
+  "main": "./ble.js",
+  "module": "./ble.js",
+  "types": "./ble.js",
+  "scripts": {
+    "build": "webpack --config ./webpack.config.js",
+    "dev": "webpack serve --config ./webpack.dev.config.js & webpack --config ./webpack.dev.config.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GyverLibs/ble.js.git"
+  },
+  "devDependencies": {
+    "webpack": "^5.103.0",
+    "webpack-cli": "^6.0.1",
+    "webpack-dev-server": "^5.2.2",
+    "html-webpack-plugin": "^5.6.5"
+  },
+  "dependencies": {
+    "@alexgyver/utils": "^1.2.4"
+  },
+  "author": "AlexGyver <alex@alexgyver.ru>",
+  "license": "MIT"
+}

package/test/index.html

@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
+  <script src="script.js" type="module" defer="defer"></script>
+  <title>BLE test</title>
+</head>
+
+<body>
+  <button id="select_b">select</button>
+  <button id="open_b">open</button>
+  <button id="close_b">close</button>
+  <button id="send_b">send</button>
+</body>
+
+</html>

package/test/script.js

@@ -0,0 +1,31 @@
+import BLEJS from "https://gyverlibs.github.io/BLE.js/ble.min.js";
+
+let i = 0;
+let ble = new BLEJS({ auto_open: true, eol: '' });
+
+// control
+select_b.onclick = () => ble.select();
+open_b.onclick = () => ble.open();
+close_b.onclick = () => ble.close();
+send_b.onclick = () => ble.sendText('Hello ' + i++);
+
+// read
+// ble.onbin = b => console.log(b);
+ble.ontext = t => console.log(t);
+
+// state
+// ble.onopen = () => {
+//     console.log('Opened', ble.getName());
+// }
+// ble.onclose = () => {
+//     console.log('Closed');
+// }
+ble.onchange = s => {
+    console.log(s);
+}
+ble.onerror = e => {
+    console.log(e);
+}
+ble.onselect = (d) => {
+    console.log('select', d);
+}

package/test_arduino/test_arduino.ino

@@ -0,0 +1,29 @@
+#include <Arduino.h>
+#include <BLESerial.h>
+// https://github.com/GyverLibs/BLESerial_ESP32
+
+void setup() {
+    Serial.begin(115200);
+    Serial.println("Start");
+
+    BLESerial.begin("ESP32C3");
+
+    BLESerial.onData([](uint8_t* data, size_t len) {
+        Serial.print("got data:");
+        Serial.write(data, len);
+        Serial.println();
+    });
+
+    BLESerial.onState([](bool conn) {
+        Serial.println(conn ? "connect" : "disconnect");
+    });
+}
+
+void loop() {
+    static uint32_t t;
+    if (millis() - t >= 3000) {
+        t = millis();
+        static int i;
+        BLESerial.send(String("Hello ") + (++i));
+    }
+}

package/test_dev/index.html

@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
+  <script src="script.js" type="module" defer="defer"></script>
+  <title>BLE test</title>
+</head>
+
+<body>
+  <button id="select_b">select</button>
+  <button id="open_b">open</button>
+  <button id="close_b">close</button>
+  <button id="send_b">send</button>
+</body>
+
+</html>

package/test_dev/script.js

@@ -0,0 +1,31 @@
+import BLEJS from "../ble";
+
+let i = 0;
+let ble = new BLEJS({ auto_open: true, eol: '' });
+
+// control
+select_b.onclick = () => ble.select();
+open_b.onclick = () => ble.open();
+close_b.onclick = () => ble.close();
+send_b.onclick = () => ble.sendText('Hello ' + i++);
+
+// read
+// ble.onbin = b => console.log(b);
+ble.ontext = t => console.log(t);
+
+// state
+// ble.onopen = () => {
+//     console.log('Opened', ble.getName());
+// }
+// ble.onclose = () => {
+//     console.log('Closed');
+// }
+ble.onchange = s => {
+    console.log(s);
+}
+ble.onerror = e => {
+    console.log(e);
+}
+ble.onselect = (d) => {
+    console.log('select', d);
+}

package/webpack.config.js

@@ -0,0 +1,14 @@
+module.exports = {
+    entry: './ble.js',
+    output: {
+        path: __dirname,
+        filename: 'ble.min.js',
+        library: {
+            type: 'module'
+        }
+    },
+    experiments: {
+        outputModule: true
+    },
+    mode: "production",
+};

package/webpack.dev.config.js

@@ -0,0 +1,39 @@
+const path = require('path');
+const PACKAGE = require('./package.json');
+const HtmlWebpackPlugin = require('html-webpack-plugin');
+
+module.exports = {
+    entry: {
+        index: './test_dev/script.js',
+    },
+
+    output: {
+        filename: 'script.js',
+        path: path.resolve(__dirname, 'dev'),
+        clean: true,
+    },
+
+    plugins: [
+        new HtmlWebpackPlugin({
+            template: `./test_dev/index.html`,
+            filename: `index.html`,
+            inject: true,
+            minify: false,
+            version: PACKAGE.version,
+            title: PACKAGE.title,
+        }),
+    ],
+
+    devServer: {
+        watchFiles: ['test_dev/*.html'],
+        static: path.resolve(__dirname, './dev'),
+        hot: true,
+        open: true,
+    },
+
+    watchOptions: {
+        poll: 1000,
+    },
+
+    mode: 'development',
+};