Device State Changed Event

The server sends device.state.changed when the state of one or more relays or digital inputs changes. The same event structure is used whether the change comes from an API command, a device report, or a platform refresh.

The first observed device state establishes a baseline and is not emitted as a change event.

Topic

device.state.changed

Event

{
  "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 Schema

Field	Type	Required	Description
deviceId	string	Yes	Unique device identifier
occurredAt	string	Yes	Event time in RFC3339 UTC
changes	array<object>	Yes	Peripheral types and channel indexes involved in this change
changes[].type	string	Yes	relay or digitalInput
changes[].indexes	array<number>	Yes	Changed channel indexes, starting at 1
correlationId	string	No	The related request requestId when the server can establish a correlation
peripherals	object	Yes	The device's complete current peripheral state block
stateUpdatedAt	string	Yes	Device state update time in RFC3339 UTC

Handling Rules

• Use changes to identify the relays or digital inputs whose state changed.
• peripherals is a complete state block, not an incremental patch. Replace the device's current peripheral state with this block.
• Changes only to analog inputs or sensor readings do not trigger this event. If those values arrive in the same state update as a relay or digital-input change, their latest values may still be included in peripherals.
• correlationId may be absent. Do not rely on it to determine whether the change was caused by a command from the current connection.
• WebSocket does not provide event history replay. Re-establish the state baseline after reconnecting; see Get Real-time Device State.
• Ignore unknown changes[].type values for forward compatibility.

See Peripheral State Reference for peripheral fields.