X-PTP通信协议说明

一、概述

Xlink IoT Gataway是物联云平台提供的一个敏捷、可扩展的物联网网关软件架构，可广泛适用于智能家居、智慧社区和智能商业等物联网的应用场景。通过Xlink IoT Gataway方案您可以快速开发网关应用，实现本地设备安全认证、协议转换和处理、执行本地计算、数据收发和缓存，支持云端及应用程序的数据采集、同步和远程访问控制。 Xlink IoT Gataway由Xlink Core Gateway和Xlink SEP 、Xlink PTP 三个部分构成。

二、Xlink Core Gateway

Xlink Core Gateway（XCG）是Xlink网关的核心程序，提供网关的设备安全、消息处理，计算、数据缓存和通信等服务。
XCG作为单独进程在OS中运行，通过进程通信与X-PTP，X-SEP应用进行交互。

二、Xlink PTP

Xlink Protocol Transform Processor （X-PTP ），基于其所开发的网关应用程序，我们称之为X- PTP应用，它用于实现子设备协议的转换和通信适配，也可以自定义数据和业务处理逻辑。
X-PTP 根据XCG提供的系列便捷的协议，使得您能够快速对接子设备，子设备可以是Z-wave、 Zigbee、BLE Mesh和RS-485等通信协议；
X-PTP应用程序会作为独立的进程在网关中运行，每个X-PTP进程可以处理不同类型的子设备接入协议。例如，您可以开发一个支持Zigbee HA的X-PTP程序，让网关支持Zigbee联盟标准的设备接入，同时也可以开发一个支持BLE Mesh或RS-485的X-PTP程序来实现相应的设备接入。
每个X-PTP进程都将连接到同一个本地的XCG进行统一的通信和管理，如下图所示：

三、XCG与X-PTP的通信协议

Xlink Protocol Transform Processor （X-PTP）是XCG与X-PTP网关程序之间的通信协议，基于MQTT，通过该协议可实现您自己开发的X-PTP网关程序与XCG的对接。

本文档以实现了Zigbee协议转换的PTP为例，其所涉及的部分XDP协议框架如下：

1. 子设备列表

说明:
PTP向XCG发送全量的设备列表
方向:
PTP -> XCG
Topic:
$xlink/ptp/{ptp_id}/devices
注意: ptp_id是PTP进程的唯一ID，具体生成方式见后面附录说明。

Payload

json

{
   "devices": [
       {
           "mac": "设备mac",
           "product_id": "设备所属产品ID",
           "state": 整型设备状态,
           "push": 是否推送
       }
   ]
}

字段	类型	是否必须	说明
devices	队列	是	设备列表
mac	字符串	是	设备MAC地址。注意：在Zigbee网关中，是Zigbee设备的Eui值。
product_id	字符串	是	设备所属产品ID。其具体获取方式见附录说明
state	整型	否	设备状态
push	布尔	否	是否推送告警，推送:true，不推送:false，默认true

2. 搜索子设备

说明:
XCG通过PTP通知Zigbee协调器进入新设备发现状态。在APP添加子设备期间，此协议会间隔5秒左右重发，PTP实现时需要注意。
PTP在最后一次收到此条消息的若干时间后（通常建议90-180秒）若没收到 $xlink/ptp/{ptp_id}/device/stopsearch（停止搜索子设备)指令，需要主动退出入网模式。
此协议会广播给所有的PTP连接
方向:
XCG -> PTP
Topic:
$xlink/ptp/{ptp_id}/device/search
注意: ptp_id是PTP进程的唯一ID，具体生成方式见后面附录说明。

Payload

json

{
 "pids":["",""],
 "sgw_macs":["AABBCCDDEEFF","AABBCCDDEEF2"]
}

