电力物联网边缘物联代理接口协议

ICS点击此处添加ICS号

点击此处添加中国标准文献分类号

T/CEC

中国电力企业联合会标准

T/CECXXXXX—XXXX

电力物联网边缘物联代理接口协议

FullserviceubiquitousIOTedgeIOTagentinterfaceprotocol

点击此处添加与国际标准一致性程度的标识

文稿版次选择

XXXX-XX-XX发布XXXX-XX-XX实施

中国电力企业联合会发布

T/CECXXXXX—XXXX

前言

本文件按照GB/T1.1—2020《标准化工作导则第1部分：标准化文件的结构和起草规则》的规定起

草。

请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别这些专利的责任。

本文件由中国电力企业联合会提出。

本文件由电力行业信息标准化技术委员会（DL/TC27）归口。

本文件起草单位：

本文件主要起草人：。

本文件首次发布。

本文件在执行中的意见或建议反馈至中国电力企业联合会标准化管理中心（北京市宣武区白广路二

条一号，100761）。

II

T/CECXXXXX—XXXX

电力物联网边缘物联代理接口协议

1范围

本文件规定了电力物联网边缘物联代理（以下简称“边设备”）与物联管理平台之间交互协议的功

能、主题、报文格式等技术要求。

本文件适用于电力物联网边设备交互协议的设计、开发、检验和验收。

2规范性引用文件

下列文件对于本文件的应用是必不可少的。凡是注日期的引用文件，仅所注日期的版本适用于本文

件。凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。

GB/T22239信息安全技术网络安全等级保护基本要求

GB/T33745—2017物联网术语

IEEE802.1ARIEEE本地和城域网标准-安全设备标识（IEEEStandardforLocaland

metropolitanareanetworks-SecureDeviceIdentity）

IEEE1588-2008用于网络测量与控制系统的精确时钟同步协议（StandardforaPrecisionClock

SynchronizationProtocolforNetworkedMeasurementandControlSystems）

MQTTV31MQTTV3.1协议规范（MQTTV3.1ProtocolSpecification）

RFC793传输控制协议（TransmissionControlProtocol.STD7,IETFRFC793）

RFC3629UTF-8，ISO10646的转换格式（UTF-8,atransformationformatofISO10646）

RFC6455WebSocket协议（TheWebSocketProtocol）

3术语和定义

《GB/T33745—2017物联网术语》界定的以及下列术语和定义适用于本文件。

4缩略语

下列缩略语适用于本文件。

IP：互联网协议（InternetProtocol）

ISO：国际标准化组织（InternationalOrganizationforStandardization）

JSON：JS对象描述（JavaScriptObjectNotation）

MQTT:消息队列遥测传输（MessageQueuingTelemetryTransport）

NB-IoT：窄带物联网（NarrowBandInternetofThings）

OSI：开放系统互联（OpenSystemInterconnection）

QoS：服务质量（QualityofService）

TCP：传输控制协议（TransmissionControlProtocol）

4G：第4代移动通信（The4thGenerationMobileCommunication）

1

T/CECXXXXX—XXXX

5G：第5代移动通信（The5thGenerationMobileCommunication）

5总体要求

5.1通信架构

边设备与物联管理平台经过安全接入网关，使用MQTT和HTTP协议进行通信交互。其中，常规的管理

数据、业务数据交互通过MQTT进行通信，HTTP仅用于应用下发等文件传输场景，即除非特指，默认的通

信协议为MQTT。使用MQTT和HTTP协议的通信架构如图1所示。

物联管理平台

MQTT/HTTPMQTT/HTTP

（管理数据、业务数据）（管理数据、业务数据）

安全接入网关

边设备边设备

子设备子设备子设备子设备

图1通信架构

5.2协议结构

边设备与物联管理平台之间所采用的MQTT和HTTP通信协议在OSI七层体系中所属位置以及协议栈数

据结构，如表1所示。

表1通信协议规约结构

协议名称对应OSI层次

MQTT、HTTP

应用层（第7层）

SSL、SSAL

TCP传输层（第4层）

IP网络层（第3层）

数据链路层（第2层）

802.3、4G/5G、NB-IoT等协议

物理层（第1层）

注：OSI第5，第6层未用。

2

T/CECXXXXX—XXXX

5.3通用要求

