EEPW论坛

1. 产品简介

1.1. 产品名称

中文名：机智云WIFI 通讯模块 英文名：GAgent

1.2. 产品功能

能够连接机智云的通用通讯模块解决方案，硬件平台无关，目前适用于WiFi通讯模块，部分功能规 格适用于蓝牙通讯模块。 为各种智能硬件提供连接机智云的能力以及与硬件进行可靠数据通讯的能力。

1.3. 系统结构图

1.4. 支持协议

机智云平台标准接入协议之App与设备通讯v4.0.1

机智云平台标准接入协议之通用数据点协议v4.0.0

机智云平台标准接入协议之设备与云端通讯v4.0.2

机智云平台标准接入协议之MCU 与WiFi 模组通讯 v4.0.3

1.5. 模式定义

1.5.1. 生产模式

用于产品大规模生产时的检测场景，参考下文的生产模式详解;

1.5.2. 配置模式

用户第一次使用或者更改网络配置的场景;

1.5.3. 工作模式

产品正常工作时的场景;

2. 产品基础信息

2.1. 产品形态

2.1.1. 标准版本形态

由机智云开发的官方的模块程序，二进制文件形式提供，客户可以直接进行模块生产和升级; 开发和维护均由机智云完成，最稳定的版本形态。

2.1.2. 二次开发版本形态

机智云提供的可供客户二次开发使用的工程目录，不开放源代码，客户可以使用工程目录进行定制 化开发;

2.1.3. 源码形态

机智云对模组合作伙伴开放协议和源码，以及技术支持，合作伙伴可以自行开发能够连接机智云的 模组;机智云提供的源码工程，重点实现协议封装和必要流程封装，配置、OTA 等细节不提供，具体参 见规格书中的说明。

2.2. 产品版本号

2.2.1. 硬件版本号

硬件版本号用于区分硬件平台，需要为每一个硬件型号进行严格区分，合作伙伴的硬件信息也需要 在此做统一管理，8 字节字符串描述，前两个字节表示厂商信息，由机智云统一分配，后6 个字节用于区 分厂商内部版本，由各厂商自由分配，每个字节可使用的字符为：0-9、a-z、A-Z. Gizwits 文档

2.2.2. 软件版本号

软件版本号使用大中小版本格式，为：XXYYZZZZ;

XX：大版本，与协议版本一致，比如 V3 协议大版本号为 03，V4 协议大版本号为 04;

YY：中版本，与驱动 lib 等相关，从 00 递增;

ZZZZ：小版本，与各种兼容性需求相关;

2.2.3. Firmware 版本号(发布日期)

1.Firmware 版本号用于描述 GAgent 软件发布的时间，共8 字节的用日期和时间来描述;

1). 格式为：年(2 位)月(2 位)日(2 位)时(2 位24 小时格式)，比如：14112521，表示2014 年11 月25 日21 点发布的版本。

2.GAgent 不固化 Firmware 版本号，Firmware 版本号从 OTA 升级得到，如果 GAgent 未从云端获取过 Firmware 版本号时(第一次烧写bin，数据区 Flash 中无此数据)，GAgent 默认使用“00000000”。

2.2.4. 云端 OTA 原则

当上传一个升级固件时，云端完全匹配硬件版本号和软件版本号去查找;

当在上述条件下，若未找到旧的升级固件，云端认为是一个全新的固件型号，将 FID 标记为1;

若找到已有的升级固件，FID 加1;

Firmware 版本号对于云端判断升级与否没有作用，仅用于增强可读性;

Firmware 版本号在 Site 站点上对应的 OTA 字段信息是“发布日期”;

2.3. 发布名称

发布文件(或文件夹)名称由三部分组成：GAgent、硬件版本名称、软件版本、发布日期、特殊标 记信息组成;

标准版本，发布bin 文件，比如庆科3162 版本的某一个版本名称为： GAgent_MX3162_04000001_14112521.bin。

二次开发版本，发布工程文件夹，比如文件夹名称： GAgent_MX3162_04000001_14112521;

汉枫模块需要有特殊标记，比如：GAgent_HFLPB100_04000001_14112521_UART.bin GAgent_HFLPB100_04000001_14112521_WEB.bin

3. 硬件规格

环境温度：-20℃~+70℃，正常工作，工作性能符合本规范要求; 2

对湿度：0~95%，不凝露;

电源要求：参考各模块厂商规格，通常为3.3V;

工作电流：3.3V 电压，平均工作电流小于50mA;

