1. MixIOT GARDS数据报文规范

• 1. MixIOT GARDS数据报文规范
  • 1.1. 文档说明
    • 1.1.1. 适用对象
    • 1.1.2. 术语和缩略词
    • 1.1.3. 参考资料
  • 1.2. 终端接入方案
  • 1.3. MixIOT GARDS接入流程
  • 1.4. GAROUTE路由协议
    • 1.4.1. 连接说明
    • 1.4.2. 请求报文
    • 1.4.3. 响应报文
  • 1.5. MixIOT GARDS报文协议
    • 1.5.1. MQTT协议说明
      • 1.5.1.1. 开源协议
      • 1.5.1.2. GARDS和标准MQTT区别
      • 1.5.1.3. Connect参数说明
    • 1.5.2. 报文协议
      • 1.5.2.1. 报文主题
      • 1.5.2.2. 报文内容
        • 1.5.2.2.1. 通过Key数据分类
        • 1.5.2.2.2. 报文参考
      • 1.5.2.3. 报文QoS
    • 1.5.3. 报文详细说明
      • 1.5.3.1. r报文
      • 1.5.3.2. n报文
      • 1.5.3.3. i报文
      • 1.5.3.4. e报文
      • 1.5.3.5. d报文

1.1. 文档说明

    本文挡是Mixlinker专为物联网领域的开发人员编写，其目的是帮助开发者搭建安全性能强大的数据通道，方便物联网终端（如工业设备，传感器、或智能家电等）快速接入智物联MixIOT平台。本文档《MixIOT GARDS数据报文规范》是物联网终端接入MixIOT标准协议。

1.1.1. 适用对象

    本文档的目的读者是物联网领域的开发人员。

1.1.2. 术语和缩略词

1.1.3. 参考资料

1. MQTT v3.1.1 OASIS Standard specification
2. JSON(JavaScript Object Notation)
3. MIX.IOT.2012.E.15.07-报文规范

1.2. 终端接入方案

说明

1. 方案1由智物联Aprus/Apieco采集器（适配器）对接工业设备/MES/DCS等，采集设备数据后以标准协议《MixIOT GARDS数据报文规范》上报至MixIOT。
2. 方案2由第三方采集器/软件（非智物联采集器）对接工业设备/MES/DCS等，采集设备数据后以“自有上报协议”上报至MixIOT Dixie，最后由MixIOT Dixie协议转换后上报至MixIOT。MixIOT Dixie涉及将第三方采集器/软件“自有上报协议”转换为MixIOT标准协议，一般都需要定制开发，这里不做详细说明。
3. 方案3由第三方采集器/软件（非智物联采集器）对接工业设备/MES/DCS等，采集设备数据后以标准协议《MixIOT GARDS数据报文规范》上报至MixIOT。

1.3. MixIOT GARDS接入流程

1. 注册终端ID，目前暂未开放自助申请界面，如需注册请联系智物联销售人员。
2. 请求GAROUTE路由服务（参见下文：GAROUTE路由协议），获取将要接入的MixIOT GARDS节点地址（路由服务非必要，可直连MixIOT GARDS节点）
3. 终端基于MQTT协议接入MixIOT GARDS节点（参见下文：MixIOT GARDS报文协议）

1.4. GAROUTE路由协议

    GAROUTE实际上是 GARDS Route的意思，它就是用来告诉接入终端，数据往哪里送。GAROUTE提供路由能力，即终端要接入MixIOT GARDS前，先向GAROUTE寻求GARDS节点地址，终端收到后再行接入该地址。

    GAROUTE路由服务非终端必要接入流程，终端可直连MixIOT GARDS节点。缺点是一旦直连GARDS节点，也就意味着接入终端固定了GARDS节点地址，如后期切换服务器就需要升级终端程序等，带来不便，故建议遵从该流程。

1.4.1. 连接说明

服务地址：garoute.mixiot.top:8000

通信协议：TCP

连接说明：

