@alexgyver/ble 1.0.9 → 1.0.10

package/README.md

@@ -22,6 +22,7 @@ config(params = {});
 // reconnect: 1000
 // chunkSize: 500
 // chunkDelay: 0
+// withResponse: false
 
 onbin(b);
 ontext(t);
@@ -36,14 +37,18 @@ static supported();
 opened();
 selected();
 getName();
+getRxProperties();
+getTxProperties();
+canWriteWithResponse();
+canWriteWithoutResponse();
+canIndicate();
 
 select();
 open();
 close();
 
-sendBin(data, fast = true, chunkSize = config.chunkSize);
-sendFrame(data, fast = true);
-sendText(text, fast = true);
+sendBin(data, options = {});
+sendText(text, options = {});
 ```
 
 Все методы отправки возвращают `Promise<boolean>`.
@@ -64,18 +69,44 @@ await ble.sendBin(data);
 `chunkSize <= 0` отключает дробление и выполняет одну characteristic write:
 
 ```js
-await ble.sendBin(data, true, 0);
+await ble.sendBin(data, { chunkSize: 0 });
 ```
 
-Для протоколов, где одна BLE write является одним транспортным frame, следует использовать `sendFrame()`:
+Для протоколов, где одна BLE write является одним транспортным frame, отключите дробление для конкретной отправки:
 
 ```js
-const ok = await ble.sendFrame(frame);
+const ok = await ble.sendBin(frame, { chunkSize: 0 });
 ```
 
-`sendFrame()` никогда не делит данные. Если characteristic или устройство не принимает запись такого размера, метод вызовет `onerror` и вернёт `false`.
+Опция `withResponse` едина для всех методов отправки:
 
-Параметр `fast` выбирает способ записи:
+```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.
 
-- `true` — `writeValueWithoutResponse`
-- `false` — `writeValueWithResponse`
+Проверка поддержки выбранного способа записи выполняется внутри `sendBin()`. При несовместимой RX characteristic метод вызывает `onerror` и возвращает `false`.

package/README_EN.md

@@ -3,8 +3,9 @@ This is an automatic translation and may be incorrect in some places. See the so
 # BLE.js
 Wrapper on Web Bluetooth API
 - Automatic reconnection
-- Shipment buffering
-- Reception buffering, separation of text by separator
+- 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/)
 
@@ -16,12 +17,14 @@ Wrapper on Web Bluetooth API
 ```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);
@@ -36,11 +39,43 @@ static supported();
 opened();
 selected();
 getName();
+getRxProperties();
+getTxProperties();
+canWriteWithResponse();
+canWriteWithoutResponse();
+canIndicate();
 
 select();
 open();
 close();
 
-sendBin(data);
-sendText(text);
+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,24 +183,32 @@ export default class BLEJS {
         }
     }
 
-    async sendText(text, fast = true) {
-        return this.sendBin((new TextEncoder()).encode(text), fast);
+    async sendText(text, options) {
+        return this.sendBin((new TextEncoder()).encode(text), options);
     }
 
-    async sendFrame(data, fast = true) {
-        return this.sendBin(data, fast, 0);
-    }
-
-    async sendBin(data, fast = true, chunkSize = this.cfg.chunkSize) {
+    async sendBin(data, options, legacyChunkSize) {
         if (!this.opened() || !this._rx) return false;
 
+        options = this._sendOptions(options, legacyChunkSize);
+
         const result = await this._sender.runNothrow(async () => {
             if (!this.opened() || !this._rx) return false;
 
             const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
             if (!bytes.length) return true;
 
-            let size = Number(chunkSize);
+            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;
+            }
+
+            let size = Number(options.chunkSize);
             if (!Number.isFinite(size) || size <= 0) size = bytes.length;
             else size = Math.max(1, Math.floor(size));
 
@@ -189,10 +218,10 @@ export default class BLEJS {
 
                     const chunk = bytes.subarray(i, i + size);
 
-                    if (fast) {
-                        await this._rx.writeValueWithoutResponse(chunk);
-                    } else {
+                    if (options.withResponse) {
                         await this._rx.writeValueWithResponse(chunk);
+                    } else {
+                        await this._rx.writeValueWithoutResponse(chunk);
                     }
 
                     if (i + size < bytes.length && this.cfg.chunkDelay > 0) {
@@ -210,6 +239,20 @@ export default class BLEJS {
         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;
     _device = null;
     _rx = null;

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){return this.sendBin((new TextEncoder).encode(t),e)}async sendFrame(t,e=!0){return this.sendBin(t,e,0)}async sendBin(e,s=!0,i=this.cfg.chunkSize){return!(!this.opened()||!this._rx)&&!0===await this._sender.runNothrow(async()=>{if(!this.opened()||!this._rx)return!1;const n=e instanceof Uint8Array?e:new Uint8Array(e);if(!n.length)return!0;let r=Number(i);r=!Number.isFinite(r)||r<=0?n.length:Math.max(1,Math.floor(r));try{for(let e=0;e<n.length;e+=r){if(!this.opened()||!this._rx)return!1;const i=n.subarray(e,e+r);s?await this._rx.writeValueWithoutResponse(i):await this._rx.writeValueWithResponse(i),e+r<n.length&&this.cfg.chunkDelay>0&&await t(this.cfg.chunkDelay)}}catch(t){return this._error(t),!1}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.9",
+  "version": "1.0.10",
   "description": "Web BLE Serial",
   "main": "./ble.js",
   "module": "./ble.js",
@@ -16,7 +16,7 @@
   "devDependencies": {
     "css-loader": "^7.1.5",
     "style-loader": "^4.0.0",
-    "webpack": "^5.110.2",
+    "webpack": "^5.110.3",
     "webpack-cli": "^7.2.3",
     "webpack-dev-server": "^6.0.0"
   },