3.7 远程串口透传（免 Lua）

将设备串口与云端建立一条端到端的数据管道，让电脑上的组态软件、调试工具、行业软件像连接本机串口一样，直接与远端设备的 COM 口进行原始字节收发，全程无需编写 Lua 脚本。

一句话理解：设备 COM 口 ⇄ 云 ⇄ 上位机工具虚拟串口 ⇄ PC 应用。

📖 特性一览

• ✅ 免脚本：无需编写 set_transparent Lua 代码，上位机一键启停
• ✅ 一键开启：点一下按钮完成"检查通道 → 启动设备服务 → 打开会话"三步
• ✅ 真实探测：上位机会通过云通道实际下发探针命令，而不是依据连接状态推断
• ✅ 端口自识别：设备会上报自身实际具备哪些串口（COM1 / COM2 / COM3），上位机只显示存在的端口，避免选到不存在的口
• ✅ 会话自恢复：设备端具备保活与掉线自停能力，云端断开自动释放串口
• ✅ 与 Lua 兼容：设备端如果已被 set_transparent() 绑定，会明确报错提醒，两者不会相互干扰

🎯 典型场景

场景	说明
现场调试	远端设备下挂第三方仪表，无法到现场时通过云透明直连仪表调试
组态软件对接	Modbus Poll / 组态王 / 力控 等打开虚拟串口即可访问远端 RS485 总线
触摸屏烧录	与触摸屏调试软件配合，远程升级 HMI 程序
固件在线维护	与设备厂家提供的专用工具对接，进行参数配置和固件升级

---

🚀 使用步骤（上位机工具）

1. 打开"透传"标签页

进入上位机工具的 透传 页面。工具会自动检查通道就绪状态：

• 通道就绪：本地/云端连接正常，可以直接开启
• 通道未就绪：面板会展开列出未通过的检查项（例如未登录云、设备未上线等）

2. 选择"设备端串口"

页面上半段 ① 设备端串口（透传的另一端） 用于告诉设备把哪一个 COM 口透传出来。

• 下拉框只会列出 当前设备型号实际存在的串口
• 波特率 / 数据位 / 校验 / 停止位与目标设备保持一致
• 如果选的口不存在，会返回错误码 7，提示 "当前设备型号没有该串口"

3. 选择"本地接入方式"

页面下半段 ② 本地接入方式（透传的这一端） 决定 PC 上以什么形式暴露该通道：

• 虚拟串口（推荐）：由上位机自动创建一个本地 COM 口，PC 应用像使用普通串口一样使用它
• 本地 TCP 端口：以 TCP Server 形式监听，供 Modbus TCP 客户端等直接连接

4. 点击「一键开启透传」

上位机会自动完成三件事：

1. 检查通道：真实探测云通道是否可用
2. 启动设备服务：让设备开启透传服务
3. 打开会话：在 PC 侧开启会话，绑定虚拟串口或 TCP 端口

任意一步失败会自动回滚，避免设备侧留下"半启动"状态。

5. 使用与关闭

• 使用中：PC 上的应用即可像操作本机串口一样读写远端设备
• 完成后点击 「关闭透传」：上位机会同时关闭本地会话 并 通知设备停止透传服务（释放 COM 口给 Lua/PLC 使用）

---

⚙️ 错误码对照

启停透传失败时，上位机会显示一个错误码，含义如下：

code	说明
0	成功
1	该串口已有使用者，冲突
2	参数不合法（波特率 / 数据位等填错）
3	打开端点失败（串口被占用，或本地 TCP 端口被拒绝）
4	设备内部错误
5	会话不匹配（防止误停别人的会话）
6	透传服务未运行
7	该型号设备不存在此串口

---

🆚 与 Lua set_transparent 的区别

	Lua set_transparent	免Lua远程透传
是否需要写脚本	是	否
启停控制方	设备 Lua 主动	上位机远程下发
端口检查	运行时才知道失败	上位机预先过滤不存在的端口
保活/掉线自停	需自行实现	内置保活，云断自动停
会话保护	无	有会话保护，防止误停别人的会话
适用人群	需要在设备脚本中融合业务逻辑的开发者	需临时打通串口的运维 / 售后 / 最终用户

注意：两者互斥。设备端已运行 set_transparent() 时，远程启动透传会提示串口已被 Lua 占用。此时请先在 Lua 中释放，或直接删除脚本中的 set_transparent() 调用。

---

❓ 常见问题

Q1：上位机提示"启动设备透传服务失败：打开端点失败"？

• 检查所选串口是否被 PLC 梯形图（如 Modbus Master 指令）或 Lua 脚本占用
• 若在 LP3232 Debug 版上，请注意该型号 Debug 版没有 COM2，请改选 COM1

Q2：一段时间无数据后连接断开？

• 属于保活机制：设备在长时间无上下行数据时会主动停止透传释放串口
• 有持续通信时不会触发；如需长期保持，可加装心跳报文

Q3：能否在启用透传的同时让 PLC/Lua 继续使用该串口？

• 不能。任一时刻同一个 COM 口只能被一方使用：要么是 Lua 脚本，要么是远程透传服务

Q4：老固件的设备，上位机怎么显示串口列表？

• 老固件不会上报自身有哪些串口，上位机会退化为默认列表 [COM1, COM2, COM3]；如果选了实际不存在的口会返回错误码 7。建议升级固件以获得准确的串口列表

---

🔗 相关文档

• 6.1 串口基础
• 5.3 TCP 客户端
• A. API 速查表

---

最后更新: 2026-08-13