串口设置：波特率：9600bps，数据位：8，校验位：无，停止位：1;

GAgent的各种形态均使用相同的硬件规格;

4. 模组状态规格

4.1. 指示灯

推荐模组提供两个指示灯，一个绿色，一个红色，用于标识模块当前的工作状态; 指示灯含义如下：

说明：为了降低功耗，连接云端正常 10 分钟，两灯熄灭;

4.2. WiFi 工作状态

模块要记录如下工作状态，并可将工作状态同步到设备(MCU)，要能上报的状态如下：

是否开启 SoftAP 模式;

是否开启 station 模式;

是否开启 onboarding 模式;

是否处于可配置状态;

WiFi 模组是否成功连接路由器;

WiFi 模组是否成功连接云端;

WiFi 模块连接的路由器信号强度发生变化，参见下文 WiFi 信号强度;

是否有 APP(客户端)连接到模组; SoftAP、station、onboarding 有组合含义，具体参见《机智云平台标准接入协议之MCU 与WiFi 模组 通讯 v4.x.x.pdf》

4.3. WiFi 信号强度

WiFi 等级分为以下 7 个等级，最小为 0，最大为 80，7 个级别采用分段式，如下：

第一级：0(当前信号=0)

第二级：20(0<当前信号<=20)

第三级：40(20<当前信号<=40)

第四级：50(40<当前信号<=50)

第五级：60(50<当前信号<=60)

第六级：70(60<当前信号<=70)

第七级：80(70<当前信号<=100)

当 GAgent 检测到的WiFi 信号的变化范围大于等于 10 以后，再去进行信号强度的分类和上报;比如 当前值为 50，如果检测出来 51，信号波动为 1，如果检测到信号 59，信号波动为 9，都不会引起信号级 别的重新计算，直到检测出 60 或者 40，波动范围大于等于 10 以后，再将新的信号强度计算级别，并上 报。

4.4. WiFi 信号上报原则

WiFi 模块的状态变化上报，WiFi信号跳级时视为变化，上报时按照协议，一次上报所有的状态值;

无论状态是否有变化，每10 分钟强制上报一次状态;

WiFi 连接到路由器后，每3 分钟扫描一次 WiFi 热点，获取当前连接的路由器的信号质量，按照分级 原则进行上报;

5. 生产模式

当产品大规模生产时，需要解决快速检测的问题，不能对产品原有的生产流程造成很大的冲击;生 产模式的统一做法如下：

生产车间配备两个检测用路由器;

WiFi 模块收到 MCU 的产测命令后，开始打开产测模式，如果某设备不设置产测按键，可以在设备 上电时，由MCU 主动发出产测命令，让模组打开产测模式，打开产测模式时，模组每 10 秒搜索一 次周边 SSID;

WiFi 模块打开产测模式后，在 3 分钟内若搜索出产测路由的 SSID，判断为生产环 境，无论当前的工作状态是什么，随机连接一个生产路由器，按照正常启动过程进行，并且需要将 模块处于 Station 模式，关闭 SoftAP 模式，关闭 AirLink，关闭 Onboarding，打开 Onbinding;

如果在3 分钟内，搜不出产测路由器，将产测模式关闭，不影响当前的工作状态;

使用 2 台 APP 设备，分别连接两个路由器进行产测，自动搜索并发送测试指令;

测试完成后，产测工具给模组发送路由器断开指令，模组收到后主动断开，并将模组处于 SoftAP 模 式，关闭 Station 模式，关闭 AirLink，关闭 Onboarding，关闭 Onbinding;

车间配备两台检测路由的原因是路由器需要定期重启来清除已有连接信息，保证检测正常;

6. 配置模式

6.1. 概述

WiFi 模块支持四种配置方式，分别是 SoftAP、WebConfig、AirLink、AirKiss;

在实验室测试要求配置成功率不低于99%;

配置重启并且成功连接路由器后(不是上电重启)，WiFi 模块在上电 30 秒内发送配置成功包，每一 秒一个包，共发送 30 次;SDK 收到此包后，认为配置成功;

6.2. SoftAP

热点名称(SSID)：XPG-GAgent-XXXX，XXXX 是 mac 地址后四位且大写;

密码：123456789;

IP 地址：10.10.100.254

UDP 配置端口：12414

打开 SoftAP 模式的方法： a) 用户按某触发键后，MCU 发送进入指令; b) WiFi 模块中无保存的要连接路由器的 SSID 信息，默认打开 SoftAP 模式;

