@alexgyver/ble 1.0.8 → 1.0.10

package/.github/workflows/pio-publish.yml

@@ -0,0 +1,32 @@
+
+name: Publish to PlatformIO Registry
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout release tag
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.release.tag_name }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install PlatformIO
+        run: pip install -U platformio
+
+      - name: Check package
+        run: pio pkg pack
+
+      - name: Publish to PlatformIO Registry
+        env:
+          PLATFORMIO_AUTH_TOKEN: ${{ secrets.PLATFORMIO_AUTH_TOKEN }}
+        run: pio pkg publish --owner gyverlibs --non-interactive

package/.github/workflows/tg-send.yml

@@ -0,0 +1,35 @@
+
+name: Telegram Message
+on:
+  release:
+    types: [published]
+jobs:
+  build:
+    name: Send Message
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check if major or minor release
+        id: semver
+        shell: bash
+        run: |
+          TAG="${{ github.event.release.tag_name }}"
+          VERSION="${TAG#v}"
+          PATCH="$(echo "$VERSION" | cut -d. -f3)"
+
+          if [[ "$PATCH" == "0" ]]; then
+            echo "should_send=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "should_send=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: send telegram message on release
+        if: steps.semver.outputs.should_send == 'true'
+        uses: appleboy/telegram-action@master
+        with:
+          to: ${{ secrets.TELEGRAM_TO }}
+          token: ${{ secrets.TELEGRAM_TOKEN }}
+          disable_web_page_preview: true
+          message: |
+            ${{ github.event.repository.name }} ${{ github.event.release.tag_name }}
+            ${{ github.event.release.body }}
+            https://github.com/${{ github.repository }}

package/README.md

@@ -1,8 +1,9 @@
 # BLE.js
 Обёртка на Web Bluetooth API
 - Автоматическое переподключение
