device-communication-node 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alice
+
+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,173 @@
+# device-communication-node
+
+🚀 轻量级统一物联网设备通信框架 (Node.js)，基于适配器设计模式，支持 TCP/UDP/TCPSERVER、串口多通道自由切换与高度抽象。
+
+> ⚠️ **当前版本为内测版本 (Beta)，请勿直接用于生产环境。**
+
+## 📦 安装
+
+由于目前处于内测阶段，请通过指定 `@next` 标签或精确版本号进行安装：
+
+```bash
+# 推荐方式
+npm install device-communication-node@next
+
+# 或者指定版本
+npm install device-communication-node@1.0.0-beta.1
+```
+
+## ✨ 核心特性
+
+- **多通道统一抽象**：一套底层逻辑，自由切换 TCP、UDP、SerialPort（串口）。
+- **优秀的架构设计**：采用 Channel -> Dispatcher -> Factory 适配器架构，职责分明。
+- **高稳定性**：针对底层网络（如 TCP Server）运行期异常进行了安全防护，防止进程崩溃。
+
+## 🛠️ 快速开始
+
+### 1. 具体设备类继承DeviceCore，并使用发送方法
+
+```
+const DeviceCore = require('../../device/core/DeviceCore');
+const checkUtils = require('../../device/utils/checkUtils');
+const hexUtils = require('../../device/utils/hexUtils');
+/**
+ * 测试设备
+ */
+class DeviceTest extends DeviceCore {
+    constructor() {
+        super();
+    }
+    /**
+     * 发送
+     */
+    async tesetSend() {
+        // 构建的完整协议帧
+        const completeFrame = Buffer.from([0x02, 0x03, 0x00, 0x0A, 0x00, 0x03, 0x25, 0xFA]);
+
+        return await this.sendSync(completeFrame, {
+            retry: 0,
+            timeout: 500,
+            parser: (readyBytes, writeBytes) => {
+
+                // 数据长度校验，应为 6
+                if (readyBytes[2] !== 6) {
+                    throw new Error(`返回数据长度异常：${readyBytes[2]}`);
+                }
+
+                if (readyBytes.length < 11) {
+                    throw new Error(`返回数据长度不足：${readyBytes.length}`);
+                }
+
+                const readUInt16 = (offset) =>
+                    ((readyBytes[offset] << 8) | readyBytes[offset + 1]) >>> 0;
+
+                const internalTemperature = readUInt16(3) / 10 - 25;
+                const externalTemperature = readUInt16(5) / 10 - 25;
+                const humidity = readUInt16(7) / 10;
+
+                return {
+                    internalTemperature,
+                    externalTemperature,
+                    humidity
+                };
+            }
+        });
+    }
+}
+
+module.exports = DeviceTest;
+```
+
+### 2.建议针对具体设备协议，在具体设备类中重写DeviceCore中以下方法
+
+```
+    /**
+     * 基础校验
+     */
+    validate(readBytes) {
+        return readBytes && readBytes.length > 0;
+    }
+
+    /**
+     * 帧匹配校验
+     */
+    isMatch(writeBytes, readBytes) {
+        return this.validate(readBytes);
+    }
+
+    /**
+     * 帧解析逻辑 - 基类默认实现 (不解决拆包粘包)
+     * 子类需重写此方法以实现特定协议的拆包
+     */
+    parseFrame(onFrameReady) {
+        // 默认实现：直接把当前收到的全部内容当成一帧抛出
+        if (this.receiveBuffer.length > 0) {
+            const frame = Buffer.from(this.receiveBuffer);
+            this.receiveBuffer = Buffer.alloc(0); // 清空
+            if (this.validate(frame)) {
+                onFrameReady(frame);
+            }
+        }
+    }
+
+    /**
+     * 主动上报处理接口
+     */
+    onAutoReport(frame) {
+        const now = new Date().toISOString().replace('T', ' ').substring(0, 19);
+        console.log(`[${now}] 主动上报帧: ${HexUtils.bytesToHexString(frame)}`);
+    }
+
+    /**
+     * 默认回调
+     */
+    defaultCallback(readBytes, writeBytes) {
+        console.log("--- 默认回调 ---");
+        console.log("发送:", HexUtils.bytesToHexString(writeBytes));
+        console.log("接收:", HexUtils.bytesToHexString(readBytes));
+    }
+
+    /**
+     * 队列清空通知
+     */
+    onAllTasksCompleted() {
+        // 子类重写
+    }
+```
+
+### 3.外部使用
+
+```
+const CommDispatcherManager = require('./device/core/commDispatcherManager')
+const DeviceTest = require('./drivers/test/DeviceTest')
+
+const main = async () => {
+
+    const dispatcher = CommDispatcherManager.create("tcp", "192.168.1.113:8234")
+    const device = new DeviceTest();
+    device.setCommDispatcher(dispatcher)
+    dispatcher.setDevice(device)
+    console.log(await device.tesetSend())
+
+}
+
+main();
+```
+
+### 4.结果
+
+```
+PS D:\code_repository\private-project\device-communication-node> npm run dev
+
+> device-communication-node@1.0.0-beta.1 dev
+> node src/index.js
+
+[Dispatcher] 执行任务: 02 03 00 0A 00 03 25 FA (尝试 1/1)
+{ internalTemperature: -25, externalTemperature: -25, humidity: 0 }
+```
+
+
+
+## 📄 开源许可证
+
+[MIT License](https://www.google.com/search?q=LICENSE) © 2026 Alice

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "device-communication-node",
+  "version": "1.0.0-beta.1",
+  "description": "轻量级统一物联网设备通信框架，支持 TCP/UDP、串口等多通道自由切换与高度抽象。",
+  "main": "src/index.js",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "node src/index.js"
+  },
+  "keywords": [
+    "device",
+    "communication",
+    "tcp",
+    "udp",
+    "hardware",
+    "iot"
+  ],
+  "author": "Alice",
+  "license": "MIT",
+  "type": "commonjs",
+  "dependencies": {
+    "serialport": "^13.0.0"
+  }
+}

