ModbusTCP通信工具 SL-WX-ModbusTcp

ModbusTCP 通信工具 (SL-WX-ModbusTcp.js)

插件市场 操作视频

基于 HTML5+ plus.android 调用 java.net.Socket 实现的 ModbusTCP 二进制协议通信工具，仅支持 Android App（5+） 环境。非 Android 环境调用任何方法会自动 reject 并弹窗提示。

⚠️ 关于 plus.net 的说明：HTML5+ 的 plus.net 模块仅提供 XMLHttpRequest（HTTP 请求），并不提供原生 TCP Socket API。ModbusTCP 是基于 TCP 的二进制协议，必须使用 Socket。因此本工具通过 plus.android.importClass('java.net.Socket') 调用 Java 原生 Socket 实现，仅 Android 可用；iOS 需要另行开发 uni 原生插件（Objective-C / Swift）。

目录结构

components/SL-WX-ModbusTcp
└── SL-WX-ModbusTcp.js

快速开始

import modbus from '@/components/SL-WX-ModbusTcp/SL-WX-ModbusTcp.js'

// 1. 连接 PLC
await modbus.connect('192.168.1.10', 502, 3000)

// 2. 读 BOOL（线圈，功能码 1）—— 起始地址 1，数量 1
const bools = await modbus.readBool(1, 1, 1, 1)
// → [true]

// 3. 读 INT16（保持寄存器，功能码 3）—— 起始地址 1000，数量 4
const ints = await modbus.readInt(1000, 4, 1, 3)
// → [1234, -5678, 90, 100]

// 4. 读 INT32（占 2 寄存器）—— 地址 1000，字节序 CDAB
const i32 = await modbus.readInt32(1000, 1, 'CDAB', 3)

// 5. 读 FLOAT（占 2 寄存器）—— 地址 2000，字节序 CDAB
const f = await modbus.readFloat(2000, 1, 'CDAB', 3)
// → 3.14

// 6. 写 BOOL（线圈，功能码 5）
await modbus.writeBool(1, true, 1)

// 7. 写 INT16（保持寄存器，功能码 6）
await modbus.writeInt(1000, 12345, 1)

// 8. 写 INT32（占 2 寄存器，功能码 16）
await modbus.writeInt32(1000, 123456789, 'ABCD', 1)

// 9. 写 FLOAT（占 2 寄存器，功能码 16）
await modbus.writeFloat(2000, 3.14159, 'ABCD', 1)

// 10. 断开
await modbus.disconnect()

环境检测

if (!modbus.isApp() || !modbus.isAndroid()) {
const platform = modbus.getPlatformName() // 'H5' | '微信小程序' | …
uni.showModal({ title: '提示', content: `当前为${platform}，无法使用 ModbusTCP` })
return
}

核心特性

• 完整 ModbusTCP 协议栈：自行构建/解析 MBAP Header（7 字节）+ PDU，支持功能码 1/2/3/4/5/6/16，覆盖线圈、离散输入、保持寄存器、输入寄存器的读写。
• BOOL / INT16 / INT32 / FLOAT 四种数据类型：读写齐全，INT32 与 FLOAT 自动处理双寄存器拼接。
• 4 种字节序：ABCD（大端）/ DCBA（小端）/ BADC / CDAB（字交换），适配不同 PLC 厂商的 32 位数据存储顺序。
• 从站号可配：每次读写可指定 unitId（1~247，默认 1），适配多从站现场。
• 浮点精度截断：readFloat 返回值自动 toFixed(6) 截断 IEEE 754 float32 精度噪声，无需手动处理。
• 异常响应解析：自动识别 Modbus 异常响应（功能码最高位 = 1），抛出含异常码与中文说明的错误。
• Transaction ID 校验：每帧递增并校验响应帧的事务标识，防止串帧。
• 粘包处理：按功能码与请求参数计算预期响应长度，精确读取，无需额外处理粘包。
• 连接自动清理：connect 前自动关闭旧 Socket / InputStream / OutputStream，可安全重复调用。
• Promise 化 API：所有读写方法返回 Promise，配合 async/await 流畅书写。
• 平台自动检测：非 Android App 环境调用自动 reject 并弹窗提示，附带 isApp() / isAndroid() / getPlatformName() 环境检测工具。