1. 客户端在和garoute.mixiot.top:8000服务器建立TCP连接之后，必须在10秒之内发出请求数据报文，否则服务端会断开该连接，释放资源。
2. 服务端在发出响应数据报文之后，会主动关闭TCP连接，以释放资源。
3. 客户端在发出请求数据报文之后，必须处于等待状态，等候服务端的响应数据，不可再发送任何数据，如果超时，请断开重新建立连接重新发送请求数据报文。
4. 客户端在收到服务端的响应数据报文之后，应该立即主动关闭TCP连接，以便服务端能快速释放资源。

1.4.2. 请求报文

客户端在连接到garoute.mixiot.top:8000端口之后，需按照如下格式组织请求数据：

Flag：请求标记

一个字节,必须是字符 “?” ，十进制 63，十六进制3f，否则，服务端会拒绝服务，多次尝试会把这些ip加入黑名单

Size：数据大小

表示Command和Payload的长度，用一个字节表示，最大255，big endian方式

Command：命令类型

0: APRUS请求GARDS服务器地址

Payload：请求报文数据

格式：Clientid,IP:PORT;说明：Clientid编号、逗号、IP地址、冒号、端口号字符串拼接。

其中IP和Port是指失效的MixIOT GARDS服务器的地址和端口，如果APRUS直接连接GAROUTE获取地址，没有无效的地址和端口，那么可以直接送Clientid 就可以了。

比如APRUS客户端当前Clientid为 865067021692333,本地保存的服务器地址和端口分别是183.63.53.249 和 1883，那么Payload内容为 865067021692333,183.63.53.249:1883,该字符串的长度是34个字节，外加1个字节的Command，那么Size=35

1.4.3. 响应报文

服务端在接收到来自客户端请求之后，按照一定的算法，返回给客户端一个新的接入地址和端口号，如数格式如下

Size：数据大小

表示Payload的长度，用一个字节表示，最大255，big endian方式

Payload:响应数据报文

格式：IP:PORT,MixIOT_ID

服务器地址（目前为ip4格式）、服务器端口号字符串拼接。如果Payload内容是183.63.53.249:1883,mixlinker那么Size=28；183.63.53.249:1883就是要接入的MixIOT GARDS节点地址（MQTT Server）;Mixlinker就是客户标示（MixIOT_ID），也是MQTT所需的UserName

1.5. MixIOT GARDS报文协议

GARDS(Generic Asynchronous Remote Data Service，即通用异步远程数据服务)服务系统，是深圳智物联公司基于MQTT 3.1.1协议研发的数据软交换系统，同时为了适应物联网的发展需求，在MQTT3.1.1协议的基础上，对于发布主题和订阅做了严格的限定。

GARDS支持标准MQTT协议接入(兼容3.1.1和3.1版本协议)，设备接入GARDS云端后，可以实现终端与GARDS云端的双向通信。具体的MQTT协议请参考MQTT 3.1.1 或 MQTT 3.1 协议文档。

1.5.1. MQTT协议说明

MQTT（Message Queuing Telemetry Transport Protocol）的全称是消息队列遥感传输协议的缩写，是一种基于轻量级代理的发布/订阅模式的消息传输协议，运行在TCP协议栈之上，为其提供有序、可靠、双向连接的网络连接保证，它的设计思想是轻巧、开放、简单、规范，易于实现。这些特点使得它对很多场景来说都是很好的选择，特别是对于受限的环境如机器与机器的通信（M2M）以及物联网环境（IoT）。

MQTT是基于二进制消息的发布/订阅（Publish/Subscribe）模式的协议，最早由IBM提出的，如今已经成为OASIS规范，MQTT是标准物联网协议，用户可以使用丰富的MQTT客户端，使用熟悉的编程语言以及设备平台开发物联网项目。

1.5.1.1. 开源协议

任何符合MQTT3.1.1协议的客户端，都能快速的接入GARDS系统，我们推荐的一些开源的客户端如下：

1.5.1.2. GARDS和标准MQTT区别

1. 支持MQTT 的PUBLISH、SUBSCRIBE、PING、PONG、CONNECT、CONNACK、DISCONNECT、UNSUBSCRIBE等报文
2. 支持Clean Session
3. 支持QoS 0/1/2
4. 支持设置连接保活心跳KeepAlive，默认GARDS服务端在1.5个心跳周期内，既没有收到客户端发布订阅报文，也没有收到PINGREQ心跳报文时，主动心跳超时断开客户端TCP连接
5. 不支持Last Will
6. 不支持Retained Message