字段	类型	是否必须	说明
pids	字符串列表	否	需要入网的产品ID列表，此字段为空表示所有产品
sgw_macs	字符串列表	否	需要开启入网的子网关MAC列表，此字段为空表示所有子网关。PTP实现上可以根据此参数控制匹配的子网关开启入网模式，从而实现子设备需入网到指定网关的场景

3. 子设备加入

说明:
当一个设备加入到网络以后，通知给XCG。
方向:
PTP -> XCG
Topic:
$xlink/ptp/{ptp_id}/device/new

Payload

json

{
   "mac":"设备mac",
   "product_id":"设备所属产品ID",
   "push":是否推送,
   "type":设备类型
}

字段	类型	是否必须	说明
mac	字符串	是	设备MAC地址。注意：在Zigbee网关中，是Zigbee设备的Eui值。
product_id	字符串	是	设备所属产品ID。其具体获取方式见附录说明
push	布尔	否	是否推送告警，推送:true，不推送:false，默认true
type	整型	否	设备类型：1-主网关，2-子设备，3-子网关; 默认值：2-子设备

4. 删除子设备

说明:
XCG通知PTP去删除一个设备。
删除结果，通过Topic:子设备操作通用结果应答应答
方向:
XCG->PTP
Topic:
$xlink/ptp/{ptp_id}/device/delete

Payload

json

{
 "msg_id":消息ID,
 "mac":"设备mac",
   "product_id":"设备所属产品ID",
   "code":操作代码
}

字段	类型	是否必须	说明
msg_id	整形	是	消息ID
mac	字符串	是	设备MAC地址。注意：在Zigbee网关中，是Zigbee设备的Eui值。
product_id	字符串	是	设备所属产品ID。其具体获取方式见附录说明
code	整形	否	操作代码：0-正常删除；1-设备激活时平台返回设备不存在，进行设备删除；2-设备上线时平台返回设备不存在，进行设备删除。

5. 子设备状态改变

说明:
当子状态、属性改变以后，通过PTP通知到XCG。
方向:
PTP -> XCG
Topic:
$xlink/ptp/{ptp_id}/device/sync

Payload

json

{
   "devices": [
       {
           "mac": "设备mac",
           "product_id": "设备所属产品ID",
           "state":设备状态,
           "push":是否推送,
   "time":状态改变时间,
           "datapoints": [
               {
                   "index": 索引,
     "name":"名称",
                   "value": "值"
               },
               {
                   "index": 索引,
     "name":"名称",
                   "value": "值"
               }
           ]
       }
   ]
}

字段	类型	是否必须	说明
mac	字符串	是	设备MAC地址。注意：在Zigbee网关中，是Zigbee设备的Eui值。
product_id	字符串	是	设备所属产品ID。其具体获取方式见附录说明
state	整形	是	设备状态
push	布尔	否	是否推送告警，推送:true，不推送:false，默认true
time	字符串	否	状态改变时间。格式为毫秒级utc时间戳，示例：“1616404559000”。
datapoints	对象	否	设备改变的数据端点列表
datapoints.index	整形	否	数据端点索引
datapoints.name	字符串	否	数据端点名称
datapoints.type	整形	否	数据端点数据类型，其定义见附录说明
datapoints.value	数字、字符串、布尔	否	数据端点值

6. 改变子设备状态

说明:
XCG发送消息给PTP改变一个子设备状态
操作结果，通过Topic:子设备操作通用结果应答应答
方向:
XCG->PTP
Topic:
$xlink/ptp/{ptp_id}/device/set

Payload

json

{
 "msg_id":"消息ID",
 "mac":"设备mac",
 "product_id":"设备所属产品ID",
 "datapoints":[
  {
   "index":"索引",
   "name":"名称",
   "type": 类型,
   "value":"值",
  },
  {
   "index":"索引",
   "name":"名称",
   "type": 类型,
   "value":"值",
  }
 ]
}

