名词解释

名词	英文	说明
设备管理云服务	Service	本文档中定义的服务端
平台即服务	PAAS	将软件研发的平台（计世资讯定义为业务基础平台）作为一种服务，以SaaS的模式提交给用户。因此，PaaS也是SaaS模式的一种应用。但是，PaaS的出现可以加快SaaS的发展，尤其是加快SaaS应用的开发速度。在2007年国内外SaaS厂商先后推出自己的PAAS平台。
设备	Device	本文档中定义的设备端
负载均衡	LB	负载均衡建立在现有网络结构之上，它提供了一种廉价有效透明的方法扩展网络设备和服务器的带宽、增加吞吐量、加强网络数据处理能力、提高网络的灵活性和可用性。 负载均衡（Load Balance）其意思就是分摊到多个操作单元上进行执行，例如Web服务器、FTP服务器、企业关键应用服务器和其它关键任务服务器等，从而共同完成工作任务。
基于位置的服务	LBS	基于位置的服务，它是通过电信移动运营商的无线电通讯网络（如GSM网、CDMA网）或外部定位方式(如GPS)获取移动终端用户的位置信息（地理坐标，或大地坐标），在地理信息系统（外语缩写：GIS、外语全称：Geographic Information System）平台的支持下，为用户提供相应服务的一种增值业务。
消息队列遥测传输协议	MQTT	MQTT（Message Queuing Telemetry Transport，消息队列遥测传输协议），是一种基于发布/订阅（publish/subscribe）模式的“轻量级”通讯协议，该协议构建于TCP/IP协议上，由IBM在1999年发布。MQTT最大优点在于，可以以极少的代码和有限的带宽，为连接远程设备提供实时可靠的消息服务。作为一种低开销、低带宽占用的即时通讯协议，使其在物联网、小型设备、移动应用等方面有较广泛的应用。MQTT是一个基于客户端-服务器的消息发布/订阅传输协议。MQTT协议是轻量、简单、开放和易于实现的，这些特点使它适用范围非常广泛。在很多情况下，包括受限的环境中，如：机器与机器（M2M）通信和物联网（IoT）。其在，通过卫星链路通信传感器、偶尔拨号的医疗设备、智能家居、及一些小型化设备中已广泛使用。
边缘计算	Edge Computing	边缘计算是指在靠近物或数据源头的一侧，采用网络、计算、存储、应用核心能力为一体的开放平台，就近提供最近端服务。其应用程序在边缘侧发起，产生更快的网络服务响应，满足行业在实时业务、应用智能、安全与隐私保护等方面的基本需求。边缘计算处于物理实体和工业连接之间，或处于物理实体的顶端。而云端计算，仍然可以访问边缘计算的历史数据。
信令	Signaling	通信系统中的控制指令，又称“信令”。它可以指导终端、交换系统及传输系统协同运行，在指定的终端之间建立临时的通信信道，并维护网络本身正常运行。信令系统是通信网的重要组成部分，是通信网的神经系统 。 除了通信时的用户信息（包括话音信息和非话业务信息）以外的控制交换机动作的信号，就是信令信息。

一、概述

1. 背景

在IoT行业中整体解决方案包括很多方向。不同业务的公司提供不同方向的解决方案。现阶段公司提供的解决方案方向为标准化、定制化硬件内容。故为了提高公司在行业内的竞争力，需要可以为客户提供一体化的解决方案建设设备管理系统。方便以后客户进行设备管理的工作。

解决了客户的基本需求之后，为了提高公司以及IoT行业的整体运营水平。可以为IoT行业提供通用的设备管理平台，并在设备管理平台的基础上构建特定业务的能力。为IoT业界建立底层的基础设施，并帮助企业进入IoT快速发展阶段。

作为一个开放的IoT平台，需要可以帮助第三方设备的接入能力。为第三方设备提供管理，业务支撑的功能。所以，需要将IoT云平台的协议部分定义完成并提供给第三方。

2. 目标

为设备管理平台提供统一的对接协议，并制定协议设计中的规则。以方便开发人员、测试人员、第三方厂商进行相关的实现工作。

3. 读者范围

研发人员，测试人员。

二、概要设计

IoT协议是云平台上管理设备的基础部分。在IoT平台上负责设备端与云服务端的通信，并可以通过协议进行设备的认证，鉴权，控制等等功能。

图片.png

