通用功能

Topic

上行： sys/dev/{productKey}/{sn}
下行： sys/server/{productKey}/{sn}
QoS： 1

method	说明
login	设备登录
time / time.ms	对时
time_sync	中台发送指令要求设备对时
topology	设备上报拓扑结构
topo_clear	平台删除网关中的全部或部分拓扑结构
上报告警规则	设备上报告警规则
restart	设备重启
ota / ota_sub	中台推送网关/子设备升级
ota_apply	设备主动请求升级
ota_info	中台获取设备信息
info	平台读取和设置设备参数
设置平台IP端口	平台读取和设置设备接入的平台IP端口
comtext	平台监听设备端口实时报文
call_topo	平台获取设备的拓扑信息
call_data	平台读取设备内存储的实时数据或历史数据
sync	平台与设备同步配置文件
config_file	平台与设备传输配置文件
夏令时	夏令时开发方案

设备连接中台时，发出登录消息，中台将设备的基本信息持久化，并主动下发投影状态给设备。

1.设备使用Topic sys/dev/{productKey}/{sn} 发出登录消息， method为login ，消息格式如下：

{
    "msgid": 567,
    "method": "login",
    "sn": "1234567890123",
    "timestamp": 1638869890,
    "payload": {
        // 启用报文压缩
        "compress": "1",
        // 启用报文压缩算法
        "compressAlgo": "LZO",
        // 启用报文加密
        "encrypt": "1",
        "upInterval": 300,
        "devname": "awt100_4g",
        "softcode": "1111",
        "softversion": "1001",
        "network": 0,
        "imei": "001122334455667",
        "ccid": "00112233445566778899",
        "mac": "ABC",
        "description": "..."
    }
}

参数	说明
`payload`	设备上报自身属性，对中台保存的设备属性进行补充。子属性： upInterval - 必填，上报间隔，平台根据此属性判断网关是否离线，单位：秒 compress - 非必填，是否启用压缩，默认为`"0"` compressAlgo - 当`compress: "1"`时必填，表示采用的压缩算法，值为"ZLIB"或"LZO"，默认为"LZO" encrypt - 非必填，是否启用加密，默认为`"0"` 。加密采用AES算法，CTS模式（Cipher Text Stealing），补码方式为PKCS5Padding，密钥key和向量iv均使用产品的SecretKey的UTF-8编码 devname - 设备名称 softcode - 固件编码 softversion - 固件版本 network - 联网方式，0表示4G，1表示wifi，2表示以太网，3表示其他 imei - IMEI码 ccid - CCID码 mac - MAC地址 description - 设备上报的自定义信息，会被存储在中台的描述信息中

参数

说明

payload

设备上报自身属性，对中台保存的设备属性进行补充。
子属性：
upInterval - 必填，上报间隔，平台根据此属性判断网关是否离线，单位：秒
compress - 非必填，是否启用压缩，默认为"0"
compressAlgo - 当compress: "1"时必填，表示采用的压缩算法，值为"ZLIB"或"LZO"，默认为"LZO"
encrypt - 非必填，是否启用加密，默认为"0" 。加密采用AES算法，CTS模式（Cipher Text Stealing），补码方式为PKCS5Padding，密钥key和向量iv均使用产品的SecretKey的UTF-8编码
devname - 设备名称
softcode - 固件编码
softversion - 固件版本
network - 联网方式，0表示4G，1表示wifi，2表示以太网，3表示其他
imei - IMEI码
ccid - CCID码
mac - MAC地址
description - 设备上报的自定义信息，会被存储在中台的描述信息中

2.中台使用Topic sys/server/{productKey}/{sn}进行响应， method为login。

更新成功，消息格式如下：

{
    "msgid": 567,
    "method": "login",
    "sn": "1234567890123",
    "res": 1,
    "timestamp": 1638869990
}

更新失败，消息格式如下：

{
    "msgid": 567,
    "method": "login",
    "sn": "1234567890123",
    "res": 0,
    "errcode": "2102",
    "timestamp": 1638869990
}

对时time

中台提供NTP（Network Time Protocol）服务，为资源受限的嵌入式设备，解决无法实时地获取服务端时间的问题。

中台的NTP服务，借鉴NTP协议原理，将中台作为NTP服务器。

对时的标准方案：设备启动/重连时，在login之后对时一次，之后周期性执行对时，通常周期不超过24小时，可根据具体情况调整。

高精准度的时间校正流程如下：

1.设备端通过Topic sys/dev/{productKey}/{sn} 向中台发送消息，会携带发送时间devicesend，

method为time时，时间精确到秒：

{
    "msgid": 568,
    "method": "time",
    "sn": "1234567890123",
    "timezone": "8",
    "timezoneMin": "30",
    "devicesend": 1638869990
}

method为time.ms时，时间需要精确到毫秒：

{
    "msgid": 568,
    "method": "time.ms",
    "sn": "1234567890123",
    "timezone": "8",
    "timezoneMin": "30",
    "devicesend": 1638869990123
}

2.中台接收设备端消息后，通过Topic sys/server/{productKey}/{sn} 回复消息，报文中会增加接收消息的时间serverreceive 和回复消息的时间serversend ，消息如下：

method为time时：

{
    "msgid": 568,
    "method": "time",
    "sn": "1234567890123",
    "timezone": "8",
    "timezoneMin": "30",
    "devicesend": 1638869990,
    "serverreceive": 1638870000,
    "serversend": 1638870001,
    
    /* 以下是夏令时信息 */
  
    // 是否启用夏令时，1-启用，0-禁用
    "dstEnable": 1,
    // 夏令时开始、结束时间
    "dstStart": 1710957600,
    "dstEnd": 1729447200,
    // 夏令时的偏移，通常为30或60，单位：分钟
    "dstOffset": 30
}

method为time.ms时：

{
    "msgid": 568,
    "method": "time.ms",
    "sn": "1234567890123",
    "timezone": "8",
    "timezoneMin": "30",
    "devicesend": 1638869990123,
    "serverreceive": 1638869990223,
    "serversend": 1638869990323,
    /* 以下是夏令时信息 */
    // 是否启用夏令时，1-启用，0-禁用
    "dstEnable": 1,
    // 夏令时开始、结束时间
    "dstStart": 1710957600,
    "dstEnd": 1729447200,
    // 夏令时的偏移，通常为30或60，单位：分钟
    "dstOffset": 30
}