字段	类型	是否必须	说明
msg_id	整形	是	消息ID
mac	字符串	是	设备MAC地址。注意：在Zigbee网关中，是Zigbee设备的Eui值。
product_id	字符串	是	设备所属产品ID。其具体获取方式见附录说明
datapoints	对象	是	设备改变的数据端点列表
datapoints.index	整形	是	数据端点索引
datapoints.name	字符串	是	数据端点名称
datapoints.type	整形	否	数据端点数据类型，其定义见附录说明
datapoints.value	数字、字符串、布尔	是	数据端点值

7. 子设备发布物属性

说明:
当子状态、属性改变以后，通过PTP通知到XCG。
方向:
PTP -> XCG
Topic:
$xlink/ptp/{ptp_id}/device/thing/publish_attribute

Payload

json

{
   "devices":[
       {
           "mac":"设备mac",
           "product_id":"设备所属产品ID",
           "state":"设备状态",
           "attribute":{
               "v":"物模型版本号",
               "time":"时间，utc时间戳表示",
               "extra":{
                   "name":"value"
               }
           }
       }
   ]
}

字段路径	类型	必填	说明
mac	String	✓	设备MAC地址注意：在Zigbee网关中是Zigbee设备的Eui值
product_id	String	✓	设备所属产品ID 具体获取方式见附录说明
state	Integer	✓	设备状态
attribute	Object	-	设备物属性对象
↳ attribute.v	String	-	物模型版本号，当前值为 `"2.0"`
↳ attribute.time	String	-	时间戳格式为毫秒级UTC时间戳示例：`"1616404559000"`
↳ attribute.extra	Object	✓	物模型属性对象示例：`{"PowerSwitch":0,"Status":true}`

8. 子设备物模型事件上报

说明:
当子设备物模型事件改变以后，通过PTP通知到XCG。
方向:
PTP -> XCG
Topic:
$xlink/ptp/{ptp_id}/device/thing/event/{event_name}/report

Payload

json

{
   "devices":[
       {
           "mac":"设备mac",
           "product_id":"设备所属产品ID",
           "state":"设备状态",
           "event":{
               "v":"物模型版本号",
               "time":"时间，long型时间戳表示",
               "extra":{
                   "xxx":"xxx"
               }
           }
       }
   ]
}

字段	类型	是否必须	说明
mac	字符串	是	设备MAC地址。注意：在Zigbee网关中，是Zigbee设备的Eui值。
product_id	字符串	是	设备所属产品ID。其具体获取方式见附录说明
state	整形	是	设备状态
event	对象	否	设备改变的物模型事件
event.v	字符串	否	物模型版本号，当前值为 `"2.0"`
event.extra	Object	是	物模型事件对象，例如：`{"code":0,"message":"OK"}`

9. 子设备物模型服务调用

说明:
XCG发送消息给PTP调用子设备物模型服务
方向:
XCG -> PTP
Topic:
$xlink/ptp/{ptp_id}/device/thing/service/{service_name}/invoke

Payload

json

{
   "msg_id":"消息ID",
   "mac":"设备mac",
   "product_id":"设备所属产品ID",
   "service":{
       "v":"物模型版本号",
       "input":{
           "xxx":"xxx"
       }
   }
}

字段	类型	是否必须	说明
msg_id	整形	是	消息ID，需要在服务调用结果中原样返回
mac	字符串	是	设备MAC地址。注意：在Zigbee网关中，是Zigbee设备的Eui值。
product_id	字符串	是	设备所属产品ID。其具体获取方式见附录说明
service	对象	是	设备物模型服务
service.input	Object	是	物模型服务输入参数，例如：`{"code":0,"message":"OK"}`

10. 子设备物模型服务调用返回结果

说明:
子设备物模型服务调用返回结果通过PTP通知到XCG。
方向:
PTP -> XCG
Topic:
$xlink/ptp/{ptp_id}/device/thing/service/{service_name}/invoke/result

Payload

json