上图中箭头指向的内容即是本协议使用的地方。具体协议使用地方为：

• 设备与边缘计算之间；
• 设备与LBS服务器之间；
• 边缘计算与LBS服务器之间；
• 设备与LBS服务器间。

IoT平台协议会涉及到多个方面的内容。其中包括：协议需要处理的业务、协议的流程、协议支持的负载均衡方式、协议通信周期、协议体规范、协议的异常处理、协议的安全性等。以下具体说明这里的项的具体内容。

1. 设备状态机

设备端与服务端的状态有完整的机制去保证。具体状态机为：

图片.png

状态机说明设备的状态以及状态切换规则，便于之后在服务端进行展示。设备状态切换如图上所示，图中箭头说明状态切换的方向。单向箭头说明只能切换到箭头指向的状态，不能切换回来。双向箭头都是在两个状态之间切换。

这里的升级态没有区分版本下载和升级版本这两个阶段，所以在升级过程中是不允许接收命令的操作。升级和命令指令操作是排他关系。

2. 协议完成的业务

IoT平台上协议需要完成的业务有：设备上线、设备下线、配置下发、设备状态上报、命令下发、设备心跳、设备升级。这些业务中需要考虑的内容有很多需要考虑系统的安全性，可靠性，在章节中会详细介绍其中内容。

3. 信令规范

信令是组成协议的原子单元，信令的流程以及处理策略形成完成的协议。每条信令可以由设备端或者服务端发送，然后由对端接收。每条信令都只有两端，但在整体的设计中会包括四个终端：设备端，边缘计算端，LBS服务端，云端。在这四个终端上的通信，只能在上面所说明的几个终端间通信。不允许其他的终端间通讯。

在本节中定义通用的协议内容，具体如下：

• 通信协议
  基础通信协议使用在TCP/IP之上的MQTT，并在MQTT的基础上使用MQTT的SSL进行安全通信的支持。在MQTT协议的支持下，使用TLV（二进制流）的方式进行上层业务的通信。
  通信过程如上图所示，通过MQTT的Broker作为中间的消息交换，将消息发送到所有设备或者部分设备。整体MQTT使用订阅发布者模式进行消息通信，与Http的请求响应方式不同。所以，使用MQTT过程中可以主动向设备端推送消息，不需要必须等待某一次请求之后再做响应。
  图片.png

针对MQTT协议的特性，需要对设备端与服务端使用MQTT的方式进行定义。MQTT协议需要使用Topic进行消息的发送与接收操作。故这里定义云服务平台上使用到的Topic以及使用方式：

编号	Topoic	订阅者	作用	QoS	备注
1	/info	服务端	设备上线信息，配置信息	2
2	/sta	服务端	设备的状态上报，心跳信息	2
3	/alret	服务端	设备的告警信息	2
4	/cmd	设备端	广播式的命令下发与确认	2	升级，重启等
5	/cmd/{设备型号}	设备端	组播式的命令下发与确认	2	升级，重启等
6	/cmd/{设备型号}/{设备MAC}	设备端	单播式的命令下发与确认	2	升级，重启等

MQTT的使用方式定义如下：
1. 订阅者使用MQTT的Topic订阅的方式进行消息接收。
2. 发送者需要将消息发送到特定的Topic中。Topic的定义如上图所示。
3. 订阅者在收到消息之后，必须发送消息确认。可以携带消息已收到，处理已成功等内容作为响应。
4. 消息的发送和接收应该尽量的不带无关字段，保证业务的同时，降低流量。

• 协议头定义
  在通信协议中已经定义协议使用MQTT协议作为承载协议，使用TLV（二进制流）的方式作为应用层处理业务的协议。并在消息接受和发送过程中不允许使用ASCII编码之外的字符进行通信。
  协议头规定协议通信过程中所必须携带的内容。这些内容用于在通信过程中判定最基本的信息。具体协议头的定义使用整体规划的TLV方式。下面定义协议头：

编号	字段	英文	长度字节	说明
1	协议版本	ProtVer	1	为了之后扩展方便，需要使用消息号区分消息协议版本
2	信令号	SigNum	1	描述一条消息具体意义，下面具体定义
3	序列号	Seq	2	为了保证消息是顺序发送与接收的，每次自增
4	消息长度	Length	2	为了校验消息体是否正常，标识消息体长度。