边设备与物联管理平台基于MQTT协议以下类型的控制报文进行连接的维护：其中基于CONNECT/

CONNACK控制报文建立MQTT连接；基于PINGREQ/PINGRESP保活MQTT连接；基于DISCONNECT控制报文断开

连接。边设备与物联管理平台基于MQTT协议的发布/订阅机制完成两者之间请求/应答报文的交互。控制

报文应满足以下要求：

a)所使用的控制报文应遵循MQTTV3.1ProtocolSpecification的格式要求。

b)PUBLISH控制报文的有效载荷字段的定义应遵循本文件5.4的要求。

c)PUBLISH控制报文的可变报头字段的定义应遵循本文件5.5的要求。

d)如无特殊说明，本文中定义的基于PUBLISH承载的请求/应答报文其QoS级别默认为0。

e)边设备与物联管理平台的交互协议可不通过MQTT协议自带的secure-MQTT提供安全保障，但

应通过下层的SSL、SSAL协议提供客户端身份的认证及传输通道的安全。

5.4协议报文有效载荷格式

5.4.1请求报文

边设备与物联管理平台交互的请求报文均承载在MQTT发布报文的有效载荷中，以JSON格式描述，请

求报文载荷通用字段定义应遵循表2的要求。

表2请求报文有效载荷通用字段定义

字段类型是否必选描述

midnumber否在请求报文中该值为请求

ID，在终端主动上报数据的

报文中该字段可不填写

deviceIdstring否设备唯一标识，涉及批量设

备操作时该字段可不填写

appstring否APP应用名称，涉及批量设

备操作时填写该字段

timestamplong是消息发送的时间戳，CST时

间,精度到秒

expirenumber否此报文过期的相对时间（相

对timestamp），单位秒，不

包含该字段，或者该字段为

-1时表示永不过期

typestring是消息类型，全大写，单词中

间用“_”隔开

paramobject否报文内容，详见本文6中各

节报文定义

5.4.2应答报文

边设备与物联管理平台交互的应答报文均承载在MQTT发布报文的有效载荷中，以JSON格式描述，应

答报文载荷通用字段定义应遵循表3的要求。应答报文载荷中“code”字段的取值应符合表4的要求。

3

T/CECXXXXX—XXXX

表3应答报文有效载荷通用字段定义

字段类型是否必选

midnumber是在应答报文中，该值为应答

所对应请求报文的请求ID

deviceIdstring否设备唯一标识，涉及批量设

备操作时该字段可不填写

timestampstring是消息发送的时间戳，CST时

间，精度到秒

typestring是消息类型,全大写，单词中间

用“_”隔开

paramobject否报文内容，详见各报文定义

codenumber是标识应答的返回码

msgstring否应答结果描述，字符串，最

大256字符

表4应答报文载荷中“code”字段的取值定义

code字段取值描述

200请求成功

202请求被接受，但是服务器未处理完

400请求失败

401请求未认证/认证错误

403请求被拒绝

404请求的资源不存在

408请求超出了服务器的等待时间

500其他错误

5.4.3JSON字段命名规范

报文采用JSON格式描述，对JSON字段命名应遵循以下要求：

a)设备名称采用首字母大写；

b)变量名、属性名第一个单词首字母小写，剩余单词首字母大写；

c)type字段约束如下：

1)为全大写单词，单词中间用下划线分隔开；

2)所有命令以“CMD_”开头；

3)所有上报数据均以“EVENT_”或“REP_”开头；

4)所有应答报文与请求报文字段相同。

d)全部使用英文单词，禁止使用拼音；

e)每个单词长度不宜超10个字符，否则尽量使用简写；

f)单词简写时应尽可能望文知意，以满足易读性为首要选择，其次尽量缩短长度。

4

T/CECXXXXX—XXXX

5.5协议报文可变报头格式

5.5.1边设备与物联管理平台交互采用基于主题的发布/订阅模式进行信息交互。主题承载在发布报文

的可变报头中，主题格式应遵守:/主题版本/边设备或直连设备ID/消息执行类别/消息动作，

/{v1}/{edgeId}/{TopicType}/{TopicCommand}，其中：

a){v1}：表示目前使用的主题版本，当前为v1,后期可发布v2、v3等版本；

