智联云 - ZhiLian.Yun

设备 TCP 接入

ZhiLian.Yun 平台支持设备直接通过 TCP 接入云平台，并支持 JSON、Plaintext、HEX 格式的上下行消息，为更复杂的设备通信提供了无限的可能性。

设备 TCP 接入点

在设备详情的连接页面中，可以找到设备的 TCP 接入点，格式如下：

markdown

tcp://项目ID.地区-api.xiujie.cn:7200  示例：tcp://000000.jn-api.xiujie.cn:7200

TCP 注册包

当设备和平台成功建立 TCP 连接后，设备必须马上向云平台发送身份信息，也称为“注册包”，完成身份认证。若设备端在一定时间内未发送注册包，云平台会自动断开设备的 TCP 连接。

markdown

<ProjectKey>&<AccessToken>$
示例： 1.000000.f0b2ea&1.10000023.12dd37$
1.000000.f0b2ea&1.10000032.a27b42$

TCP 消息类型

上行

以下主题用于设备向平台发布消息。

消息类型	Method
设备上报属性值	attributes/post
设备获取属性值	attributes/get
设备获取期望值	attributes/desired_get
清除期望属性	attributes/desired_delete
接收下发的属性回复	attributes/set_reply
接收属性采集回复	attributes/acquisition_reply
设备上报事件	event/post
批量上报(或历史上报)	batch/post
设备回复命令	command/send_reply
设备自定义数据上报	data/`<identifier>`
子设备已连接	gateway/connect
子设备已断开	gateway/disconnect
设备文件上传	file/upload

下行

以下主题用于设备接收平台下发的消息。

消息类型	Method
接收属性上报的响应	attributes/post_reply
接收属性获取的响应	attributes/get_reply
设备获取期望值响应	attributes/desired_get_reply
接收清除期望属性响应	attributes/desired_delete_reply
接收下发的属性	attributes/set
接收属性采集	attributes/acquisition
接收事件上报的响应	event/post_reply
批量上报(或历史上报)的响应	batch/post_reply
接收下发的命令	command/send
接收自定义数据下发	data/`<identifier>`
子设备已连接响应	gateway/connect_reply
子设备已断开响应	gateway/disconnect_reply
设备文件上传响应	file/upload_reply

设备上报属性

当设备自身的属性发生变化时，通过向平台上报属性，实现平台设备属性的及时更新，以及应用系统的设备数据实时更新。

设备发送消息

设备主动向云端上报设备属性值。

json

{
  "id": 1,                // 消息序号
  "method":"attributes/post", // 消息类型
  "ack": 1,               // 服务器是否应答，可选，0:云端平台不应答，1:云端平台应答
  "time":1626197189638,   // 属性采集时间戳毫秒级 可选，不填或填写0，当前时间以服务器时间为主
  "data":{                // 属性数据
    "ATTR1":"VALUE1", 
    "ATTR2":"VALUE2",
  },
  "gw":{
      "SUB_DEVICE_ADDR1":{ // 子设备1地址    
        "ATTR1":"value1",   // 子设备1属性1
        "ATTR2":"value2",
      },
      "SUB_DEVICE_ADDR2":{ // 子设备2地址
        "ATTR1":"value1",   // 子设备2属性1
        "ATTR2":"value2",   // 子设备2属性2
      }
  }
}

设备发布以上消息后，控制台的设备详情页会实时更新显示设备属性的最新值。

平台回复消息

云端处理上报后，默认不对属性上报消息进行响应，除非设备端在上报时显式指定 ack 为 1。

json

{
    "id":1,                // 与对应的上报消息的 id 保持一致，通过 id 来标识应答关系。
    "time":1626197189640,  // 服务器毫秒级时间戳。
    "method":"attributes/post_reply", // 消息类型
    "code":200              // 200 代表成功，默认值。非 200 代表失败。
}

设备获取属性

设备发送消息

当设备希望从平台获取属性当前值时，发送消息到如下主题：

json

