Get Real-Time Device State

device.state.get requests a device refresh before returning the latest available state for one device. Use it for an explicit detail-page refresh, not for high-frequency polling of a device list.

Permission

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"
  }
}

When the device is offline, the service may return the last synchronized state with status set to OFFLINE. Use stateUpdatedAt to evaluate its freshness.

Choosing the Right Interface

• Explicit refresh on a device detail page: use device.state.get.
• Paginated account device list: use REST List Devices.
• Continuous online, offline, power, and peripheral updates: listen for WebSocket events.
• After reconnecting: query important devices once instead of refreshing every device in the account.

Possible errors include INVALID_REQUEST, AUTH_SCOPE_DENIED, DEVICE_NOT_FOUND, DEVICE_BUSY, RATE_LIMITED, DEVICE_TIMEOUT, GATEWAY_UNAVAILABLE, and INTERNAL_ERROR.