考虑到设备上传的timezone和timezoneMin 可能会出现不规范（例如：包含空格的Unicode编码\u0001），所以如果出现错误，则按照标准的错误回复，返回如下报文，其中错误码2114 表示非法的时区格式：

{
    "msgid": 568,
    "method": "time",
    "sn": "1234567890123",
    "res": 0,
    "errcode": "2114",
    "timestamp": 1638869890
}

3.设备端接收到中台回复，会根据本地时间，给出接收回复的时间devicereceive。

4.根据以上出现的4个时间，计算设备端与中台的时间差，得出设备端获取到的，服务端当前的精确时间为：

(serverRecvTime + serverSendTime + deviceRecvTime - deviceSendTime) / 2

参数	说明
`timezone`	设备所在时区的小时偏移量，字符串，范围`"-12"`～`"14"`
`timezoneMin`	设备所在时区的分钟偏移量，字符串，范围`"00"`、 `30`、 `"45"`。小时和分钟偏移量分为2个属性，主要是为了兼顾不支持分钟偏移量的设备，这类设备只需要解析`timezone`即可，不会因为解析`timezone`得到一个浮点数而出错
`devicesend`	设备发送时间，unix时间戳
`serverreceive`	平台接受时间，unix时间戳
`serversend`	平台发送时间，unix时间戳
`dstEnable`	是否启用夏令时，1-启用，0-禁用
`dstStart`	夏令时开始时间，unix时间戳
`dstEnd`	夏令时结束时间，unix时间戳
`dstOffset`	夏令时的偏移，通常为30或60，单位：分钟

发送指令要求设备对时time_sync

中台可以主动发起对时请求，要求具有时钟芯片的设备进行对时。

1.中台通过Topic sys/server/{productKey}/{sn} 向设备发送消息：

{
    "msgid": 628131887239491584,
    "method": "time_sync",
    "sn": "1234567890123",
    "timestamp": 1638869890
}

2.设备端收到消息后，通过Topic sys/dev/{productKey}/{sn} 向中台回复确认收到：

{
    "msgid": 628131887239491584,
    "method": "time_sync",
    "sn": "1234567890123",
    "res": 1,
    "timestamp": 1638869990
}

3.设备端通过 time / time.ms 向平台发起对时。

设备上报拓扑结构topology

网关可以发送消息来上报自身的拓扑结构，中台收到后，将子设备信息保存到数据库。

1.设备端使用Topic sys/dev/{productKey}/{sn}反馈信息给中台， method为topology。

// 仪表拓扑
{
    "msgid": 126,
    "method": "topology",
    "sn": "1234567890123",
    "timestamp": 1638870090,
    "payload": {
        "meter": [
            {
                "addr": "4_1",
                "devsn": "ascb1-123456",
                "devname": "ASCB-1",
                "productkey": "NjI4NDc1NTg5OTE2OTcxMDA4",
                "name": "DDSY",
                "softcode": "1111",
                "softversion": "1001",
                "network": 0,
                "imei": "001122334455667",
                "ccid": "00112233445566778899",
                "portid": "1",
                "meteraddr": "1"
            }
        ],
        "diagram": [
            {
                "addr": "1_1",
                // 回路名称
                "name": "进线",
                // 类型
                "type": "INCOMING",
                // 上级节点
                "parent": "",
                // 是否显示控制按钮
                "control": {
                    // 分合闸按钮
                    "SWITCH": "1",
                    // 负控打开按钮
                    "LOADCONTROL": "1",
                    // 负控复位按钮
                    "LOADCONTROLRECOVER": "1",
                    // 强控按钮
                    "FORCESWITCH": "1"
                }
            },
            { "addr": "1_2", "name": "空调", "type": "AIR_CONDITION", "parent": "1_1", "control": {...} },
            { "addr": "1_3", "name": "插座", "type": "SOCKET", "parent": "1_1", "control": {...} },
            { "addr": "1_4", "name": "照明", "type": "LIGHTING", "parent": "1_1", "control": {...} }
        ]

    }
}

一级属性	二级属性	三级属性	类型	说明
payload
	meter		Array	子设备列表
		addr	String	必填，子设备的唯一编号，用来定位网关/通讯模块下的设备/回路，下发命令时需要用到。
		productkey	String	子设备ProductKey，平台会优先匹配该字段来生成子设备型号信息
		name	String	productkey和name二选一必填，产品名称，如果不填写productkey，中台会根据name字段来匹配产品名称，如果存在产品信息，则创建该型号的子设备，如果不存在产品信息，会自动创建一个新的产品型号，然后基于新的型号创建子设备。
		devsn	String	子设备序列号，说明性字段
		devname	String	子设备名称，说明性字段
		softcode	String	固件编码
		softversion	String	固件版本
		network	Integer	联网方式，0表示4G，1表示wifi，2表示以太网，3表示其他
		imei	String	IMEI码
		ccid	String	CCID码
		portid	String	仪表连接的网关端口编号，当使用网关连接中台时上报，中台下发透传命令时，会将此属性发给网关
		meteraddr	String	仪表连接网关时的表地址，当使用网关连接中台时上报，中台下发透传命令时，会将此属性发给网关
	diagram		Array
		addr	String	子设备唯一编号，与meter中的addr保持对应。
		name	String	回路名称
		type	String	类型，可扩展。 INCOMING-进线 AIR_CONDITION-空调 SOCKET-插座 LIGHTING-照明等
		parent	String	上级回路，与meter中的addr保持对应。
		control	Object	支持哪些控制功能，可扩展。 SWITCH-非合闸 LOADCONTROL-负控打开 LOADCONTROLRECOVER-负控复位 FORCESWITCH-强控

如果需要上传分组拓扑信息，可以通过 "cmd": "topo_group" 上报，上报组拓扑之前，需要先上报上面的仪表拓扑报文。