b){edgeId}：表示直接与物联管理平台建立MQTT长连接的边设备或直连设备ID；

c){TopicType}：主题的类别，主要有device、container、app、service、topo五种。device

表示该主题为设备类消息，service表示为业务类消息，app表示应用类消息，container表

示容器消息，topo表示端设备消息；

d){TopicCommand}：表示消息的动作如控制、采集的数据、请求或应答。

5.5.2主题的主要内容和用途见表5，其中，方向取值为：up、down。当为up时表示边设备或直连终

端发布由物联管理平台订阅的主题；为down时表示物联管理平台发布由边设备或直连终端订阅的主题。

表5主题内容及用途

主题分类主题内容方向用途

/v1/{edgeId}/device/commanddown用于物联管理平台向边设备发送设备控制命

令，如设备升级、控制设备等

/v1/{edgeId}/device/replyup用于对物联管理平台发送的设备控制命令的

应答

/v1/{edgeId}/device/requestup用于边设备向物联管理平台发送设备管理相

关的请求命令，如请求连接等

设备管理/v1/{edgeId}/device/responsedown用于对边设备发送的设备管理相关的请求命

令的应答

/v1/{edgeId}/device/dataup用于边设备向物联管理平台主动上报设备相

关的状态、事件等

/v1/{edgeId}/topo/requestup用于边设备向物联管理平台发送拓扑信息的

请求命令

/v1/{edgeId}/topo/responsedown用于对边设备发送的拓扑信息的请求命令的

应答

/v1/{edgeId}/container/commanddown用于物联管理平台向边设备发送的容器控制

请求命令，如容器安装、启动、停止等

容器管理/v1/{edgeId}/container/replyup用于对物联管理平台的容器控制请求命令的

应答

/v1/{edgeId}/container/dataup用于边设备向物联管理平台主动上报容器相

关的状态、事件等

/v1/{edgeId}/app/commanddown用于物联管理平台向边设备发送应用控制请

求命令，如应用安装、启动、停止等

应用管理/v1/{edgeId}/app/replyup用于对物联管理平台发送的应用控制请求命

令的应答

/v1/{edgeId}/app/dataup用于边设备向物联管理平台主动上报应用相

关的状态、事件等

5

T/CECXXXXX—XXXX

/v1/{edgeId}/service/commanddown用于物联管理向边设备发送业务交互请求命

令

/v1/{edgeId}/service/replyup用于对物联管理的业务交互请求命令的应答

/v1/{edgeId}/service/dataup用于边设备向物联管理平台主动上报业务相

关的采集数据

业务交互/v1/{edgeId}/service/eventup用于边设备向物联管理平台主动上报业务相

关的事件数据

/v1/{edgeId}/service/requestup用于边设备向物联管理平台发送业务相关的

请求命令

/v1/{edgeId}/service/responsedown用于物联管理平台对边设备转发业务相关的

请求应答

6功能及报文格式

6.1功能概述

边设备与物联管理平台交互的功能应包含设备管理、容器管理、应用管理、业务交互等多个方面。

设备管理包括设备升级、设备控制等。容器管理包括容器安装、升级、启动、停止、删除、配置、状态

查询等。应用管理包括应用下发、应用控制、应用配置、应用升级等。业务交互应包含物模型下发、数

据上报等。

6.2设备管理

6.2.1设备接入

设备接入主要用于边设备的接入及主动断开的操作，包括：设备接入请求、设备接入应答、设备主

动断开上报。

设备接入请求

边设备通过发布主题“/v1/${edgeId}/device/request”消息，向物联管理平台发送设备接入请求

报文，其格式应遵循5.4.1节的规定。报文载荷中包含的字段取值应符合以下要求：

a)type字段：EVENT_LINKUP；

b)param字段定义如表6所示。

表6设备接入请求报文载荷字段定义

字段类型是否必选描述

devobject是边设备信息，详见附录A

cpuobject是CPU信息，详见附录A

memobject是内存信息，详见附录A

diskobject是磁盘信息，详见附录A

osobject是操作系统信息，详见附录A

其他的边设备信息，其中每

linksarray是个元素为一个JSON对象，其

定义详见附录A

6

T/CECXXXXX—XXXX

设备接入应答

物联管理平台对边设备信息进行记录和校验，并通过主题“/v1/${edgeId}/device/response”向