{
  "id": 2,
  "time":1626197189638,  // 设备时间戳毫秒级 可选，不填或填写0，以服务器时间为主
  "method":"attributes/get", // 消息类型
  "data":{               
      "keys":["Key1","Key2"],// 属性标识 []:表示所有属性
  },
  "gw":{                     // 网关下子设备数据获取平台上属性
      "SUB_DEVICE_ADDR1":{   // 子设备1地址
         "keys":[]           // 子设备1属性标识
      },
      "SUB_DEVICE_ADDR2":{   // 子设备2地址
         "keys":[]           // 子设备2属性标识
      },
  },
}

平台回复消息

云端接收获取属性消息之后,平台回复消息

json

{
    "id":2,               // 与对应的上报消息的 id 保持一致，通过 id 来标识应答关系。
    "time":1626197189640, // 服务返回时间戳，13 位毫秒级。
    "method":"attributes/get_reply", // 消息类型
    "code":200            // 200 代表成功，默认值。非 200 代表失败。
    "data":{              // 设备属性
      "color":{
          "value":"red",
          "time":1626197189640
      }, 
      "brightness":{
          "value":500,
          "time":1626197189640
      }
    }
    "gw":{                        // 网关下子设备属性         
      "SUB_DEVICE_ADDR1":{        // 子设备1地址
          "attr1":{           // 子设备1属性1
              "value":"value",
              "time":1626197189640
          }, 
          "attr2":{
              "value":"value",
              "time":1626197189640
          }
      },
      "SUB_DEVICE_ADDR2":{        // 子设备2地址
          "attr1":{      
              "value":"value",
              "time":1626197189640
          }, 
          "attr2":{
              "value":"value",
              "time":1626197189640
          }
      }
  }
}

设备获取期望属性

markdown

# 期望值场景说明：
设备处于离线状态，无法直接下发指令。希望在云端提供暂存指令的能力，当设备上线时可以主动查询，然后执行状态更新。
低功耗类设备周期性的休眠/唤醒。当设备被唤醒时，可以主动查询云端是否有需要执行的指令。

设备发送消息

当设备希望从平台获取属性当前值时，发送消息到如下主题：

json

{
  "id": 2,
  "ack": 1,              // 服务器是否应答，可选，0:云端平台不应答，1:云端平台应答
  "time":1626197189638,  // 设备时间戳毫秒级 可选，不填或填写0，以服务器时间为主
  "method":"attributes/desired_get", // 消息类型
  "data":{               
      "keys":["Key1","Key2"] // 属性标识 平台只返回暂存的设置属性值
  },
  "gw":{                     // 网关下子设备数据获取平台上属性
      "SUB_DEVICE_ADDR1":{   // 子设备1地址
         "id": 21,           // 子设备1序号，可选
         "keys":[]           // 子设备1属性标识
      },
      "SUB_DEVICE_ADDR2":{   // 子设备2地址
         "id": 22,           // 子设备2序号，可选
         "keys":[]           // 子设备2属性标识
      },
  }
}

平台回复消息

json

{
    "id":2,               // 与对应的上报消息的 id 保持一致，通过 id 来标识应答关系。
    "time":1626197189640, // 服务返回时间戳，13 位毫秒级。
    "method":"attributes/desired_get_reply", // 消息类型
    "code":200            // 200 代表成功，默认值。非 200 代表失败。
    "data":{              // 设备属性
      "color":{
          "value":"red",
          "time":1626197189640,
          "version":0    // 期望属性版本号 云端每次对期望属性做修改都会导致期望属性版本号自增，清除期望属性时也需要该值。
      }, 
      "brightness":{
          "value":500,
          "time":1626197189640, 
          "version":0    
      }
    }
    "gw":{                        // 网关下子设备属性         
      "SUB_DEVICE_ADDR1":{        // 子设备1地址
          "attr1":{           // 子设备1属性1
              "value":"value",
              "time":1626197189640,
              "version":0  
          }, 
          "attr2":{
              "value":"value",
              "time":1626197189640,
              "version":0 
          }
      },
      "SUB_DEVICE_ADDR2":{        // 子设备2地址
          "attr1":{      
              "value":"value",
              "time":1626197189640,
              "version":0 
          }, 
          "attr2":{
              "value":"value",
              "time":1626197189640,
              "version":0
          }
      }
  },
}