{
    "msgid": 126,
    "method": "topology",
    "sn": "1234567890123",
    "timestamp": 1638870090,
    "payload": {
        // 组拓扑信息
        "cmd": "topo_group",
        "meter": [
            {
            "addr": "asl_1_2",
            "name": "ASL200",
            "group": [
                // type：组类型，single-单控组，multi-群控组，
                //      ignore-忽略，默认为multi
                // category：组类型，说明性字段。
                //      ignore-忽略，single-单控，box-电箱总控，
                //      floor-楼层总控，building-楼宇总控，area-区域总控，
                //      gateway-网关总控，device-设备总控，custom-用户自定义
                // name：组名，说明字段
                // num：组号
                { "type": "ignore", "category": "ignore", "name": "1", "num": "1" },
                { "type": "single", "category": "single", "name": "1", "num": "1" },
                { "type": "multi", "category": "building", "name": "A楼", "num": "2" },
                { "type": "multi", "category": "floor", "name": "A楼1层", "num": "3" }
            ],
            // 以下非必填
            "softcode": "1111",
            "softversion": "1001"
            }
        ]
    }
}

2.中台收到消息后，会根据payload中填写的子设备addr，查询中台数据库，如果子设备已存在，则将其他信息更新到数据库，如果子设备不存在，则在数据库创建子设备。

3.中台使用Topic sys/server/{productKey}/{sn}对设备进行响应， method为topology。

成功消息格式如下：

{
    "msgid": 126,
    "method": "topology",
    "sn": "1234567890123",
    "res": 1,
    "timestamp": 1638870100
}

失败消息格式如下：

{
    "msgid": 126,
    "method": "topology",
    "sn": "1234567890123",
    "res": 0,
    "timestamp": 1638870100
}

删除设备拓扑topo_clear

当平台上删除某个子设备时，需要将其同步到网关，避免网关下次上报拓扑时，仍旧将该子设备报上来。支持删除部分或全部子设备拓扑。

1.平台使用Topic sys/server/{productKey}/{sn}发出消息， method为topo_clear。

// 全量删除 sys/server/pk/sn
{
    "msgid": 628131887239491584,
    "method": "topo_clear",
    "sn": "1234567890123",
    "timestamp": 1638869990,
    "payload ": {
        "addr": [ "ALL" ]
    }
}

// 部分删除 sys/server/pk/sn
{
    "msgid": 628131887239491584,
    "method": "topo_clear",
    "sn": "1234567890123",
    "timestamp": 1638869990,
    "payload ": {
        "addr": [ "1_1", "1_2" ]
    }
}

参数	说明
`payload.addr`	需要删除的子设备数组，数组，必填，全部删除写作`["ALL"]`。

2.设备通过Topic sys/dev/{productKey}/{sn}返回结果，如果网关拓扑中不存在下发的addr，也要返回成功。

上报告警规则

设备走完登录流程，上报topology后，要将告警规则上报给平台，可以按照addr不同进行拆包，并且在设备运行期间每天上报一次，以保证平台数据的同步，网关和直连表的协议存在差异。

网关上报告警规则alarm_config

1.设备使用Topic sys/dev/{productKey}/{sn} 发出消息， method为alarm_config ，消息格式如下：

{
    "msgid": 567,
    "method": "alarm_config",
    "sn": "1234567890123",
    "fragNo": 1,
    "fragment": 3,
    "timestamp": 1638869890,
    "payload": {
        "meter": [{
            "addr": "02122082300059",
            "rules": [{
                "code": "Ua",
                "enable": 1,
                "type": "0",
                "delay": "10",
                "deadzone": "10",
                "high2": "200",
                "high1": "100",
                "low2": "10",
                "low1": "50",
                "condition": "0",
                "relateCode": "Ua",
                "desc": "电压"
            }, {
                "code": "DO1",
                "enable": 1,
                "type": "1",
                "condition": "0",
                "delay": "1",
                "on_desc": "门禁开",
                "off_desc": "门禁关"
            }]
        }, {
            "addr": "02122082300059",
            "rules": [{
                "code": "DO1",
                "enable": 1,
                "type": "1",
                "condition": "0",
                "delay": "1",
                "on_desc": "门禁开",
                "off_desc": "门禁关"
            }]
        }]
    }
}

一级属性	二级属性	三级属性	类型	说明
`fragNo`			Integer	分包的包序号，分包时需要保证所有包的timestamp一致
`fragment`			Integer	分包的包数量，分包时需要保证所有包的timestamp一致
`payload.meter`			Array	仪表报警规则
	`addr`		String	仪表地址
	`rules`		Array
		`code`	String	报警点位，对应实时数据中的设备状态参量
		`enable`	Integer	1-启用，0-禁用
		`type`	String	参量类型，"0"-遥测，"1"-遥信
		`delay`	String	延时上报时间，单位:秒
		`deadzone`	String	死区（非必须）
		`high2`	String	高高限
		`high1`	String	高限
		`low2`	String	低低限
		`low1`	String	低限
		`relateCode`	String	非必须，遥测参数，type="0"时启用，关联参数上报实时数据
		`desc`	String	非必须，遥测参数，type="0"时启用，说明字段
		`condition`	String	非必须，遥信参数，type="1"时启用，"0"-0变1报警，"1"-1变0报警，"2"-变化报警
		`on_desc`	String	非必须，遥信参数，type="1"时启用，报警描述ON
		`off_desc`	String	非必须，遥信参数，type="1"时启用，报警描述OFF

2.中台使用Topic sys/server/{productKey}/{sn}进行响应， method为alarm_config。

成功，消息格式如下：

{
    "msgid": 567,
    "method": "alarm_config",
    "sn": "1234567890123",
    "res": 1,
    "timestamp": 1638869990
}

失败，消息格式如下：

{
    "msgid": 567,
    "method": "alarm_config",
    "sn": "1234567890123",
    "res": 0,
    "errcode": "2102",
    "timestamp": 1638869990
}

直连表上报告警规则

1.直连表使用实时数据Topic data/up/{productKey}/{sn} 发出消息， method为update ，消息格式如下：

{
  "msgid": 1771890773,
  "timestamp": 1771890773,
  "sendtime": 1771890773,
  "sn": "26010900570001",
  "method": "update",
  "fragNo": 1,
  "fragment": 3,
  "version": 0,
  "reported": {
    "26010900570001": {
      "state": "ONLINE",
      "UHighSw": "0",
      "UHighVal01": "0.000",
      "UHighVal02": "0.000",
      "UHighDelay": "0.0",
      "UHighAH": "0",
      "UHighDO1": "0",
      "UHighDO2": "0",
      "UHighDO1Re": "0",
      "UHighDO2Re": "0",
      "ULowSw": "0",
      "ULowVal01": "0.000",
      "ULowVal02": "0.000",
      "ULowDelay": "0.0",
      "ULowAH": "0",
      "ULowDO1": "0",
      "ULowDO2": "0",
      "ULowDO1Re": "0",
      "ULowDO2Re": "0"
    }
  }
}

