开发指南

本文详细介绍了网关局域网通信协议规范，以便帮助您正确地把涂鸦网关设备接入第三方应用。

通信模型

1. 网关开启局域网通信功能后，间隔 5s 发送 UDP 广播设备 UUID 和 WebSocket 的端口。
2. 第三方应用记录设备 UUID 和密钥的映射关系。当接收到网关广播时并且 WebSocket 未连接，则建立 WebSocket 连接。
3. 网关向第三方应用发起身份认证请求。
4. 第三方应用响应网关的身份认证请求。
5. 网关向第三方应用发起身份认证结果。
6. 双方分别使用自己生成的随机数和对端生成的随机数进行异或运算，得到会话密钥，后续的数据使用会话密钥进行加密和解密。

协议格式

WebSocket 的数据采用 JSON 格式，每条消息都包含 type 键值，表示消息的类型。

身份认证成功后，双向通信的消息有两种类型：

• 发送请求消息，对端需要回复响应消息。

• 发送事件消息，对端不需要回复响应消息。

请求消息格式

键值	类型	是否必选	描述
id	整形	是	消息 ID
type	字符串	是	消息类型，参考 协议详情
data	对象	否	请求数据

响应消息格式

键值	类型	是否必选	描述
id	整形	是	响应的消息 ID
type	字符串	是	消息类型，取值 result
success	布尔值	是	是否成功 true：成功 false：失败
result	对象	否	当 success 为 true，表示响应的数据
error	对象	否	当 success 为 false，表示错误的消息

事件消息格式

键值	类型	是否必选	描述
id	整形	是	消息 ID
type	字符串	是	消息类型，取值 event
event_type	字符串	是	事件类型
data	对象	否	事件数据

协议详情

身份认证

auth_required 数据格式

键值	类型	是否必选	描述
type	字符串	是	消息类型，取值 auth_required
data	对象	是	消息的数据内容
data.nonce	字符串	是	Base64 编码的 16 字节随机数

示例：

{
    "type": "auth_required",
    "data": {
        "nonce": "VOHiQDnXJatfv4fBPyHvEw=="
    }
}

auth 数据格式

键值	类型	是否必选	描述
type	字符串	是	消息类型，取值 auth
data	对象	是	消息的数据内容
data.nonce	字符串	是	Base64 编码的 16 字节随机数
data.hmac	字符串	是	Base64 编码的哈希值，该哈希值是对网关的随机数进行签名得到的

示例：

{
    "type": "auth",
    "data": {
        "nonce": "RIf328KU8EHKP1tH3XAtTw==",
        "hmac": "uZ3DiPiw3wFbb2w1lFZ/ZtzgzLuzK72xM95SGVIze3M="
    }
}

auth_ok 数据格式

键值	类型	是否必选	描述
type	字符串	是	消息类型，取值 auth_ok
data	对象	是	消息的数据内容
data.hmac	字符串	是	Base64 编码的哈希值，该哈希值是对第三方应用的随机数进行签名得到的

示例：

{
    "type": "auth_ok",
    "data": {
        "hmac": "+nThfHD+Ku/lWNMJJsoA+9ayrEgl/nlNtcokrFYTOQ8=",
    }
}

获取设备列表

请求数据格式

键值	类型	是否必选	描述
id	整形	是	消息 ID
type	字符串	是	消息类型，取值 get_devices

示例：

{
    "id": 1,
    "type": "get_devices",
}

响应数据格式

键值	类型	是否必选	描述
id	整形	是	请求的消息 ID
type	字符串	是	消息类型，取值 result
success	布尔值	是	是否成功 true：成功 false：失败
result	数组	是	设备列表

示例：

{
    "id": 1,
    "type: "result",
    "success": true,
    "result": [
        "000d6ffffe67e2ca",
        "a4c1380bb1d2f0d5",
        "a4c1385acafc01b5",
        "a4c138e72a0fb5a9",
        "a4c138807e3b1182"
    ]
}

获取设备信息

请求数据格式

键值	类型	是否必选	描述
id	整形	是	消息 ID
type	字符串	是	消息类型，取值 get_schema
data	数组	是	设备列表

示例：

{
    "id": 2,
    "type": "get_schema",
    "data": [
      "000d6ffffe67e2ca"
    ]
}

响应数据格式

键值	类型	是否必选	描述
id	整形	是	请求的消息 ID
type	字符串	是	消息类型，取值 result
success	布尔值	是	是否成功 true：成功 false：失败
result	数组	是	数据内容
result[0].devid	字符串	是	设备 ID
result[0].category	字符串	是	设备的品类 Code
result[0].function	数组	是	功能集
result[0].function[0].code	字符串	是	功能 DP Code 键值
result[0].function[0].type	字符串	是	功能 DP Code 类型
result[0].functions[0].values	字符串	是	功能 DP Code 取值范围
result[0].status	数组	是	状态集
result[0].status[0].code	字符串	是	状态 DP Code 键值
result[0].status[0].type	字符串	是	状态 DP Code 类型
result[0].status[0].values	字符串	是	状态 DP Code 取值范围