1.5.1.3. Connect参数说明

• ClientId 即在上文中注册的终端ID，在GARDS系统中，ClientId必须唯一，一个ClientId只能在GARDS系统保持一个连接会话，如果一个ClientId同时多处或者多地尝试connect，会造成互相踢的局面，最终都不能正常连接到GARDS系统。

• User Name 不能为空，开发者可以向管理员索要。

• Password 不能为空，开发者可以向管理员索要。

• Clean Session 当客户端成功连接到GARDS系统之后，系统会为该次连接创建一个连接会话，该会话的生存期限为48个小时，如果客户端需要接收离线消息，那么设置该值为false，如果不需要离线消息就设置为true。

• Keep Alive 单位为秒，如果客户端在该周期内和GARDS系统没有任何数据交换，在达到该阈值时，客户端应该向GARDS系统发送PINGREQ报文，表示客户端现在还在，如果在达到该阈值时客户端没有发送PINGREQ报文，GARDS系统会在keepalive x1.5秒之后，断开和该客户端的连接，释放系统资源。对于目前的物联网，一般都是在KeepAlive时间内周期性publish某一个主题和payload给GARDS系统，如果没有任何有意义的报文发布，请发布PINGREQ报文。该值的影响GARDS系统的disconnected消息的生成时间，如果遇到网络异常，或者客户端断电，用户对disconnected的时间很关心，那么该值应该设置小一些，接收到设备下线的时间间隔为keepalive x 1.5 秒.

• Protocol Level 协议级别，请设置为 4 。

• Protocol Name 协议名称，请设置为 MQTT 。

• Will 该类参数GARDS系统暂时不做处理。

• Retain 该参数GARDS系统暂不处理。客户端在通过TCP和GARDS系统建立连接之后，必须在10秒之内，发送CONNECT报文，否则GARDS系统会断开该TCP连接。

1.5.2. 报文协议

    针对物联网行业的需求，MixIOT GARDS对报文主题做了一些限定，也就是下文所述报文主题、报文内容、报文QoS规范。

1.5.2.1. 报文主题

特殊说明：

为保证MixiOT基本数据功能，强制要求第三方终端实现r报文。

1.5.2.2. 报文内容

APRUS对文本类主题报文以JSON数据格式打包后发送到云端，对非文本类主题报文二进制打包后发送到云端。

JSON数据结构为{ "key1":"value1", "key2":"value2", ...}的键值对结构。在面向对象的语言中，key 为对象的属性，value 为对应的值。

key必须是以字母开始，后面跟字母或者数字组成的字符串，除此自外不能包含其它字符。对于value的表示，如果事物的某一个属性p，它的值可以确定是整数，假设为10，那么它的JSON表达式为{"p":10} ；如果它的值可以确定是浮点数，假设为20.3，那么它的JSON表达式为{"p":20.3}；如果它的值为一个字符串，那么请对该值使用双引号描述，比如{"p":"on"}；比如一个设备有属性p1类型为整型,值为10，p2类型为浮点型,值为20.3，p3类型为字符串,值为on，那么它的r报文的JSON表达式为{"p1":10,"p2":20.3,"p3":"on"}。

1.5.2.2.1. 通过Key数据分类

物联网数据的分类，不仅是对数据属性的区分，而且可以通过这种分类，对数据的合理性进行验证，并通过这种合理性的验证结果，推导出某种异常（或者正常）趋势的可能性。

APRUS采集到的数据打包后为JSON格式，JSON是由一组或多组”key”:”value”组成，数据分类是基于”key”第一个字符，如L代表STA，L开头的都可认是状态数据；A代表ALERT，A开头的都可认为是报警数据，如下图：

• “L”:状态类 STA，设备的运行状态值

如：主机电流 L1_3_7_0，风机输出电压 L1_3_7_1。

• “E”:事件类 EVNT，设备的事件

可由一些状态参数判断并衍生出来。

如：加卸载事件 E1_3_7_0 由 7 号寄存器 bit0 加卸载状态衍生而来；启停事件 E1_3_7_1由 7 号寄存器 bit1 运行停止状态衍生而来。