退出机制 a) WiFi 模块收到了配置信息后关闭 SoftAP 模式; b) 10 分钟未收到配置信息后，关闭 onboard 监听和 webconfig 功能(无网模式，只能处理串口事件);

路由器搜索功能：在 SoftAP 模式下，每15 秒搜索一次当前的路由器信息，包含：SSID 和信号强弱， 在 SDK 获取的时候立即返回;

获取 WiFi 模块的配置信息：按照协议接收配置信息数据，返回确认数据，不进行密码正确性检查， 不做字符转义，保存到 flash;保存后重启模组。

进入时设置当前WiFi模块的状态为打开 SoftAP，并向MCU 同步WiFi状态;

退出时设置当前WiFi模块的状态为关闭 SoftAP，并向MCU 同步WiFi状态;

指示灯按照约定执行;

6.3. WebConfig

当 WiFi 模块进入 SoftAP 模式时，使用手机或者 PC 可以连接到 WiFi 模块，此时，使用浏览器可以 登陆 WiFi 模块，进行网络配置;

WiFi 模块的 SSID、PASS、IP 同 SoftAP 规格;

浏览器服务端口：80;

支持字符：a-z、A-Z、0-9、‘-’(减号)、‘_’(下划线)、‘.’(小数点);(后期可以支持可见字符转 义)

输入 SSID 和PASS 最长 32 字节;

收到配置信息后，做合法性检查(长度，非法字符)，不合法提示错误信息，合法后提示配置成功;

打开 WebConfig 和退出WebConfig 的方法同 SoftAP 规格;

指示灯和WiFi 状态在进入 SoftAP 时，按照 SoftAP 规格执行;

将配置信息保存到 flash 后重启模块;

6.4. AirLink

不同的模块提供的 AirLink 细节不同，WiFi 模块调用厂商提供的系统接口进入 AirLink 模式;

AirLink 包含 SmartLink、EasyLink 等模块厂商提供的快速配置方法;

进入方式： a) 用户触发某按键，按照协议发送进入 AirLink 的指令; b) 当前状态如果是 station，且成功连接路由器，不进入 AirLink;

退出方式： a) WiFi 模块收到了配置信息后关闭 AirLink 模式; b) 60 秒未收到配置信息后，关闭 AirLink 模式，尝试恢复配置前的状态;

进入时，设置当前的 WiFi 状态为开启onboarding，并向 MCU 同步WiFi 状态;

退出时，设置当前的 WiFi 状态为关闭onboarding，并向 MCU 同步WiFi 状态;

指示灯按照对应的状态显示;

6.5. AirKiss

AirKiss 是微信的快速配置标准;

AirKiss 的规格与 AirLink相同，不做单独处理;

需要厂商同时支持 AirLink 和 AirKiss;

7. 工作模式(小循环)

7.1. 发现

WiFi 模块上电后，30 秒内，每一秒发送一个上电宣告包，此 30 秒内，模组可以不相应机智云的发 现包，但是要相应其他协议的(比如京东)发现包;

上电宣告包采取广播，广播地址：255.255.255.255，端口：2415;

收到 SDK 发送的搜索包后，立即回复搜索相应包;

搜索的响应，使用UDP 单播;

宣告包和搜索相应包按照协议规定严格执行;

7.2. 获取 Passcode

模块初始化后，自身随机产生 Passcode，用于云端注册和 APP 绑定的安全鉴权;

Passcode 为10-32 个字节的随机字符串;

模组收到进入配置的命令后(进入AirLink和SoftAP等)，按照MCU在握手过程中发送模组的bindable time 开启 bind 功能;

若模组当前未处于 bindable 状态，获取Passcode的时候返回空的Passcode;

7.3. SDK(APP)登陆

模块本地使用TCP 长连接与 SDK 建立通讯;

模块是服务端，SDK 是客户端，模块 TCP 监听端口是12416;

SDK 与模块建立连接后，需要发送 Passcode，模块需要验证 Passcode是否匹配，匹配后允许 SDK 登 陆和控制，否则只允许获取 Passcode，不接收心跳包等命令;

7.4. 控制与状态

模组采用透传的策略将控制数据进行转发;

收到 SDK 的控制命令时，将 Hi 包头替换成Hd 包头后将数据发送给 MCU;

收到云端的控制命令时，将 He 和 Hi 包头替换成 Hd 包头后将数据发送给MCU;

收到 MCU 的主动状态上报时，先回复 ACK，再将 Hd 包头替换成 Hi 发送给本地 SDK，再添加 He 包头发送给云端;

