能源控制器APP接口及开发规范

能源控制器

APP接口及开发规范

二。二O年六月

目录

1范围...................................................................................3

2规范性引用文件..........................................................................3

3术语和定义..............................................................................3

4App框架概述...........................................................................3

5App通信架构...........................................................................4

6App消息模型...........................................................................6

7App接入规范..........................................................................11

8App设计方案..........................................................................13

9App消息接口标识......................................................................17

附录A（规范性附录）App消息接口定义...............................................22

附录B（规范性附录）访问交采数据的约定............................................49

附录C（规范性附录）透明任务结果的存储............................................52

附录D（规范性附录）电能表事件上报流程............................................53

附录E（规范性附录）桌面显示实现的约定............................................58

附录F（规范性附录）消息举例.......................................................59

能源控制器APP接口及开发规范

1范围

本标准规定了能源控制器APP接口以及APP的开发规范。

本标准适用于用能源控制器［以下简称“终端”）中APP之间的通信数据交换。

2规范性引用文件

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

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

GB/T16262.1-2006信息技术抽象语法记法（ASN.1）第1部分基本记法规范

GB/T17966—2000微处理器系统的二进制浮点运算

DL/T790.6-2010采用配电线载波系统的配电自动化第6部分A-XDR编码规则

3术语和定义

ASN.1

AbstractSyntaxNotationOne,一种ISO/ITU-T标准，描述了一种对数据进行表示、编

码、传输和解码的数据格式。

A-XDR

AbstractexternalDataRepresentation,抽象的外部数据表示。

MQTT

MessageQueuingTelemetryTransport»消息队列遥测传输。ISO标准（ISO/IECPRF20922）

下基于发布/订阅范式的消息协议。它工作在TCP/IP协议族上，是为硬件性能低下的远

程设备以及网络状况糟糕的情况下而设计的发布/订阅型消息协议，需要一个消息中间

件。

4App框架概述

基于统一终端平台的App,使用消息总线框架,App之间的交互全部通过消息总线进行。

消息驱动支持IPC（Inter-ProcessCommunication,进程间通信）、TCP、UDP、MQTT等多

种模式，可根据系统资源及运行环境灵活剪裁仅支持其中一种或多种。基于本消息总线架构，

App需符合消息驱动规范，方可接入系统，消息驱动规范见下文描述。

系统管理器，负责所有用户App以及其他系统级App的接入以及管理。系统管理器具

有软、硬件看门狗双重保护，异常可自动恢复。其他A即的生命周期，由系统管理器的保

活机制负责监控并管理。

用户App

消息总线

系统App

系统管理器

图1消息框架

5App通信架构

5.1信息交换模型

5.1.1概述

图2消息交换模型

App之间的数据交换借助于消息实现。消息的传输可支持IPC、TCP、UDP或MQTT

等方式。由服务提供方（服务器角色）定义消息接口，服务使用方（客户机角色）根据定义

的消息接口访问相应的服务。一个App既可以是服务提供方，同时乜可以是某些服务的使

用方，同时具有服务器与客户机多重角色。

5.1.2消息的优先级

在本消息通信框架中，消息队列带有优先级机制，确保高优先级消息可以优先处理，应

对某曲对时效性要求高的操作。优先级数组越小，表示优先级越高，0为最高优先级。

阳：笛品讷闽

图3消息队列

5.1.3同步消息

发送程序首先向接收程序发起一个请求（发送消息），发送程序紧接着就会堵塞它自身

的进程，直到收到接收程序的响应。发送程序在收到响应后会继续向下进行处理。同步方

式的请求/响应通信如下图所示。

发送程序接收程序

图4同步消息模型

5.1.4异步消息

当使用异步消息传送时，调用者在发送消息以后可以不用等待响应，可以接着处理其

他任务。对于异步通信，一个应用程序（请求者或发送者）将请求发送给另一个应用程序，

然后可以继续向下执行它自身的其他任务。发送程序无须等待接收程序的执行和返回结果,

而是可以继续处理其他请求。

1.服求

r|二＞2后续处理［一

图5异步消息模型

