消息格式

所有 WebSocket 文本消息都使用 JSON。

消息由 type 和 topic 区分语义：

type	方向	说明
request	客户端到服务	客户端发起一次请求
reply	服务到客户端	服务回复某个 request
event	服务到客户端	服务主动推送事件

Request

{
  "type": "request",
  "requestId": "req_status_001",
  "topic": "device.status.get",
  "data": {
    "deviceId": "abc123456789"
  }
}

字段说明：

字段	类型	必填	说明
type	string	是	固定为 request
requestId	string	是	客户端生成的请求 ID，同一连接内应唯一
topic	string	是	请求主题
data	object	是	请求数据

Success Reply

{
  "type": "reply",
  "requestId": "req_status_001",
  "topic": "device.status.get",
  "success": true,
  "data": {
    "deviceId": "abc123456789",
    "name": "YourDeviceName",
    "deviceType": "SM4_T_TH",
    "status": "ONLINE",
    "peripherals": {
      "relays": [
        {
          "index": 1,
          "on": false
        },
        {
          "index": 2,
          "on": false
        },
        {
          "index": 3,
          "on": true
        },
        {
          "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"
  }
}

Error Reply

{
  "type": "reply",
  "requestId": "req_op_001",
  "topic": "device.operation.execute",
  "success": false,
  "error": {
    "code": "COMMAND_REJECTED",
    "message": "Command was rejected."
  }
}

字段说明：

字段	类型	必填	说明
type	string	是	固定为 reply
requestId	string	是	对应请求的 requestId
topic	string	是	对应请求的 topic
success	boolean	是	请求是否处理成功
data	object	成功时返回	响应数据
error	object	失败时返回	错误信息
error.code	string	失败时返回	错误码
error.message	string	失败时返回	人类可读说明，仅用于展示、日志和排障

Event

{
  "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": false
        },
        {
          "index": 2,
          "on": false
        },
        {
          "index": 3,
          "on": true
        },
        {
          "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"
  }
}

字段说明：

字段	类型	必填	说明
type	string	是	固定为 event
topic	string	是	事件主题
data	object	是	事件数据

外设状态字段的详细说明，参见 外设状态说明。

命名规则

• type 只使用 request、reply、event
• topic 使用小写英文和点号分段，例如 device.status.get
• requestId 由客户端生成，可使用业务唯一 ID、UUID 或带前缀的短 ID
• 时间字段使用 RFC3339 UTC 字符串
• JSON 字段使用 camelCase
• 客户端应忽略暂时无法识别的新增字段