RS485 透传命令

向支持 RS485 的设备发送原始总线数据并等待从站响应。服务不解析 Modbus 业务字段；调用方负责构造请求、CRC 和响应解析。

端点与权限

POST /wlte/v1/devices/{deviceId}/rs485/transceive

需要 device:control。

请求

POST {baseUrl}/wlte/v1/devices/{deviceId}/rs485/transceive
Authorization: Bearer {accessToken}
Content-Type: application/json
Idempotency-Key: <调用方生成的唯一字符串>

{
  "requestHex": "02060034000109F7"
}

curl 示例：

curl --request POST '{baseUrl}/wlte/v1/devices/{deviceId}/rs485/transceive' \
  --header 'Authorization: Bearer {accessToken}' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <调用方生成的唯一字符串>' \
  --data '{
    "requestHex": "02060034000109F7"
  }'

requestHex 是 1 到 30 字节的连续十六进制字符串，不包含空格、0x 前缀或分隔符。

成功响应

{
  "code": "COMMAND_ACCEPTED",
  "message": "Command accepted.",
  "requestId": "req_001",
  "data": {
    "command": {
      "id": "cmd_001",
      "deviceId": "rek053537488",
      "operation": "device.rs485.transceive",
      "status": "SUCCESS",
      "params": {
        "requestHex": "02060034000109F7"
      },
      "result": {
        "responseHex": "02060034000109F7"
      },
      "createdAt": "2026-07-15T08:30:00Z"
    }
  }
}

HTTP 状态码为 202 Accepted。

• params.requestHex 是规范化后的请求数据。
• result.responseHex 只在收到从站响应时返回。
• TIMEOUT 表示等待窗口内没有收到响应，此时 result 不返回。
• SENT 表示相同幂等键对应的原命令仍在等待结果。

幂等与重试

新的透传操作使用新 Idempotency-Key。未收到明确 HTTP 响应，或限流后重试完全相同的请求时，复用原 key。相同 key 配不同请求会返回 IDEMPOTENCY_CONFLICT。

如果命令已返回 TIMEOUT，复用原 key 只会返回原来的 commandId 和 TIMEOUT，不会再次发送 RS485 数据。判断外设命令可以安全重试后，使用新 key 发起新的透传操作。

使用 data.command.id 调用 查询命令结果。

可能返回 INVALID_REQUEST、AUTH_SCOPE_DENIED、DEVICE_NOT_FOUND、DEVICE_BUSY、DEVICE_OFFLINE、IDEMPOTENCY_CONFLICT、COMMAND_REJECTED、RATE_LIMITED、GATEWAY_UNAVAILABLE 或 INTERNAL_ERROR。