API 列表

连接 / 断开

connect(host, port, timeout) → Promise<true>

建立到 PLC 的 TCP 连接。连接前会自动清理旧连接。

disconnect() → Promise<true>

断开连接，依次关闭 InputStream、OutputStream、Socket，释放 Java 侧资源。

isConnected() → Boolean

同步方法，返回当前是否处于已连接状态。

读取

readBool(addr, count, unitId, funcCode) → Promise<Boolean[]>

读取线圈或离散输入，返回布尔值数组。

readInt(addr, count, unitId, funcCode) → Promise<Number[]>

读取保持寄存器或输入寄存器，返回有符号 16 位整数数组（-32768~32767）。

readInt32(addr, unitId, wordOrder, funcCode) → Promise<Number>

读取 32 位有符号整数，占 2 个连续寄存器。

readFloat(addr, unitId, wordOrder, funcCode) → Promise<Number>

读取 32 位浮点数，占 2 个连续寄存器。返回值已做 toFixed(6) 精度截断。

写入

writeBool(addr, value, unitId) → Promise<true>

写单个线圈（功能码 5）。

writeInt(addr, value, unitId) → Promise<true>

写单个保持寄存器（功能码 6）。

writeInt32(addr, value, wordOrder, unitId) → Promise<true>

写 32 位有符号整数，占 2 个连续寄存器（功能码 16）。

writeFloat(addr, value, wordOrder, unitId) → Promise<true>

写 32 位浮点数，占 2 个连续寄存器（功能码 16）。

环境检测

isApp() → Boolean

同步方法，返回当前是否运行在 App 环境（APP-PLUS 编译条件）。

isAndroid() → Boolean

同步方法，返回当前是否为 Android 平台。非 Android 的 App 环境（如 iOS）返回 false。

getPlatformName() → String

同步方法，返回当前平台名称字符串，用于提示文案。可能的返回值：'H5' / '微信小程序' / '支付宝小程序' / '当前平台'。

功能码说明

字节序说明

32 位数据（INT32 / FLOAT）占用 2 个连续寄存器，共 4 字节。不同 PLC 的字节排列顺序不同，本工具支持 4 种字节序：

大多数 PLC 默认 ABCD，调用时可不传 wordOrder 参数（自动取默认值）。具体字节序请参考设备厂商文档。

使用示例

示例 1：读线圈状态（BOOL）

// 读地址 1~8 的 8 个线圈
const bools = await modbus.readBool(1, 8, 1, 1)
// bools = [true, false, true, true, false, false, true, false]

示例 2：读保持寄存器（INT16）

// 读地址 1000~1003 的 4 个保持寄存器
const ints = await modbus.readInt(1000, 4, 1, 3)
// ints = [1234, -5678, 90, 100]

示例 3：读浮点数（FLOAT，32 位）

// 读地址 2000 的 float（占 D2000~D2001 两个寄存器），字节序 ABCD
const f = await modbus.readFloat(2000, 1, 'ABCD', 3)
// f = 3.14

示例 4：写线圈（BOOL）

// 写线圈地址 1 为 ON
await modbus.writeBool(1, true, 1)

// 写线圈地址 2 为 OFF
await modbus.writeBool(2, false, 1)

示例 5：写浮点数（FLOAT，32 位）

// 写 float 到地址 2000（占 D2000~D2001），字节序 ABCD
await modbus.writeFloat(2000, 3.14159, 'ABCD', 1)

示例 6：批量轮询示例

async function poll() {
try {
const [bools, ints, f] = await Promise.all([
modbus.readBool(1, 8, 1, 1), // 线圈状态
modbus.readInt(1000, 4, 1, 3), // 寄存器值
modbus.readFloat(2000, 1, 'ABCD', 3) // 浮点数
])
console.log('bools:', bools)
console.log('ints:', ints)
console.log('float:', f)
} catch (e) {
console.error('轮询失败:', e.message)
await modbus.disconnect()
}
}

// 每 1 秒轮询一次
setInterval(poll, 1000)

ModbusTCP 帧结构

MBAP Header（7 字节）

PDU

异常响应

注意事项

预览界面说明

预览页面 pages/modbustcp/modbustcp.vue 提供完整的交互式调试面板，包含以下区域：