-- Буферизация отправки
-- Буферизация приёма, разделение текста по разделителю
+- Последовательная отправка без пересечения записей
+- Настраиваемое дробление больших отправок
+- Отдельная атомарная отправка одного BLE frame
 
 [demo](https://gyverlibs.github.io/BLE.js/test/)
 
@@ -14,12 +15,14 @@
 ```js
 constructor(params = {});
 config(params = {});
-// eol: /\r?\n/
 // serviceUUID: '0000ffe0-0000-1000-8000-00805f9b34fb'
-// charxUUID: '0000ffe1-0000-1000-8000-00805f9b34fb'
+// rxUUID: '0000ffe1-0000-1000-8000-00805f9b34fb'
+// txUUID: '0000ffe2-0000-1000-8000-00805f9b34fb'
 // auto_open: false
-// max_tx: 20
 // reconnect: 1000
+// chunkSize: 500
+// chunkDelay: 0
+// withResponse: false
 
 onbin(b);
 ontext(t);
@@ -34,11 +37,76 @@ static supported();
 opened();
 selected();
 getName();
+getRxProperties();
+getTxProperties();
+canWriteWithResponse();
+canWriteWithoutResponse();
+canIndicate();
 
 select();
 open();
 close();
 
-sendBin(data);
-sendText(text);
-```
+sendBin(data, options = {});
+sendText(text, options = {});
+```
+
+Все методы отправки возвращают `Promise<boolean>`.
+
+## Дробление отправки
+
+`sendBin()` делит данные на несколько BLE characteristic writes по `chunkSize`. Задержка между записями задаётся через `chunkDelay`:
+
+```js
+const ble = new BLEJS({
+    chunkSize: 100,
+    chunkDelay: 5,
+});
+
+await ble.sendBin(data);
+```
+
+`chunkSize <= 0` отключает дробление и выполняет одну characteristic write:
+
+```js
+await ble.sendBin(data, { chunkSize: 0 });
+```
+
+Для протоколов, где одна BLE write является одним транспортным frame, отключите дробление для конкретной отправки:
+
+```js
+const ok = await ble.sendBin(frame, { chunkSize: 0 });
+```
+
+Опция `withResponse` едина для всех методов отправки:
+
+```js
+await ble.sendBin(data, { withResponse: true });
+await ble.sendText('hello', { withResponse: true });
+```
+
+Для атомарного фрейма с GATT response обе опции можно совместить:
+
+```js
+await ble.sendBin(frame, { withResponse: true, chunkSize: 0 });
+```
+
+При `withResponse: true` используется `writeValueWithResponse()`. Promise отправки завершается после ответа GATT-сервера, поэтому режим подходит для последовательной передачи с транспортным backpressure. Значение по умолчанию задаётся одноимённой настройкой конструктора.
+
+Для обратной совместимости второй boolean-аргумент продолжает трактоваться как старый `fast`: `true` выбирает Write without Response, `false` — Write with Response. Третий аргумент старой формы задаёт `chunkSize`:
+
+```js
+await ble.sendBin(data, false, 100);
+```
+
+Перед использованием можно проверить свойства найденных характеристик:
+
+```js
+if (!ble.canWriteWithResponse()) throw new Error('Write with Response is unavailable');
+if (!ble.canWriteWithoutResponse()) throw new Error('Write without Response is unavailable');
+if (!ble.canIndicate()) throw new Error('Indications are unavailable');
+```
+
+`getRxProperties()` и `getTxProperties()` возвращают объект `BluetoothCharacteristicProperties` либо `null`, пока соединение не открыто. `startNotifications()` включает доступный режим, но не позволяет JavaScript принудительно выбрать Indication вместо Notification. Если протоколу нужны именно Indication, TX characteristic на устройстве следует объявлять как indicate-only.
+
+Проверка поддержки выбранного способа записи выполняется внутри `sendBin()`. При несовместимой RX characteristic метод вызывает `onerror` и возвращает `false`.

package/README_EN.md

@@ -0,0 +1,81 @@
+This is an automatic translation and may be incorrect in some places. See the source README and examples for authoritative information.
+
+# BLE.js
+Wrapper on Web Bluetooth API
+- Automatic reconnection
+- Sequential writes without overlapping operations
+- Configurable splitting of large writes
+- Atomic sending of a single BLE frame
+
+[demo](https://gyverlibs.github.io/BLE.js/test/)
+
+> **Browser**: https://gyverlibs.github.io/BLE.js/BLE.min.js
+
+> **Node**: npm i @alexgyver/ble
+
+## Doc.
+```js
+constructor(params = {});
+config(params = {});
+// serviceUUID: '0000ffe0-0000-1000-8000-00805f9b34fb'
+// rxUUID: '0000ffe1-0000-1000-8000-00805f9b34fb'
+// txUUID: '0000ffe2-0000-1000-8000-00805f9b34fb'
+// auto_open: false
+// reconnect: 1000
+// chunkSize: 500
+// chunkDelay: 0
+// withResponse: false
+
+onbin(b);
+ontext(t);
+
+onopen():
+onclose():
+onchange(s):
+onselect(name);
+onerror(e);
+
+static supported();
+opened();
+selected();
+getName();
+getRxProperties();
+getTxProperties();
+canWriteWithResponse();
+canWriteWithoutResponse();
+canIndicate();
+
+select();
+open();
+close();
+
+sendBin(data, options = {});
+sendText(text, options = {});
+```
+
+All send methods return `Promise<boolean>`.
+
+The `withResponse` option is shared by all send methods:
+
+```js
+await ble.sendBin(data, { withResponse: true });
+await ble.sendText('hello', { withResponse: true });
+```
+
+Set `chunkSize: 0` when one protocol frame must map to exactly one characteristic write:
+
+```js
+await ble.sendBin(frame, { withResponse: true, chunkSize: 0 });
+```
+
+With `withResponse: true`, the library uses `writeValueWithResponse()` and validates that the connected RX characteristic supports it. The send Promise resolves after the GATT response, providing transport-level backpressure. The constructor option with the same name selects the default mode.
+
+The legacy boolean argument remains supported: `true` means Write without Response and `false` means Write with Response. The legacy third argument still sets `chunkSize`:
+
+```js
+await ble.sendBin(data, false, 100);
+```
+
+`canWriteWithResponse()`, `canWriteWithoutResponse()`, and `canIndicate()` expose the capabilities of the connected RX and TX characteristics. `getRxProperties()` and `getTxProperties()` return their complete `BluetoothCharacteristicProperties`, or `null` while disconnected. Every send validates the selected write mode and returns `false` through the usual error path when it is unsupported.
+
+Web Bluetooth does not let JavaScript explicitly select Indication instead of Notification. A protocol that requires Indication should expose an indicate-only TX characteristic on the peripheral.

package/ble.js

@@ -25,6 +25,7 @@ export default class BLEJS {
             reconnect: 1000,
             chunkSize: 500,
             chunkDelay: 0,
+            withResponse: false,
         };
 
         this.cfg = { ...def, ...params };
@@ -50,6 +51,26 @@ export default class BLEJS {
         return this._device ? this._device.name : 'None';
     }
 
+    getRxProperties() {
+        return this._rx?.properties ?? null;
+    }
+
+    getTxProperties() {
+        return this._tx?.properties ?? null;
+    }
+
+    canWriteWithResponse() {
+        return !!this._rx?.properties?.write;
+    }
+
+    canWriteWithoutResponse() {
+        return !!this._rx?.properties?.writeWithoutResponse;
+    }
+
+    canIndicate() {
+        return !!this._tx?.properties?.indicate;
+    }
+
     async select() {
         try {
             await this.close();
@@ -162,37 +183,74 @@ export default class BLEJS {
         }
     }
 
-    async sendText(text, fast = true) {
-        await this.sendBin((new TextEncoder()).encode(text), fast);
+    async sendText(text, options) {
+        return this.sendBin((new TextEncoder()).encode(text), options);
     }
 
-    async sendBin(data, fast = true) {
+    async sendBin(data, options, legacyChunkSize) {
         if (!this.opened() || !this._rx) return false;
 
-        return this._sender.runNothrow(async () => {
+        options = this._sendOptions(options, legacyChunkSize);
+
+        const result = await this._sender.runNothrow(async () => {
             if (!this.opened() || !this._rx) return false;
 
-            const chunkSize = this.cfg.chunkSize;
             const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+            if (!bytes.length) return true;
 
-            for (let i = 0; i < bytes.length; i += chunkSize) {
-                if (!this.opened() || !this._rx) return false;
+            if (options.withResponse) {
+                if (!this.canWriteWithResponse()) {
+                    this._error('RX characteristic does not support Write with Response');
+                    return false;
+                }
+            } else if (!this.canWriteWithoutResponse()) {
+                this._error('RX characteristic does not support Write without Response');
+                return false;
+            }
 
-                const chunk = bytes.slice(i, i + chunkSize);
+            let size = Number(options.chunkSize);
+            if (!Number.isFinite(size) || size <= 0) size = bytes.length;
+            else size = Math.max(1, Math.floor(size));
 
-                if (fast) {
-                    await this._rx.writeValueWithoutResponse(chunk);
-                } else {
-                    await this._rx.writeValueWithResponse(chunk);
-                }
+            try {
+                for (let i = 0; i < bytes.length; i += size) {
+                    if (!this.opened() || !this._rx) return false;
 
-                if (this.cfg.chunkDelay > 0) {
-                    await sleep(this.cfg.chunkDelay);
+                    const chunk = bytes.subarray(i, i + size);
+
+                    if (options.withResponse) {
+                        await this._rx.writeValueWithResponse(chunk);
+                    } else {
+                        await this._rx.writeValueWithoutResponse(chunk);
+                    }
+
+                    if (i + size < bytes.length && this.cfg.chunkDelay > 0) {
+                        await sleep(this.cfg.chunkDelay);
+                    }
                 }
+            } catch (e) {
+                this._error(e);
+                return false;
             }
 
             return true;
         });
+
+        return result === true;
+    }
+
+    _sendOptions(options, legacyChunkSize) {
+        if (typeof options === 'boolean') {
+            return {
+                withResponse: !options,
+                chunkSize: legacyChunkSize ?? this.cfg.chunkSize,
+            };
+        }
+
+        return {
+            withResponse: options?.withResponse ?? this.cfg.withResponse,
+            chunkSize: options?.chunkSize ?? this.cfg.chunkSize,
+        };
     }
 
     _state = BLEJS.State.Closed;
@@ -271,4 +329,4 @@ export default class BLEJS {
                 break;
         }
     }
-}
+}

package/ble.min.js

@@ -1 +1 @@
-const t=t=>new Promise(e=>setTimeout(e,t));class e{constructor(){this._session=0,this.reset()}run(t){const e=this._session,s=this._queue.then(()=>{if(e!==this._session)throw new Error("Queue empty");return t()});return this._queue=s.catch(()=>{}),s}runNothrow(t){return this.run(t).catch(()=>null)}reset(){this._session++,this._queue=Promise.resolve()}}class s{static State={Closed:"closed",Opening:"opening",Open:"open",Closing:"closing"};ontext=null;onbin(t){}onopen(){}onclose(){}onchange(t){}onselect(t){}onerror(t){}constructor(t={}){this.cfg={serviceUUID:"0000ffe0-0000-1000-8000-00805f9b34fb",rxUUID:"0000ffe1-0000-1000-8000-00805f9b34fb",txUUID:"0000ffe2-0000-1000-8000-00805f9b34fb",auto_open:!1,reconnect:1e3,chunkSize:500,chunkDelay:0,...t}}config(t={}){this.cfg={...this.cfg,...t}}static supported(){return"bluetooth"in navigator}opened(){return this._state===s.State.Open}selected(){return!!this._device}getName(){return this._device?this._device.name:"None"}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(){return this._lifecycle.runNothrow(async()=>this._device?!!this.opened()||(this.cfg.reconnect&&(this.retry=!0),await this._open(),this.opened()):(this._error("No device"),!1))}async _open(){if(this._state===s.State.Closed){this._change(s.State.Opening);try{const t=await this._device.gatt.connect(),e=await t.getPrimaryService(this.cfg.serviceUUID);this._rx=await e.getCharacteristic(this.cfg.rxUUID),this._tx=await e.getCharacteristic(this.cfg.txUUID),await this._tx.startNotifications(),this._tx.addEventListener("characteristicvaluechanged",this._data_h),this._sender.reset(),this._change(s.State.Open)}catch(e){this._error(e),this._sender.reset(),this._change(s.State.Closed),this.retry&&t(this.cfg.reconnect).then(()=>{this._lifecycle.runNothrow(()=>this._open())})}}}async close(){return this._lifecycle.runNothrow(async()=>(this.retry=!1,this._sender.reset(),this._state!==s.State.Closed&&await this._close(),!0))}async _close(){if(this._state!==s.State.Closed){this._change(s.State.Closing);try{this._device?.gatt?.connected?this._device.gatt.disconnect():await this._disconnect()}catch(t){this._error(t),await this._disconnect()}}}async sendText(t,e=!0){await this.sendBin((new TextEncoder).encode(t),e)}async sendBin(e,s=!0){return!(!this.opened()||!this._rx)&&this._sender.runNothrow(async()=>{if(!this.opened()||!this._rx)return!1;const i=this.cfg.chunkSize,n=e instanceof Uint8Array?e:new Uint8Array(e);for(let e=0;e<n.length;e+=i){if(!this.opened()||!this._rx)return!1;const c=n.slice(e,e+i);s?await this._rx.writeValueWithoutResponse(c):await this._rx.writeValueWithResponse(c),this.cfg.chunkDelay>0&&await t(this.cfg.chunkDelay)}return!0})}_state=s.State.Closed;_device=null;_rx=null;_tx=null;retry=!1;_sender=new e;_lifecycle=new e;async _disconnect(e){if(this._sender.reset(),this._tx)try{this._tx.removeEventListener("characteristicvaluechanged",this._data_h)}catch(e){}this._rx=null,this._tx=null,this._change(s.State.Closed),this.retry&&t(this.cfg.reconnect).then(()=>{this._lifecycle.runNothrow(()=>this._open())}),await t(50)}_disconnect_h=this._disconnect.bind(this);_data(t){try{const e=t.target.value,s=new Uint8Array(e.buffer,e.byteOffset,e.byteLength);this.onbin(s),this.ontext&&this.ontext((new TextDecoder).decode(s))}catch(t){this._error(t)}}_data_h=this._data.bind(this);_error(t){this.onerror("[BLE] "+t)}_change(t){if(this._state!==t)switch(this._state=t,this.onchange(t),t){case s.State.Open:this.onopen();break;case s.State.Closed:this.onclose()}}}export{s as default};
+const e=e=>new Promise(t=>setTimeout(t,e));class t{constructor(){this._session=0,this.reset()}run(e){const t=this._session,s=this._queue.then(()=>{if(t!==this._session)throw new Error("Queue empty");return e()});return this._queue=s.catch(()=>{}),s}runNothrow(e){return this.run(e).catch(()=>null)}reset(){this._session++,this._queue=Promise.resolve()}}class s{static State={Closed:"closed",Opening:"opening",Open:"open",Closing:"closing"};ontext=null;onbin(e){}onopen(){}onclose(){}onchange(e){}onselect(e){}onerror(e){}constructor(e={}){this.cfg={serviceUUID:"0000ffe0-0000-1000-8000-00805f9b34fb",rxUUID:"0000ffe1-0000-1000-8000-00805f9b34fb",txUUID:"0000ffe2-0000-1000-8000-00805f9b34fb",auto_open:!1,reconnect:1e3,chunkSize:500,chunkDelay:0,withResponse:!1,...e}}config(e={}){this.cfg={...this.cfg,...e}}static supported(){return"bluetooth"in navigator}opened(){return this._state===s.State.Open}selected(){return!!this._device}getName(){return this._device?this._device.name:"None"}getRxProperties(){return this._rx?.properties??null}getTxProperties(){return this._tx?.properties??null}canWriteWithResponse(){return!!this._rx?.properties?.write}canWriteWithoutResponse(){return!!this._rx?.properties?.writeWithoutResponse}canIndicate(){return!!this._tx?.properties?.indicate}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(e){this._error(e),this._device=null}return this.onselect(this.getName()),this.cfg.auto_open&&this.open(),this.selected()}async open(){return this._lifecycle.runNothrow(async()=>this._device?!!this.opened()||(this.cfg.reconnect&&(this.retry=!0),await this._open(),this.opened()):(this._error("No device"),!1))}async _open(){if(this._state===s.State.Closed){this._change(s.State.Opening);try{const e=await this._device.gatt.connect(),t=await e.getPrimaryService(this.cfg.serviceUUID);this._rx=await t.getCharacteristic(this.cfg.rxUUID),this._tx=await t.getCharacteristic(this.cfg.txUUID),await this._tx.startNotifications(),this._tx.addEventListener("characteristicvaluechanged",this._data_h),this._sender.reset(),this._change(s.State.Open)}catch(t){this._error(t),this._sender.reset(),this._change(s.State.Closed),this.retry&&e(this.cfg.reconnect).then(()=>{this._lifecycle.runNothrow(()=>this._open())})}}}async close(){return this._lifecycle.runNothrow(async()=>(this.retry=!1,this._sender.reset(),this._state!==s.State.Closed&&await this._close(),!0))}async _close(){if(this._state!==s.State.Closed){this._change(s.State.Closing);try{this._device?.gatt?.connected?this._device.gatt.disconnect():await this._disconnect()}catch(e){this._error(e),await this._disconnect()}}}async sendText(e,t){return this.sendBin((new TextEncoder).encode(e),t)}async sendBin(t,s,i){return!(!this.opened()||!this._rx)&&(s=this._sendOptions(s,i),!0===await this._sender.runNothrow(async()=>{if(!this.opened()||!this._rx)return!1;const i=t instanceof Uint8Array?t:new Uint8Array(t);if(!i.length)return!0;if(s.withResponse){if(!this.canWriteWithResponse())return this._error("RX characteristic does not support Write with Response"),!1}else if(!this.canWriteWithoutResponse())return this._error("RX characteristic does not support Write without Response"),!1;let n=Number(s.chunkSize);n=!Number.isFinite(n)||n<=0?i.length:Math.max(1,Math.floor(n));try{for(let t=0;t<i.length;t+=n){if(!this.opened()||!this._rx)return!1;const r=i.subarray(t,t+n);s.withResponse?await this._rx.writeValueWithResponse(r):await this._rx.writeValueWithoutResponse(r),t+n<i.length&&this.cfg.chunkDelay>0&&await e(this.cfg.chunkDelay)}}catch(e){return this._error(e),!1}return!0}))}_sendOptions(e,t){return"boolean"==typeof e?{withResponse:!e,chunkSize:t??this.cfg.chunkSize}:{withResponse:e?.withResponse??this.cfg.withResponse,chunkSize:e?.chunkSize??this.cfg.chunkSize}}_state=s.State.Closed;_device=null;_rx=null;_tx=null;retry=!1;_sender=new t;_lifecycle=new t;async _disconnect(t){if(this._sender.reset(),this._tx)try{this._tx.removeEventListener("characteristicvaluechanged",this._data_h)}catch(t){}this._rx=null,this._tx=null,this._change(s.State.Closed),this.retry&&e(this.cfg.reconnect).then(()=>{this._lifecycle.runNothrow(()=>this._open())}),await e(50)}_disconnect_h=this._disconnect.bind(this);_data(e){try{const t=e.target.value,s=new Uint8Array(t.buffer,t.byteOffset,t.byteLength);this.onbin(s),this.ontext&&this.ontext((new TextDecoder).decode(s))}catch(e){this._error(e)}}_data_h=this._data.bind(this);_error(e){this.onerror("[BLE] "+e)}_change(e){if(this._state!==e)switch(this._state=e,this.onchange(e),e){case s.State.Open:this.onopen();break;case s.State.Closed:this.onclose()}}}export{s as default};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexgyver/ble",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "Web BLE Serial",
   "main": "./ble.js",
   "module": "./ble.js",
@@ -14,14 +14,14 @@
     "url": "git+https://github.com/GyverLibs/ble.js.git"
   },
   "devDependencies": {
-    "css-loader": "^7.1.4",
+    "css-loader": "^7.1.5",
     "style-loader": "^4.0.0",
-    "webpack": "^5.106.2",
-    "webpack-cli": "^7.0.2",
-    "webpack-dev-server": "^5.2.4"
+    "webpack": "^5.110.3",
+    "webpack-cli": "^7.2.3",
+    "webpack-dev-server": "^6.0.0"
   },
   "dependencies": {
-    "@alexgyver/utils": "^1.2.8"
+    "@alexgyver/utils": "^1.2.18"
   },
   "author": "AlexGyver <alex@alexgyver.ru>",
   "license": "MIT"

package/test/script.js

@@ -1,5 +1,5 @@
-// import BLEJS from "https://gyverlibs.github.io/BLE.js/ble.min.js";
-import BLEJS from "../ble.js";
+import BLEJS from "https://gyverlibs.github.io/BLE.js/ble.min.js";
+// import BLEJS from "../ble.js";
 
 let i = 0;
 let ble = new BLEJS({ auto_open: true });