@alexgyver/serial 1.0.11 → 1.0.13

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,7 +1,8 @@
 # Serial.js
 Обёртка на Web Serial API
 - Автоматическое переподключение
-- Сохранение последнего выбранного порта
+- Восстановление ранее разрешённого порта
+- Безопасная работа с несколькими разрешёнными портами
 - Буферизация отправки
 - Буферизация приёма, разделение текста по разделителю
 
@@ -17,8 +18,14 @@ constructor(params = {});
 config(params = {});
 // eol: /\r?\n/
 // baud: 115200
+// dataBits: 8
+// stopBits: 1
+// parity: 'none'
+// bufferSize: 255
+// flowControl: 'none'
 // auto_open: false
 // reconnect: 1000
+// forgetOtherPorts: true
 
 onbin(b);
 ontext(t);
@@ -32,12 +39,40 @@ onerror(e);
 static supported();
 opened();
 selected();
+getInfo();
 getName();
 
 select();
+restore();
+getPorts();
+forget();
 open();
 close();
 
 sendBin(data);
 sendText(text);
-```
+```
+
+`select()` использует порт, возвращённый системным диалогом выбора. По умолчанию `forgetOtherPorts: true` - разрешение остаётся только у выбранного порта, поэтому после перезагрузки страницы его можно восстановить автоматически.
+
+Для приложений, работающих с несколькими портами, нужен `forgetOtherPorts: false`. В этом режиме библиотека не отзывает чужие разрешения, а `restore()` автоматически выбирает порт только тогда, когда разрешён ровно один. Если портов несколько, надо вызвать `select()`.
+
+- `getPorts()` возвращает все ранее разрешённые порты
+- `restore()` восстанавливает порт без системного диалога, если выбор однозначен
+- `forget()` закрывает текущий порт и отзывает только его разрешение
+
+## Настройки порта
+
+При открытии библиотека передаёт в `SerialPort.open()` параметры `baud`, `dataBits`, `stopBits`, `parity`, `bufferSize` и `flowControl`. Например:
+
+```js
+const serial = new SerialJS({
+    baud: 115200,
+    bufferSize: 4096,
+    flowControl: 'hardware',
+});
+```
+
+`flowControl: 'hardware'` включает RTS/CTS и работает только при поддержке со стороны порта и физического подключения. Значение по умолчанию — `'none'`.
+
+`sendBin()` последовательно выполняет отправки и ожидает Promise от `writer.write()`. Это использует backpressure Web Serial, но не является прикладным подтверждением обработки данных устройством.

package/README_EN.md

@@ -0,0 +1,70 @@
+This is an automatic translation and may be incorrect in some places. See the source README and examples for authoritative information.
+
+# Serial.js
+Wrapper on Web Serial API
+- Automatic reconnection
+- Restoration of a previously authorized port
+- Safe handling of multiple authorized ports
+- Sequential writes
+- Buffered text reception and splitting
+
+[demo](https://gyverlibs.github.io/Serial.js/test/)
+
+> **Browser**: https://gyverlibs.github.io/Serial.js/Serial.min.js
+
+> **Node**: npm i @alexgyver/serial
+
+## Doc.
+```js
+constructor(params = {});
+config(params = {});
+// eol: /\r?\n/
+// baud: 115200
+// dataBits: 8
+// stopBits: 1
+// parity: 'none'
+// bufferSize: 255
+// flowControl: 'none'
+// auto_open: false
+// reconnect: 1000
+// forgetOtherPorts: true
+
+onbin(b);
+ontext(t);
+
+onopen():
+onclose():
+onchange(s):
+onselect(name);
+onerror(e);
+
+static supported();
+opened();
+selected();
+getInfo();
+getName();
+
+select();
+restore();
+getPorts();
+forget();
+open();
+close();
+
+sendBin(data);
+sendText(text);
+```
+
+The library passes `baud`, `dataBits`, `stopBits`, `parity`, `bufferSize`, and `flowControl` to `SerialPort.open()`. For example:
+
+```js
+const serial = new SerialJS({
+    baud: 115200,
+    bufferSize: 4096,
+    flowControl: 'hardware',
+});
+```
+
+Hardware flow control uses RTS/CTS and only works when both the port and the physical connection support it. The default is `'none'`.
+
+`sendBin()` serializes writes and awaits the Promise returned by `writer.write()`. This applies Web Serial backpressure, but it does not confirm that the remote application has processed the data.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexgyver/serial",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "description": "Web Serial API wrapper",
   "main": "./serial.js",
   "module": "./serial.js",
@@ -14,14 +14,14 @@
     "url": "git+https://github.com/GyverLibs/Serial.js.git"
   },
   "devDependencies": {
-    "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",
     "style-loader": "^4.0.0",
-    "css-loader": "^7.1.4"
+    "css-loader": "^7.1.5"
   },
   "dependencies": {
-    "@alexgyver/utils": "^1.2.8"
+    "@alexgyver/utils": "^1.2.18"
   },
   "author": "AlexGyver <alex@alexgyver.ru>",
   "license": "MIT"