一级属性	二级属性	三级属性	类型	说明
`fragNo`			Integer	分包的包序号，分包时需要保证所有包的timestamp一致
`fragment`			Integer	分包的包数量，分包时需要保证所有包的timestamp一致
`reported`			Object
	属性		String	仪表地址
		参数 + `Sw`	String	使能开关，"0"-禁用，"1"-启用参数按如下规则：遥测报警：电参量+High/Low，例如过压UHigh/欠压ULow 功能码：与平台协商确定报警码，例如缺相为PhaseLoss
		参数 + `Val01`	String	遥测报警时必须。预警阈值
		参数 + `Val02`	String	遥测报警时必须。报警阈值
		参数 + `Delay`	String	可选。延时，单位:秒
		参数 + `AH`	String	可选。报警回滞量
		参数 + `DO1`	String	可选。是否联动DO1
		参数 + `DO2`	String	可选。是否联动DO2
		参数 + `DO1Re`	String	可选。DO1恢复动作，"1"-跳闸 "0"-无动作
		参数 + `DO2Re`	String	可选。DO2恢复动作，"1"-跳闸 "0"-无动作

2.中台使用Topic data/down/{productKey}/{sn}进行响应， method为update。

成功，消息格式如下：

{
    "msgid": 567,
    "method": "update",
    "sn": "1234567890123",
    "res": 1,
    "timestamp": 1638869990
}

失败，消息格式如下：

{
    "msgid": 567,
    "method": "update",
    "sn": "1234567890123",
    "res": 0,
    "errcode": "2102",
    "timestamp": 1638869990
}

设备重启restart

1.中台使用Topic sys/server/{productKey}/{sn}推送信息， method为restart ，消息格式如下：

{
    "msgid": 628131887239491584,
    "method": "restart",
    "sn": "1234567890123",
    "timestamp": 1638869890
}

2.设备端接收到消息后，应当立即使用Topic sys/dev/{productKey}/{sn}反馈信息给中台， method为restart ，然后再重启设备。

{
    "msgid": 628131887239491584,
    "method": "restart",
    "sn": "1234567890123",
    "res": 1,
    "timestamp": 1638870090
}

推送设备升级ota

1.中台使用Topic sys/server/{productKey}/{sn}推送OTA信息，

升级网关时， method为ota ，消息格式如下：

{
    "msgid": 628131887239491584,
    "method": "ota",
    "sn": "1234567890123",
    "timestamp": 1638869890,
    "payload": {
        "softcode": "1111",
        "softversion": "1001",
        "file": [
            {
                "url": "http://iot.acrel-eem.com/download/902418652506419200",
                "size": 335571,
                "md5": "35149b871cf1db1b0fc8efbfdc99c37f"
            }
        ]
    }
}

升级子设备时， method为ota_sub ，消息格式如下：

{
    "msgid": 628131887239491584,
    "method": "ota_sub",
    "sn": "1234567890123",
    "timestamp": 1638869890,
    "payload": {
        "sn": [ "1_1", "1_2" ],
        "softcode": "1111",
        "softversion": "1001",
        "file": [
            {
                "url": "http://iot.acrel-eem.com/download/902418652506419200",
                "size": 335571,
                "md5": "35149b871cf1db1b0fc8efbfdc99c37f"
            }
        ]
    }
}

参数	二级属性	说明
`softcode`		固件编号
`softversion`		固件版本
`sn`		需要升级的子设备序列号/地址的数组，与拓扑中上报的addr保持一致。当升级子设备时，sn为`["ALL"]`表示升级全部子设备，此时网关需要匹配子设备的软件编号
`file`		设备升级使用的固件包信息，支持一个固件中包含多个文件的情况。
	`url`	固件下载URL
	`size`	固件大小，单位：Byte
	`md5`	MD5校验码

2.设备收到消息后，要先使用Topic sys/dev/{productKey}/{sn}回复消息确认收到，然后下载固件进行升级。

{
    "msgid": 628131887239491584,
    "method": "ota",  // 子设备升级时为ota_sub
    "sn": "1234567890123",
    "res": 1,
    "timestamp": 1638869990
}

设备主动请求升级ota_apply

1.设备主动请求升级时，使用Topic sys/dev/{productKey}/{sn}发送消息， method为ota_apply。

{
    "msgid": 125,
    "method": "ota_apply",
    "sn": "1234567890123",
    "timestamp": 1638869990,
    "payload": {
        "softcode": "1111",
        "softversion": "1001"
    }
}

2.中台接收到消息后，根据softcode和softversion查询到相应的固件信息，然后使用Topic sys/server/{productKey}/{sn} 反馈信息给设备， method为ota_apply。

{
    "msgid": 125,
    "method": "ota_apply",
    "sn": "1234567890123",
    "timestamp": 1638870090,
    "payload": {
        "softcode": "1111",
        "softversion": "1001",
        "file": [
            {
                "url": "http://iot.acrel-eem.com/download/1",
                "size": 123456,
                "md5": "abc"
            },
            {
                "url": "http://iot.acrel-eem.com/download/2",
                "size": 123567,
                "md5": "def"
            }
        ]
    }
}

或反馈失败信息，例如：未找到相应的OTA信息。

{
    "msgid": 125,
    "method": "ota_apply",
    "sn": "1234567890123",
    "res": 0,
    "errcode": "3101",
    "timestamp": 1638870090
}

中台获取设备信息ota_info

中台通过向设备发送消息，查询设备端当前的OTA信息。

1.中台使用Topic sys/server/{productKey}/{sn}推送信息， method为ota_info ，消息格式如下：

{
    "msgid": 628131887239491584,
    "method": "ota_info",
    "sn": "1234567890123",
    "timestamp": 1638869890,
    "payload": {
        "sn": [
            "12345"
        ]
    }
}

参数	说明
`payload`	当需要查询子设备属性时，填写的信息，如果只需要查询设备/网关的信息，无需payload属性： sn - 子设备SN，数组，但当前每次只允许下发1个子设备SN

