接入 RS-485 外设
适用场景
适用于支持 RS-485 的 WLTE 设备需要与外设交换原始字节的场景。OpenAPI 提供数据透传，不会自动实现完整的 Modbus 协议栈。
你的服务需要构造应用协议数据、按需计算 CRC、解析响应，并根据外设语义制定重试规则。
推荐流程
- 从查询设备列表读取目标设备的
deviceType。 - 在设备类型定义列表中找到相同的 profile。
- 只有
supportedOperations包含device.rs485.transceive时才开放透传功能。 - 需要修改波特率时，单独检查
device.rs485.baudRate.set，并从查询设备配置读取当前值。 - 使用新的
Idempotency-Key提交原始请求，并保存返回的命令 ID。 - 只有状态为
SUCCESS时才解析command.result.responseHex；状态为SENT时查询命令结果。
分步骤实现
1. 校验能力和配置
不要根据设备名称或其他型号推断 RS-485 能力，应以 supportedOperations 为准。透传需要 device:control，修改波特率需要 device:config。
波特率端点接受的范围和单位以设置 RS485 波特率为准。设备与外设必须使用相同波特率。
2. 构造原始请求
REST 调用通过 RS485 透传命令发送 requestHex。当前契约接受 1 到 30 字节的连续十六进制字符串，不能包含空格、0x 前缀或分隔符。
外设使用 Modbus RTU 时，应用需要自行构造地址、功能码、数据和 CRC。OpenAPI 只转发字节并返回原始响应，不校验 Modbus 寄存器或功能码语义。
3. 处理命令结果
SUCCESS：按外设协议解析result.responseHex。SENT：调用查询命令结果。FAILED：停止并展示已确认的失败。TIMEOUT：等待窗口内没有匹配响应，不能据此认定外设写入失败。
使用 WebSocket 时，匹配到请求的数据在操作 reply 中返回。延迟到达或设备主动发送的数据可能通过 device.rs485.received 到达，该事件不提供历史补发。
关键接口与事件
| 用途 | 文档 |
|---|---|
| 确认设备能力 | 查询设备类型定义列表 |
| 通过 REST 发送原始数据 | RS485 透传命令 |
| 通过 WebSocket 发送原始数据 | RS485 透传 |
| 设置波特率 | 设置 RS485 波特率 |
| 读取当前配置 | 查询设备配置 |
| 接收未匹配数据 | RS485 数据事件 |
失败与恢复策略
- 只有在 HTTP 结果未知或被限流后重试完全相同的透传请求时，才复用原幂等键。
- 将
TIMEOUT视为原命令的不确定终态；复用原 key 不会重新发送数据。需要再次执行且外设命令允许安全重试时，生成新 key。 - 应用数据前，在自己的解析器中校验响应长度、协议校验码、地址和功能码。
- 无法容忍丢失时，应及时持久化主动或延迟到达的数据；WebSocket 事件不会补发。
- 遵守设备操作限流，不要向同一台设备并行发送透传请求。
生产环境注意事项
- 为每条物理 RS-485 总线或设备维护一个协调后的请求队列。
- 原始总线数据可能包含敏感值时，应在日志中脱敏。
- 记录命令 ID、幂等键、请求和响应长度、最终状态及
requestId，不要记录凭证或 access token。 - 开启自动重试前，使用真实外设测试超时和重复响应行为。