Execute Device Operation

Execute operations for one or more relays on a specified device over a WebSocket connection. The current version supports ON, OFF, and JOG.

Topic

device.operation.execute

Permission

Required:

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"
          }
        ]
      }
    }
  }
}

Request data Schema

Field	Type	Required	Description
deviceId	string	Yes	Unique device identifier
operation.name	string	Yes	Operation name. The current version only supports device.relay.set
operation.params.relays	array	Yes	Relay operation list. It must contain at least one item
operation.params.relays[].index	integer	Yes	Relay index, starting from 1
operation.params.relays[].state	string	Yes	Target state. Allowed values: ON, OFF, JOG

Action descriptions:

Value	Description
ON	The relay stays closed
OFF	The relay stays open
JOG	Momentary close, then automatic open. Duration is defined by the device's persisted jog configuration

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"
    }
  }
}

Rules

• data.device reuses the Device schema from REST device detail responses
• Because this reply returns both operation and the device peripheral state data, device information is nested under device
• data.device.peripherals is complete peripheral state data, not an incremental diff
• operation.status=SUCCESS means all relay operations in the request completed successfully
• All items in relays are processed as one atomic operation. If any item fails, the whole request returns success=false
• If the device is offline, the service returns success=false with error.code=DEVICE_OFFLINE
• If a relay index is invalid or the operation is not supported, the service returns success=false with error.code=COMMAND_REJECTED

Errors

Possible responses:

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