5.2请求/响应类型的数据交换

该数据交换模型支持App的客户机进程，向其他App的服务器应用进程提出服务请求,

服务器应用进程向客户机应用进程提供服务响应。

客户机应用服务器应用

服务请求

客户机服务器

--------------------服务响应-------------------------

图6请求/响应模式的消息交换

5.3通知类型的数据交换

该数据交换模型支持App的服务器进程向其他App的客户机应用进程发出通知，同时

不需要客户机应用进程确认。

服务器应用客户机应用

图7通知模式的消息交换

6App消息模型

6.1消息驱动

6.1.1点对点通信

点对点通信模式，不需要系统管理器参与消息路由，App互相之间可直接点对点通信。

此种模式适用于App基于IPC或UDP驱动方式。基于IPC驱动的App,必须位于同一

主机内。基于UDP驱动的App无此限制，可位于任意具有独立IP地址的设备内（容器或

其他智能终端或计算机）。

示意图如下：

6.1.2路由转发

需要系统管理器参与消息路由，App互相之间不可以直接通信。

此种模式适用于任意异构驱动模式App之间的互相通信，或基于TCP驱动方式的App

之间互相通信。系统管理器内置TCP服务器，其他采用TCP驱动的App为客户机。

示意图如下：

图9路由转发消息驱动

6.1.3MQTT

基于MQTT模式，由系统内置MQTTBroker充当消息中心角色，完成消息转发。MQTT

主题规则：消息发送方名称/消息接收方名称，接收方名称为“Broadcast”表示广播。

V_____________________________T

图10MQTT消息驱动

6.2消息结构定义

图11消息帧组成

字段/位域76513210长度格式定义

1PRIORITYPRM1BIN

2INDEX2BIN

3LABEL2BINHEAD

4SOURCE（以0结尾）NASCII

5DESTINATION(以0结尾)NASCII

6MSG，s-TAG4BIN

7MSG,s-LengthNA-XDRMSG

8MSG's-PayloadNA-XDR

图12消息帧结构定义

PRM：启动标志位（PRM=1,表示启动）；

PRIORITY：优先级（数值越小优先级越高，。为最高优先级）；

INDEX：消息序号（从0循环递增,响应消息同请求消息保持一致）;

LABEL：消息标签（发送方附加标签，响应时带回）；

SOURCE：消息发送方名称，字符串，以0结尾，命名规范见7.2；

DESTINATION：消息接收方名称，字符串，以0结尾，命名规范见7.2；

MSG,s—TAG：消息接口ID（消息接口定义见9）；

MSG's—Length：消息有效载荷长度，采用可变长度编码（A-XDR）；

MSG's—Payload：有效载荷，即消息数据单元（定义见附录

6.3字节格式

消息帧的基本单元为8位字节，传输顺序为低位在前，高位在后；低字节在前，高字节

在后。

6.4消息数据单元

6.4.1标记规则与编码规则

消息数据单元（MPDU）的标记规则遵循ASN.1的抽象语法，详见GB/T16262.1—2006。

消息数据单元（MPDU）的编码规则遵循A-XDR,详见DL/T790.6—2010。

6.4.2通用数据类型

消息数据单元使用的数据类型见错误!未找到引用源。。

表1消息数据单元使用的数据类型定义

类型描述标记定义数值范围

NULL0空

bool3布尔值（BOOLEAN）1或0

bit-string4位串(BITSTRING)

double-long532位整数(Integer32)

double-long-unsi

632位正整数(doub1e-1ong-unsigned)

gned

类型描述标记定义数值范围

保留7-8

octet-string98位位组(字节)串(OCTETSTRING)

ASCII字符串(VisibleString)

visible-string10

中文编码格式为GB2312

保留11

UTF8-string12UTF-8编码的字符串

保留13-14

integer158位整数(integer)-128...127

long1616位整数(long)-32768...32767

unsigned178位正整数(Unsigned8)0...255

long-unsigned1816位正整数(Unsignedl6)0...65535

保留19

long642064位整数(Integer64)-22...2"T

long64-unsigned2164位正整数(Unsigned64)0...2e-l

