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

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

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

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

3. 子设备加入

说明:
- 当一个设备加入到网络以后，通知给XCG。
方向:
- PTP -> XCG
Topic:

$xlink/ptp/{ptp_id}/device/new

Payload

{
   "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:[子设备操作通用结果应答](3）Xlink IoT Gateway X-PTP协议.md)应答；
方向:
- XCG->PTP
Topic:

$xlink/ptp/{ptp_id}/device/delete

Payload

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

{
   "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:[子设备操作通用结果应答](3）Xlink IoT Gateway X-PTP协议.md)应答；
方向:
- XCG->PTP
Topic:

$xlink/ptp/{ptp_id}/device/set

Payload

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

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

字段	类型	是否必须	说明
mac	字符串	是	设备MAC地址。注意：在Zigbee网关中，是Zigbee设备的Eui值。
product_id	字符串	是	设备所属产品ID。其具体获取方式见附录说明
state	整形	是	设备状态
attribute	对象	否	设备改变的物属性
attribute.time	字符串	否	时间戳。格式为毫秒级utc时间戳，示例：“1616404559000”。
attribute.v	字符串	否	物模型版本号，当前值为”2.0”
attribute.extra	Object	是	物模型属性对象，例如：”extra”:{ “PowerSwitch”:0,”Status”: true }

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

说明:
- 当子设备物模型事件改变以后，通过PTP通知到XCG。
方向:
- PTP -> XCG
Topic:

$xlink/ptp/{ptp_id}/device/thing/event/{event_name}/report

Payload

{
   "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	是	物模型事件对象，例如：”extra”:{ “code”:0,”message”: “OK” }

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

说明:
- XCG发送消息给PTP调用子设备物模型服务
方向:
- XCG->PTP
Topic:

$xlink/ptp/{ptp_id}/device/thing/service/{service_name}/invoke

Payload

{
   "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	是	物模型服务输入参数，例如：”input”:{ “code”:0,”message”: “OK” }
service.v	字符串	否	物模型版本号，当前 “2.0”

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

说明:
- 子设备物模型服务调用返回结果通过PTP通知到XCG。
方向:
- PTP -> XCG
Topic:

$xlink/ptp/{ptp_id}/device/thing/service/{service_name}/invoke/result

Payload

{
   "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.oupput	Object	是	物模型服务返回参数对象，例如”output”:{ “code”:0,”message”: “OK” }

11. 子设备离开

说明:
- 当设备由于什么原因，从Zigbee网络离开，Zigbee协调器会通知PTP，PTP再通知XCG
方向:
- PTP -> XCG
Topic:

$xlink/ptp/{ptp_id}/device/left

Payload

{
 "mac":"设备mac",
 "product_id":"设备所属产品ID"
}

12. 子设备操作通用结果应答

说明:
- PTP在完成一个设备状态改变后，进行应答。
方向:
- PTP -> XCG
Topic:

$xlink/ptp/{ptp_id}/device/optresult

Payload:

{
 "msg_id":消息ID
 "mac":"设备mac",
 "product_id":"设备所属产品ID",
 "code":结果值,
 "desc":"结果描述"
}

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

13. 获取设备列表信息

说明:
- XCG向PTP发送一条TOPIC，强制PTP向XCG发送两条Topic
  - $xlink/ptp/{ptp_id}/devices
  - $xlink/ptp/{ptp_id}/device/sync
- 其中sync中会带着所有的设备，以及其datapoint值
方向:
- XCG -> PTP
Topic:

$xlink/ptp/{ptp_id}/devices_public

Payload
```
{
 "code": 获取代码
}
```

字段	类型	是否必须	说明
code	整形	否	0-只获取设备列表 1-强制所有子设备上报数据端点

14. PTP保持在线

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

$xlink/ptp/{ptp_id}/ptp_keepalive

Payload:


{
 "interval":间隔时间，单位秒,
    "mac":"网关mac",
    "address":"网关IP地址"
}

字段	类型	是否必须	说明
interval	整形	是	PTP保持在线，本次keepalive和下次keepalive包将要间隔的时间，单位秒。最小3秒，最大不超过180秒（3分钟）。若2个间隔时间内没收到keepalive topic，XCG会认为该PTP实例离线。其下挂接的所有Zigbee设备，也会设置为离线。
mac	字符串	否	主网关或子网关MAC地址。
address	字符串	否	主网关或子网关IP地址。

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

说明
- PTP发送一条自定义数据到XCG
方向
- PTP -> XCG
Topic

$xlink/ptp/{ptp_id}/ptp_custom_msg

Payload

{
 "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}/cg_custom_msg

Payload

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

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

17. 查询最新的升级任务

说明:
- PTP发送消息给XCG查询最新的升级任务
- 查询结果结果，通过Topic:[查询最新的升级任务结果](3）Xlink IoT Gateway X-PTP协议.md)应答；
方向:
- PTP->XCG
Topic:

$xlink/ptp/{ptp_id}/firmware/check

Payload

{
 "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.4升级任务类型, 默认为wifi
current_version	整形	是	设备当前版本
identify	整形	是	用来定位多MCU或多子设备的情况，type若为”wifi”，identify设置为0。

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

说明:
- XCG发送消息给PTP查询到的最新的升级任务的结果
方向:
- XCG->PTP
Topic:

$xlink/ptp/{ptp_id}/firmware/check/result

Payload

{
 "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.4升级任务类型, 默认为wifi

19. 上报升级结果

说明:
- PTP升级成功之后，发送消息给XCG报告最新的设备版本等信息。
方向:
- PTP->XCG
Topic:

$xlink/ptp/{ptp_id}/firmware/report

Payload

{
 "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.4升级任务类型, 默认为wifi
current_version	整形	是	设备当前版本
identify	整形	是	用来定位多MCU或多子设备的情况，type若为”wifi”，identify设置为0。
type	整形	是	升级任务类型
mod	整形	是	固件型号
identify	整形	是	用来定位多MCU或多子设备的情况
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:[运维操作通用结果应答](3）Xlink IoT Gateway X-PTP协议.md)应答。
方向:
- XCG->PTPO
Topic:

$xlink/ptpo/{ptp_id}/switch

Payload

{
   "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:


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

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

23. PTPO保持在线

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

$xlink/ptpo/{ptp_id}/ptpo_keepalive

Payload:

{
 "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:

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

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

25. 运维功能调用

说明:
- XCG通过PTPO（Protocol Transform Processor Operation）通知PTP执行功能调用。
- 执行结果，通过Topic:[运维操作通用结果应答](3）Xlink IoT Gateway X-PTP协议.md)应答。
方向:
- XCG->PTPO
Topic:

$xlink/ptpo/{ptp_id}/optcall

Payload

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

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

{
   "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的云端通信协议，以便于您接入自己开发的云平台。

上次更新：2024-05-09