消息头中的有具体的使用的长度为6个字节。这些字节都是使用网络字节序进行网络传输的。具体的字节流方式为：

图片.png

• 协议体定义
  协议体的内容由每个消息具体定义。消息体中也是使用TLV的方式进行编解码，然后在设备端与云服务端都需要编解码操作。所以，需要实现一套Java版的协议编解码包然后提供给设备端和云服务端使用，使用jar包版本控制协议版本。

4. 协议通信周期

在协议通信过程中，消息的上报与下发都需要遵循某种周期。这些周期定义通信过程中的各种事件的发生频率、以及异常的处理情况。在通信过程中可能会遇到各种各样的周期，IoT云平台上使用周期的方式基本上可以定义为以下两种：

• 设备上存储的固定周期配置；
• 服务端下发的周期配置；

使用这些周期的优先级为服务端下发的配置优先级最高，其次是设备端上的配置。在上线过程中会伴随着配置下发，如果配置没有下发或者下发错误。可以使用设备上本地存储的配置进行。

这里定义设备上的默认事件周期：

编号	事件	周期	说明
1	上线	5min	如果未上线，并且设备状态正常，则周期性发送上线消息。只到接收到响应
2	状态	5min	设备上线后，从上线时间点开始隔一个周期发送状态消息
3	心跳	5min	上线后，隔1.5隔周期后发送第一个心跳。
4	告警检测	1min	在设备上做设备的状态检测，如果在这个过程中发生了告警则直接上报。
5	配置下发	0ms	服务端在发送完成上线确认后，立即发送配置下发消息
6	消息确认	0ms	订阅端收到消息之后，需要进行处理，处理完成之后立即返回
7	确认等待	1min	发送端在发送了消息之后，一个周期未得到响应则重发
8	重发次数	3times	在通信过程中发现3个心跳周期都没有接收到任何消息则认为对端已下线。
9	重发间隔	1min	在周期中如果没有得到响应，则尝试重发

5. 协议流程

协议流程主要用来描述设备和服务在交互过程中的交互流程。即在怎样的上下文上等待还是发送怎样的消息。

这里定义的协议都是有两端和多端的情况。Peer-To-Peer是进行两个设备间的通信。多端的是进行广播消息。一般情况下认为服务端为一个端，因为在服务端需要处理大量请求时使用的多节点是用来做负载的。而设备端定义每一个设备为一端，因为每一个设备上的情况都是不一致的，操作过程中需要对每一个设备进行管理。

从整体上规划的内容是设备端都是单个服务端发送消息。服务端可能向一个设备，一组设备，全部设备发送消息。具体的消息发送由业务确定，但整体上一条消息发送必须由另外一条消息确认。

消息流程可以由设备端和服务端功能协商出具体的流程，主要为了满足业务即可。在之后的章节中每个协议定义都会有流程说明。

6. 负载均衡

云平台的地域分布相对来说比较广泛，设备数相对来说也是比较多的。所以，在规划和设计过程中使用LBS和LB解决整体的负载。如下图所示：

使用Local的主机完成地域性的接入工作。使用设备接入层负责vpc上行数据的接入。两种方式完成系统整体的业务需求。

7. 协议安全

从协议角度考虑协议被劫持，在MQTT的基础上使用SSL的方式加强数据传输方案的安全性。并使用TLV的方式将消息进行序列化。

从承载层和业务层都对数据进行了保密处理。

8. 协议异常处理

协议中的异常：整体策略上以重试为主，如果重试多次仍失败后则重新上线。并在这个基础之上辅以异常处理策略解决。

异常处理需要将异常记录到服务端，并在服务端可以展示出在什么时间，发生了什么样的异常，怎样处理恢复的。

在异常的处理过程中比较重要的点是需要记录用户操作。防止在之后用户操作问题造成系统的异常。

9. 开发方法

开发方式需要有Mock服务完成两端的对接工作。并使用协议Jar的方式统一设备端与服务端的协议。

10. 测试方式

测试方式需要进行MQTT客户端模拟器进行协议包的发送与接收。在模拟器上模拟客户端在发生异常以及处理异常时对端的处理。

11. 其他

-流量获取

编号	运营商	网址
1	移动	http://ec.iot.10086.cn/sso/security/login
2	电信	https://www.ct10649.com:4821/ecportal/#
3	联通	https://m2m.10646.cn/