{
   "msg_id":"消息ID",
   "mac":"设备mac",
   "product_id":"设备所属产品ID",
   "service_result":{
       "v":"物模型版本号",
       "code":"xx",
       "output":{
           "xxx":"xxx"
       }
   }
}

字段	类型	是否必须	说明
msg_id	整型	是	消息ID，需要原样返回服务端调用中的msg_id
mac	字符串	是	设备MAC地址。注意：在Zigbee网关中，是Zigbee设备的Eui值。
product_id	字符串	是	设备所属产品ID。其具体获取方式见附录说明
service_result	对象	是	子设备物模型服务调用返回结果
service_result.v	字符串	否	物模型版本号，当前值为 `"2.0"`
service_result.output	Object	是	物模型服务返回参数对象，例如：`{"code":0,"message":"OK"}`

15. PTP发送自定义数据到XCG

说明:
PTP发送一条自定义数据到XCG
方向:
PTP -> XCG
Topic:
$xlink/ptp/{ptp_id}/ptp_custom_msg

Payload

json

{
   "type":"text/json/base64",
   "body":"普通文字/json数据/base64编码的二进制数据"
}

字段	类型	是否必须	说明
type	字符串	是	消息body格式
body	字符串/json数据	是	字符串或者是json数据，由type决定

16. XCG发送自定义数据到PTP

说明:
XCG发送一条自定义数据到PTP
方向:
XCG -> PTP
Topic:
$xlink/ptp/{ptp_id}/xcg_custom_msg

Payload

json

{
   "type":"text/json/base64",
   "body":"普通文字/json数据/base64编码的二进制数据"
}

字段	类型	是否必须	说明
type	字符串	是	消息body格式
body	字符串/json数据	是	字符串或者是json数据，由type决定

17. 查询最新的升级任务

说明:
PTP发送消息给XCG查询最新的升级任务
查询结果通过Topic:查询最新的升级任务结果应答
方向:
PTP -> XCG
Topic:
$xlink/ptp/{ptp_id}/firmware/check

Payload

json

{
 "msg_id":"消息ID",
 "mac":"设备mac",
 "product_id":"设备所属产品ID",
 "type":"升级任务类型",
 "current_version":"设备当前版本",
 "identify":"用来定位多MCU或多子设备的情况"
}

字段	类型	是否必须	说明
msg_id	整形	是	消息ID
mac	字符串	是	设备MAC地址。注意：在Zigbee网关中，是Zigbee设备的Eui值。
product_id	字符串	是	设备所属产品ID。其具体获取方式见附录说明
type	整形	是	升级任务类型，见附录 4.6，默认为wifi
current_version	整形	是	设备当前版本
identify	整形	是	用来定位多MCU或多子设备的情况，type若为"wifi"，identify设置为0

18. 查询最新的升级任务结果

说明:
XCG发送消息给PTP查询到的最新的升级任务的结果
方向:
XCG -> PTP
Topic:
$xlink/ptp/{ptp_id}/firmware/check/result

Payload

json

{
 "msg_id":"消息ID",
 "mac":"设备mac",
 "product_id":"设备所属产品ID",
 "resultcode":"升级任务查询结果代码",
 "id":"自动升级任务ID",
 "name":"升级任务名称",
 "description":"描述",
 "from_version":"起始版本号",
 "from_version_url":"起始版本文件地址",
 "from_version_md5":"起始版本文件MD5",
 "from_version_size":"起始版本文件大小",
 "target_version":"目标版本号",
 "target_version_url":"目标版本文件地址",
 "target_version_md5":"目标版本文件MD5",
 "target_version_size":"目标版本文件大小",
 "upgrade_count":"已升级设备数量",
 "status":"任务状态",
 "type":"固件类型",
 "identify":"用来定位多MCU或多子设备的情况"
}

