设备状态变化事件

设备 IO 状态变化时发送 device.state.changed。

Topic

device.state.changed

Event — 远程控制触发

由 API 命令触发时，reason 为 remoteControl，correlationId 为触发该变化的请求 requestId。

{
  "type": "event",
  "topic": "device.state.changed",
  "data": {
    "deviceId": "abc123456789",
    "occurredAt": "2026-04-03T00:41:44Z",
    "reason": "remoteControl",
    "correlationId": "req_op_001",
    "peripherals": {
      "relays": [
        {
          "index": 1,
          "on": true
        },
        {
          "index": 2,
          "on": false
        },
        {
          "index": 3,
          "on": false
        },
        {
          "index": 4,
          "on": false
        }
      ],
      "digitalInputs": [
        {
          "index": 1,
          "active": false
        },
        {
          "index": 2,
          "active": false
        },
        {
          "index": 3,
          "active": false
        },
        {
          "index": 4,
          "active": false
        }
      ],
      "sensors": [
        {
          "index": 1,
          "type": "TEMP",
          "value": 30.4,
          "unit": "C",
          "status": "ONLINE"
        },
        {
          "index": 2,
          "type": "TEMP",
          "value": 32.6,
          "unit": "C",
          "status": "ONLINE"
        },
        {
          "index": 2,
          "type": "HUMI",
          "value": 54,
          "unit": "%",
          "status": "ONLINE"
        }
      ]
    },
    "stateUpdatedAt": "2026-04-03T00:41:44Z"
  }
}

Event — 设备侧触发

由设备本地触发时，reason 为 localChange，不含 correlationId。

{
  "type": "event",
  "topic": "device.state.changed",
  "data": {
    "deviceId": "abc123456789",
    "occurredAt": "2026-04-03T00:41:44Z",
    "reason": "localChange",
    "peripherals": {
      "relays": [
        {
          "index": 1,
          "on": false
        },
        {
          "index": 2,
          "on": false
        },
        {
          "index": 3,
          "on": false
        },
        {
          "index": 4,
          "on": false
        }
      ],
      "digitalInputs": [
        {
          "index": 1,
          "active": false
        },
        {
          "index": 2,
          "active": false
        },
        {
          "index": 3,
          "active": false
        },
        {
          "index": 4,
          "active": false
        }
      ],
      "sensors": [
        {
          "index": 1,
          "type": "TEMP",
          "value": 30.4,
          "unit": "C",
          "status": "ONLINE"
        },
        {
          "index": 2,
          "type": "TEMP",
          "value": 32.6,
          "unit": "C",
          "status": "ONLINE"
        },
        {
          "index": 2,
          "type": "HUMI",
          "value": 54,
          "unit": "%",
          "status": "ONLINE"
        }
      ]
    },
    "stateUpdatedAt": "2026-04-03T00:41:44Z"
  }
}

data 结构

字段	类型	必填	说明
deviceId	string	是	设备唯一标识
occurredAt	string	是	事件发生时间，RFC3339 UTC
reason	string	否	状态变化原因，见下表
correlationId	string	否	关联请求 ID，仅 reason=remoteControl 时出现
peripherals	object	是	完整外设状态数据
stateUpdatedAt	string	是	设备状态更新时间，RFC3339 UTC

reason 枚举

值	触发场景	correlationId
remoteControl	由 API 命令触发（device.operation.execute 或 REST 继电器命令）	对应请求的 requestId
localChange	设备侧触发；由于设备固件限制，无法确定具体来源（可能为面板按键、数字输入或其他本地硬件事件）	不出现

规则

• data.peripherals 复用 REST 设备详情中的 peripherals 结构
• data.peripherals 是完整外设状态数据，不是增量 diff
• 客户端收到事件后应按整块替换设备硬件状态
• reason 字段可能缺失；缺失时客户端不应假设触发来源