package/serial.js

@@ -23,12 +23,18 @@ export default class SerialJS {
         const def = {
             eol: /\r?\n/,
             baud: 115200,
+            dataBits: 8,
+            stopBits: 1,
+            parity: 'none',
+            bufferSize: 255,
+            flowControl: 'none',
             auto_open: false,
             reconnect: 1000,
+            forgetOtherPorts: true,
         };
         this.cfg = { ...def, ...params };
 
-        this._setLastPort().then(() => this.onselect(this.getName()));
+        this.restore().then(() => this.onselect(this.getName()));
         this.splitter = new StreamSplitter(this.cfg.eol);
         this.splitter.ontext = (t) => {
             try {
@@ -57,10 +63,14 @@ export default class SerialJS {
         return !!this._port;
     }
 
+    getInfo() {
+        return this._port?.getInfo() ?? null;
+    }
+
     getName() {
         if (!this._port) return 'None';
 
-        switch (this._port.getInfo().usbProductId) {
+        switch (this.getInfo().usbProductId) {
             case 0x55d3: return 'CH343';
             case 0x7584: return 'CH340S';
             case 0x7522: case 0x7523: return 'CH340';
@@ -74,48 +84,87 @@ export default class SerialJS {
     async select() {
         try {
             await this.close();
-            this._port = null;
-            let ports = await navigator.serial.getPorts();
-            for (let p of ports) await p.forget();
-            await sleep(50);
-            await navigator.serial.requestPort();
-            await this._setLastPort();
+            const port = await navigator.serial.requestPort();
+
+            if (this.cfg.forgetOtherPorts) {
+                const ports = await navigator.serial.getPorts();
+                for (const p of ports) {
+                    if (p !== port) await p.forget();
+                }
+            }
+
+            this._port = port;
         } catch (e) {
             this._error(e);
         }
         this.onselect(this.getName());
-        if (this.cfg.auto_open) this.open();
+        if (this.cfg.auto_open) return this.open();
+        return this.selected();
+    }
+
+    async getPorts() {
+        return navigator.serial.getPorts();
+    }
+
+    async restore() {
+        const ports = await this.getPorts();
+        this._port = this.cfg.forgetOtherPorts
+            ? (ports[0] ?? null)
+            : (ports.length === 1 ? ports[0] : null);
         return this.selected();
     }
 
+    async forget() {
+        await this.close();
+        if (!this._port) return false;
+
+        const port = this._port;
+        this._port = null;
+
+        try {
+            await port.forget();
+            this.onselect(this.getName());
+            return true;
+        } catch (e) {
+            this._port = port;
+            this._error(e);
+            return false;
+        }
+    }
+
     async open() {
-        const ports = await navigator.serial.getPorts();
-        if (!ports.length) return false;
+        if (this.opened()) return true;
+        if (this._openPromise) return this._openPromise;
+        if (this._state !== SerialJS.State.Closed) return false;
 
         if (this.cfg.reconnect) this.retry = true;
 
-        this._open();
-        return true;
+        const promise = this._connect();
+        this._openPromise = promise;
+        const result = await promise;
+        if (this._openPromise === promise) this._openPromise = null;
+        return result;
     }
-    async _open() {
-        if (this._state !== SerialJS.State.Closed) return;
-
+    async _connect() {
         this._change(SerialJS.State.Opening);
 
         try {
-            await this._setLastPort();
+            if (!this._port) await this.restore();
 
             if (!this._port) {
                 throw new Error('No port');
             }
 
-            if (this._state === SerialJS.State.Closing) return;
+            if (this._state === SerialJS.State.Closing) {
+                await this._cleanup();
+                return false;
+            }
 
-            await this._port.open({ baudRate: this.cfg.baud });
+            await this._port.open(this._openOptions());
 
             if (this._state === SerialJS.State.Closing) {
-                await this._port.close();
-                return;
+                await this._cleanup();
+                return false;
             }
 
             this.writer = this._port.writable.getWriter();
@@ -123,7 +172,18 @@ export default class SerialJS {
 
             this._sender.reset();
             this._change(SerialJS.State.Open);
+            void this._listen();
+            return true;
+        } catch (e) {
+            this._error(e);
+        }
+
+        await this._cleanup();
+        return false;
+    }
 
+    async _listen() {
+        try {
             while (this._state === SerialJS.State.Open) {
                 const { value, done } = await this.reader.read();
 
@@ -147,6 +207,10 @@ export default class SerialJS {
             this._error(e);
         }
 
+        await this._cleanup();
+    }
+
+    async _cleanup() {
         this._sender.reset();
 
         try {
@@ -168,7 +232,7 @@ export default class SerialJS {
 
         if (this.retry) {
             setTimeout(() => {
-                if (this.retry) this._open();
+                if (this.retry) this.open();
             }, this.cfg.reconnect);
         }
     }
@@ -219,11 +283,16 @@ export default class SerialJS {
     async sendBin(data) {
         if (!this.opened() || !this.writer) return false;
 
-        return this._sender.runNothrow(async () => {
-            if (!this.opened() || !this.writer) return false;
-            await this.writer.write(data);
-            return true;
-        });
+        try {
+            return await this._sender.run(async () => {
+                if (!this.opened() || !this.writer) return false;
+                await this.writer.write(data);
+                return true;
+            });
+        } catch (e) {
+            if (this.opened()) this._error(e);
+            return false;
+        }
     }
 
     //#region private
@@ -231,10 +300,17 @@ export default class SerialJS {
     _decoder = new TextDecoder();
     _sender = new SerialExecutor();
     _state = SerialJS.State.Closed;
-
-    async _setLastPort() {
-        let ports = await navigator.serial.getPorts();
-        this._port = ports.length ? ports[0] : null;
+    _openPromise = null;
+
+    _openOptions() {
+        return {
+            baudRate: this.cfg.baud,
+            dataBits: this.cfg.dataBits,
+            stopBits: this.cfg.stopBits,
+            parity: this.cfg.parity,
+            bufferSize: this.cfg.bufferSize,
+            flowControl: this.cfg.flowControl,
+        };
     }
 
     _error(e) {
@@ -251,4 +327,4 @@ export default class SerialJS {
             case SerialJS.State.Closed: this.onclose(); break;
         }
     }
-}
+}

package/serial.min.js

@@ -1 +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._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 r{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/,baud:115200,auto_open:!1,reconnect:1e3,...t},this._setLastPort().then(()=>this.onselect(this.getName())),this.splitter=new e(this.cfg.eol),this.splitter.ontext=t=>{try{this.ontext?.(t)}catch(t){this._error(t)}}}config(t={}){this.cfg={...this.cfg,...t},this.splitter.eol=this.cfg.eol}static supported(){return"serial"in navigator}opened(){return this._state==r.State.Open}selected(){return!!this._port}getName(){if(!this._port)return"None";switch(this._port.getInfo().usbProductId){case 21971:return"CH343";case 30084:return"CH340S";case 29986:case 29987:return"CH340";case 21778:case 21795:case 21892:return"CH341";case 1026:case 1027:case 1028:case 1029:case 24577:case 1538:case 24592:return"FT232";case 38144:case 258:case 1281:case 32937:case 6e4:case 60001:case 60003:return"CP210x"}return"Unknown"}async select(){try{await this.close(),this._port=null;let e=await navigator.serial.getPorts();for(let t of e)await t.forget();await t(50),await navigator.serial.requestPort(),await this._setLastPort()}catch(t){this._error(t)}return this.onselect(this.getName()),this.cfg.auto_open&&this.open(),this.selected()}async open(){return!!(await navigator.serial.getPorts()).length&&(this.cfg.reconnect&&(this.retry=!0),this._open(),!0)}async _open(){if(this._state===r.State.Closed){this._change(r.State.Opening);try{if(await this._setLastPort(),!this._port)throw new Error("No port");if(this._state===r.State.Closing)return;if(await this._port.open({baudRate:this.cfg.baud}),this._state===r.State.Closing)return void await this._port.close();for(this.writer=this._port.writable.getWriter(),this.reader=this._port.readable.getReader(),this._sender.reset(),this._change(r.State.Open);this._state===r.State.Open;){const{value:t,done:e}=await this.reader.read();if(e)break;if(t){try{this.onbin?.(t)}catch(t){this._error(t)}this.ontext&&this.splitter.write(this._decoder.decode(t,{stream:!0}))}}}catch(t){this._error(t)}this._sender.reset();try{this.reader&&this.reader.releaseLock()}catch(t){}try{this.writer&&this.writer.releaseLock()}catch(t){}this.reader=null,this.writer=null;try{this._port&&await this._port.close()}catch(t){}this._change(r.State.Closed),this.retry&&setTimeout(()=>{this.retry&&this._open()},this.cfg.reconnect)}}async close(){return this.retry=!1,this._sender.reset(),await this._close(),!0}async _close(){switch(this._state){case r.State.Closed:return;case r.State.Opening:this._change(r.State.Closing);break;case r.State.Open:if(this._change(r.State.Closing),this.reader)try{await this.reader.cancel()}catch(t){}}let e=0;for(;this._state===r.State.Closing;)if(await t(10),++e>200){this._error("Close timeout"),this._change(r.State.Closed);break}}async sendText(t){return this.sendBin((new TextEncoder).encode(t))}async sendBin(t){return!(!this.opened()||!this.writer)&&this._sender.runNothrow(async()=>!(!this.opened()||!this.writer||(await this.writer.write(t),0)))}_port=null;_decoder=new TextDecoder;_sender=new s;_state=r.State.Closed;async _setLastPort(){let t=await navigator.serial.getPorts();this._port=t.length?t[0]:null}_error(t){this.onerror("[SerialJS] "+t)}_change(t){if(this._state!==t)switch(this._state=t,this.onchange(t),t){case r.State.Open:this.onopen();break;case r.State.Closed:this.onclose()}}}export{r as default};
+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._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 r{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/,baud:115200,dataBits:8,stopBits:1,parity:"none",bufferSize:255,flowControl:"none",auto_open:!1,reconnect:1e3,forgetOtherPorts:!0,...t},this.restore().then(()=>this.onselect(this.getName())),this.splitter=new e(this.cfg.eol),this.splitter.ontext=t=>{try{this.ontext?.(t)}catch(t){this._error(t)}}}config(t={}){this.cfg={...this.cfg,...t},this.splitter.eol=this.cfg.eol}static supported(){return"serial"in navigator}opened(){return this._state==r.State.Open}selected(){return!!this._port}getInfo(){return this._port?.getInfo()??null}getName(){if(!this._port)return"None";switch(this.getInfo().usbProductId){case 21971:return"CH343";case 30084:return"CH340S";case 29986:case 29987:return"CH340";case 21778:case 21795:case 21892:return"CH341";case 1026:case 1027:case 1028:case 1029:case 24577:case 1538:case 24592:return"FT232";case 38144:case 258:case 1281:case 32937:case 6e4:case 60001:case 60003:return"CP210x"}return"Unknown"}async select(){try{await this.close();const t=await navigator.serial.requestPort();if(this.cfg.forgetOtherPorts){const e=await navigator.serial.getPorts();for(const s of e)s!==t&&await s.forget()}this._port=t}catch(t){this._error(t)}return this.onselect(this.getName()),this.cfg.auto_open?this.open():this.selected()}async getPorts(){return navigator.serial.getPorts()}async restore(){const t=await this.getPorts();return this._port=this.cfg.forgetOtherPorts?t[0]??null:1===t.length?t[0]:null,this.selected()}async forget(){if(await this.close(),!this._port)return!1;const t=this._port;this._port=null;try{return await t.forget(),this.onselect(this.getName()),!0}catch(e){return this._port=t,this._error(e),!1}}async open(){if(this.opened())return!0;if(this._openPromise)return this._openPromise;if(this._state!==r.State.Closed)return!1;this.cfg.reconnect&&(this.retry=!0);const t=this._connect();this._openPromise=t;const e=await t;return this._openPromise===t&&(this._openPromise=null),e}async _connect(){this._change(r.State.Opening);try{if(this._port||await this.restore(),!this._port)throw new Error("No port");return this._state===r.State.Closing?(await this._cleanup(),!1):(await this._port.open(this._openOptions()),this._state===r.State.Closing?(await this._cleanup(),!1):(this.writer=this._port.writable.getWriter(),this.reader=this._port.readable.getReader(),this._sender.reset(),this._change(r.State.Open),this._listen(),!0))}catch(t){this._error(t)}return await this._cleanup(),!1}async _listen(){try{for(;this._state===r.State.Open;){const{value:t,done:e}=await this.reader.read();if(e)break;if(t){try{this.onbin?.(t)}catch(t){this._error(t)}this.ontext&&this.splitter.write(this._decoder.decode(t,{stream:!0}))}}}catch(t){this._error(t)}await this._cleanup()}async _cleanup(){this._sender.reset();try{this.reader&&this.reader.releaseLock()}catch(t){}try{this.writer&&this.writer.releaseLock()}catch(t){}this.reader=null,this.writer=null;try{this._port&&await this._port.close()}catch(t){}this._change(r.State.Closed),this.retry&&setTimeout(()=>{this.retry&&this.open()},this.cfg.reconnect)}async close(){return this.retry=!1,this._sender.reset(),await this._close(),!0}async _close(){switch(this._state){case r.State.Closed:return;case r.State.Opening:this._change(r.State.Closing);break;case r.State.Open:if(this._change(r.State.Closing),this.reader)try{await this.reader.cancel()}catch(t){}}let e=0;for(;this._state===r.State.Closing;)if(await t(10),++e>200){this._error("Close timeout"),this._change(r.State.Closed);break}}async sendText(t){return this.sendBin((new TextEncoder).encode(t))}async sendBin(t){if(!this.opened()||!this.writer)return!1;try{return await this._sender.run(async()=>!(!this.opened()||!this.writer||(await this.writer.write(t),0)))}catch(t){return this.opened()&&this._error(t),!1}}_port=null;_decoder=new TextDecoder;_sender=new s;_state=r.State.Closed;_openPromise=null;_openOptions(){return{baudRate:this.cfg.baud,dataBits:this.cfg.dataBits,stopBits:this.cfg.stopBits,parity:this.cfg.parity,bufferSize:this.cfg.bufferSize,flowControl:this.cfg.flowControl}}_error(t){this.onerror("[SerialJS] "+t)}_change(t){if(this._state!==t)switch(this._state=t,this.onchange(t),t){case r.State.Open:this.onopen();break;case r.State.Closed:this.onclose()}}}export{r as default};