字段	类型	是否必须	说明
msg_id	整形	是	消息ID
mac	字符串	是	设备MAC地址。注意：在Zigbee网关中，是Zigbee设备的Eui值。
product_id	字符串	是	设备所属产品ID。其具体获取方式见附录说明
resultcode	整形	是	上报结果，0：成功，1：失败
id	字符串	是	自动升级任务ID
name	字符串	是	自动升级任务名称，32个字符以内
description	字符串	是	描述，250个字符以内
from_version	整形	是	起始版本号，32位整形
from_version_url	字符串	是	起始版本文件地址
from_version_md5	字符串	是	起始版本文件MD5值
from_version_size	整形	是	起始版本文件大小
target_version	整形	是	目标版本文件号
target_version_url	字符串	是	目标版本文件地址
target_version_md5	字符串	是	目标版本文件MD5
target_version_size	整形	是	目标版本文件大小
upgrade_count	整形	是	已升级设备数量
status	整形	是	任务状态：0：停止状态，1：启动状态，默认为停止状态。
type	整形	是	升级任务类型，见附录 4.6，默认为wifi

19. 上报升级结果

说明:
PTP升级成功之后，发送消息给XCG报告最新的设备版本等信息。
方向:
PTP -> XCG
Topic:
$xlink/ptp/{ptp_id}/firmware/report

Payload

json

{
 "msg_id":"消息ID",
 "mac":"设备mac",
 "product_id":"设备所属产品ID",
 "type":"升级任务类型",
 "mod":"固件型号",
 "identify":"用来定位多MCU或多子设备的情况",
 "last_version":"升级前version",
 "current_version":"升级后version",
 "result":"升级结果, 0:成功, 1:失败",
 "desc":"升级状况描述",
 "start_date":"升级开始时间",
 "end_date":"升级结束时间"
}

字段	类型	是否必须	说明
msg_id	整形	是	消息ID
mac	字符串	是	设备MAC地址。注意：在Zigbee网关中，是Zigbee设备的Eui值。
product_id	字符串	是	设备所属产品ID。其具体获取方式见附录说明
type	整形	是	升级任务类型，见附录 4.6，默认为wifi
mod	整形	是	固件型号
identify	整形	是	用来定位多MCU或多子设备的情况，type若为"wifi"，identify设置为0
last_version	整形	是	升级前version
current_version	整形	是	升级后version
result	整形	是	升级结果，0：成功，1：失败
desc	字符串	否	升级状况描述
start_date	字符串	否	升级开始时间，例：`2015-10-09T08:15:40.843Z`
end_date	字符串	否	升级结束时间，例：`2015-10-09T08:15:40.843Z`

20. 停止搜索子设备

说明:
XCG通过PTP通知Zigbee协调器停止新设备发现状态
此协议会广播给所有的PTP连接
方向:
XCG -> PTP
Topic:
$xlink/ptp/{ptp_id}/device/stopsearch
注意: ptp_id是PTP进程的唯一ID，具体生成方式见后面附录说明。
Payload
无

21. 网关地址切换

说明:
XCG通过PTPO（Protocol Transform Processor Operation）通知PTP切换网关地址。
切换结果，通过Topic:运维操作通用结果应答应答。
方向:
XCG -> PTPO
Topic:
$xlink/ptpo/{ptp_id}/switch

Payload

json

{
 "msg_id":"消息ID",
 "mac":"设备mac",
 "product_id":"设备所属产品ID",
 "ip":"新的网关IP地址",
 "port":"新的网关端口"
}

字段	类型	是否必须	说明
msg_id	整形	是	消息ID
mac	字符串	是	设备MAC地址。注意：在Zigbee网关中，是Zigbee设备的Eui值。
product_id	字符串	是	设备所属产品ID。其具体获取方式见附录说明
ip	字符串	是	网关IP地址
port	整形	是	网关端口

22. 运维操作通用结果应答

说明:
PTPO（Protocol Transform Processor Operation）在完成一个设备状态改变后，进行应答。
方向:
PTPO -> XCG
Topic:
$xlink/ptpo/{ptp_id}/optresult

Payload

json