清除期望属性

设备发送消息

设备接收期望属性后，更新本地状态成功，然后向云端发送清除期望属性的消息。

json

{
  "id": 2,
  "ack": 1,              // 服务器是否应答，可选，0:云端平台不应答，1:云端平台应答
  "time":1626197189638,  // 设备时间戳毫秒级 可选，不填或填写0，以服务器时间为主
  "method":"attributes/desired_delete", // 消息类型
  "data":{               
      "color":{
          "version":1   // 当清除期望属性时需要带上查询时获取的版本号。只有当清除请求的版本号等于云端记录的版本号时，才能清除成功。
      }, 
      "brightness":{
          "version":2    
      }
  },
  "gw":{                     // 网关下子设备
      "SUB_DEVICE_ADDR1":{   // 子设备1地址
          "attr1":{
              "version":10 
          }, 
          "attr2":{
              "version":1    
          }
      },
      "SUB_DEVICE_ADDR2":{   // 子设备2地址
          "attr1":{
              "version":10 
          }, 
          "attr2":{
              "version":1    
          }
      },
  },
}

平台回复消息

设备接收云端返回的期望属性删除响应。

json

{
    "id":2,               // 与对应的上报消息的 id 保持一致，通过 id 来标识应答关系。
    "time":1626197189640, // 服务返回时间戳，13 位毫秒级。
    "method":"attributes/desired_delete_reply", // 消息类型
    "code":200            // 200 代表成功，默认值。非 200 代表失败。
}

事件上报

设备发送消息

设备主动向云端上报设备事件触发的消息。

json

{
  "id": 2,
  "ack": 1,              // 服务器是否应答，可选，0:云端平台不应答，1:云端平台应答
  "time":1626197189638,  // 事件发生时间戳毫秒级 可选，不填或填写0，以服务器时间为主
  "method":"event/post", // 消息类型
  "data":{               // 事件数据
      "key":"alarmEvent",// 事件的模型定义 key。
      "value":{          // 事件数据
          "temp":-10.0
      }
  },
  "gw":{                     // 网关下子设备数据上报       
      "SUB_DEVICE_ADDR1":{   // 子设备1地址
         "id": 21,           // 子设备1事件序号,可选
         "key":"alarmEvent"  // 子设备1事件Key
         "value":{           // 子设备1事件数据
           "temp":-10.0
         }
      },
      "SUB_DEVICE_ADDR2":{   // 子设备2地址
         "id": 22,           // 子设备2事件序号,可选
         "key":"alarmEvent"  // 子设备2事件Key
         "value":{           // 子设备2事件数据
           "temp":-10.0
         }
      },
  },
}

平台回复消息

云端接收事件消息之后，默认不对消息进行响应，除非设备在上报消息中显式指定 ack 为 1。

json

{
    "id":2,               // 与对应的上报消息的 id 保持一致，通过 id 来标识应答关系。
    "time":1626197189640, // 服务返回时间戳，13 位毫秒级。
    "method":"event/post_reply", // 消息类型
    "code":200            // 200 代表成功，默认值。非 200 代表失败。
}

批量上报(或历史上报)

设备发送消息

设备主动向云端上报设备事件触发的消息。

json

