RS485 透传命令

向支持 RS485 的设备下发一段原始总线请求，并等待设备返回从站响应。该接口适用于需要与设备后接 RS485 或 Modbus RTU 从站通信的场景。

本接口只传输原始十六进制数据，不解析 Modbus 业务字段。调用方负责构造请求、校验 CRC，并解释响应中的 responseHex。

适用范围

• 仅支持具备 RS485 透传能力的设备。
• 建议先调用 查询设备列表 获取 deviceId，再调用 查询设备类型定义列表 确认设备能力。
• 设备离线、设备不支持该能力或底层网关不可用时，命令可能被拒绝或超时。

限流

平台会对命令类接口实施限流，防止设备或总线被高频请求影响稳定性。收到 429 RATE_LIMITED 时，应根据 Retry-After 响应头或响应体中的 retryAfterSeconds 再重试。

同步等待

• 首次请求最多同步等待约 10 秒。
• 如果在等待窗口内收到 RS485 从站响应，返回 status=SUCCESS，并在 result.responseHex 中返回原始响应数据。
• 如果等待窗口内未收到响应，返回 status=TIMEOUT，表示本次操作未确认成功；此时通常不会返回 result。
• 如果调用方复用同一个 Idempotency-Key 重试，而原请求仍在等待设备确认，则可能返回 SENT。

端点

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

权限要求

Scope	必须	说明
device:control	是	向指定设备下发 RS485 透传命令

请求

完整地址：

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

请求头：

Authorization: Bearer {accessToken}
Content-Type: application/json
Accept: application/json
Idempotency-Key: <调用方生成的唯一字符串>

路径参数：

参数	类型	必填	规则
deviceId	string	是	不能为空

请求体：

{
  "requestHex": "02060034000109F7"
}

字段规则：

字段	类型	必填	规则
requestHex	string	是	RS485/Modbus RTU 原始请求数据，连续十六进制字符串，长度为 1 到 30 字节

requestHex 可以使用大写或小写十六进制字符，但不应包含空格、0x 前缀或分隔符。

Idempotency-Key

Idempotency-Key 是必填请求头，由调用方生成的唯一字符串，用于标识一次操作意图。服务端通过它防止网络重试或应用层重试导致同一命令被重复执行。

场景	操作
发送一次新的 RS485 透传请求	生成新 key
请求发出后网络超时，未收到任何响应	复用原 key 重试同一请求
收到 429 RATE_LIMITED 后需要重试同一请求	复用原 key 重试同一请求
requestHex 或目标设备发生变化	生成新 key

重复请求行为：

• 同一客户端、同一路径、相同 key + 相同请求体：返回原始命令 id 和当前状态，不会重复执行。
• 相同 key 但请求体不同：返回 409 IDEMPOTENCY_CONFLICT。
• 服务端至少保留约 48 小时的幂等记录；超过有效期后相同 key 会被视为新请求。

成功响应

HTTP 状态码：

202 Accepted

响应体（收到 RS485 响应）：

{
  "code": "COMMAND_ACCEPTED",
  "message": "Command accepted.",
  "requestId": "req_001",
  "data": {
    "id": "cmd_001",
    "deviceId": "rek053537488",
    "type": "RS485_TRANSCEIVE",
    "status": "SUCCESS",
    "result": {
      "responseHex": "02060034000109F7"
    },
    "createdAt": "2026-06-11T00:00:00Z"
  }
}

响应体（等待窗口超时）：

{
  "code": "COMMAND_ACCEPTED",
  "message": "Command accepted.",
  "requestId": "req_001",
  "data": {
    "id": "cmd_001",
    "deviceId": "rek053537488",
    "type": "RS485_TRANSCEIVE",
    "status": "TIMEOUT",
    "createdAt": "2026-06-11T00:00:00Z"
  }
}

状态说明

• SENT：命令已被接受，但当前仍在等待设备最终确认；该状态通常只会出现在复用同一个 Idempotency-Key 的重复请求或后续查询中。
• SUCCESS：已收到 RS485 从站响应。
• FAILED：命令未成功完成。
• TIMEOUT：在等待窗口内未收到 RS485 响应，应按未确认成功处理。

响应 data 结构

字段	类型	必填	说明
id	string	是	命令唯一标识；需持久化，后续用于查询命令结果
deviceId	string	是	设备唯一标识
type	string	是	命令类型，固定为 RS485_TRANSCEIVE
status	string	是	命令状态，枚举：SENT、SUCCESS、FAILED、TIMEOUT
result	object	否	命令结果。超时或失败时可能不存在
result.responseHex	string	否	RS485 从站返回的原始十六进制数据
createdAt	string	是	命令创建时间，RFC3339 UTC

查询命令结果

如果首次响应未返回最终结果，或调用方需要在后续流程中确认状态，可使用响应中的 data.id 调用 查询命令结果。

错误响应

可能返回：

• 400 INVALID_REQUEST
• 401 AUTH_REQUIRED
• 401 AUTH_INVALID
• 401 AUTH_EXPIRED
• 403 AUTH_SCOPE_DENIED
• 404 DEVICE_NOT_FOUND
• 409 IDEMPOTENCY_CONFLICT
• 422 COMMAND_REJECTED
• 422 DEVICE_OFFLINE
• 429 RATE_LIMITED
• 503 GATEWAY_UNAVAILABLE
• 500 INTERNAL_ERROR