对接过程基本上都一样的，过程是：

• 联系客户经理，向客户经理提供申请开通平台账号。
• 从技术上对接平台，获取流量信息。

然后，咱购买sim卡的时候不是通过客户经理，是通过中间代理商的。代理商不会给咱账号。

在IoT云平台上对设备上的流量使用情况，以及流量使用过程的统计暂时使用设备上上报的内容。在设备上可能统计不准确，之后考虑形成规模之后对Sim卡的购买，销售也做相关的控制。

• 版本编码
  现在系统上使用两个版本号完成版本管理工作。
  • 内部版本号
    事例：

customer=zhilai
project=fengchao
require=R001
hardware=RSC-1320-AB412
baseline=imx6-android4.4-v1
version=0100

内部版本号使用上面6个字段定义。从英文明上既可以指导具体意义。每个字段的长度如下表所示：

字段	长度（字节）
customer	10
project	10
require	4
Hardware	30
baseline	30
version	4

• 外部版本号

外部版本号即呈现给客户的版本号，这里以其中的一个举例：

MTB-911 F010 A712C001B021-20180713

这个版本号总长度为34个字节，我们在协议制定过程中使用40个字节存储外部版本号。
因外部版本号是根据客户的要求确定的，所以不再规定版本号的编码规则。

• 型号编码
  型号编码用来规范之后在协议中使用版本号的方式。

三、信令定义表

1. 协议定义

协议是由信令以及信令间的流程组成的。所以，这里对信令的编码进行定义。在TLV格式中有一个字节专门标识信令号。

信令名	英文名	信令号	作用
设备上线	Online	1	设备上线
消息确认	Result	2	用来确认消息
配置下发	Config	3	配置信息下发
设备状态	Status	4	设备状态上报
状态查询	Query	5	查询设备上的状态
设备告警	Alarm	6	设备上报告警
告警恢复	Recovery	7	设备上告警恢复
设备命令	Command	8	设备命令下发
设备心跳	Heartbeat	9	设备心跳
新版本查询	NewVersion	A	新版本查询
设备升级	Upgrade	B	设备升级命令
升级进度	Progress	C	设备升级进度
升级结果	UpgradeRes	D	版本升级结果
待扩展			等待扩展

对信令号进行统一的编码后，还可以进行扩展。一个字节一共256个编号可以使用，现在使用了12个编号后面的编号留给协议扩展使用。这里的编号顺序基本上按照交互过程中信令使用的顺序进行的编号，可以从一个侧面反映出设备的整体处理过程。

协议扩展时使用顺序编号的方式，不允许跳过某一个编号进行下一个编号的使用。并在扩展信令时需要考虑对一个Modle的双端可获取的问题。即对某一件事物设备端既可以主动通知服务端，也需要服务端可以从设备端读取到。这样对于某些客户关心的内容，而上报不是那么及时时就可以采用服务端手动触发的方式将设备数据获取到。

因为IoT云平台是需要设备常态化在线的，不在线就说明出现故障。所以，在信令定义中不可以出现“设备下线”信令。

2. 协议错误码定义

错误码用来标识错误原因。在代码层次可以一目了然的判断错误原因。并且在响应信令中还包括具体内容，都可以进行相关的错误原因标识工作。

错误码	英文名	返回码	作用
成功	Online	0	成功
通用失败	Fail	1	通用失败
业务失败			扩展
待扩展

3. 协议分类

接下来对上面信令列表中的信令进行了分类，大概分为：

• 设备上线
• 设备配置
• 设备命令
• 设备状态
• 设备心跳
• 设备升级

从名称上就可以知道这些分类负责那些内容。这里概要的说明这些信令都需要流程、处理策略、触发机制、周期、方向，在每一个章节中都会有详细的说明。

四、设备上线协议定义

设备上线是第一条信令，但是不是设备上线准备工作的开始。设备上线过程需要在IoT云平台上配置完成后才允许发送上线消息。设备在IoT平台上包括很多信息，例如：设备型号，MAC地址，告警阈值，升级策略等等。所以，第一步请先到IoT平台上将设备导入，或配置形成一条允许上线的设备后再进行接下来的步骤。

1. 流程

上线过程可以扩展到更前端的协议。上线的设备需要有协议栈的支持，在协议栈的支持下接收和发送TCP/IP数据。然后还需要有MQTT的功能库的支持，这样可以保证业务协议的支撑。再接着才是本文档内定义的协议。