边设备发送设备接入应答报文，其格式应遵循5.4.2节的规定。报文载荷中包含的字段取值应符合以下

要求：

a)type字段：EVENT_LINKUP；

b)param字段：无。

设备主动断开上报

终端因某些原因需要与平台主动断开连接时，可通过主题“/v1/{edgeId}/device/data”向平台发

送主动断开连接请求报文。报文载荷中包含的字段取值应符合以下要求：

a)type字段：EVENT_LINKDOWN；

b)param字段定义如表7所示。

表7设备主动断开连接请求报文载荷字段定义

字段类型是否必选描述

断开原因，如“PowerOff”、

reasonstring是“RebootOS”、“Restart

Link”等

6.2.2设备升级

设备升级是指对设备操作系统及相关固件的升级：物联管理平台下发设备升级命令，边设备接到升

级命令后，先对升级命令应答，之后边设备文件下载和安装。在升级操作完成后，将升级结果上报至物

联管理平台。在升级过程中，物联管理平台可以发送升级状态查询命令，边设备将升级任务实时状态发

给物联管理平台。

设备升级命令

物联管理平台通过主题“/v1/${edgeId}/device/command”向边设备下发设备升级命令，其格式应

遵循5.4.1节的规定。报文载荷中包含的字段取值应符合以下要求：

a)type字段：CMD_SYS_UPGRADE；

b)param字段定义如表8所示。

表8设备升级命令报文载荷字段定义

字段类型是否必选描述

本升级操作作为一个工作任

jobIdnumber是

务，分配的ID

从接收到该升级指令时间后

开始升级的时间间隔（单位：

policynumber否

秒），缺省或等于0时，表示

立即升级

versionstring是升级后的版本号

升级类型，0表示补丁升级，

upgradeTypenumber是

1表示文件系统升级，2表示

7

T/CECXXXXX—XXXX

内核升级，3表示全量升级

（文件系统+内核升级）

fileobject是升级文件信息

设备升级命令应答

边设备在收到升级命令后，通过主题“/v1/${edgeId}/device/reply”向物联管理平台发送设备升

级命令应答报文，其格式应遵循5.4.2节的规定。报文载荷中包含的字段取值应符合以下要求：

a)type字段：CMD_SYS_UPGRADE；

b)param字段：无。

设备升级状态查询

边设备收到升级命令后，开始进行升级操作。在升级过程中，物联管理平台通过主题

“/v1/${edgeId}/device/command”可以查询升级任务的状态。报文载荷中包含的字段取值应符合以下

要求：

a)type字段：CMD_STATUS_QUERY；

b)param字段定义如表9所示。

表9设备升级状态查询报文载荷字段定义

字段类型是否必选描述

升级操作作为一个工作任

jobIdnumber是

务，分配的ID

设备升级状态查询应答

边设备通过主题“/v1/${edgeId}/device/reply”向物联管理平台上报设备升级状态，其格式应遵

循5.4.2节的规定。报文载荷中包含的字段取值应符合以下要求：

a)type字段：CMD_STATUS_QUERY；

b)param字段定义如表10所示。

表10设备升级状态查询应答报文载荷字段定义

字段类型是否必选描述

progressnumber是进度。百分比，省略百分号

描述当前升级过程执行过

程。包括：

1：待下载

statenumber是2：下载中

3：待安装

4：安装中

5：安装完毕

升级操作作为一个工作任

jobIdnumber是

务，分配的ID

设备升级结果上报

8

T/CECXXXXX—XXXX

当设备升级指令执行完毕后，边设备将执行结果通过主题“/v1/${edgeId}/device/data”主动上

报给物联管理平台。报文载荷中包含的字段取值应符合以下要求：

a)type字段：REP_JOB_RESULT；

b)param字段定义如表11所示。

表11设备升级结果上报报文载荷字段定义

字段类型是否必选描述

升级操作作为一个工作任

jobIdnumber是

务，分配的ID

codenumber是升级结果编码

升级结果的描述，例如下载

msgstring否

地址不可用

6.2.3设备监视

设备监视是指对设备运行状态、设备事件、设备日志进行监视以及对设备配置参数进行管理的功能，

包括：设备状态查询、设备信息查询、设备配置参数修改、设备日志召回等。