package/src/device/channel/CommChannel.js

@@ -0,0 +1,73 @@
+const EventEmitter = require('events')
+const HexUtils = require('../utils/HexUtils')
+/**
+ * 通信通道抽象类，定义了通信通道的基本接口和事件机制。
+ */
+class CommChannel extends EventEmitter {
+    constructor() {
+        super()
+
+        this.charset = 'gb2312'
+        this.isOpen = false
+
+        // 正在连接的Promise（防重复open）
+        this.openingPromise = null
+    }
+
+    // 防止重复 open 的统一入口
+    _dedupeOpen(createFn) {
+        if (this.isOpen) {
+            return Promise.resolve()
+        }
+
+        if (this.openingPromise) {
+            return this.openingPromise
+        }
+
+        this.openingPromise = Promise.resolve()
+            .then(createFn)
+            .finally(() => {
+                this.openingPromise = null
+            })
+
+        return this.openingPromise
+    }
+
+    getConfig() {
+        throw new Error('必须实现 getConfig() 方法')
+    }
+
+    open() {
+        throw new Error('必须实现 open() 方法')
+    }
+
+    close() {
+        throw new Error('必须实现 close() 方法')
+    }
+
+    send(data) {
+        throw new Error('必须实现 send() 方法')
+    }
+
+    sendString(message) {
+        const buffer = Buffer.from(message, this.charset)
+        this.send(buffer)
+    }
+
+    onReceive(source, data) {
+        this.emit('receive', source, data, data.length)
+    }
+
+    triggerOpen(resource) {
+        this.isOpen = true
+        this.emit('open', resource)
+    }
+
+    triggerClose(resource) {
+        this.isOpen = false
+        this.emit('close', resource)
+    }
+}
+
+module.exports = CommChannel
+

package/src/device/channel/SerialChannel.js