2.设备端接收到消息后，使用Topic sys/dev/{productKey}/{sn}反馈信息给中台， method为ota_info。

{
    "msgid": 628131887239491584,
    "method": "ota_info",
    "sn": "1234567890123",
    "timestamp": 1638870090,
    "payload": {
        "softcode": "1111",
        "softversion": "1001",
        "sn": [
            "12345"
        ],
        "info": [
            {
                "softcode": "101",
                "softversion": "101"
            }
        ]
    }
}

参数	说明
`payload`	设备上报自身属性，对中台保存的设备属性进行补充。子属性： softcode - 设备/网关固件编码 softversion - 设备/网关固件版本 sn - 当下发指令时存在`payload.sn` ，即查询子设备信息时，返回值中可以此属性，用来反馈查询到ota信息的子设备SN，未查询到OTA信息的子设备SN必须从中删除，以保证和`info`属性中的信息一一对应。 info - 数组，当下发指令时存在`payload.sn` ，即查询子设备信息时，返回值中存在此属性，返回子设备的ota信息。

参数

说明

payload

设备上报自身属性，对中台保存的设备属性进行补充。
子属性：
softcode - 设备/网关固件编码
softversion - 设备/网关固件版本
sn - 当下发指令时存在payload.sn ，即查询子设备信息时，返回值中可以此属性，用来反馈查询到ota信息的子设备SN，未查询到OTA信息的子设备SN必须从中删除，以保证和info属性中的信息一一对应。
info - 数组，当下发指令时存在payload.sn ，即查询子设备信息时，返回值中存在此属性，返回子设备的ota信息。

这么做主要是为了协议的扩展性考虑，现在考虑到一个设备/网关下面可能挂几百个设备，如果一次下发大量子设备SN，可能造成设备负载过高，所以在调用中台接口时，每次只允许查询1个子设备，即payload.sn 数组的最大容量为1，但是在中台的协议设计上，保留了一次查询多个子设备信息的扩展性，那么，当一次下发多个子设备SN时，网关可能需要分包响应，那么如果不能建立起sn和info的对应关系，中台就无法知道当前返回的是哪些子设备的OTA信息，所以要求响应中的payload.sn 必须与payload.info一一对应，以保证协议的可扩展性。

读取和设置设备参数info

平台网站通过此method读取和设置参数。由于参数较多，因此需要通过type属性来区分是哪类参数。平台网站根据当前的界面或用户的操作可以单独读取或者设置单个或几个参数。

读命令

平台发出

// 平台发出读命令
{
    "msgid": "948061032286580737",
    "method": "info",
    "sn": "1234567890123",
    "timestamp": 1638869990,
    "payload ": {
        "cmd": "READ",
        "type": "UART"
    }
}

设备回复

{
    "msgid": "948061032286580737",
    "method": "info",
    "sn": "1234567890123",
    "res": 1,
    "timestamp": 1638870100,
    "payload": {
        "num": 1,
        "baud": 1200,
        "databits": 6,
        "parity": "NONE",
        "stop": 1
    }
}

写命令

平台发出

{
    "msgid": "948061032286580737",
    "timestamp": 1715146974,
    "method": "info",
    "sn": "24041506850011",
    "payload": {
        "cmd": "WRITE",
        "type": "UART",
        "num": 1,
        "baud": 1200,
        "databits": 6,
        "parity": "NONE",
        "stop": 1
    }
}

设备回复

{
    "msgid": 628131887239491584,
    "method": "info",
    "sn": "1234567890123",
    "res": 1,
    "timestamp": 1638870090
}

参数	类型	说明
cmd	string	READ:读取参数； WRITE:设置参数；
type	string	STATIC：固定值参数，只需读取一次 BASIC：基础参数，平台IP端口等 UART:串口参数 ETH:网口参数 GSM:4G参数 LORA:lora参数 WIFI:wifi参数 DIDO:开关量、模拟量参数 INVERTER:光伏逆变器数据, 详见文档AWT200 防逆流专用方案设计 INVERTER_LIST:读取逆变器地址列表，详见文档AWT200 防逆流专用方案设计

下面按照type分别列出不同类型的参数

STATIC ，静态参数，运行后不会变化

参数	类型	读/写	说明
product	string	r	设备型号
productKey	string	r	中台productkey
softcode	string	r	程序编号
softversion	string	r	程序版本
softbootload	string	r	bootload固件版本
softdevelopment	string	r	内部开发版本
produceTime	string	r	设备生产时间
imei	string	r	通讯模组序列号
ccid	string	r	SIM卡号

BASIC ，基础参数

参数	类型	读/写	说明
sn	string	r/w	设备序列号
timezone	string	r/w	时区标准格式 "+08:00" "-01:30"
platform	array[]	r/w	应用平台的连接信息，数组，具体参照设置平台IP端口
runTime	string	r	设备运行时间以秒为单位计时
runState	string	r	设备当前运行状态 "run" - 运行中 "alarm" - 报警中
ethState	string	r	设备当前网口状态 "no line" - 未插入网线 "run" - 正常通讯中(只有一个端口连接成功即可) "error" - 网口通讯异常（网线已插入，由于某些原因没有收发包数）
gsmState	string	r	设备当前4G状态 "off" - 无线模块未启用 "init" - 初始化中 "check sim" - 检查sim卡 "no net" - 入网失败 "run" - 正常通讯中(只有一个端口连接成功即可) "ppp error" - 拨号失败
gsmRssi	int	r	信号强度百分值%
wifiRssi	int	r	信号强度百分值%
loraRssi	int	r	信号强度百分值%
sendPkt	int	r	总发送包数
recvPkt	int	r	总接收包数
devCnt	int	r	下行设备总数（网关有此参数）
devOnlineCnt	int	r	下行设备在线数（网关有此参数）
uartCnt	int	r	串口个数
ethCnt	int	r	网口个数
loraCnt	int	r	lora端口个数（没有填0）
wifiCnt	int	r	wifi端口个数
gsmCnt	int	r	gsm端口个数
diCnt	int	r	输入开关量个数
doCnt	int	r	输出开关量个数
aiCnt	int	r	输入模拟量个数
memUsed	int	r	内存已使用大小单位：KB
memUsedPct	string	r	内存使用率单位：%
memUsedMax	int	r	内存已使用最大值单位：KB

UART ，串口参数