{
  "id": 2,
  "ack": 1,              // 服务器是否应答，可选，0:云端平台不应答，1:云端平台应答
  "time":1626197189638,  // 上报时间戳毫秒级 可选，不填或填写0，以服务器时间为主
  "method":"batch/post", // 消息类型
  "data":{               // 事件数据
      "attributes":[
          {
              "key":"color",
              "value":"red",
              "time":1626197189640 // 属性采集时间戳毫秒级,可选
          },
          {
              "key":"color",
              "value":"red",
              "time":1626197170640 // 属性采集时间戳毫秒级,可选
          },
          {
              "key":"brightness",
              "value":500,
              "time":1626197189640 // 属性采集时间戳毫秒级,可选
          }
      ],
      "events":[
          {
            "key":"alarmEvent",  // 事件的模型定义 key。
            "time":1626197189640 // 事件发生时间戳毫秒级,可选
            "value":{            // 事件数据
                "temp":-10.0
            }
          }
      ]

  },
  "gw":{                     // 网关下子设备数据上报       
      "SUB_DEVICE_ADDR1":{   // 子设备1地址
         "attributes":[
            {
              "key":"color",
              "value":"red",
              "time":1626197182640 // 属性采集时间戳毫秒级,可选
            },
            {
              "key":"color",
              "value":"red",
              "time":1626197189640 // 属性采集时间戳毫秒级,可选
            },
          ],
          "events":[
              {
                "id": 21,            // 事件序号,可选
                "key":"alarmEvent",  // 事件的模型定义 key。
                "time":1626197189640 // 事件发生时间戳毫秒级,可选
                "value":{            // 事件数据
                    "temp":-10.0
                }
              }
          ]
      },
      "SUB_DEVICE_ADDR2":{   // 子设备2地址
         "attributes":[
            {
              "key":"color",
              "value":"red",
              "time":1626197182640 // 属性采集时间戳毫秒级,可选
            },
            {
              "key":"color",
              "value":"red",
              "time":1626197189640 // 属性采集时间戳毫秒级,可选
            },
          ],
          "events":[
              {
                "key":"alarmEvent",  // 事件的模型定义 key。
                "time":1626197189640 // 事件发生时间戳毫秒级,可选
                "value":{            // 事件数据
                    "temp":-10.0
                }
              }
          ]
      },
  },
}

平台回复消息

云端接收事件消息之后，默认不对消息进行响应，除非设备在上报消息中显式指定 ack 为 1。

json

{
    "id":2,               // 与对应的上报消息的 id 保持一致，通过 id 来标识应答关系。
    "time":1626197189640, // 服务返回时间戳，13 位毫秒级。
    "method":"batch/post_reply", // 消息类型
    "code":200            // 200 代表成功，默认值。非 200 代表失败。
}

属性下发

设备接收消息

设备接收云端发送的属性设置消息。

json

{
    "id":3,
    "time":1626197189638,
    "method":"attributes/set", // 消息类型
    "data":{              // 设备属性下发
      "color":"red", 
      "brightness":50
    }
    "gw":{                   // 网关下子设备属性下发         
      "SUB_DEVICE_ADDR1":{        // 子设备1地址
        "ATTRIBUTES1":"value1",   // 子设备1属性1
        "ATTRIBUTES2":"value2",
      },
      "SUB_DEVICE_ADDR2":{        // 子设备2地址
        "ATTRIBUTES1":"value1",   // 子设备2属性1
        "ATTRIBUTES2":"value2",   // 子设备2属性2
      }
  },
}

设备回复消息

设备在处理属性设置之后，需要设备对属性设置消息进行回复。

json

{
    "id":3,               // 原样返回
    "time":1626197189640,
    "method":"attributes/set_reply", // 消息类型
    "code":200            // 200 代表成功，默认值。非 200 代表失败。
}

属性采集

设备接收消息

设备接收云端发送的属性采集消息。

json

{
  "id": 2,
  "time":1626197189638,  // 设备时间戳毫秒级 可选，不填或填写0，以服务器时间为主
  "method":"attributes/acquisition", // 消息类型
  "data":{               
      "keys":["Key1","Key2"],// 属性标识 
  },
  "gw":{                     // 网关下子设备数据获取平台上属性
      "SUB_DEVICE_ADDR1":{   // 子设备1地址
         "keys":[]           // 子设备1属性标识
      },
      "SUB_DEVICE_ADDR2":{   // 子设备2地址
         "keys":[]           // 子设备2属性标识
      },
  },
}

