轻网关方案接入机智云流程

文档编辑

修订历史

版本	修订内容	修订人	修订日期
V1.0	起稿	Bobo	2019/08/13

1、本文编写背景

本文主要介绍了机智云的轻网关解决方案，以及提供轻网关方案的使用流程和工具。

2、轻网关方案简介与概念

2.1、轻网关方案的目的

• 解决蓝牙、433、232、485、zigbee等无法直接接入广域网的产品的入网问题。

• 去除设备之间的差异化，将所有不同品类的设备按照统一的处理方法，开发者不需要了解各个通讯方式的差异性，使用统一的接口即可控制这些设备

2.2、轻网关方案的适用范围

• 一般网关类型的产品都可以适用
• 网关需要使用资源较少，性能较低的模组的产品
• 不要求断网下能够使用的产品

2.3、轻网关方案模型

3、轻网关方案开发前准备

3.1、网关产品创建

• 创建网关产品，技术方案选择网关方案，设备类型选择网关，根据网关的实际情况选择通讯方式，传输方式选择定长的方式。

3.2、子设备产品创建

• 创建子设备产品，技术方案选择网关方案，设备类型选择子设备，根据子设备的实际情况选择通讯方式，传输方式选择定长的方式。

3.3、轻网关方案数据点创建

当创建好子设备产品之后，可以根据子设备的产品功能，创建对应的数据点，例如子设备是一个蓝牙灯泡，具有开关，颜色以及亮度等功能，只需要在子设备产品下创建数据点即可，网关产品不需要。

3.4、轻网关方案协议获取

• 获取网关产品的通讯串口协议，点击产品详情，点击向导的MCU开发资源一栏，获取对应的协议进行下一步的开发

• 获取子设备产品的通讯串口协议，点击产品详情，点击向导的MCU开发资源一栏，获取对应的协议进行下一步的开发

4、轻网关方案硬件接入与开发

4.1、MCU方案接入

• MCU方案数据关系图

• 步骤1、使用自动生成代码或者MCU的通讯协议实现网关设备的基本通讯，可以参考3.4章节获取的网关协议，使得网关设备连上云端。

备注：网关MCU串口通讯协议中的3.1章节，设备属性字段的bit8必须置为1

• 步骤2、连上云端之后，需按照以下流程注册子设备，上报子设备在线状态，上报子设备业务状态等，详情查看以下流程图。

• 步骤3、根据文章的3.4章节与3.5章节，获取协议与资料，下载对应的协议与gGateway的MCU SDK，按照上述流程实现对应功能

4.1.1、子设备注册

当网关连云端之后，首先是注册设备，以下注册设备的方式有两种，本节主要讲解第一种。

1、通过网关去代替子设备向云端注册

2、通过APP去代替子设备向云端注册（详细说明在本文5.3章节）

• 网关代理子设备注册时序图

步骤1、根据本文3.4章节，拿到对应网关产品的MCU通讯协议。

步骤2、查看文档中的5.1（MCU向通讯模组请求子设备请求注册），根据以下表格，向移动通讯模组发送对应的串口数据。

字段序号	字段名称	字节长度	说明
1	固定包头	2	0xFFFF
2	包长度	2	len(命令…校验和)
3	命令(CMD)	1	0x53
4	包序号	1	详情查看MCU通讯协议的2.3章节
5	flags	2	0x0000
6	sub Product Key长度	1	子设备PK长度（通常为32字节）
7	sub Product Key	sPK长度	字符串，子设备PK内容
8	sub Product Secret长度	1	子设备PS长度（通常为32字节）
9	sub Product Serret	sPS长度	字符串，子设备PS内容
10	devExtra	8	子设备对应的设备属性(通常都为0)
11	arglen	1	参数长度(最大8个字节，可以看作消息ID)
12	arg	arglen(max 8)	连接云端标识参数内容
13	is_reset	1	批量注册此值为 0；批量注销此值为 1
14	devNum	1	子设备数量
15	maclen	1	子设备 mac 地址长度(通常在16个字节以内)
16	mac	maclen	字符串，子设备 mac 地址
17	meshIdLen	1	子设备云端标识的长度
18	meshId	meshIdLen	字符串，子设备云端标识的内容
19	校验和	1	详情查看MCU通讯协议的2.3章节

备注：若 14号字段devNum 大于 1 则重复 15-18 字段
备注：meshId：蓝牙mesh设备一般填写mesh网络的id号，其他设备一般使用mac地址作为meshId

