文档中心
机智云 文档中心
English
热搜词
APP
SDK
Android
ios
WIFI
轻网关方案接入机智云流程
文档编辑

修订历史

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

1、本文编写背景

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

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

2.1、轻网关方案的目的

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

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

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

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

2.3、轻网关方案模型

img

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

3.1、网关产品创建

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

img

3.2、子设备产品创建

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

img

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

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

img

3.4、轻网关方案协议获取

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

img

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

img

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

4.1、MCU方案接入

  • MCU方案数据关系图

img

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

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

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

img

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

4.1.1、子设备注册

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

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

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

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

img

步骤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、子设备上下线状态同步

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

img

步骤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、上报子设备业务状态

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

img

步骤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、接收子设备业务状态

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

img

步骤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、轻网关方案设备重置

  • 轻网关方案设备重置

img

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

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

img

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

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

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

4.2、SOC方案接入(自动生成代码)

  • SOC方案数据关系图

img

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

5.1、App接入资料下载

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手册进行查看,也可以参考以下示例代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// 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代理注册子设备时序图

img

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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