设备运行参数主动上报

边设备通过主题“/v1/${edgeId}/device/data”向物联管理平台上报设备实时运行参数。memUsed

字段为object，描述内存的信息，其各字段定义应符合表13要求。linkState字段为数组类型，每个成

员描述了一个外接设备的相关信息，字段定义如表14所示。报文载荷中包含的字段取值应符合以下要求：

a)type字段：REP_SYS_STATUS；

b)param字段定义如表12所示。

表12设备运行参数上报报文载荷字段定义

字段类型是否必选描述

cpuRatenumber是CPU负载（例如50表示50%）

memUsedobject是内存信息

磁盘占用总空间，以M为单

diskUsednumber是

位

主板（cpu）温度，单位：摄

tempValuenumber是

氏度℃

devDateTimestring是设备当前时间

devStDateTimestring是设备最近一次启动时间

devRunTimenumber是设备运行时长，单位：秒

其他的设备信息，其中每个

linkStatearray是

元素表示一类设备元素

longitudestring否地理位置信息经度

latitudestring否地理位置信息经度

表13memUsed字段定义

9

T/CECXXXXX—XXXX

字段类型是否必选描述

占用的物理内存（例如50

phynumber是

表示50%）

占用的虚拟内存（例如50

virtnumber否

表示50%）

表14linkState字段定义

字段类型是否必选描述

接口的名称如为以太网口，

namestring是

则形如“eth1”

statusstring是设备接口状态，如up/down

设备运行参数查询

物联管理平台通过主题“v1/{edgeId}/device/command”发布设备运行参数查询命令。报文载荷中

包含的字段取值应符合以下要求：

a)type字段：CMD_SYS_STATUS；

b)param字段：无。

设备运行参数查询应答

边设备通过主题“v1/{edgeId}/device/reply”对物联管理平台发布的设备运行参数查询命令进行

应答。报文载荷中包含的字段取值应符合以下要求：

a)type字段：CMD_SYS_STATUS；

b)param字段的定义应遵循表12、13、14的要求。

设备软、硬件信息查询

物联管理平台通过主题“/v1/{edgeId}/device/command”发布设备信息查询命令，对边设备的软

硬件信息进行查询。报文载荷中包含的字段取值应符合以下要求：

a)type字段：CMD_INFO_QUERY；

b)param字段：无。

设备软、硬件信息查询应答

边设备通过主题“v1/{edgeId}/device/reply”对物联管理平台发布的设备信息查询命令进行应答。

报文载荷中包含的字段取值应符合以下要求：

a)type字段：CMD_INFO_QUERY；

b)param字段的定义应遵循表15的要求。

表15设备信息查询应答报文载荷字段定义

字段类型是否必选描述

devobject是边设备信息，详见附录A

cpuobject是CPU信息，详见附录A

memobject是内存信息，详见附录A

diskobject是磁盘信息，详见附录A

10

T/CECXXXXX—XXXX

temperatureobject否温度监控信息

osobject是操作系统信息，详见附录A

其他的边设备信息，其中每

linksarray是个元素表示一类设备元素，

详见附录A

repPeriodobject否主动上报的上报时间间隔

temperature字段为object类型，描述温度监控信息，其字段定义应符合表16要求。

表16temperature字段定义

字段类型是否必选描述

tempnumber否主板温度，单位℃

temLownumber是主板温度监控低温阈值

temHighnumber是主板温度监控高温阈值

repPeriod字段为object类型，其各字段定义如表17所示。

表17repPeriod字段定义

字段类型是否必选描述

终端状态主动上报的时间间

devPeriodnumber否

隔，单位：秒

容器状态主动上报的时间间

conPeriodnumber否

隔，单位：秒

APP状态主动上报的时间间

appPeriodnumber否

隔，单位：秒

注：上述表中字段应所至少出现一个。

设备配置参数修改

物联管理平台通过主题“v1/{edgeId}/device/command”发布边设备配置修改命令。报文载荷中包

含的字段取值应符合以下要求：

a)type字段：CMD_SYS_SET_CONFIG；

b)param字段定义应符合表18的要求。

表18设备配置参数修改命令报文载荷字段定义

字段类型是否必选描述

devNamestring否设备名称

CPU监控阈值，例如50表示

cpuLmtnumber否

50%