参数	类型	读/写	说明
num	int	c	指定第几个串口，从1开始
baud	int	r/w	波特率 1200/2400/4800/9600/19200/38400/115200
databits	int	r/w	数据位 6/7/8
parity	string	r/w	奇偶校验位 NONE/ODD/EVEN
stop	int	r/w	停止位 1\1.5\2

ETH ，网口参数

参数	类型	读/写	说明
num	int	c	指定第几个网口，从1开始
ip	string	r/w	本地ip地址
gateway	string	r/w	默认网关地址
mask	string	r/w	子网掩码
mac	string	r/w	MAC地址
dhcp	string	r/w	dhcp开关 ON/OFF
sendbytes	string	r	发送字节数
recvbytes	string	r	接收字节数

GSM ，蜂窝网络参数

参数	类型	读/写	说明
switch	string	r/w	开关 ON/OFF
ip	string	r/w	本地ip地址
gateway	string	r/w	默认网关地址
mask	string	r/w	子网掩码
apnName	string	r/w	apn节点名称
apnUser	string	r/w	apn账号
apnPass	string	r/w	apn密码
sendbytes	string	r	发送字节数
recvbytes	string	r	接收字节数

LORA ，LORA参数

参数	类型	读/写	说明
num	int	c	指定第几个lora，从1开始
freq	int	r/w	lora频段，单位HZ
factor	int	r/w	扩频因数
bandwidth	int	r/w	带宽单位HZ

WIFI ，Wi-Fi参数

参数	类型	读/写	说明
wlanAP	string	r/w	AP热点名称
password	string	r/w	AP热点密码

DIDO ，开关量参数

参数	类型	读写	说明

设置平台IP端口

读命令

平台发出

// 平台发出读命令
{
    "msgid": "948061032286580737",
    "method": "info",
    "sn": "1234567890123",
    "timestamp": 1638869990,
    "payload ": {
        "cmd": "READ",
        "type": "BASIC"
    }
}

设备回复

{
    "msgid": "948061032286580737",
    "method": "info",
    "sn": "1234567890123",
    "res": 1,
    "timestamp": 1638870100,
    "payload": {
        "platform": [{
            // 远程配置，1-应用平台
            "remoteConfig": 1,
            // 注册服务，http/https
            "registerProtocol": "https",
            "registerHost": "register.acrel.com",
            "registerPort": 20001,
            // mqtt设置
            // 协议，mqtt/mqtts
            "mqttProtocol": "mqtts",
            "mqttHost": "access.acrel.com",
            "mqttPort": 20071,
            "mqttUsername": "acrel",
            "mqttPassword": "Acrel123",
            "mqttClientId": "NUOCMQPQWSN123456"
        },{
            // 远程配置，2-买断客户保留mqtt到托管调试平台
            "remoteConfig": 2,
            // 注册服务，http/https
            "registerProtocol": "https",
            "registerHost": "register.acrel.com",
            "registerPort": 20001,
            // mqtt设置
            // 协议，mqtt/mqtts
            "mqttProtocol": "mqtts",
            "mqttHost": "debug.acrel.com",
            "mqttPort": 20071,
            "mqttUsername": "acrel",
            "mqttPassword": "Acrel123",
            "mqttClientId": "NUOCMQPQWSN123456"
        }]
    }
}

写命令

平台发出

{
    "msgid": "948061032286580737",
    "timestamp": 1715146974,
    "method": "info",
    "sn": "24041506850011",
    "payload": {
        "cmd": "WRITE",
        "type": "BASIC",
        "platform": [{
            // 远程配置，1-应用平台
            "remoteConfig": 1,
            // 注册服务，http/https
            "registerProtocol": "https",
            "registerHost": "register.acrel.com",
            "registerPort": 20001,
            // mqtt设置
            // 协议，mqtt/mqtts
            "mqttProtocol": "mqtts",
            "mqttHost": "access.acrel.com",
            "mqttPort": 20071,
            "mqttUsername": "acrel",
            "mqttPassword": "Acrel123",
            "mqttClientId": "NUOCMQPQWSN123456"
        },{
            // 远程配置，2-买断客户保留mqtt到托管调试平台
            "remoteConfig": 2,
            // 注册服务，http/https
            "registerProtocol": "https",
            "registerHost": "register.acrel.com",
            "registerPort": 20001,
            // mqtt设置
            // 协议，mqtt/mqtts
            "mqttProtocol": "mqtts",
            "mqttHost": "debug.acrel.com",
            "mqttPort": 20071,
            "mqttUsername": "acrel",
            "mqttPassword": "Acrel123",
            "mqttClientId": "NUOCMQPQWSN123456"
        }]
    }
}

设备回复

{
    "msgid": 628131887239491584,
    "method": "info",
    "sn": "1234567890123",
    "res": 1,
    "timestamp": 1638870090
}

监听设备端口实时报文comtext

平台网站监测端口收发的实时报文。平台网站可以打开或者关闭监测报文功能一段时间，打开后，设备同时向调试MQTT发送报文，或者接收调试平台发出的命令，到时间后该功能自动关闭，避免无限发送消息损耗流量。

平台打开监听端口功能10分钟

// 平台下发
{
    "msgid": 123,
    "method":"comtext",
    "timestamp": 1638869990,
    "sn": "1234567890123",
    "payload":{
        "cmd":"SWITCH",
        "com":"uart",
        "comNo":1,
        "switch":"ON",
        "openTime":10
    }
}

// 设备回复
{
    "msgid": 123,
    "sn": "1234567890123",
    "timestamp": 1638870100,
    "method":" comtext",
    "res":1
}

监听启用期间，设备向调试平台mqtt发送实时数据

{
    "msgid": 123,
    "sn": "1234567890123",
    "timestamp": 1638870100,
    "method":" comtext",
    // 1:成功，0:失败，失败没有payload
    "res":1,
    "payload":{
        "cmd":"TEXT_UP",
        "com":"uart1",
        "text":"01030001840A"
    }
}

监听启用期间，平台可以向设备发送透传调试指令

// 平台下发
{
    "msgid": 123,
    "method":"comtext",
    "timestamp": 1638869990,
    "sn": "1234567890123",
    "payload":{
        "cmd":"RW_MODBUS",
        "text":"01100000000102010000"
    }
}