@@ -0,0 +1,112 @@
+const { SerialPort } = require('serialport')
+const CommChannel = require('./CommChannel')
+
+class SerialChannel extends CommChannel {
+
+    constructor(path, baudRate) {
+        super()
+
+        this.path = path
+        this.baudRate = baudRate || 19200
+
+        this.port = null
+    }
+
+    getIsOpen() {
+        return this.isOpen
+    }
+
+    getConfig() {
+        return {
+            path: this.path,
+            baudRate: this.baudRate
+        }
+    }
+
+    async open() {
+        return this._dedupeOpen(() => {
+            return new Promise((resolve, reject) => {
+
+                if (this.isOpen && this.port && this.port.isOpen) {
+                    resolve()
+                    return
+                }
+
+                if (this.port) {
+                    try {
+                        this.port.removeAllListeners()
+                    } catch (e) { }
+                    this.port = null
+                }
+
+                this.port = new SerialPort({
+                    path: this.path,
+                    baudRate: this.baudRate,
+                    autoOpen: false
+                })
+
+                const openTimeout = setTimeout(() => {
+                    reject(new Error(`串口打开超时: ${this.path}`))
+                }, 2000)
+
+                this.port.open((err) => {
+                    clearTimeout(openTimeout)
+
+                    if (err) {
+                        reject(new Error(`串口打开失败: ${err.message}`))
+                        return
+                    }
+
+                    this.triggerOpen(this.port)
+                    resolve()
+                })
+
+                this.port.on('data', (data) => {
+                    this.onReceive(this.port, data)
+                })
+
+                this.port.on('error', (err) => {
+                    console.error(`串口 [${this.path}] 错误:`, err.message)
+
+                    if (err.message.includes('Access denied') ||
+                        err.message.includes('Disconnected')) {
+                        this.isOpen = false
+                    }
+                })
+            })
+        })
+    }
+
+    close() {
+
+        if (!this.isOpen || !this.port || !this.port.isOpen) {
+            this.isOpen = false;
+            return;
+        }
+
+        this.port.close((err) => {
+            if (err) {
+                console.error(`[SerialChannel] 关闭串口 ${this.path} 失败:`, err.message);
+            }
+            this.isOpen = false;
+            this.triggerClose(this.port);
+        })
+    }
+
+    send(data) {
+        if (!this.isOpen) {
+            throw new Error('串口未打开')
+        }
+
+        return new Promise((resolve, reject) => {
+            this.port.write(data, (err) => {
+                if (err) reject(err)
+                else {
+                    this.port.drain(resolve)
+                }
+            })
+        })
+    }
+}
+
+module.exports = SerialChannel

package/src/device/channel/TcpChannel.js

@@ -0,0 +1,84 @@
+const net = require('net')
+const CommChannel = require('./CommChannel')
+
+class TcpChannel extends CommChannel {
+
+    constructor(host, port) {
+        super()
+
+        this.host = host
+        this.port = port
+
+        this.socket = null
+    }
+
+    getIsOpen() {
+        return this.isOpen
+    }
+
+    getConfig() {
+        return {
+            host: this.host,
+            port: this.port
+        }
+    }
+
+    open() {
+        return this._dedupeOpen(() => {
+
+            return new Promise((resolve, reject) => {
+
+                this.socket = new net.Socket()
+
+                const connectTimeout = setTimeout(() => {
+                    this.socket.destroy()
+                    reject(new Error(`TCP连接超时 ${this.host}:${this.port}`))
+                }, 2000)
+
+                this.socket.connect(this.port, this.host, () => {
+                    clearTimeout(connectTimeout)
+
+                    this.triggerOpen(this.socket)
+                    resolve()
+                })
+
+                this.socket.on('error', (err) => {
+                    clearTimeout(connectTimeout)
+                    reject(new Error(`TCP连接失败: ${err.message}`))
+                })
+
+                this.socket.on('close', () => {
+                    this.isOpen = false
+                    this.triggerClose(this.socket)
+                })
+
+                this.socket.on('data', (data) => {
+                    this.onReceive(this.socket, data)
+                })
+            })
+        })
+    }
+
+    close() {
+        if (!this.socket) return
+
+        this.socket.destroy()
+        this.socket = null
+        this.isOpen = false
+    }
+
+    send(data) {
+        if (!this.isOpen || !this.socket) {
+            throw new Error('TCP未连接')
+        }
+
+        return new Promise((resolve, reject) => {
+            this.socket.write(data, (err) => {
+                if (err) reject(err)
+                else resolve()
+            })
+        })
+    }
+}
+
+module.exports = TcpChannel