设备回复消息

设备在属性采集之后，需要属性采集消息进行回复。

json

{
  "id": 1,                // 消息序号
  "ack": 1,               // 服务器是否应答，可选，0:云端平台不应答，1:云端平台应答
  "time":1626197189638,   // 属性采集时间戳毫秒级 可选，不填或填写0，当前时间以服务器时间为主
  "method":"attributes/acquisition_reply", // 消息类型
  "code":200            // 200 代表成功，默认值。非 200 代表失败。
  "data":{                // 属性数据    
    "ATTR1":"VALUE1", 
    "ATTR2":"VALUE2",
  },
  "gw":{
      "SUB_DEVICE_ADDR1":{ // 子设备1地址    
        "ATTR1":"value1",   // 子设备1属性1
        "ATTR2":"value2",
      },
      "SUB_DEVICE_ADDR2":{ // 子设备2地址
        "ATTR1":"value1",   // 子设备2属性1
        "ATTR2":"value2",   // 子设备2属性2
      }
  }
}

功能调用(命令下发)

设备接收消息

设备接收云端发送的功能调用消息。

json

{
    "id":4,
    "time":1626197189638,
    "method":"command/send"    // 消息类型
    "data":{
          "key": "set_param",   // 功能的模型定义 key。
          "input": {             // 功能调用的输入参数，key 为模型Key，value 为模型值。
              "input_param1":"value1", 
              "input_param2":"value2"
          }
    },
    "gw":{ 
        "SUB_DEVICE_ADDR1":{     // 子设备1地址
          "id":4,                // 子设备1序号,可选
          "key": "set_param",   // 子设备1功能的模型定义 key。
          "input": {             // 子设备1功能调用的输入参数 
              "input_param1":"value1", 
              "input_param2":"value2"
          }
        }
    }
}

设备回复消息

设备在处理功能调用之后，总是会对功能调用消息进行响应。

json

{
    "id":4,
    "time":1626197189640,
    "method":"command/send_reply",      // 消息类型
     "code":200,  // 200 代表成功，默认值。非 200 代表失败。
    "data":{
          "key": "set_param", // 功能的模型定义 key。
          "output": {          // 功能调用的输出参数，key 为参数 Key，value 为参数值。
              "output_param1":"value1", 
              "output_param2":"value2"
          }
    },
    "gw":{ 
        "SUB_DEVICE_ADDR1":{     // 子设备1地址
          "id":4,                // 子设备1序号，原样返回
          "key": "set_param",    // 子设备1功能的模型定义 key。
          "output": {            // 子设备1功能调用的输出参数 
              "output_param1":"value1", 
              "output_param2":"value2"
          },
          "code":200            // 200 代表成功，默认值。非 200 代表失败。
        }
    }
}

子设备已连接

网关设备发送消息

当网关确定子设备已连接时，可上报消息通知平台。

json

{
  "id": 101,             // 消息序号
  "ack": 1,               // 服务器是否应答，可选，0:云端平台不应答，1:云端平台应答
  "time":1626197189638,   // 设备毫秒级时间戳 可选，不填或填写0，以服务器时间为主
  "method":"gateway/connect"    // 消息类型
  "gw":{
      "device":"SUB_DEVICE_ADDR1"  // 子设备地址
      "typeKey": "TYPE_KEY",      // 可选,自动注册子设备使用
      "productKey": "PRODUCT_KEY" // 可选,自动注册子设备使用
  }
}

平台回复消息

当网关确定子设备已连接时，可上报消息通知平台。

json

{
    "id":101,             // 与对应的上报消息的 id 保持一致，通过 id 来标识应答关系。
    "time":1626197189640,  // 服务器毫秒级时间戳。
    "method":"gateway/connect_reply"                // 消息类型
    "code":200              // 200 代表成功，默认值。非 200 代表失败。
}

子设备已断开

网关设备发送消息

