查询设备实时状态

device.state.get 会先请求设备刷新，再返回单个设备的最新可用状态。它适合用户主动查看设备详情，不适合高频轮询设备列表。

权限

device:read

Request

{
  "type": "request",
  "requestId": "req_state_001",
  "topic": "device.state.get",
  "data": {
    "deviceId": "abc123456789"
  }
}

Reply

{
  "type": "reply",
  "requestId": "req_state_001",
  "code": "SUCCESS",
  "message": "OK.",
  "data": {
    "deviceId": "abc123456789",
    "name": "YourDeviceName",
    "deviceType": "SM4_T_TH",
    "status": "ONLINE",
    "peripherals": {
      "relays": [
        { "index": 1, "on": true }
      ],
      "digitalInputs": [
        { "index": 1, "active": false }
      ],
      "analogInputs": [],
      "sensors": []
    },
    "stateUpdatedAt": "2026-07-15T08:30:00Z"
  }
}

如果设备离线，服务可能返回最后一次同步的状态，并将 status 标记为 OFFLINE。stateUpdatedAt 可用于判断状态更新时间。

如何选择

• 设备详情页需要用户主动刷新：使用 device.state.get。
• 账号设备列表、分页和批量展示：使用 HTTP 查询设备列表。
• 持续感知上线、离线、断电和外设变化：监听 WebSocket 事件。
• 断线重连后：对关键设备调用一次 device.state.get，不要循环刷新账号下的全部设备。

可能返回 INVALID_REQUEST、AUTH_SCOPE_DENIED、DEVICE_NOT_FOUND、DEVICE_BUSY、RATE_LIMITED、DEVICE_TIMEOUT、GATEWAY_UNAVAILABLE 或 INTERNAL_ERROR。