上线过程分两个步骤：设备认证和设备上线。

• 设备认证

上线策略：只有通过设备认证的设备才允许上线。如果没有通过设备认证，则不允许上线操作。

因为在开放的IoT平台上会对设备的归属、设备的使用情况做统计。最终呈现给客户形成收费依据。所以，针对没有通过认证的设备是无法得知设备的归属的，无归属的设备是不允许上线的。

在这里定义的认证过程最好是可以完成LBS的工作。使用如下图所示的方式是最好的LBS协议过程。这样可以在返回认证Token的同时顺带返回相关的LBS服务器信息。

初期阶段在实现MVP时，最好的方式是使用DNS动态获取的方式获得MQTT服务器相关位置然后通过User：Password的方式进行相关的认证工作。具体内容下一节介绍。

• 设备上线

设备上线场景有多重方式触发：升级，上电，掉线，重启。

在做固件升级时，升级完成也伴随着重启的过程。在重启完成后，系统还是会将业务进程进行启动。在业务进程启动完成就需要进行设备上线信令的发送。

设备加电或者上电后，也伴随着设备上系统的启动。如升级一样，设备启动后的第一要务就是进入上线流程。

设备掉线的原因非常多，设备的流量用完、设备的网络不可用、设备故障都是可能的情况。

2. 认证过程

在进行MVP模式平台开发时，我们使用的认证过程为使用MQTT协议中的用户名，密码方式进行。用户名密码具体存储在MongoDB中Device_Auth_Info集合中。密码是设备端发送过来的密码的sha256哈希后的值。

因为设备现实情况的限制，在这里可以定义。定义可以使用MAC地址作为用户名，然后使用MD5哈希过的MAC+型号+“IoT”实现。

在进行IoT云平台全平台开发过程需要使用上面介绍的方案进行设备认证。

3. 信令

• 设备上线信令
  信令方向：设备端->服务端
  信令编号：1（Online）
  信令体：
  本信令是变长信令。信令中会根据网络接入类型填写不同的字段。

编号	字段	英文	长度字节	说明
1	协议头		6	每个信令都必须带协议头。
2	设备物理地址	MAC	6	每个设备的物理地址都是唯一的。所以这里用MAC地址作为设备的唯一标识。
3	客户	customer	10	标识客户
4	项目	Project	10	项目
5	需求	Require	4	说明客户在项目上的具体哪个需求
6	硬件版本	Hardware	30	硬件版本
7	软件基线	Baseline	30	软件基线
8	版本	Version	4	软件版本
9	外部版本	OutterVer	40	外部软件版本
10	网络类型	NetWork	1	每个字节标识一种类型： 1:NB-iot 2:Wifi 3:Eth 4:BigZee 5:扩展使用 每种类型都有它特有的字段，可以进行定义。每种类型的网络连接方式都在下面进行了说明，不在接入类型中则不存在信令中
11	IMEI	IMEI	9	NB-iot，通信用的设备入网许可证号，使用BCD码存储15~17位的数字，如果不全则补F
12	ICCID	ICCID	10	NB-iot，集成电路卡识别码，使用BCD码存储的20位数字。
13	IP地址	IP Addr	4	NB-iot,Wifi,Eth网络方式
14	SSID	SSID	10	Wifi方式，wifi名称
15	带宽	BandWidth	1	ETH,Wifi方式，网络带宽： 1:10M 2:100M 3:1000M

• 设备上线确认信令
  信令方向：服务端->设备端
  信令编号：2（Result）
  信令：

编号	字段	英文	长度字节	说明
1	协议头		6	每个信令都必须带协议头。
2	结果	Result	1	接收到的信令是否处理成功： 0：成功， 其他失败：具体失败错误码的定义由具体业务确定
3	失败原因	Message	100	在失败的情况下才有本字段，本字段最多传输一百个字节

五、设备配置协议定义

1. 流程

存储

设备上线完成后设备端需要知道相关的配置参数。设备根据配置参数再去进行下面相关的设备操作等动作。这里先说明配置的存储方式，帮助之后在设备端、服务端加载配置时使用。配置的存储方式分为三种：
1. 设备端需要存储默认的设备配置信息；
2. 服务端会存储一份默认配置，这份配置可以针对每个设备型号，每个软件版本进行维护。
3. 服务端会存储特定的配置。例如：运维人员给设备设置的特殊参数，给一批设备设置的参数。

