设备状态变化事件

当一个或多个继电器或数字输入的状态发生变化时，服务端发送 device.state.changed。无论变化来自 API 命令、设备主动上报还是平台刷新，均使用同一事件结构。

首次取得设备状态时只建立状态基线，不会把初始值作为一次变化推送。

Topic

text

device.state.changed

Event

json

{
  "type": "event",
  "topic": "device.state.changed",
  "data": {
    "deviceId": "abc123456789",
    "occurredAt": "2026-07-18T08:30:00Z",
    "changes": [
      {
        "type": "relay",
        "indexes": [1, 3]
      },
      {
        "type": "digitalInput",
        "indexes": [2]
      }
    ],
    "correlationId": "req_op_001",
    "peripherals": {
      "relays": [
        { "index": 1, "on": true },
        { "index": 2, "on": false },
        { "index": 3, "on": true },
        { "index": 4, "on": false }
      ],
      "digitalInputs": [
        { "index": 1, "active": false },
        { "index": 2, "active": true },
        { "index": 3, "active": false },
        { "index": 4, "active": false }
      ]
    },
    "stateUpdatedAt": "2026-07-18T08:30:00Z"
  }
}

data 结构

字段	类型	必填	说明
`deviceId`	string	是	设备唯一标识
`occurredAt`	string	是	事件发生时间，RFC3339 UTC
`changes`	`array<object>`	是	本次变化涉及的外设类型和通道索引
`changes[].type`	string	是	`relay` 或 `digitalInput`
`changes[].indexes`	`array<number>`	是	发生变化的通道索引，索引从 `1` 开始
`correlationId`	string	否	服务端能够关联到某次请求时，值为该请求的 `requestId`
`peripherals`	object	是	设备当前的完整外设状态块
`stateUpdatedAt`	string	是	设备状态更新时间，RFC3339 UTC

处理规则

使用 changes 判断哪些继电器或数字输入发生了变化。
peripherals 是完整状态块，不是增量数据；客户端应使用它替换该设备当前的外设状态。
模拟量输入或传感器读数单独变化时不会触发本事件。如果它们与继电器或数字输入在同一次状态更新中返回，最新值仍可能包含在 peripherals 中。
correlationId 可能缺失。客户端不能依赖它判断变化是否来自本连接发出的命令。
WebSocket 不提供历史事件回放。断线重连后应重新建立状态基线，详见查询设备实时状态。
客户端应忽略未知的 changes[].type，以兼容后续扩展。

外设字段说明见外设状态参考。

设备状态变化事件 ​

Topic ​

Event ​

data 结构 ​

处理规则 ​

设备状态变化事件

Topic

Event

data 结构

处理规则