执行设备操作

通过 WebSocket 长连接对指定设备的一个或多个继电器下发操作命令，支持 ON、OFF、JOG 三种动作。

Topic

device.operation.execute

权限

需要：

device:control

Request

{
  "type": "request",
  "requestId": "req_op_001",
  "topic": "device.operation.execute",
  "data": {
    "deviceId": "abc123456789",
    "operation": {
      "name": "device.relay.set",
      "params": {
        "relays": [
          {
            "index": 1,
            "state": "ON"
          },
          {
            "index": 3,
            "state": "OFF"
          }
        ]
      }
    }
  }
}

请求 data 结构

字段	类型	必填	说明
deviceId	string	是	设备唯一标识
operation.name	string	是	操作名称，当前只支持 device.relay.set
operation.params.relays	array	是	继电器操作列表，至少包含一项
operation.params.relays[].index	integer	是	继电器序号，从 1 开始
operation.params.relays[].state	string	是	目标状态，只允许 ON、OFF、JOG

动作说明：

值	说明
ON	继电器保持接通
OFF	继电器保持断开
JOG	点动：继电器短暂闭合后自动断开，时长由设备持久化配置决定

Reply

{
  "type": "reply",
  "requestId": "req_op_001",
  "topic": "device.operation.execute",
  "success": true,
  "data": {
    "operation": {
      "name": "device.relay.set",
      "status": "SUCCESS"
    },
    "device": {
      "deviceId": "abc123456789",
      "name": "YourDeviceName",
      "deviceType": "SM4_T_TH",
      "status": "ONLINE",
      "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"
    }
  }
}

规则

• data.device 复用 REST 设备详情中的 Device 结构
• 由于此 reply 同时返回 operation 和设备外设状态数据，因此设备信息保留在 device 字段下
• data.device.peripherals 是完整外设状态数据，不是增量 diff
• operation.status=SUCCESS 表示所有继电器操作均已完成
• relays 列表中所有项作为一次原子操作处理，任意项失败则整体返回 success=false
• 如果设备离线，服务返回 success=false，error.code 为 DEVICE_OFFLINE
• 如果继电器序号不合法或操作不支持，服务返回 success=false，error.code 为 COMMAND_REJECTED

错误

可能返回：

• INVALID_REQUEST
• AUTH_SCOPE_DENIED
• DEVICE_NOT_FOUND
• DEVICE_OFFLINE
• COMMAND_REJECTED
• RATE_LIMITED
• INTERNAL_ERROR