• “F”:故障类 FLT，设备的故障信息 如：主电机电流故障 F1_3_7_5，空滤器堵塞 F1_3_7_6。

• “A”:报警类 ALT，设备的报警信息

如：油泵电流报警 A1_3_8_1，油温报警 A1_3_8_2。

1.5.2.2.2. 报文参考

1.5.2.3. 报文QoS

对于消息的QoS(Quality of Service,即服务质量)，设定消息的默认QoS级别如下：

1）状态类消息上报，默认用QoS0

2）事件／告警／故障类消息上报，默认用QoS1

3）反向控制APIP指令默认用QoS2

1.5.3. 报文详细说明

报文分上行报文和下行报文：

• 上行报文为APRUS -> MixIOT GARDS，
• 下行报文为MixIOT GARDS -> APRUS

上下行报文格式均为Json，即{"KEY":"VALUE","KEY":"VALUE",…}；上行报文主题和QOS要明确；所有上行报文和下行报文交互的前提为APRUS成功连接MixIOT GARDS服务器。

文档中会对每个报文做详细解释，包括r、n、i、d报文，r报文APRUS采集对象的数据及相关信息，不同的r报文上报规律不同；n报文APRUS固有属性、自身信息，一定存在且按一定规律上报；i报文是数据终端在冷启动、热启动、复位需要上报的报文；d报文是采集终端的诊断信息，当每次收到diagnose指令之后，采集终端会对自身进行自我检测，检测之后把检测结果上报；e报文是采集终端异常检测程序检测到的确定的异常。

目的为指导开发者规范上行与下行报文，明确规定物联网数据在APRUS -> MixIOT GARDS的交互过程；为使用者提供异常排查信息。

1.5.3.1. r报文

r报文的内容包括两部分。

1.数据终端采集的，被采集对象的数据或相关文本信息，如状态、事件、故障、报警、设定，报文规则如：

STA(状态)类数据，按固定周期(5s，10s，15s，20s，30s，60s，300s);

EVENT(事件)类数据，采集到事件发生时；

FLT(故障)类数据，当采集到故障发生时；

ALT(报警)类数据，当采集到报警发生时；

SET(设定)类数据，当数据采集终端初始化时，以及设定值变化时。

DATA

设备数据，数据包括状态(STA)、报警(ALT)、故障(FLT)、事件(EVENT附加报文)、设备运行状态(Z)。

格式:

{"Lx_x_x":value,"Ex_x_x":value,"Z":value…}

举例:

{"L1_3_0":123.20,"E1_3_6":0,"Z":1}

说明:

2.数据采集终端自身的状态数据，如信号强度、位置信息、L99、升级、数据采集终端运行状态。

CSQ

数据采集终端信号强度，数据采集终端信号强度范围为0~31，可以划分5个等级1~4，等级1为信号最差，等级4为信号最强。

格式:

{"csq":value}

举例:

{"csq":25}

说明:

GPS & BASE

位置信息包括GPS定位信息及基站定位信息，GPS定位信息为主要位置信息，基站定位信息为辅助位置信息，GPS无法定位是通过基站定位进行辅助定位，基站定位位置不准。

格式:

{"gps":"value"}
{"base":"value"}

举例:

{"gps":"22.57970,113.92177"}
{"base":"2866,1089"}

说明:

L99

每小时与每天KEY，给统计程序触发，L99_1为每个整点一刻上报一次；L99_24为每天的零点一刻上报一次，上报的数据关注KEY无需关注VALUE。

格式:

{"L99_1":hour}
{"L99_24":0}

举例:

{"L99_1":3}
{"L99_24":0}

说明:

Upgrade

升级进度报文，远程升级时显示升级进度，如果升级失败显示失败详情；明确当前升级情况。

格式:

{"upgrade":"value","file":"value"}

举例:

{"upgrade":"remosu","file":"10%"}

说明:

MCSTA

智物联采集器状态，采集器自身运行状态检测，自身运行状态正常每隔1小时上报一次value为run报文，自身运行状态不正常每隔1个小时上报value为error报文同时上报一次异常报文(i)。

格式

{"mcsta":"value"}

举例

{"mcsta":"run"}

说明:

1.5.3.2. n报文