当收到MCU 对某一个查询命令的返回时，模块仅将数据单独回复给查询命令发起者;

当收到 MCU 对某一个控制命令的返回时，模块仅将 MUC 的 ACK 单独回复给控制命令发起者;然 后将 MCU 上报的状态进行广播，包括服务器;

7.5. 模组和 SDK心跳

在连续4 秒未收到模组数据时，SDK 主动向模块发送心跳数据，模块收到后返回心跳确认;

SDK 连续 12 秒收不到来自于模块的数据(包含心跳和其他数据)，认为与模块连接失效，SDK 主动 断开与模块的连接;

模块连续 12 秒收不到来自于 SDK 的数据(包含心跳和其他数据)，认为与 SDK 连接失效，模块主 动断开与模块的连接;(汉枫的描述符个数限制，导致即使释放短时间内也无法使用，需要具体测 试);

7.6. 模组和 MCU心跳

在连续55 秒没有收到MCU 数据后，模块主动向MCU 发送心跳数据，MCU 收到后返回心跳确认;

模组连续 180 秒收不到来自于 MCU 的数据(包含心跳和其他数据)，认为串口通讯异常，模组自己 重启;

MCU 连续 180 秒收不到来自于模组的数据(包含心跳和其他数据)，认为串口通讯异常，将模组重 启;

7.7. Reset 清空机制

需要清空： 1. DNS解析保存的 IP;第三方(如京东)的设备信息; 2. DID; 3. PASSCODE; 4. 路由器 SSID、路由器 PASS; 说明：不清空 FID;

7.8. ProductKey更改机制

需要清空： 1. DID; 2. PASSCODE; 3. FID; 4. FirmWare Version; 5. 第三方(如京东)的设备信息;

8. 工作模式(大循环)

8.1. 名字解释

DID：机智云给每一个设备分配的唯一 ID，字符串;22 字节;

ProductKey：产品型号唯一 ID，字符串;32 字节;

Passcode：模组随机生成的密码;10 字节;

8.2. 模组注册

模组需要在云端注册后，才能够正常使用，注册协议使用 HTTP API 接口，参见模组与服务器通讯协 议;

当模组无DID 时，按照协议向云端发送注册请求;

注册时，需要给云端提供ProductKey 和Passcode;

云端根据 ProductKey 和 Passcode 以及随机数生成 DID 后返回给模组，模组收到后保存到 flash 中， 除非模组被 reset，否则一直使用此DID;

注册失败，模组获取不到DID，不进行剩余的云端交互;

8.3. 模组注销

当模组收到设备的 reset 指令后，需要将模组已有的DID 进行注销;

8.4. 模组 Provision

模组获取DID 后，可向云端获取M2M 服务器地址和端口，参见模组与服务器通讯协议;

获取后到地址和端口后，可以进行M2M 服务器登陆;

模组无默认 M2M 服务器地址和端口，无法获取时，不进行剩余云端操作;

模组每次启动都会进行Provision 操作;

模组收到HTTP Server 返回 9016 错误后，不注销 DID(如果 passcode 错误，注销会失败)、重新进行 以下过程：注册、Provision、登陆、订阅;收到其他错误字后重新尝试 Provision 过程;

模组从云端获取此 ProductKey 是否需要连接第三方云，以及第三方云的关键字，模组根据关键字做 云适配(比如打开京东的发现、获取 UUID 等功能);

8.5. 模组登陆

当获取到要登陆的 M2M 服务器地址和端口后，模组发起向服务器的 TCP 长连接，本过程无验证;

登陆时需要向云端发送DID 和Passcode 以及Keep Alive Timer，模组默认Keep Alive Timer 为120 秒;

此时不能将模组的状态设置成连接云端成功;

8.6. 模组订阅

模组按照协议向云端发起订阅，订阅全部完成后，模组的状态设置成连接云端成功;

8.7. 数据转发

模组处理来自于M2M 服务器的数据时，需要按照MQTT 协议去除掉 He 包头，此时数据与来自于本 地 APP 的数据完全相同，按照 Hi+P0 数据格式处理;

模组收到来自于MCU 的程序后，如果需要发送给服务器，需按照 MQTT 协议增加 He 包头，发送给 M2M 服务器;

转发规则具体参见协议;

8.8. 与 M2M服务器心跳

模组登陆 M2M 服务器成功后，在连续 55 秒未收到服务器数据时，向服务器发送心跳，服务器收到 心跳后立即返回心跳确认;