步骤3、之后模组会立马回复CMD为0x54的ACK，等待注册完成后，模组会主动推送0x55命令的数据包给到MCU，MCU可以通过子设备的注册结果，判断是否注册成功。

4.1.2、子设备上下线状态同步

• 子设备上下线状态同步时序图

步骤1、查看MCU通讯协议文档中的5.3章节（ MCU向通讯模组发送子设备上下线状态同步），根据以下表格向移动通讯模组发送对应的串口数据

字段序号	字段名称	字节长度	说明
1	固定包头	2	0xFFFF
2	包长度	2	len(命令…校验和)
3	命令(CMD)	1	0x05
4	包序号	1	详情查看MCU通讯协议的2.3章节
5	flags	2	0x0000
6	action	1	0x71
7	子设备状态个数	2	子设备状态信息个数(可同时更新多个设备状态)
8	状态信息		见下表“网关子设备上下线状态信息”
9	校验和	1	详情查看MCU通讯协议的2.3章节

• 网关子设备上下线状态信息

字段序号	字段名称	字节长度	说明
1	子设备meshId长度	1	子设备云端标识长度
2	子设备meshId		字符串，子设备云端标识
3	子设备上下线状态	1	0 表示离线，1 表示在线

步骤2、发送完之后，会立马收到CMD为0x06的数据，之后即可在子产品详情的设备日志或者APP中看到子设备的状态变更。

4.1.3、上报子设备业务状态

• 子设备业务状态上报时序图

步骤1、当子设备上报状态之后，MCU先按照客户自有的私有协议解析出对应的功能点。

步骤2、根据文章3.4章节，下载子设备和网关的MCU通讯协议查看MCU通讯协议文档中的5.5章节（ MCU向通讯模组发送子设备的业务指令），根据以下表格向移动通讯模组发送对应的串口数据。

字段序号	字段名称	字节长度	说明
1	固定包头	2	0xFFFF
2	包长度	2	len(命令…校验和)
3	命令(CMD)	1	0x05
4	包序号	1	详情查看MCU通讯协议的2.3章节
5	flags	2	0x0000
6	action	1	0x73
7	网关子设备数据个数	2	子设备业务数据的个数(可同时上报多个设备状态)
8	网关子设备数据内容		见下表“网关子设备业务数据格式”
9	校验和	1	详情查看MCU通讯协议的2.3章节

• 网关子设备业务数据格式

字段序号	字段名称	字节长度	说明
1	子设备meshId长度	1	子设备云端标识长度
2	子设备meshId		字符串，子设备云端标识
3	业务指令长度	2	网关子设备业务指令所占字节数
4	业务指令内容		见下表”网关子设备action+P0”

• 网关子设备action+P0

字段序号	字段名称	字节长度	说明
1	action	1	0x04
2	dev_status(P0)	（可变）	设备状态，详情查看子设备通讯协议的2.2章节

4.1.4、接收子设备业务状态

• 子设备业务状态接收时序图

步骤1、当APP或者其他业务应用端下发控制指令，设备MCU会立马收到一条CMD为0x03，action为0x72的数据包，具体数据包可以在网关的MCU串口协议获取，也可以参见下表了解协议中的内容。

字段序号	字段名称	字节长度	说明
1	固定包头	2	0xFFFF
2	包长度	2	len(命令…校验和)
3	命令(CMD)	1	0x03
4	包序号	1	详情查看MCU通讯协议的2.3章节
5	flags	2	0x0000
6	action	1	0x72
7	网关子设备数据个数	2	子设备业务数据的个数(可接收上报多个设备状态)
8	网关子设备数据内容		见下表“网关子设备业务数据格式”
9	校验和	1	详情查看MCU通讯协议的2.3章节

• 网关子设备业务数据格式

字段序号	字段名称	字节长度	说明
1	子设备meshId长度	1	子设备云端标识长度
2	子设备meshId		字符串，子设备云端标识
3	业务指令长度	2	网关子设备业务指令所占字节数
4	业务指令内容		见下表”网关子设备action+P0”

• 网关子设备action+P0

字段序号	字段名称	字节长度	说明
1	action	1	0x01
2	attr_flags	(可变)	数据有效标志位，详情查看子设备通讯协议的2.1章节
3	attr_vals	（可变）	设备状态，详情查看子设备通讯协议的2.1章节

步骤2、当收到数据之后，根据子设备的通讯协议，解析对应的P0数据，转换成客户自有的私有协议，发送对应的控制命令，控制对应的子设备。

步骤3、当控制成功之后，重新执行步骤4.1.3，重新上报设备的最新状态。

4.1.5、轻网关方案设备重置

• 轻网关方案设备重置