enum22枚举的元素在对象属性或方法的描述中定义0...255

float3223octet-string(SIZE(4))

float6424octet-string(SIZE(8))

date_time25octet-string(SIZE(10))

date26octet-string(SIZE(5))

time27octet-string(SIZE(3))

date_time_s28octet-string(SIZE(7))

29-25

保留

5

6.4.3数据类型定义

6.4.3.1浮点数据类型

浮点数据类型包括float32以及float64,格式定义见GB/T17966-2000„

6.4.3.2date_time数据类型

日期时间date_time的数据类型定义见错误!未找到引用源。。

表2date_time数据类型定义

数据类型定义说明

date_time：：=SEQUENCE日期和时间的十六进制格式。

(year、milliseconds=FFFFH表示无效。

yearlong-unsigned,month、day_of_month、day_of_weekhour、minute>

monthunsigned,second=FFll表示无效。

day_of_monthunsigned.dayofweek：。表示周日，1…6分别表示周一到周六。

数据类型定义说明

day_of_weekunsigned,

hourunsigned.

minuteunsigned,

secondunsigned.

millisecondslong-unsigned

}

6.4.3.3date_time_s数据类型

日期时间date_time_s的数据类型定义见错误!未找到引用源。。

表3date_time_s数据类型定义

数据类型定义说明

date_time_s：：=SEQUENCE日期和时间的十六进制格式。

(year=FFFFH表示无效。

yearlong-unsigned.monthsday、hour、minute、second=FFH表示无效。

monthunsigned,

dayunsigned,

hourunsigned.

minuteunsigned,

secondunsigned

}

6.4.3.4date数据类型

日期date的数据类型定义见错误!未找到引用源。。

表4date数据类型定义

数据类型定义说明

date：：=SEQUENCE日期的十六进制格式。

(year=FFFFH表示无效。

yearlong-unsigned,monthNday_of_month、day_of_week=FEH

monthunsigned,表示无效。

day_of_monthunsigned.

dayofweekunsigned

)

6.4.3.5time数据类型

时间time的数据类型定义见错误!未找到引用源。。

表5time数据类型定义

数据类型定义说明

time：：=SEQUENCE时间的十六进制格式。

(hour、minute、second=FFH表示无效。

hourunsigned,

minuteunsigned,

secondunsigned

}

7App接入规范

7.1App校验

每个App(package)在提交软件中心时，由软件管理中心通过ESAM加密机自动在app

末尾增加RN以及MAC,App在下载到终端后，由终端通过本体ESAM芯片对MAC进行

校验，校验通过方可执行。

App

bin

RNMAC

图13App校验码

7.2命名规范

App消息队列命名规则(以名称第一个字符为关键字)：