模组连续120 秒没有收到服务器的数据时，认为与 M2M 服务器的连接异常，断开服务器连接，继续 使用当前的M2M 服务器地址和端口进行重连;

模组与M2M 服务器的连接异常断开后，重连服务器时采取递增策略，即断开后立即重连服务器，仍 失败后，等待 10 秒，再次连接，若仍失败，等待 10*2 秒后尝试，依此类推，每次重连失败后都延 长10 秒后再重连;

尝试 10 次仍然失败时，重新进行 Provision;

尝试连接2 小时仍然失败时，为防止域名失效等异常，模组重启;

如客户端重启后，按照正常流程从0 秒延迟开始连接服务器;

8.9. MQTT错误字处理

1.错误字0x00

a) 含义：成功;

b) 处理：正常运行;

2.错误字0x01

a) 含义：MQTT 协议版本号不对，目前支持 MQTT 3.1;一般不会有这个问题，除非使用了不对应 版本的 MQTT Client 库。

b) 处理：不重新注册、按照重连服务器机制进行;

3.错误字0x02

a) 含义： i. Client Identifier 长度不对，允许的长度范围应是 1~23B ii. Client Identifier 已被使用。一般这种情况只会出现在手机连接的情况。如是设备使用已在线 的 Client Identifier 连接，会踢前一个 session 下线而不会报这个错误(设备是使用 DID 作 为 Client Ifentifier 的值)。

b) 处理：不重新注册、按照重连服务器机制进行;

4.错误字0x03

a) 含义：服务不可用，机智云M2M 服务器不会向客户端报这个错误。

b) 处理：不重新注册、按照重连服务器机制进行;

5.错误字0x04

a) 含义：用户名和密码(或 DID/Passcode)不正确。对设备来说，也有可能是由于设备已注销了。

b) 处理：不注销 DID(如果 passcode 错误，注销会失败)、重新注册、Provision、登陆、订阅;

6.错误字0x05

a) 含义：非授权访问，机智云M2M 服务器不会向客户端报这个错误。

b) 处理：不重新注册、按照重连服务器机制进行;

9. OTA

模组支持上电版本检查升级和 M2M 服务器推送升级;

模组在 Provision 后，登陆 M2M 服务器之前进行升级检查，尝试一次，HTTP GET 超时 3 秒，得不 到返回信息时不重试;

上电检查时，模组向 M2M 服务器上报DID、ProductKey、升级类型、硬件版本号、软件版本号、当 前 FID;

如果 flash 中未保存过 FID，或者当前 FID 为 0 时，检查升级时，将 FID 提交为 1，但是模组不改变 当前 FID 值;

模组支持自身升级和 MCU 升级，由升级类型区分;

模组判定M2M服务器返回的FID不等于当前FID时，则按照返回的url进行文件下载并写flash，flash 写成功以后，更新当前的 FID;

模组根据不同平台特性进行自身的升级处理;

模组对MCU 的升级暂不实现;

10. 安全性

模组根据平台特点，可以选择支持 SSL 长连接，SSL 只用于大循环;

如果小循环登陆后，SDK 或者 APP 未发送正确的 Passcode，如果心跳超时，模组主动断开连接;

11. DNS解析原则

模组启动，解析 API 和 M2M 服务器域名;

若 DNS 解析成功，在内存中缓存 IP 地址;

DNS解析失败，不进行和此 DNS 相关的服务器操作;

模组成功登陆到 M2M 后，正常工作时，一个小时进行一次 M2M 域名的 DNS 解析，如果成功，判 断 IP 地址是否变化，若IP 变化，内存中缓存新的 IP 地址;

DNS解析尽量不要对主进程进行阻塞;

12. 故障恢复

模块自身具有一定的故障恢复能力，在异常情况下需要自身恢复正常。

可发现路由器掉线，且定时重新连接路由器，若路由器恢复工作，模块则能自动重新连接到路由器， 若路由器不能恢复工作，模块一直尝试连接路由器。

任何异常导致的系统崩溃，崩溃后可以立即重启系统，恢复正常工作。

任何异常导致的系统阻塞可以自动重启系统，恢复正常工作，需要模组提供硬件看门狗，模组定期 喂狗，看门狗连续 5 分钟收不到数据，重启系统。

13. 日志

模组提供小循环网络日志功能，并可以由 SDK 关闭或者打开;

模组发布时默认关闭网络日志功能;

使用符合日志协议的客户端连接到模组后，模组可以将日志信息输出到客户端;

模组日志级别按照协议定义实施;

模组可以在 SoftAP 模式和 Station 模式下提供日志功能;