控制继电器

通过 device.operation.execute 控制设备的一路或多路继电器。一次请求中的多路操作会作为一个命令下发。

整批操作只占用一次设备操作额度。不要为了控制不同继电器而连续发送多条消息。

权限

device:control

Request

{
  "type": "request",
  "requestId": "req_relay_001",
  "topic": "device.operation.execute",
  "data": {
    "deviceId": "abc123456789",
    "idempotencyKey": "idem_relay_001",
    "operation": {
      "name": "device.relay.set",
      "params": {
        "relays": [
          { "index": 1, "action": "ON" },
          { "index": 2, "action": "OFF" }
        ]
      }
    }
  }
}

单路控制使用只包含一个元素的 relays 数组。

params 字段

字段	类型	必填	说明
relays	array	是	非空继电器操作列表
relays[].index	integer	是	继电器序号，从 1 开始；同一请求内不能重复
relays[].action	string	是	ON、OFF 或 JOG

JOG 的持续时长由设备中保存的点动配置决定。

Reply

{
  "type": "reply",
  "requestId": "req_relay_001",
  "code": "COMMAND_ACCEPTED",
  "message": "Command accepted.",
  "data": {
    "command": {
      "id": "cmd_01HX...",
      "deviceId": "abc123456789",
      "operation": "device.relay.set",
      "status": "SUCCESS",
      "params": {
        "relays": [
          { "index": 1, "action": "ON" },
          { "index": 2, "action": "OFF" }
        ]
      },
      "createdAt": "2026-07-15T08:30:00Z"
    },
    "state": {
      "deviceId": "abc123456789",
      "status": "ONLINE",
      "peripherals": {
        "relays": [
          { "index": 1, "on": true },
          { "index": 2, "on": false }
        ],
        "digitalInputs": [
          { "index": 1, "active": false }
        ],
        "analogInputs": [],
        "sensors": []
      },
      "stateUpdatedAt": "2026-07-15T08:30:00Z"
    }
  }
}

字段	类型	必填	说明
data.command	object	是	本次命令及其状态
data.command.id	string	是	命令 ID，可用于 REST 查询命令结果
data.command.operation	string	是	固定为 device.relay.set
data.command.params.relays	array	是	规范化后的继电器操作
data.command.status	string	是	SENT、SUCCESS、FAILED 或 TIMEOUT
data.state	object	否	设备确认包同时携带的最新运行状态
data.state.peripherals	object	否	可能同时包含继电器、数字输入、模拟量和传感器状态

state 只在本次设备响应包含可用状态时返回。不要为了补齐 state 再立即发送一次状态查询；需要确认后续变化时，监听 device.state.changed。

幂等与重试

• 未收到明确回复时，重试同一次操作必须复用 idempotencyKey。
• 新操作必须生成新 key。
• TIMEOUT 后复用原 key 不会再次控制设备；确认需要执行新的物理操作后使用新 key。
• 相同 key 配不同参数会返回 IDEMPOTENCY_CONFLICT。
• requestId 仅用于关联当前连接中的请求和回复，不替代幂等键。

错误

可能返回 INVALID_REQUEST、AUTH_SCOPE_DENIED、DEVICE_NOT_FOUND、DEVICE_BUSY、DEVICE_OFFLINE、IDEMPOTENCY_CONFLICT、COMMAND_REJECTED、RATE_LIMITED、GATEWAY_UNAVAILABLE 或 INTERNAL_ERROR。

对应 REST 接口：执行继电器命令。