// 设备回复
{
    "msgid": 123,
    "sn": "1234567890123",
    "timestamp": 1638870100,
    "method":" comtext",
    "res":1,
    "payload":{
        "cmd":"RW_MODBUS",
        "text":"01100000000102010000"
    }
}

参数	类型	说明
cmd	string	SWITCH:开关 TEXT_DOWN:下发报文内容 TEXT_UP:回复报文内容 RW_MODBUS:仪表modbus透传通道
com	string	端口类型名称
comNo	int	此类型下的端口序号
switch	string	ON/OFF
openTime	int	打开时间，到时间关闭，单位分，范围1-60，默认15分钟
res	int	1：操作成功 0：操作失败
text	string	报文内容

获取设备拓扑信息call_topo

平台网站通过此命令获取设备的拓扑信息。目的是为了方便method:call_data的数据召回逻辑。

平台发出命令

// 平台下发
{
    "msgid": 123,
    "timestamp": 1638869990,
    "sn": "1234567890123",
    "method":"call_topo",
    "payload": {
        "cmd": "GET"
    }
}

// 设备回复
{
    "msgid": 123,
    "sn": "1234567890123",
    "timestamp": 1638870100,
    "res":1,
    "method": "call_topo",
    "payload": {
        "cmd": "GET",
        "portCnt": 2,
        "topoInfo": [
            {
                "com": "uart1",
                //地址抄表
                "style":"addr/sn",
                "devList": ["1","2","3"],
                "staList": [1, 0, 1]
            },
            {
                "com": "uart2",
                //序列号抄表
                "devList": ["1111111111111_1", "22222222222222", "33333333333333"]
            }
        ]
    }
}

平台下发修改拓扑命令

// 平台下发
{
    "msgid": 123,
    "timestamp": 1638869990,
    "sn": "1234567890123",
    "method":"call_topo",
    "payload":{
        "cmd":"MODIFY",
        "topoInfo":{
            "com":"uart1",
            "style":"addr/sn",
            "dev":""
        }
    }
}

// 设备回复
{
    "msgid": 123,
    "sn": "1234567890123",
    "timestamp": 1638870100,
    "method": "call_topo",
    "res":1,
    "payload": {
        "cmd": "MODIFY"
    }
}

payload	json类型	说明
cmd	string	GET: 主动获取拓扑信息 MODIFY: 修改拓扑信息（预留）
com	string	端口类型名称
portCnt	int	拓扑结构中使用到的端口总数
topoInfo	array/obj	拓扑信息，元素为端口和此端口下的设备列表
devList	array/string	此端口下每个设备的地址或序列号，按顺序排列

读取设备内数据call_data

平台网站通过此命令读取设备内采集的实时数据或历史数据，回复数据时的JSON字段参考中台。如果是多回路的，则读取所有回路的数据。

此命令还可以使设备向调试平台转发实时数据，持续一段时间后关闭，以避免流量消耗。

平台读取实时数据

// 平台下发
{
    "msgid": 123,
    "timestamp": 1638869990,
    "sn": "1234567890123",
    "method": "call_data",
    "payload": {
        "cmd": "REAL_TIME",
        "com": "uart1",
        "style": "addr/sn",
        "dev": "01234567890123"
    }
}

// 设备回复
{
    "msgid": 123,
    "sn": "1234567890123",
    "timestamp": 1638870100,
    "method": "call_data",
    "res": 1,
    "payload": {
        "cmd": "REAL_TIME",
        "com": "uart1",
        "style": "addr/sn",
        "dev": "01234567890123",
        "realData": {
            "ua":" ",
            "ub":" ",
            ...
        }
    }
}

平台读取历史数据

// 平台下发
{
    "msgid": 123,
    "sn": "1234567890123",
    "timestamp": 1638870100,
    "method": "call_data",
    "payload": {
        "cmd": "HIS_TIME",
        "com": "uart1",
        "style": "addr/sn",
        "dev": "01234567890123",
        "hisTimeStart": "2020-10-01 20:00",
        "hisTimeEnd": "2020-10-01 21:00"
    } 
}

// 设备回复
{
    "msgid": 123,
    "sn": "1234567890123",
    "timestamp": 1638870100,
    "method": "call_data",
    "res": 1,
    "payload": {
        "cmd": "HIS_TIME",
        "com": "uart1",
        "style": "addr/sn",
        "dev": "01234567890123",
        "hisData": [
            {
                "hisTime": "2020-10-01 20:00",
                "ua": " ",
                "ub": " ",
                //……  
            },
            {
                "hisTime": "2020-10-01 20:00",
                "ua": " ",
                "ub": " ",
                //……  
            }
        ]
    }
}

平台打开实时数据推送10分钟

// 平台下发
{
    "msgid": 123,
    "sn": "1234567890123",
    "timestamp": 1638870100,
    "method":"call_data",
    "payload":{
        "cmd":" AUTO_PUSH",
        "switch":"ON",
        "openTime":10,
        "com": "uart1",
        "style": "addr/sn",
        "dev": "01234567890123",
    }
}

// 设备回复
{
    "msgid": 123,
    "sn": "1234567890123",
    "timestamp": 1638870100,
    "method": "call_data",
    "res":1
}

平台读取设备的开关量和模拟量

// 平台下发
{
    "msgid": 123,
    "sn": "1234567890123",
    "timestamp": 1638870100,
    "method": "call_data",
    "payload":{
        "cmd":"DIDOAI"
    }
}

// 设备回复
{
    "msgid": 123,
    "sn": "1234567890123",
    "timestamp": 1638870100,
    "method": "call_data",
    "res": 1,
    "payload": {
        "cmd": "DIDOAI",
        "di": [1,0,0,0,0,0],
        "do": [1,1,1,1],
        "ai": [12,4905]
    }
}

平台打开实时数据推送10分钟

// 平台下发
{
    "msgid": 123,
    "sn": "1234567890123",
    "timestamp": 1638870100,
    "method":"call_data",
    "payload":{
        "cmd":" AUTO_PUSH",
        "switch":"ON",
        "openTime":10,
        "com": "uart1",
        "style": "addr/sn",
        "dev": "01234567890123",
    }
}

// 设备回复
{
    "msgid": 123,
    "sn": "1234567890123",
    "timestamp": 1638870100,
    "method": "call_data",
    "res":1
}