加载

存储在不同的位置的配置信息是需要加载或者生效才可以真正的应用到具体场景中。下面说明加载机制：
1. 设备上电之后直接加载设备上的默认存储的配置信息；
2. 上线流程通过后，服务端会下主动的下发配置信息到设备端。设备端在接收到配置信息后应该马上加载配置信息；
3. 设备处于在线状态后，如果服务端发生了配置变更，会主动的发送配置信息给设备。这个时候设备端也是需要马上加载配置信息的。

2. 配置项

配置信息里面可以分为很多种配置项。配置项里面又可以定义具体的配置内容。因为设备上配置的内容较多，需要进行分类管理。

具体的配置包括的项目：

编号	项目	英文	说明	具体字段
1	告警阈值	Alarm Threshold	告警的触发阈值，可以由上下限。	1. CPU 2. 内存 3. 存储 4. 温度 5. 信号 6. 流量
2	网络参数	NetWork	网络的参数信息	1. 生效的网络连接模式 2. 每日流量 3. SSID
3	上报周期	Reporting Cycle	各种消息上报的周期	1. 状态周期 2. 心跳周期
4	策略	Strategy	设备上处理事件的方式选择	1. 下线策略 2. 重试策略 3. 升级策略 4. 新版本查询策略 5. 重启策略 6. 告警扫描策略 7. 告警上报策略 8. 配置生效策略
5	再扩展

3. 配置项编码

在信令码流中定义使用配置项组合的方式进行配置下发。可以进行配置的选择行下发，以支撑流量控制的情况尽量减少数据的传输。所以，必须对配置项进行编码，以接收方和发送方判断具体码流中的配置项。配置项编码如下：

每个编码段都只是用了部分号码。其他的号码可以在之后扩展时使用。

4. 配置项默认值

默认值具体如下图所示：

5. 信令

设备配置信令采用选择组合的信令组织方式进行。具体为选择一些配置项，将这些项的配置加载到二进制流中。在解析的时候按照二进制流前端所说明配置项类型进行解析。

每个配置项在一个信令中尽量不要重复出现。重复出现以最后一次的配置为准。

• 配置下发
  信令方向：服务端->设备端
  信令编号：3（Config）
  信令：

编号	字段	英文	长度字节	说明
1	协议头		6	每个信令都必须带协议头。
2	配置项类型	Type	1	描述具体配置那个配置项。
3	配置项内容	Context	变长	配置项具体的配置内容。 配置项类型和配置项内容不断重复

• 配置下发响应
  信令方向：设备端->服务端
  信令编号：2（Result）

六、设备命令协议定义

设备命令都是从服务端下发命令到设备端。具体命令的处理过程由业务执行方式定义。这里说明命令的规范。在协议扩展中如涉及到其他方式的通信，协议中不予支持。其他通信方式具体使用的通信协议，通信过程由业务确定。例如：抓日志命令，在抓取了日志命令后日志的传输不得使用MQTT协议，具体是使用的协议需要有抓日志业务确定。

设备端必须可以识别命令，并按照命令的动作进行执行。故之后扩展时需要通知服务端和设备端同时进行支持，并在版本号中进行升级。

1. 分类

命令	编码	说明	字段
重启	0	设备重启	无
抓日志	1	抓取设备端日志	分类 策略
定时重启	2	定时重启	时间 是否循环
定时启动	3	设备下电之后定时启动	时间
定时关机	4	设备在线时定时关机	时间
扩展

2. 流程

有服务端下发命令信令到设备端。设备端收到命令信令之后发送响应信令。设备端发送响应后再进行命令的处理流程。处理完成之后的流程还是需要具体业务进行定义的。

3. 信令

• 命令下发信令
  信令方向：服务端->设备端
  信令编号：8（Command）

信令：

编号	字段	英文	长度字节	说明
1	协议头		6	每个信令都必须带协议头。
2	配置项类型	Type	1	描述具体配置那个配置项。
3	配置项内容	Context	变长	配置项具体的配置内容。 配置项类型和配置项内容不断重复

• 命令下发响应信令
  信令方向：设备端->服务端
  信令编号：2（Result）

七、设备状态协议定义

