WebSocket 客户端
网关以客户端身份向外发起连接到外部 streaming 服务器（ws / wss）的 endpoint， 实时接收推送消息的模式。
| 场景 | 使用哪种模式 |
|---|---|
| 外部 IT 系统通过 REST POST 发送数值时 | HTTP 推送 |
| 外部 streaming 服务器通过 WebSocket 持续推送数值时 | WebSocket 客户端（本页） |
| 直接读取厂内 PLC 数值时 | Modbus / OPC-UA 等 |
注册表单输入项
| 输入栏 | 填写内容 | 示例 |
|---|---|---|
| IP 地址 | WebSocket 服务器主机 | 192.168.10.99, stream.example.com |
| 端口 | WebSocket 服务器端口（ws=80，wss=443 为标准） | 8765, 443 |
| PATH | endpoint 路径（默认 /） | /stream/v1 |
| TLS | 是否使用 wss | false (ws) / true (wss) |
| SUBSCRIBE MESSAGE | 连接建立后发送一次的消息（可选） | {"op":"subscribe","topic":"line1.tempC"} |
| 采集周期 | 网关读取缓存值的周期（ms） | 1000 |
实际连接 URL：<scheme>://<host>:<port><PATH>（例：ws://192.168.10.99:8765/stream/v1）
标签的 PLC 地址表示法 —— 4-mode JSON
当服务器发送的消息为 JSON 时，使用与 MQTT / Apache Kafka 相同的 4-mode 解码器提取数值。
假设服务器按如下方式推送：
{"tempC": 25.7, "humid": 40.2, "running": true, "meta":{"unit":"degC"}}
| 模式 | 标签的 PLC 地址 | 获取的值 |
|---|---|---|
| KEY（top-level） | tempC | 25.7 |
| KEY | humid | 40.2 |
| KEY | running | true |
| PATH（JSON Pointer） | :$.meta.unit | degC |
| RAW | _raw_ 或 :_raw_（或留空） | 整条消息 |
| SCALAR | （消息不是 JSON 时）_raw_ | 消息原文 |
WebSocket 为单一通道，因此没有 topic 部分 —— 将 : 前面部分留空，或直接只写 key 即可。
若不是 JSON，或希望原样接收整条消息，使用 _raw_ 或留空即可。
常见用例
| 用例 | 做法 |
|---|---|
| 云端 streaming broker（实时行情、汇率、天气等） | 将服务器推送的 JSON 键原样注册为标签 |
| ROS 2 / rosbridge_server | 连接 rosbridge 的 WebSocket → 接收 topic 消息 |
| 厂内自建 streaming 网关 | 通常为明文 ws 8080 / 8765 —— tls=false |
| 外部安全 SaaS（需要证书） | wss 443 —— tls=true |
| 服务器要求 subscribe 握手 | 在 SUBSCRIBE MESSAGE 中填入约定的 payload |
常见问题与解决
| 现象 | 原因 | 解决 |
|---|---|---|
| 收不到值 | 服务器未推送消息 | 用 wscat -c ws://<host>:<port><path> 直接接收，确认控制台是否有输出 |
| 收不到值 | 未设置 subscribe 消息（而服务器要求） | 查阅服务器手册后注册 SUBSCRIBE MESSAGE |
[WS] connect 실패: timeout | 防火墙 / 端口 / DNS | 确认端口是否被阻断，用 telnet / nc 检查 TCP 是否可连接 |
[WS] connect 실패: handshake | path / TLS 设置错误 | 直接验证 URL <scheme>://<host>:<port><path> |
| TLS 证书错误 | 自签名（self-signed） | 生产环境建议使用正式证书。临时情况可请系统管理员添加 cacerts |
| 各 JSON 键的值为空 | 消息格式不是 JSON | 先用 _raw_ 接收后确认格式 |