当网关确定子设备已断开时，可上报消息通知平台。

json

{
  "id": 102,             // 消息序号
  "ack": 1,               // 服务器是否应答，可选，0:云端平台不应答，1:云端平台应答
  "time":1626197189638,   // 设备毫秒级时间戳 可选，不填或填写0，以服务器时间为主
  "method":"gateway/disconnect"                // 消息类型
  "gw":{
      "device":"SUB_DEVICE_ADDR1"
  },
}

平台回复消息

当网关确定子设备已断开时，可上报消息通知平台。

json

{
    "id":102,             // 与对应的上报消息的 id 保持一致，通过 id 来标识应答关系。
    "time":1626197189640, // 服务器毫秒级时间戳。
    "method":"gateway/disconnect_reply"                // 消息类型
    "code":200            // 200 代表成功，默认值。非 200 代表失败。
}

设备文件上传

设备发送消息

设备进行文件上传时，需要先请求云端获取上传的预签名 URL，然后根据获取的预签名 URL 上传文件。

json

{
  "id": 201,              // 消息序号
  "ack": 1,               // 服务器是否应答，可选，0:云端平台不应答，1:云端平台应答
  "time":1626197189638,   // 设备毫秒级时间戳 可选，不填或填写0，以服务器时间为主
  "method":"file/upload"                // 消息类型
  "data":{
      "type":"file",         // 业务类型,固定字符 file
      "fileName":"a.png",   // 文件名称
      "relatedId":"IPC_ID", // 关联ID，比如:产生文件的设备,或事件名称
      "remark":""            // 备注
  },
}

平台回复消息

用于设备文件上传的预签名 URL，可用来直接上传文件到云存储。

json

{
    "id":201,             // 与对应的上报消息的 id 保持一致，通过 id 来标识应答关系。
    "time":1626197189640, // 服务器毫秒级时间戳。
    "code":200            // 200 代表成功，默认值。非 200 代表失败。
    "method":"file/upload_reply"                // 消息类型
    "data":{
      "type":"file", 
      "url":"http://upload.xjzl.cn/?file_name=a.png&related_id=IPC_ID&sign=1245678"
    }
}

设备 TCP 接入 ​

设备 TCP 接入点 ​

TCP 注册包 ​

TCP 消息类型 ​

上行 ​

下行 ​

设备上报属性 ​

设备发送消息 ​

平台回复消息 ​

设备获取属性 ​

设备发送消息 ​

平台回复消息 ​

设备获取期望属性 ​

设备发送消息 ​

平台回复消息 ​

清除期望属性 ​

设备发送消息 ​

平台回复消息 ​

事件上报 ​

设备发送消息 ​

平台回复消息 ​

批量上报(或历史上报) ​

设备发送消息 ​

平台回复消息 ​

属性下发 ​

设备接收消息 ​

设备回复消息 ​

属性采集 ​

设备接收消息 ​

设备回复消息 ​

功能调用(命令下发) ​

设备接收消息 ​

设备回复消息 ​

子设备已连接 ​

网关设备发送消息 ​

平台回复消息 ​

子设备已断开 ​

网关设备发送消息 ​

平台回复消息 ​

设备文件上传 ​

设备发送消息 ​

平台回复消息 ​

设备 TCP 接入

设备 TCP 接入点

TCP 注册包

TCP 消息类型

上行

下行

设备上报属性

设备发送消息

平台回复消息

设备获取属性

设备发送消息

平台回复消息

设备获取期望属性

设备发送消息

平台回复消息

清除期望属性

设备发送消息

平台回复消息

事件上报

设备发送消息

平台回复消息

批量上报(或历史上报)

设备发送消息

平台回复消息

属性下发

设备接收消息

设备回复消息

属性采集

设备接收消息

设备回复消息

功能调用(命令下发)

设备接收消息

设备回复消息

子设备已连接

网关设备发送消息

平台回复消息

子设备已断开

网关设备发送消息

平台回复消息

设备文件上传

设备发送消息

平台回复消息