WebSocket JSON 主站

WebSocket JSON 主站作为 ws/wss 客户端连接设备，按明确的 JSON 文本合同读取、写入和订阅变量。插件名称为“WebSocket JSON 主站”，类型标识为 WebSocketJsonMaster。公共操作见采集配置。连接、握手、掩码、控制帧和关闭由 TouchSocket 官方 WebSocket 客户端完成；业务层只处理 JSON 文本，不自动识别二进制帧或厂商私有 schema。

创建设备

进入“开发配置 → 采集配置”，在“无通道”下添加 WebSocket JSON 主站，填写设备端点和消息合同，保存并启用。无需创建 TCP 通道；握手和连接由设备独立管理。

连接每 15 秒发送一次带随机正文的 Ping，并在 5 秒内等待正文相同的 Pong；未收到匹配 Pong 时结束会话并重新连接。收到服务端 Ping 时原样回复其正文；控制帧可出现在文本分片之间，不会改变 JSON 消息的重组顺序。断线后重新建立会话并恢复已确认订阅，业务写入仍以匹配的远端应答为准。

参数	说明
设备端点	ws:// 或 wss:// 绝对地址。wss 使用系统证书信任和主机名校验。
访问令牌	可选 Bearer 握手凭据，仅填设备配置，不放入 URL。
子协议	可选的单个 HTTP token，例如 gateway-json；不含空白、逗号、换行或非 ASCII 字符。填写后要求服务端明确接受同一 subprotocol。
请求超时毫秒	100–120000，默认 5000，连接、发送及业务确认共用期限。
最大消息字节数	128–16777216，默认 1048576，限制分片重组后的完整消息。
读取、写入模板	按设备 schema 配置完整 JSON，保留关联编号。
订阅模板	可选；使用地址数组全量替换订阅，空数组取消全部。
响应映射指针	Type、RequestId、Address、Value、Success 分别定位实际响应字段。
响应类型、推送类型	默认 response 与 event，只有匹配类型才参与对应处理。

消息合同示例

默认读、写模板为：

{"type":"read","requestId":"$requestId","address":"$address"}

{"type":"write","requestId":"$requestId","address":"$address","value":"$value"}

可选订阅模板为：

{"type":"subscribe","requestId":"$requestId","addresses":"$addresses"}

占位符必须占据完整 JSON 值；不能写成 "room-$address"。$value 保留输入 JSON 类型，$addresses 替换为地址数组。

响应示例 {"type":"response","requestId":"原请求编号","success":true,"value":23.5}；推送示例 {"type":"event","address":"temperature","value":24.0}。指针默认 /type、/requestId、/address、/value、/success。响应必须同时满足类型、关联编号和 success 为布尔 true；发送完成或握手成功不等于写成功。

配置变量

变量地址直接填写设备业务地址，例如 temperature，不是 HTTP 路径或 JSON Pointer。使用对应数字、Boolean、String 或 Object 数据类型。设备订阅模板开启后，运行时将有效变量地址同步给远端，只有订阅 ACK 成功后才标记关系建立。

1. 在设备“实时变量”页新增或编辑变量，点击“变量地址”右侧的“字段编辑”。
2. 在“点位地址”输入设备消息合同中的原始标识，最多 1024 个字符且不含控制字符。地址大小写、空格和转义字符应与远端约定一致。
3. 点击“确认并回填”，再点击变量窗口的“确定”。重新打开字段窗口核对原始地址；“取消”会放弃尚未回填的修改。

检查实时变量

保持当前设备，在采集工作区顶部切换到“实时变量”标签，核对地址、当前值、在线状态、采集时间、变化时间与错误。周期读的采集时间会推进；源端推送新值时，应同时看到当前值和变化时间更新。

在授权测试范围内写入后，先确认远端业务 ACK，再读回并检查实时变量。远端返回的 JSON null 会显示为 -，不能单凭该占位符判断离线，应同时查看在线状态和错误列。

协议调试与特殊方法

选中设备，打开顶部“协议调试”。第一个页签“核心状态”显示连接、订阅和请求状态；“特殊方法”位于“核心状态”右侧。

使用工作区顶部“刷新”更新会话摘要。已确认的调试订阅地址和最近推送分别分页，默认每页 20 项；自动更新保留当前页。分页只改变查看范围，不撤销订阅，也不改变单条消息的字节限制。

1. 在读取页输入地址，执行单读；批量页逐行输入地址，逐项核对结果。
2. 在写入页填写目标地址和 JSON 值，核对权限与测试范围，确认后发送，再读回远端值。
3. 在订阅页填写地址集合并提交，确认订阅 ACK 和最新推送；从源端改变值验证新消息。
4. 使用空集合取消临时订阅。离开页面时清理当前调试订阅，设备正常变量订阅仍由运行管理。
5. 断线后查看重连和订阅恢复；超过期限的写入不自动重放，应读取确认状态。

TouchSocket 负责解析和组合连续文本分片；“最大消息字节数”同时约束帧头声明长度和累计重组后的完整 UTF-8 消息，在读取正文前拒绝超过剩余预算的帧，不能用分成多个帧绕过限制。控制帧不会进入业务变量；收到 Close、超限消息、服务端掩码、未协商扩展或非法分片时会结束当前会话并按退避策略重连。批量读取最多 32 个地址，订阅集合最多 1024 个地址，均按业务 ACK 确认后才更新状态。

特殊方法提供 ReadAddressAsync、ReadAddressesAsync、WriteAddressAsync、SetDebugSubscriptionsAsync，与专属面板使用同一连接、消息合同和确认机制。地址集合参数使用 JSON 字符串数组，写值使用强类型 JSON 文本。

JSON 参数按方法参数顺序填写数组，可省略使用默认值的尾部参数，也可使用“字段编辑”。例如执行 ReadAddressAsync：

["temperature"]

专属订阅页可核对业务确认后的订阅数、通知值与接收时间：

故障处理

现象	检查与处理
握手失败	检查端点、Bearer、子协议、源站证书与网络；网关管理端 API 令牌不等于设备令牌。
连接成功但请求超时	核对 response 类型、requestId 指针与编号类型；服务端必须回传相同字符串编号。
业务拒绝	检查 success 是否为布尔 true；设备拒绝写入时不更新本地成功状态。
订阅无数据	检查订阅 ACK、event 类型、地址和值指针，确认推送地址与变量完全一致。
超大或非文本消息	检查完整消息大小和 JSON 文本合同；不能把二进制帧当 JSON 解析。
Ping 超时并重连	检查设备是否及时处理 Ping 并原样返回 Pong；TCP 仍连接或持续发送业务消息不能替代 Pong 确认。
重连后值不恢复	检查运行变量地址和重新订阅确认、服务端 session 状态以及最近消息时间。