{
 "msg_id":"消息ID",
 "mac":"设备mac",
 "code":"结果值",
 "desc":"结果描述"
}

字段	类型	是否必须	说明
msg_id	整形	是	消息ID
mac	字符串	否	设备MAC地址。注意：在Zigbee网关中，是Zigbee设备的Eui值。
code	整形	是	结果值，具体结果定义见附录 4.10
desc	字符串	否	可选的消息描述

23. PTPO保持在线

说明:
PTPO向XCG发送一条topic，申明自己在线
约定：当PTPO第一次连接上MQTT服务后，第一条发布的Topic应该是此Topic。
方向:
PTPO -> XCG
Topic:
$xlink/ptpo/{ptp_id}/ptpo_keepalive

Payload

json

{
 "interval":"间隔时间，单位秒"
}

字段	类型	是否必须	说明
interval	整形	是	PTP保持在线，本次keepalive和下次keepalive包将要间隔的时间，单位秒。最小3秒，最大不超过180秒（3分钟）。若2个间隔时间内没收到keepalive topic，XCG会认为该PTPO实例离线。

24. 运维事件通知

说明:
PTPO（Protocol Transform Processor Operation）通知网关发生运维事件。
方向:
PTPO -> XCG
Topic:
$xlink/ptpo/{ptp_id}/optevent

Payload

json

{
 "eventcode":"事件代码",
 "param1":"参数1"
}

字段	类型	是否必须	说明
eventcode	整形	是	事件代码，具体定义见附录 4.5
param1	字符串	否	可选参数1

25. 运维功能调用

说明:
XCG通过PTPO（Protocol Transform Processor Operation）通知PTP执行功能调用。
执行结果，通过Topic:运维操作通用结果应答应答。
方向:
XCG -> PTPO
Topic:
$xlink/ptpo/{ptp_id}/optcall

Payload

json

{
 "msg_id":"消息ID",
 "mac":"设备mac",
 "product_id":"设备所属产品ID",
 "param1":"参数1",
 "param2":"参数2",
 "callcode":"功能代码"
}

字段	类型	是否必须	说明
msg_id	整形	是	消息ID
mac	字符串	是	设备MAC地址。注意：在Zigbee网关中，是Zigbee设备的Eui值。
product_id	字符串	是	设备所属产品ID。其具体获取方式见附录说明
param1	字符串	否	可选参数1
param2	字符串	否	可选参数2
callcode	整形	是	功能代码，具体定义见附录文档

26. 升级结果上报的结果

说明:
XCG发送消息给PTP 关于升级结果上报的结果
方向:
XCG->PTP
Topic:
$xlink/ptp/{ptp_id}/firmware/report/result
Payload
json
```
{
 "msg_id":消息ID,
```

"mac":"设备mac", "product_id":"设备所属产品ID", "resultcode":"升级上报结果代码", "startdate":"升级结果上报的升级开始时间" }


| 字段       | 类型   | 是否必须 | 说明                                                           |
| :--------- | :----- | :------- | :------------------------------------------------------------- |
| msg_id     | 整形   | 是       | 消息ID                                                         |
| mac        | 字符串 | 是       | 设备MAC地址。 **注意** ：在Zigbee网关中，是Zigbee设备的Eui值。 |
| product_id | 字符串 | 是       | 设备所属产品ID。其具体获取方式见附录说明                       |
| resultcode | 整形   | 是       | 上报结果，0：成功，1：失败                                     |
| startdate  | 字符串 | 是       | 升级结果上报的升级开始时间, 例：2015-10-09T08:15:40.843Z       |

### 27. 网关事件通知

- **说明**:

  > XCG通过PTPO（Protocol Transform Processor Operation）通知PTP网关事件。

- **方向**:

  > XCG->PTPO

- **Topic**:

  > `$xlink/ptpo/{ptp_id}/gwevent`