示例：

{
    "id": 2,
    "type": "result",
    "success": true,
    "result": [
      {
          "devid":"000d6ffffe67e2ca",
          "category": "kg",
          "function":[
             {
                "code":"switch_1",
                "type":"Boolean",
                "values":"{}"
             },
             {
                "code":"countdown_1",
                "type":"Integer",
                "values":"{\"unit\":\"s\",\"min\":0,\"max\":43200,\"scale\":0,\"step\":1}"
             }
          ],
           "status":[
             {
                "code":"switch_1",
                "type":"Boolean",
                "values":"{}"
             },
             {
                "code":"countdown_1",
                "type":"Integer",
                "values":"{\"unit\":\"s\",\"min\":0,\"max\":43200,\"scale\":0,\"step\":1}"
             }
          ]
      }
    ]
}

获取设备状态

请求数据格式

键值	类型	是否必选	描述
id	整形	是	消息 ID
type	字符串	是	消息类型，取值 get_status
data	数组	是	设备列表

示例：

{
    "id": 3,
    "type": "get_status",
    "data": [
      "000d6ffffe67e2ca"
    ]
}

响应数据格式

键值	类型	是否必选	描述
id	整形	是	请求的消息 ID
type	字符串	是	消息类型，取值 result
success	布尔值	是	是否成功 true：成功 false：失败
result	数组	是	数据内容
result[0].devid	字符串	是	设备 ID
result[0].online	布尔值	是	是否在线 true：在线 false：离线
result[0].value	数组	是	状态集
result[0].value[0].k	字符串	是	状态 DP Code 键值
result[0].value[0].v	布尔值/整形/字符串/对象	是	状态 DP Code 取值

示例：

{
    "id": 3,
    "type": "result",
    "success": true,
    "result": [
        {
            "devid": "000d6ffffe67e2ca",
              "online": true,
            "value": [
              {
                  "k": "switch_1",
                "v": true
              }
            ]
        }
    ]
}

控制设备

请求数据格式

键值	类型	是否必选	描述
id	整形	是	消息 ID
type	字符串	是	消息类型，取值 set_value
data	数组	是	数据内容
data[0].device	字符串	是	设备 ID
data[0].value	数组	是	功能集
data[0].value[0].k	字符串	是	功能 DP Code 键值
data[0].value[0].v	布尔值/整形/字符串/对象	是	功能 DP Code 取值

示例：

{
    "id": 4,
    "type": "set_value",
    "data": [
        {
            "devid": "000d6ffffe67e2ca",
            "value": [
                {
                    "k": "switch_1",
                    "v": true
                }
            ]
        }
    ]
}

响应数据格式

键值	类型	是否必选	描述
id	整形	是	请求的消息 ID
type	字符串	是	消息类型，取值 result
success	布尔值	是	是否成功 true：成功 false：失败

示例：

{
    "id": 4,
    "type": "result",
    "success": true
}

设备注册更新事件

事件数据格式

键值	类型	是否必选	描述
id	整形	是	消息 ID
type	字符串	是	消息类型，取值 event
event_type	字符串	是	事件类型，取值 registry_updated
data	对象	是	数据内容
data.devid	字符串	是	设备 ID
data.state	整形	是	状态 1：绑定 2：解绑 3：解绑并清除数据

示例：

{
    "id": 100,
    "type": "event",
    "event_type": "registry_updated",
    "data": {
        "devid": "000d6ffffe67e2ca",
        "state": 1
    }
}

设备在线更新事件

事件数据格式

键值	类型	是否必选	描述
id	整形	是	消息 ID
type	字符串	是	消息类型，取值 event
event_type	字符串	是	事件类型，取值 online_updated
data	对象	是	数据内容
data.devid	字符串	是	设备 ID
data.state	布尔值	是	true：上线 false：离线
data.value[0].k	字符串	是	DP Code
data.value[0].v	布尔值/整形/字符串/对象	是	DP Code 的值

示例：

{
    "id": 102,
    "type": "event",
    "event_type": "online_updated",
    "data": {
        "devid": "000d6ffffe67e2ca",
        "state": true
    }
}

设备状态变化事件

事件数据格式

键值	类型	是否必选	描述
id	整形	是	消息 ID
type	字符串	是	消息类型，取值 event
event_type	字符串	是	事件类型，取值 state_changed
data	对象	是	数据内容
data.devid	字符串	是	设备 ID
data.value	数组	是	状态集
data.value[0].k	字符串	是	状态 DP Code 键值
data.value[0].v	布尔值/整形/字符串/对象	是	状态 DP Code 取值

示例：

{
    "id": 101,
    "type": "event",
    "event_type": "state_changed",
    "data": {
        "devid": "000d6ffffe67e2ca",
        "value": [
            {
                "k": "switch_1",
                "v": true
            }
        ]
    }
}

注意事项

• 身份认证过程，密钥使用 App 面板展示的密钥。
• 身份认证成功，密钥使用会话密钥。
• 妥善保管设备的密钥，避免密钥泄露。