V：表示App内部线程消息队列，如[monitor”,App可将接口消息分发至内部处

理线程，达到高并发的目的；

T：表示App使用基于TCP方式的消息驱动，如"T-myAppl”；

4U\表示App使用基于UDP方式的消息驱动，基于该模式，名称中必须包含App

所在的设备IP地址以及使用的端口号，如"U-myApp2:locaIhost[9000/；

名称中出现localhost,表示使用本机地址，9000为UDP端口号；

4M5：表示App使用基于MQTT方式的消息驱动，如“M-myApp2”；

T：表示App使用基于IPC驱动方式，如LsmiOS。

App消息队列名称在消息传输过程中，用来对源、目标App消息队列进行寻址，并填

充在消息结构中的SOURCEWDESTINATION字段中。如果DESTINATION字段为

空字符串，表示改消息广播至所有注册的其他App。

7.3注册机制

App下载到终端后，经终端校验通过，加入到启动列表，由系统管理器负责启动执行,

如果App在启动后三分钟内仍未发送注册消息到系统管理器完成注册，将会被系统管理器

kill。注册请求由App发起，系统管理器给与确认。

7.4注册查询

App可以向系统管理器查询已注册App信息，支持通过关键词查询，获取待交互App

信息（如IP地址及端口号等），无论App如何部署，均可达成互相通信目的。

图15注册查询

7.5保活机制

系统管理器按设定间隔自动向所有注册的App发送Keepalive消息，App收到该消息后

给予确认，如果连续多个周期（间隔）未收到App的确认，系统管理器认为该App为异常

状态，将执行后续异常恢及策略。

7.6事件通知

App可以向系统管理器订阅事件，当事件发生时，由系统管理器通知到App,系统级消

息主要包含：紧急停电、系统停电、系统复位、系统上电、校时。

紧急停电一表示系统的后备电源系统无法支撑继续运行；

系统停电一供电电源系统已关闭，后备电源已启用，在后备电源工作时间满后自动关机;

系统复位一系统需要重启；

系统上电一由掉电转为上电状态时通知；

系统校时一当系统时钟被修改时。

8App设计方案

8.1系统App

系统App在智能终端中有且仅有唯一一个App即系统管理器，系统管理器命名为

“smiOS”,系统管理器负责终端内部App的管理以及系统监控，确保系统稳定可靠运行。

1、系统监控功能

监控系统软件、硬件工作情况，当发生告警或故障时生产相应的日志文件，提供设

备维护相关接口。具体包括：

a）远程查看设备信息，包括设备厂商及版本信息、设备生产信息、设备编号、设

备操作系统版本、CPU使用率、RAM使用率、存储使用率等。

b）远程配置设备信息。

c）检测的设备故障，包括FLASH故障、时钟故障、RAM故障、ESAM故障等。

d）设备维护，提供设备对时、设备重启等。

e）日志管理，提供统一的日志记录功能，日志分类管理，日志级别可分为信息、

告警、错误、调试等。

2、容器管理功能

负责容器的安装、卸载、启动、停止和状态查询，提供管理接口指令和接口APL

并具有对容器监控功能，对容器内的使用资源如CPU使用率、RAM使用率和存储

使用率超限进行监控并产生告警和H志。

3、APP管理功能：对APP进行管理，包括APP安装、升级、卸载、启停、查看APP

状态。

4、系统安全：检查容器镜像和APP的合法性。

5、连接物联管理平台：负责连接物联管理平台，接收和实现物联管理平台的管理请求;

6、系统管理器具备消息分发路由的功能，在使用异构通信环境中负责消息转发；

7、系统管理器消息接口定义见9.3°

8.2基础App

8.2.1设计原则

对“共享资源”进行管理，避免多App并发访问带来的冲突，同时对“共享资源”进

行优先级管理，且具有与业务无关特征。共享资源包括数据、外设等。

基础App通过消息总线以消息的方式为其他App提供服务。

基础App不应与主站系统之间存在数据交换。

8.2.2数据中心

数据中心负责对整个系统的数据存储管理、数据服务，数据中心命名为“dbCenter”。各

App通过消息总线与数据中心进行交互。

1、数据存储服务

数据中心提供针对应用APP的数据存储服务，并根据分类存储机制，支持基于

SQLITE3的数据文件方式存储以及基于内存文件的非持久化数据存储。

2、数据访问服务

数据中心提供针对应用APP的数据访问服务，支持精准和模糊方式查询，同时，

针对应用APP访问较多的终端参数文件，提供参数文件在系统内存中的加载，实

现更高速度的响应。

3、数据备份和检查

数据中心可以向系统管理器订阅系统级事件，当事件发生时，由系统管理器通知到

数据中心，当收到系统级事件（紧急停电、系统停电、系统复位、系统上电）时进

行易失性数据的备份，系统恢复正常后恢复易失性数据。

数据中心运行过程中，定期对易失性数据进行备份，确保异常状态下数据无丢失。

数据中心根据先入先出规则，定期删除过期数据，保证系统有充足的数据存储空间

存储数据。

4、数据中心应有数据安全保证策略和措施，确保数据文件不被损坏和丢失；

5、数据中心应自动统计其他App访问频率，通过安全策略防止其他App恶意攻击；

6、数据中心消息接口定义见0。

8.2.3无线远程拨号管理

无线远程拨号管理App负责无线公/专网通信模块的管理，负责完成拨号、模块状态监

控以及相关统计功能，无线远程拨号管理App命名为“wirelessDCM”。

1、拨号功能

无线远程拨号管理App可根据当前SIM卡运营商信息和网络制式，自动匹配相应

的APN、用户名和密码等参数，进行拨号，建立PPP链接。优先使用4G或更高

速率的网络。

App支持以指定的网络制式进行拨号链接。

App支持断开当前PPP桂接功能；

当无线网络出现异常，可自动在不同网络制式见切换，异常解除后，可自动恢复。

2、状态监控功能

无线公网拨号管理App应能实时监控当前拨号网络状态，一旦链路状态发生变更，

应及时发出网络变更消息，通知其他APP。

3、数据统计功能

无线公网拨号管理App应能实时统计拨号次数、失败次数、最后一次拨号成功时

间等数据。

4、无线远程拨号管理消息定义见A.3。

8.2.4本地通信管理

本地通信管理App负责终端本地通信模块（以下简称CCO）的管理，依据《Q/GDW1376.2

集中器本地通信模块接口协议》及其后续修订，遵照相关流程完成对CCO的初始化和档案

同步，通过CCO实现与STA节点的数据交互。本地通信管理App命名为“ccoRouter”。

1、本地通信管理App实现“虚拟路由”功能，支持通过分时竟略实现“多通道”链

路，应用App可通过各自链路通道实现“并发”抄表；

2、支持HPLC、窄带载波、微功率无线等符合Q/GDW1376.2标准的本地模块；

3、针对本地通信模块（CCO）运行过程中STA主动上报的事件进行管理，将上报内

容推送给订阅事件的关联应用App；

4、针对终端与本地通信模块（CCO）交互中的各类异常，以及关联应用APP的异常

访问进行处理，保证控制通道和抄表通道通畅；

5、本地通信消息定义见A.4。

8.2.5模组管理器

模组管理器实现模组插拔检查，根据《能源控制器功能模组接口协议》获取并提供模组

设备基本信息，实现模组设备即插即用，模组管理器App命名为“mapManager”。

1、管理物理端口与模块的对应关系，不同物理接口上插入同类型或不同类型的模组,

可对模组进行类型识别，并对同类型的模组的物理顺序进行管理，实现逻辑端口与

物理端口的映射关系；

2、模组管理器管理与所有模组的控制命令通道的数据交互，实现终端本地模组的通用

操作（如重启、初始化等）以及模组信息查询，可转发其它应用与控制命令通道的

数据：

3、模组管理器负责对模组进行状态监控，异常可自动恢复，支持对模组的在线升级；

4、模组管理器消息定义见A.5。

8.3边缘计算App

8.3.1设计原则

边缘计算App完成功能纯粹的边缘计算、分析类业务（如电能质量分析、线损分析等）。

边缘计算App不对外提供服务。

边缘计算App与主站系统间不存在数据交互。

8.3.2App规划

边缘计算App规划详见《统一终端平台一边缘计算及业务App功能规范》。

8.4业务App

8.4.1设计原则

业务App与主站系统间存在数据交互，遵循一App对应一主站原则，不允许一个App

连接到多个不同的主站。

业务App的实现方式不拘泥于单一二进制文件/单一进程，可以多样化（多二进制文件

或者多进程），可通过多进程协作模式完成某一特定场景业务功能。

8.4.2App规划

业务App规划详见《能源控制器边缘计算及业务App功能规范》c

9App消息接口标识

9.1接口标识

接口标识由四字节组成，采用十六进制编码表示，其格式定义见下表所示。

表6接口标识格式定义

接口标识

IIDI0P

bit31-bitl6bitl5-bitO

接口标识按字节划分为HD和IOP,采用分类编码的方式定义各个接口标识编码，未定

义的接口标识编码保留。

9.2IID=0000H

IIDROOOH的接口标识定义见表7o

表7IIDR000H接口标识定义

接口标识

IIDI0P

0001H：紧急停电（事件）

0002H：系统停电（事件）

0003H：系统复位（事件）

0004H：系统上电（事件）

0005H：系统校时（事件）

0000H：通用消息接口

0010H：心跳检测

0011H：执行维护命令

001211：透明传输

0013H：版本信息

0014H：错误信息

9.3IID=0001H

IIDROOIH的接口标识定义见表8o

表8IID=OOO1H接口标识定义

接口标识

IIDI0P

0001H：以太网插拔（事件）

0010H：App请求注册

001111：App取消注册

0012H：查询已注册App

0001H：系统管理器消息接口

001311：查询指定App信息

0020H：事件订阅

0021H：事件取消订阅

0022H：查询订阅的事件信息

接口标识

IIDIOP

0030H：请求系统审尼

0031H：查询电源状态

0032H：查询以太网插拔状态

0035H：配置本机IP地址

0036H：添加路由表

0037H：删除路由表

0038H：时钟同步

0039H：启动SNTP对时

003AH：获取设备信息

003BII：执行system命令

003CH：获取容器信息

003DH：获取容器内App信息

9.4IID=0002H

UDROU2H的接LI标识定义见表9。

表9IID=02H接口标识定义

接口标识

IIDIOP

0001H：拨号状态变化事件（事件）

OO1OH：查询模块信息

0011H：查询拨号状态

0012H：发送短信

0013H：接收短信

0002H：无线模块拨号管理App消息接口

0014H：修改拨号参数

0015H：重新拨号

0016H：获取GPS定位信息

0017H：设置鉴权方式

001811：设置短信参数

9.5IID=0003H

IID=0003H的接口标识定义见表10。

表10IID=0003H接口标识定义

接口标识

IIDIOP

0001H：上报事件数据（事件）

0002H：上报离网事件（事件）

0010H：抄表端口功能配置

000311：本地通信管理App消息接口

0020H：添加表档案

0021H：删除表档案

0022H：清除表档案

接口标识

IIDIOP

0031H：上报抄表数据

0033H：数据透传

0034H：启动搜表

0035H：暂停搜表

0036H：上报搜表数据

0037H：获取从节点监控延时

0038H：从节点监控

0039H：获取广播延时

003AH：广播

003BH：模块地址设置

003DH：当前配置档案数

003EH：主动抄表

0040H：暂停抄表

0041H：恢复抄表

0042H：里启抄表

0043H：查询档案

0050H：查询HPLC信息

0051H：上报HPLC查询信息

0052H：HPLC频点设置

0053H：HPLC频点查询

005411：HPLC台区识别

0055H：HPLC离网感知

0056H：HPLC拒绝节点上报

0060H：查询抄表状态

0061H：查询抄表模块信息

9.6IID=0004H

IID=0004H的接口标识定义见表11。

表11IID=04H接口标识定义

接口标识

1ID1OP

0001H：模组插拔事件（事件）

0010H：查询模组信息

0011H：查询模组槽位信息

0012H：查询模组插拔状态

0004H：模组管理器消息接口

0013H：模组复位

0014H：模组重启

0015H：文件传输

0016H：查询所有模组信息

9.7IID=0005H

IID=0005H的接口标识定义见表12

表12IID=0005H接口标识定义

接口标识

IIDIOP

0001H：数据更新事件（事件）

0002H：初始化事件（事件）

0010H：读普通数据

0011H：写普通数据

0012H：开始读记录型数据

0013H：单步读取记录数据

0014H：结束记录型数据读取

0005H：数据中心消息接口

0015H：写记录型数据

0016H；更新记录数据

0020H：获取存储记录条数

0021H：获取存储记录深度

003011：数据初始化

0031H：清除指定数据

0032H：恢复出厂

9.8IID=0006H

IID=0006H的接口标识定义见表13。

表13IID=0006H接口标识定义

接口标识

IIDI0P

0001H：以太网远程端口开放监控（事件）

0002H：以太网外联信息监控（事件）

0003H：关键目录文件变更监控（事件）

0006H：安全在线监测消息接口0004H：以太网登录控制台监控（事件）

000511：危险命令操作监控（事件）

0006H：Root口令变更监控（事件）

0010H：启动/关闭SSH服务

9.9IID=0007H

IID=0007H的接口标识定义见表14