package/src/device/channel/TcpServerChannel.js

@@ -0,0 +1,149 @@
+const net = require('net')
+const CommChannel = require('./CommChannel')
+
+class TcpServerChannel extends CommChannel {
+
+    constructor(port = 9000, host = '0.0.0.0') {
+        super()
+
+        this.port = port
+        this.host = host
+
+        this.server = null
+        this.isOpen = false
+
+        // 管理所有客户端
+        this.clients = new Set()
+    }
+
+    getIsOpen() {
+        return this.isOpen
+    }
+
+    getConfig() {
+        return {
+            host: this.host,
+            port: this.port
+        }
+    }
+
+    open() {
+        return this._dedupeOpen(() => {
+
+            if (this.isOpen) {
+                return Promise.resolve()
+            }
+
+            this.server = net.createServer((socket) => {
+                this.clients.add(socket)
+                this.onClientConnect(socket)
+
+                socket.on('data', (data) => {
+                    this.onReceive(socket, data)
+                })
+
+                socket.on('close', () => {
+                    this.clients.delete(socket)
+                    this.onClientDisconnect(socket)
+                })
+
+                socket.on('error', (err) => {
+                    this.emit('clientError', socket, err)
+                })
+            })
+
+            this.server.on('error', (err) => {
+                console.error('TCP Server 运行期错误:', err)
+                if (!this.server.listening) {
+                    this._handleCloseCleanup()
+                }
+            })
+
+            return new Promise((resolve, reject) => {
+                const startErrorHandler = (err) => {
+                    reject(err)
+                }
+
+                this.server.once('error', startErrorHandler)
+
+                this.server.listen(this.port, this.host, () => {
+                    this.server.off('error', startErrorHandler)
+
+                    this.isOpen = true
+                    this.triggerOpen(this.server)
+                    resolve()
+                })
+            })
+        })
+    }
+
+    _handleCloseCleanup() {
+        this.isOpen = false
+        // 关闭所有客户端
+        for (const client of this.clients) {
+            client.destroy()
+        }
+        this.clients.clear()
+        this.triggerClose(this.server)
+    }
+
+    close() {
+        if (!this.isOpen) return Promise.resolve()
+
+        return new Promise((resolve) => {
+            this._handleCloseCleanup()
+
+            if (this.server) {
+                this.server.close(() => {
+                    this.server = null
+                    resolve()
+                })
+            } else {
+                resolve()
+            }
+        })
+    }
+
+    send(data, client = null) {
+
+        if (!this.isOpen) {
+            throw new Error('TCP Server未启动')
+        }
+
+        // 如果指定 client，就单发
+        if (client) {
+            return this._write(client, data)
+        }
+
+        // 否则广播
+        const tasks = []
+        for (const c of this.clients) {
+            tasks.push(this._write(c, data))
+        }
+
+        return Promise.all(tasks)
+    }
+
+    _write(socket, data) {
+        return new Promise((resolve, reject) => {
+            // 检查客户端连接是否还可写
+            if (!socket.writable) {
+                return reject(new Error('客户端连接已不可写'))
+            }
+            socket.write(data, (err) => {
+                if (err) reject(err)
+                else resolve()
+            })
+        })
+    }
+
+    onClientConnect(socket) {
+        this.emit('clientConnect', socket)
+    }
+
+    onClientDisconnect(socket) {
+        this.emit('clientDisconnect', socket)
+    }
+}
+
+module.exports = TcpServerChannel