步骤1、当设备触发重置功能，MCU需要发送命令(cmd)为0x0b的命令给通讯模组，详情查看网关MCU串口通讯协议的3.4章节。

步骤2、当通讯模组收到命令之后，会清空模组的信息并重启，重启之后，会向MCU获取设备信息，这时候需要MCU回复设备的信息，详情查看网关MCU串口通讯协议的3.1章节。

步骤3、这里需要重点关注MCU回复的信息的第12个字段，设备属性，设备属性的第bit9-bit12，具体功能如下表

功能名称	功能描述
网关重置	仅重置网关，清空网关信息，解绑网关与用户的关系，并不会解绑网关与子设备的关系，也不会解绑子设备与用户关系
网关重置+所有子设备重置	重置网关和子设备，解绑网关和子设备之间关系，解绑网关和子设备与用户的关系
所有子设备重置	解绑网关与其之下所有子设备的关系，解绑子设备与用户的关系

步骤4、当通讯模组重新联网之后，重置功能才能生效，如果是WIFI设备，需要重新配网才能生效，GRPS等待其重新连接云端即可。

4.2、SOC方案接入（自动生成代码）

• SOC方案数据关系图

5、轻网关方案App接入与开发

5.1、App接入资料下载

• 使用轻网关方案必须使用最新版本的SDK，最新版本的SDK的下载地址为：https://download.gizwits.com/zh-cn/p/95/97

5.2、App基础接入

• 实现轻网关功能之前，首先需要实现SDK的基础功能，具体功能以及SDK的获取请跳转到以下文档进行查看：

  IOS：http://docs.gizwits.com/zh-cn/AppDev/iOSSDKA2.html

  Android：http://docs.gizwits.com/zh-cn/AppDev/AndroidSDKA2.html

• 这里需要注意，当订阅设备的时候需要订阅子设备和网关设备，都需要改用这个接口【setSubscribe:autoGetDeviceStatus:】，接口的具体使用可以查看上述文档拿到SDK手册进行查看，也可以参考以下示例代码

// mDevice 是从设备列表中获取到的设备实体对象
mDevice.setListener(mListener);
mDevice.setSubscribe(true,false); // 订阅设备，不自动获取设备状态，用于订阅子设备
mDevice.setSubscribe(true,true); // 订阅设备，同时自动获取设备状态，用于订阅网关设备
mDevice.setSubscribe(false,false); // 解除订阅，不获取设备状态
// 实现回调
GizWifiDeviceListener mListener = new GizWifiDeviceListener() {
@Override
public void didSetSubscribe(GizWifiErrorCode result, GizWifiDevice
device, boolean isSubscribed) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 订阅或解除订阅成功
} else {
// 失败
}
}
};

5.3、App代理注册子设备

• App代理注册子设备时序图

步骤1、若子设备是蓝牙设备，可以通过蓝牙的方式获取到子设备的MAC等信息，若是RF，zigbee的设备，可以通过扫描二维码的方式，拿到子设备的MAC等信息，获取了信息之后将调用SDK中的安全注册接口。

步骤2、调用安全绑定接口之前必须先绑定网关设备，拿到网关设备的设备对象，之后调用SDK中的【deviceSafetyRegister】接口，示例代码如下：

GizWifiSDK.sharedInstance().setListener(mListener);
List<ConcurrentHashMap<String, String>> deviceInfos = new ArrayList
<ConcurrentHashMap<String, String>> ();
ConcurrentHashMap<String, String> deviceInfo = new ConcurrentHashMap
<String, String> ();
deviceInfo.put("mac", "device_mac");//子设备mac地址
deviceInfo.put("meshID", "your_meshID");//子设备的meshid，子设备标识
deviceInfo.put("alias", "your_alias");//子设备别名
deviceInfo.put("authCode", "your_authCode");//授权码，需联系机智云客服获取
deviceInfos.add(deviceInfo);
//设备安全注册接口。mDevice 是设备的代理网关
GizWifiSDK.sharedInstance().deviceSafetyRegister(mDevice,
"device_productKey", deviceInfos);
// 实现回调
GizWifiSDKListener mListener=new GizWifiSDKListener() {
@Override
public void didDeviceSafetyRegister(List<ConcurrentHashMap<String,
String>> successDevices, List<ConcurrentHashMap<String,Object>>
failedDevices) {
//接收注册成功和注册失败的设备
}
};

步骤3、注册成功之后，通过设备回调拿到设备对象，按照5.2的流程，执行后续的订阅设备、绑定设备、与控制设备等基础功能即可。

6、FAQ