设备的状态可以分为正常状态、异常状态和故障状态。设备上的状态机在第二章中已经说明。在设备处于正常状态下发送的状态信令，设备处于异常状态下需要上报状态信令和告警信令。在设备处于故障状态时无法完成通信，所以，只能处于下线状态。

状态信令中包括设备上主要的一些状态，不携带非主要信息。以这样的方式降低系统对流量，带宽的要求。在告警信令中也是只包含产生告警的告警项，所以，告警信令需要由告警项组织成整体的二进制流。

1. 告警分类

针对设备上不同的部分设计了不同的告警。以及在不同的设备上也会产生设备所特有的告警。告警阈值的计算方式上分为两种：

• 数值型告警
• 百分比型告警
  这两种的计算方式或者触发方式定义了告警中的数值的上报方式。
  在这里定义一些设备的告警分类：

告警	编号	阈值类型	说明
CPU负载	1	百分比	超过CPU负载之后可能不能正常完成业务
内存	2	百分比	超过内存百分比之后不能正常开展业务
存储	3	百分比	超过存储百分比之后不能正常开展业务
主板温度	4	数值	主板温度过温会下线或产生火灾等情况
信号	5	数值	信号是保证通信的基础
流量	6	数值	流量是满足业务要求使用
CPU温度	7	数值	CPU温度过温会下线或其他灾害情况
扩展			编号采用一个字节存储，最多可以有256个

2. 流程

设备上线后再隔一个状态上报周期，开始上报状态信息。在设备上线后，需要进行告警扫描动作，在任何时候告警扫描出告警后，就需要上报告警信息。

设备的告警在上报过程中不需要考虑告警是否已经上报过。告警是否已经上报，是否重复由服务端进行判断。

3. 信令

• 状态上报信令

信令方向：设备端->服务端
信令编号：4（Status）
信令：

编号	字段	英文	长度字节	说明
1	协议头		6	每个信令都必须带协议头。
2	流量	Flow	4	设备端的上行和下行流量的和，单位KB。每个月清空一遍。
3	信号强度	Signal Intensity	1	信号的强度。单位dBm
4	CPU使用率	CPU Rate	2	Cpu使用率
5	CPU温度	CPU temperature	1	Cpu温度
6	内存	Memory	1	内存使用率
7	存储	Storey	1	存储使用率
8	重发次数	Retransmission times	1	失败重试次数，每次收到响应之后清空
9	业务扩展			业务相关字段

• 状态上报响应信令

信令方向：服务端->设备端
信令编号：2（Result）

• 告警上报信令

信令方向：设备端->服务端
信令编号：6（Alarm）
信令：

编号	字段	英文	长度字节	说明
1	协议头		6	每个信令都必须带协议头。
2	告警项类型	Type	1	描述具体告警为那个告警项。
3	告警项项内容	Context	变长	告警项具体的告警内容。 告警项类型和告警项内容不断重复

• 告警上报响应信令

信令方向：服务端->设备端
信令编号：2（Result）

• 告警恢复信令

信令方向：设备端->服务端
信令编号：7（Recovery）
信令：

编号	字段	英文	长度字节	说明
1	协议头		6	每个信令都必须带协议头。
2	告警项类型	Type	1	描述具体告警为那个告警项。
3	告警项项内容	Context	变长	告警项具体的告警内容。 告警项类型和告警项内容不断重复

• 告警恢复响应信令

信令方向：服务端->设备端
信令编号：2（Result）

八、设备心跳协议定义

设备状态保持策略为在一个状态周期内如果有任何消息就说明状态在线，不需要再对设备的状态进行维护。服务端会认为设备在这个迭代内是在线的。在MQTT协议中有相关的心跳保持支持，可以认为在MQTT协议上存在的设备就是在线的设备。

1. 流程

上线后，隔1.5隔周期后发送第一个心跳。

2. 信令

• 心跳信令
  信令方向：设备端->服务端
  信令编号：9（Heartbeat）

信令：

编号	字段	英文	长度字节	说明
1	协议头		6	每个信令都必须带协议头。

• 心跳响应信令
  信令方向：服务端->设备端
  信令编号：2（Result）

九、设备升级协议定义

设备端升级主要涉及到版本管理功能。版本管理功能在服务端使用全量包，差分包，APP包三种管理方式进行版本包的管理。在MVP实现过程中，使用FTP方式作为文件发布的方式。在实现IoT云平台开放式最好的方式需要进行先同步到就近服务器上，再由设备去就近服务器上进行获取。