属性	类型	说明
cmd	string	AUTO_PUSH:实时数据自动推送 REAL_TIME:实时数据 HIS_TIME:历史数据索引 DIDOAI:开关量数据
switch	string	ON/OFF AUTO_PUSH的使能开关
openTime	int	打开时间，到时间关闭单位分范围1-60 默认15分钟
com	string	端口名称
num	int	对应端口下某个设备的地址
devSN	string	设备序列号
hisTimeStart	string	历史数据开始时间
hisTimeEnd	string	历史数据结束时间
realData	object	实时数据内容
hisData	array	历史数据内容，一个时刻一个数组元素
hisTime	string	回复的历史数据时间

平台与设备同步配置文件sync

平台与设备同步配置文件，设备对比版本后，如果设备上的配置文件较新，则上传配置文件到平台；如果平台上的配置文件较新，则下载配置文件到设备。

设备主动上传同步状态 (sys传输中 clt等待传输)

// 平台下发
{
    "msgid": 123,
    "sn": "1234567890123",
    "timestamp": 1638870100,
    "method":"sync",
    "payload":{
        "cmd":"STATUS",
        "status": [
            {"file":"sys.json", "sta":"trans"} , 
            {"file":"clt.json", "sta":"totrans"}
        ]
    }
}

// 设备回复
{
    "msgid": 123,
    "sn": "1234567890123",
    "timestamp": 1638870100,
    "method": "sync",
    "res":1
}

平台网站下发配置文件和版本

// 平台下发
{
    "msgid": 123,
    "sn": "1234567890123",
    "timestamp": 1638870100,
    "method":"sync",
    "payload":{
        "cmd":"CHECK",
        "status": [
            {"file":"sys.json", "url":"http", "ver":"2022-03-20 20:00"} , 
            {"file":"clt.json", "url":"http", "ver":"2022-03-20 21:00"}
        ]
    }
}

// 设备回复
{
    "msgid": 123,
    "sn": "1234567890123",
    "timestamp": 1638870100,
    "method": "sync",
    "res":1
}

属性	类型	说明
cmd	string	CHECK:控制设备检查配置文件版本号 STATUS:同步状态上报

CHECK

属性	类型	说明
fileVer	array	json数组的形式传输文件名称和此文件的版本号。注：以最后一次修改配置文件的时间为版本号,到分钟。格式：yyyy-mm-dd hh:mm { "fileVer":[ { "file":"sys.json", "url":"http://", "ver":"2022-03-20 20:00" } , { "file":"clt.json" , "url":"http", "ver":"2022-03-20 21:00" } ] }

STATUS

属性	类型	说明
status	array	json数组的形式显示文件名称和此文件当前的传输状态，一旦任何一个文件传输状态有变化，会上传此cmd。 totrans：准备传输 trans：传输中 trans_done：传输完成 trans_fail：传输失败例： "status":[ {"file":"sys.json","sta":"trans"} , {"file":"clt.json", "sta":"totrans"} ]

平台与设备传输配置文件config_file

平台网站可以主动获取设备内的配置文件，或者控制设备下载配置文件。平台网站下发method: sync后，通常会使用到此method。

平台控制设备上传文件

// 平台下发
{
    "msgid": 123,
    "sn": "1234567890123",
    "timestamp": 1638870100,
    "method":"config_file",
    "payload":{
        "cmd":"UP",
        "fileList":[
            {
                "fileName":"sys.json",
                "url":"http://IP:PORT/exchange/debug/config_file/upload/AWT200TEST0010/1000"
            },
            {
                "fileName":"clt.json",
                "url":"http://IP:PORT/exchange/debug/config_file/upload/AWT200TEST0010/1000"
            }
        ]
    }
}

// 设备回复
{
    "msgid": 123,
    "sn": "1234567890123",
    "timestamp": 1638870100,
    "method": "config_file",
    "res": 1
}

平台控制设备下载文件

// 平台下发
{
    "msgid": 123,
    "sn": "1234567890123",
    "timestamp": 1638870100,
    "method":"config_file",
    "payload":{
        "cmd":"DOWN",
        "fileList":[
            {
                "fileName":"sys.json",
                "fileSzie":6550,
                "url":"http://1.2.3.4:80/file/sys.json",
                "md5":""
            },
            {
                "fileName":"clt.json",
                "fileSzie":6550,
                "url":"http://1.2.3.4:80/file/clt.json",
                "md5":""
            }
        ]
    }
}

// 设备回复
{
    "msgid": 123,
    "sn": "1234567890123",
    "timestamp": 1638870100,
    "method": "config_file",
    "res": 1
}

平台获取设备的文件列表

// 平台下发
{
    "msgid": 123,
    "sn": "1234567890123",
    "timestamp": 1638870100,
    "method":"config_file",
    "payload":{
        "cmd":"GETLIST"
    }
}

// 设备回复
{
    "msgid": 123,
    "sn": "1234567890123",
    "timestamp": 1638870100,
    "method": "config_file",
    "res": 1
}

平台删除网关内文件

// 平台下发
{
    "msgid": 123,
    "sn": "1234567890123",
    "timestamp": 1638870100,
    "method":"config_file",
    "payload":{
        "cmd":"DELETE",
        "fileList": [ "sys.json" ]
    }
}

// 设备回复
{
    "msgid": 123,
    "sn": "1234567890123",
    "timestamp": 1638870100,
    "method": "config_file",
    "res": 1
}

payload	类型	说明
cmd	string	UP:设备上传文件 DOWN:设备下载文件 GETLIST:平台获取设备内的文件列表 DELETE：平台删除网关内指定名称文件
fileList	array	目标文件列表
fileName	string	文件名称
fileSize	int	文件字节大小
fileVer	string	文件版本
url	string	文件网络地址
md5	string	MD5校验值

19 三月 2026

通用功能

Topic

设备登录login

对时time

发送指令要求设备对时time_sync

设备上报拓扑结构topology

删除设备拓扑topo_clear

上报告警规则

网关上报告警规则alarm_config

直连表上报告警规则

设备重启restart

推送设备升级ota

设备主动请求升级ota_apply

中台获取设备信息ota_info

读取和设置设备参数info

设置平台IP端口

监听设备端口实时报文comtext

获取设备拓扑信息call_topo

读取设备内数据call_data

平台与设备同步配置文件sync

平台与设备传输配置文件config_file