- **Payload**

  ```json
  {
     "gwcode":网关事件代码,
   "param1":"参数1"
  }

字段	类型	是否必须	说明
gwcode	整形	是	网关事件代码，具体定义见附录文档
param1	字符串	否	可选参数1

四、附录

4.1. 设备状态

值	说明
0	默认状态,当前未返回有参考意义的状态值,请勿依赖此状态值
1	设备在线
2	未知
3	设备无响应
4	设备离开(即未入网或已退网)
5	设备被踢
6~15	预留

4.2、PTP的相关数据

1. PTP ID

PTP ID是PTP程序与XCG之间的唯一的标志ID，约定以"ptp_16个随机字符"来定义。

2. PTP默认连接网关MQTT服务端口

PTP默认连接网关机器（本机为127.0.0.1）的23883端口作为MQTT Topic的收发地址。

4.3、Zigbee与物联云平台

1. Zigbee网关下挂子设备类型与物联云平台产品的关系

Zigee网关下挂的子设备由于具有Zigbee HA的DeviceType类型（ 也就是HA Profile的Device ID ），在物联云平台中针对这些类型的产品，预先定义了多种产品。
每种产品都有既定的数据端点配置，用来对应Zigbee HA Device的属性。物联云平台以及APP通过操作这些数据端点，用来控制实际的Zigbee设备。
产品ID与DeviceType的对应关系，可以预制在脚本中，也可以通过云端进行配置同步。

2. Zigbee设备的MAC地址以及物联云平台的DeviceID

物联云平台定位一个设备依靠从平台下发全局唯一的设备ID（DeviceID），也通过ProductID和MAC（Machine Address Code）值定位一个设备。
在Zigbee网关场景下，Zigbee设备会有一个Unique ID，我们将这个Unique ID作为在物联云平台中的设备MAC值使用。
子设备通过Xlink Core Gateway激活后获取到的DeviceID，存储在Xlink Core Gateway中，不会传递给PTP程序，PTP程序也无需关心。
当用户需要从云端控制一个Zigbee下子设备，就直接操作这个子设备对应的DeviceID即可。

3. Zigbee子设备在物联云平台的上线

当一个子设备加入到Zigbee网络，通过topic通知到网关后，XCG直接将这个设备在物联云端激活。
当子设备通过SYNC topic将状态通知给XCG后，XCG会通过具体的“state”值，将子设备在云端的状态设置为“在线”或者“离线”。

4.4. 数据端点数据类型

值	说明
-1	未知
0	单字节(无符号)
1	16位短整型（有符号）
2	16位短整型（无符号）
3	32位整型（有符号）
4	32位整型（无符号）
5	64位整型（有符号）
6	64位整型（无符号）
7	浮点（单精度）
8	浮点（双精度）
9	字符串
10	字节数组（base64编码）
11	布尔类型

4.5. 运维事件代码

值	说明
0	重置清除所有子设备信息，并重启服务
1	设置为主网关模式
2	配置为从网关模式
3	配置为单网关模式
4	准备升级，停止服务

4.6. 功能代码

值	说明
1	执行升级
2	更新升级参数，其中param1是pkey，param2是deviceid和当前固件版本
3~255	预留

4.7. 硬件类型

值	说明
1	LED指示灯
2	按钮

4.8. 网关事件代码

值	说明
0	网关初始
1	网关云端在线，param1是网关MAC地址
2	网关云端离线，param1是网关MAC地址
3	网关正进行云端连接中，param1是网关MAC地址
4	网关停止，param1是网关MAC地址
5	云端时间同步， param1作为时间参数，格式参考4.9节
6	PTP心跳超时，XCG移除PTP通知。param1是PTPID
7	PTPO心跳超时，XCG移除PTPO通知。param1是PTPID
8	网关数据端点模板获取成功，param1是网关MAC地址

4.9. 时间同步格式

时间格式：“yyyyMMdd hh:mm :ss|zone”。其中zone表示时区，有符号。时区的表示方式为GMT方式；如：GMT +0800，那么时区的值为800，如果时区为－0530，则时区的值为－530。例子：“20180324 09:23 :51|800”。

4.10 操作通用结果应答结果值

值	说明
0	操作成功
1~5000	预留
5001~65535	自定义

五、常见问题

哪些 CPU 架构和操作系统与Xlink Core Gateway兼容？
支持ARM、MIPS和X86架构，Embedded Linux、Android、PC等运行环境。
是否支持连接到自己开发的云平台
物联云平台可向核心客户和战略级合作伙伴开放Xlink Core Gateway的云端通信协议，以便于您接入自己开发的云平台。

APP 开发

APP SDK集成

C端APP集成

X-PTP通信协议说明 ​

一、概述 ​

二、Xlink Core Gateway ​

二、Xlink PTP ​

三、XCG与X-PTP的通信协议 ​

1. 子设备列表 ​

2. 搜索子设备 ​

3. 子设备加入 ​

4. 删除子设备 ​

5. 子设备状态改变 ​

6. 改变子设备状态 ​

7. 子设备发布物属性 ​

8. 子设备物模型事件上报 ​

9. 子设备物模型服务调用 ​

10. 子设备物模型服务调用返回结果 ​

15. PTP发送自定义数据到XCG ​

16. XCG发送自定义数据到PTP ​

17. 查询最新的升级任务 ​

18. 查询最新的升级任务结果 ​

19. 上报升级结果 ​

20. 停止搜索子设备 ​

21. 网关地址切换 ​

22. 运维操作通用结果应答 ​

23. PTPO保持在线 ​

24. 运维事件通知 ​

25. 运维功能调用 ​

26. 升级结果上报的结果 ​

四、附录 ​

4.1. 设备状态 ​

4.2、PTP的相关数据 ​

1. PTP ID ​

2. PTP默认连接网关MQTT服务端口 ​

4.3、Zigbee与物联云平台 ​

1. Zigbee网关下挂子设备类型与物联云平台产品的关系 ​

2. Zigbee设备的MAC地址以及物联云平台的DeviceID ​

3. Zigbee子设备在物联云平台的上线 ​

4.4. 数据端点数据类型 ​

4.5. 运维事件代码 ​

4.6. 功能代码 ​

4.7. 硬件类型 ​

4.8. 网关事件代码 ​

4.9. 时间同步格式 ​

4.10 操作通用结果应答结果值 ​

五、常见问题 ​

X-PTP通信协议说明

一、概述

二、Xlink Core Gateway

二、Xlink PTP

三、XCG与X-PTP的通信协议

1. 子设备列表

2. 搜索子设备

3. 子设备加入

4. 删除子设备

5. 子设备状态改变

6. 改变子设备状态

7. 子设备发布物属性

8. 子设备物模型事件上报

9. 子设备物模型服务调用

10. 子设备物模型服务调用返回结果

15. PTP发送自定义数据到XCG

16. XCG发送自定义数据到PTP

17. 查询最新的升级任务

18. 查询最新的升级任务结果

19. 上报升级结果

20. 停止搜索子设备

21. 网关地址切换

22. 运维操作通用结果应答

23. PTPO保持在线

24. 运维事件通知

25. 运维功能调用

26. 升级结果上报的结果

四、附录

4.1. 设备状态

4.2、PTP的相关数据

1. PTP ID

2. PTP默认连接网关MQTT服务端口

4.3、Zigbee与物联云平台

1. Zigbee网关下挂子设备类型与物联云平台产品的关系

2. Zigbee设备的MAC地址以及物联云平台的DeviceID

3. Zigbee子设备在物联云平台的上线

4.4. 数据端点数据类型

4.5. 运维事件代码

4.6. 功能代码

4.7. 硬件类型

4.8. 网关事件代码

4.9. 时间同步格式

4.10 操作通用结果应答结果值

五、常见问题