1. 分类

设备升级可以有多种分类：从系统升级、APP升级。从差分升级、全量升级。以下面表格说明具体意义：

	系统	app
全量	完成系统整体升级	独立APP的全量包升级
差分	从某个确定的版本选择差分包升级到响应版本	无

在设备升级过程中的APP和差分升级的组合现阶段不支持，因为APP包本来就比较小。如果需要可以直接进行，对流量的影响较小。

设备升级还可以按照发起端的不同进行区分。发起端主要可以分为：设备端触发，服务端触发。以下表说明具体意义：

	系统	app
设备端	无	APP升级
服务端	控制升级	控制升级

设备端尽量不要触发系统升级，因为系统升级可能会造成运营人员在未知的情况下对设备进行了升级操作。然后如果升级出现故障，则需要手动恢复。不想APP升级可以重新在升级一遍即可。

2. 流程

• 设备端触发

设备端可以发送NewVersion信令给服务端，用以查询服务端的最新版APP版本。这种场景主要为了满足上层业务在快速的发生变化的情况。可以满足系统快速迭代，快速升级的需求。

服务端在接收到设备端发送的NewVersion信令后，立即响应设备结果信息。响应完成之后，再进行比较与判断，如果判断有新版本就需要再次下发版本升级命令给设备端。

• 服务端触发

服务端触发的版本升级，即为运营人员手动触发。运营人员可以根据各种方式选择要升级的设备，并对设备进行批量，单个升级操作。

设备端升级完成APP后，需要立即上报升级结果。

3. 设备上升级点

设备上有很多内容可以升级，这里定义升级过程中可能会升级到的点。以方便在升级命令中携带，并指明需要升级的软件。下面是设备上的可以升级的升级点：

升级点编号	升级点	英文报名	功能
1	系统	System	整体性升级
2	锁控板固件升级	Firmware	主要用于升级锁控板固件（此项功能预留接口即可，APP端未实现）
3	锁控板中间层APP	BoardDriver	与丰巢客户端交互，控制锁控板、打印机、扫描枪等相关外设
4	记录Log	OemLogcat	用于记录设备运行过程中的日志
5	串口调试APP	ComAssistant	用于调试串口通信

4. 信令

• 新版本查询信令
  信令方向：设备端->服务端
  信令编号：A（NewVersion）
  信令：

编号	字段	英文	长度字节	说明
1	协议头		6	每个信令都必须带协议头。
2	升级点	Upgrade Point	1	设备上的升级点，除系统外所有的升级点都可以。
3	版本	Version	4	版本 App编号和App版本是一个数组

• 新版本查询响应信令
  信令方向：服务端->设备端
  信令编号：2（Result）

• 版本升级信令
  信令方向：服务端->设备端
  信令编号：B（Upgrade）
  信令：

编号	字段	英文	长度字节	说明
1	协议头		6	每个信令都必须带协议头。
2	升级点	Upgrade Point	1	设备上的升级点
3	升级类型	Upgrade Type	1	升级类型： 1：全量升级 2：差分升级
4	版本号	Version	30	版本 只下发单个的升级
5	版本地址	URL	255	版本地址
6	用户名	User	50	用户名
7	密码	Password	50	密码

• 版本升级响应信令
  信令方向：设备端->服务端
  信令编号：2（Result）

• 版本进度信令
  信令方向：设备端->服务端
  信令编号：C（Progress）
  信令：

编号	字段	英文	长度字节	说明
1	协议头		6	每个信令都必须带协议头。
2	待完善			初期阶段不涉及升级进度

• 新版本查询响应信令
  信令方向：服务端->设备端
  信令编号：2（Result）

• 版本升级结果信令
  信令方向：设备端->服务端
  信令编号：B（Upgrade）
  信令：

编号	字段	英文	长度字节	说明
1	协议头		6	每个信令都必须带协议头。
2	升级点	Upgrade Point	1	升级的内容
3	升级结果	Upgrade Result	1	升级结果：0：成功，其他：失败
4	失败原因	Message	100	升级失败时才会携带失败原因

• 版本升级结果响应信令
  信令方向：服务端->设备端
  信令编号：2（Result）

十、遗留问题

1. MQTT客户端选择

https://github.com/mqtt/mqtt.github.io/wiki/libraries