n报文是数据终端自身的信息，如数据采集终端标识、硬件版本号、MCU版本号、通讯模块版本号、LUA脚本版本号、位置信息、SIM卡标识等。n报文的上报规则为是数据采集终端上电初始化一定上报或者按照固定周期上报，固定周期上报规则为当LUA版本号为V0时每隔2分钟上报一次，目的为时数据采集终端自动更新脚本为客户所需最新脚本；当LUA版本号为非V0时，说明数据采集终端中已经存在有脚本，每隔4小时上报一次，目的为说明数据采集终端正常运行及触发更新最新LUA脚本。

DEV

采集终端标识，数据采集终端对接的设备(对象)，根据客户的实际使用的设备设定，最好是控制器类型加型号，如西门子S7-200为SIMENSS7-200。

格式

{"DEV":"value"}

举例

{"DEV":"SIMENSS7-200"}

说明:

ICCID

SIM卡标识，SIM卡的ID，每张SIM卡有唯一的标识，此标识可以查看SIM卡的状态，SIM卡的流量等等关于SIM卡的信息，如何数据采集终端出现掉网首先应查看SIM卡的状态。

格式:

{"ICCID":"value"}

举例:

{"ICCID":"898602B5191650139849"}

说明:

GPS & BASE

位置信息包括GPS定位信息及基站定位信息，GPS定位信息为主要位置信息，基站定位信息为辅助位置信息，GPS无法定位是通过基站定位进行辅助定位，基站定位位置不准。

格式:

{"gps":"value"}
{"base":"value"}

举例:

{"gps":"22.57970,113.92177"} {"base":"2866,1089"}

说明:

VER

版本信息，版本信息包括硬件版本信息，MCU版本信息，通讯模块版本信息，LUA脚本版本信息。LUA、MCU、REMOSU版本号规则如下：

格式:

{"LUA":"value","MCU":"value","REMOSU":"value","HW":"value"}

举例:

{"LUA":"MA4207.L.V221.R","MCU":"MA4207.M.V225.R","REMOSU":"MA5207.R.V222.R","HW":"MB:A2-026161724 CB:A2-08xx21709"}

说明:

1.5.3.3. i报文

i报文是数据终端在冷启动、热启动、复位需要上报的报文，此报文内容为数据终端启动检测结果报文，只有结果没有其他，一共对6个单元模块进行检测。

单元模块：HW、LUA、MCU、REMOSU、COLL 、LOCA

检测结果：DiagnosisPassed/DiagnosisFailed/DiagnosisUnkown

上报格式为：

{"HW":"DiagnosisPassed","LUA":"DiagnosisPassed","MCU":"DiagnosisFailed","REMOSU":"DiagnosisFailed","COLL":"DiagnosisFailed","LOCA":"DiagnosisPassed"}

说明:

1.5.3.4. e报文

采集终端异常检测程序检测到的确定的异常，由于会出现断网异常无法上报的情况，因此区分运行异常(RUN)与重连异常(RECONN)，运行异常为联网运行过程中产生的异常，重连异常为在断网时产生的异常，如断开服务器了报文此时无法上报，保存报文在重新成功连接服务器之后将此报文上报。

状态分类：CONN(出现异常时网络正常)，RECONN(出现异常时网络断开)。

异常模块：HW、LUA、MCU、REMOSU、COLL 、LOCA。

上报格式：

{"Sta":"value","Uint":"value","Err":"value"}

说明:

表1

1.5.3.5. d报文

采集终端的诊断信息，当每次收到diagnose指令之后，采集终端会对自身进行自我检测，检测之后把检测结果上报，如果检测完全通过(采集终端无异常)则只有检测结果信息，如果检测不通过(采集终端有异常)则上报检测结果，同时附加异常模块的调试信息。

单元模块：HW、LUA、MCU、REMOSU、COLL 、LOCA。

检测结果：DiagnosisPassed/DiagnosisFailed/DiagnosisUnkown

上报格式：

{"Uint":"MCU","Result":"DiagnosisFailed","Info":"lua task stk over"}
{"Uint":"HW","Result":"DiagnosisUnkown"}
{"Uint":"REMOSU","Result":" DiagnosisPassed ","Info":"Remosu task stop"}

说明：