|
1. 产品简介1.1. 产品名称1.2. 产品功能 能够连接机智云的通用通讯模块解决方案，硬件平台无关，目前适用于WiFi通讯模块，部分功能规格适用于蓝牙通讯模块。 为各种智能硬件提供连接机智云的能力以及与硬件进行可靠数据通讯的能力。 1.3. 系统结构图1.4. 支持协议1) 机智云平台标准接入协议之App与设备通讯v4.0.1 2) 机智云平台标准接入协议之通用数据点协议v4.0.0 3) 机智云平台标准接入协议之设备与云端通讯v4.0.2 4) 机智云平台标准接入协议之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；机智云开发的各硬件的版本前两字节是“00”，各型号列表如下： 2.2.2. 软件版本号1) 软件版本号使用大中小版本格式，为：XXYYZZZZ; 2) XX：大版本，与协议版本一致，比如V3协议大版本号为03，V4协议大版本号为04； 3) YY：中版本，与驱动lib等相关，从00递增； 4) ZZZZ：小版本，与各种兼容性需求相关； 2.2.3. Firmware版本号(发布日期)1) Firmware版本号用于描述GAgent软件发布的时间，共8字节的用日期和时间来描述； 2) 格式为：年（2位）月（2位）日（2位）时（2位24小时格式），比如：14112521，表示2014年11月25日21点发布的版本。 3) GAgent不固化Firmware版本号，Firmware版本号从OTA升级得到，如果GAgent未从云端获取过Firmware版本号时（第一次烧写bin，数据区Flash中无此数据），GAgent默认使用“00000000”。 2.2.4. 云端OTA原则1) 当上传一个升级固件时，云端完全匹配硬件版本号和软件版本号去查找； 2) 当在上述条件下，若未找到旧的升级固件，云端认为是一个全新的固件型号，将FID标记为1； 3) 若找到已有的升级固件，FID加1； 4) Firmware版本号对于云端判断升级与否没有作用，仅用于增强可读性； 5) Firmware版本号在Site站点上对应的OTA字段信息是“发布日期”； 2.3. 发布名称1) 发布文件（或文件夹）名称由三部分组成：GAgent、硬件版本名称、软件版本、发布日期、特殊标记信息组成； 2) 标准版本，发布bin文件，比如庆科3162版本的某一个版本名称为： GAgent_MX3162_04000001_14112521.bin。 3) 二次开发版本，发布工程文件夹，比如文件夹名称： GAgent_MX3162_04000001_14112521； 4) 汉枫模块需要有特殊标记，比如：GAgent_HFLPB100_04000001_14112521_UART.bin GAgent_HFLPB100_04000001_14112521_WEB.bin 3. 硬件规格1) 环境温度：-20℃~+70℃，正常工作，工作性能符合本规范要求； 2) 相对湿度：0~95%，不凝露； 3) 电源要求：参考各模块厂商规格，通常为3.3V； 4) 工作电流：3.3V电压，平均工作电流小于50mA； 5) 串口设置：波特率：9600bps，数据位：8，校验位：无，停止位：1; 6) GAgent的各种形态均使用相同的硬件规格； 4. 模组状态规格4.1. 指示灯推荐模组提供两个指示灯，一个绿色，一个红色，用于标识模块当前的工作状态； 指示灯含义如下： 说明：为了降低功耗，连接云端正常10分钟，两灯熄灭； 4.2. WiFi工作状态模块要记录如下工作状态，并可将工作状态同步到设备（MCU），要能上报的状态如下： 1) 是否开启 SoftAP 模式； 2) 是否开启 station 模式; 3) 是否开启 onboarding模式； 4) 是否处于可配置状态； 5) WiFi模组是否成功连接路由器; 6) WiFi模组是否成功连接云端; 7) WiFi模块连接的路由器信号强度发生变化，参见下文WiFi信号强度； 8) 是否有APP（客户端）连接到模组； SoftAP、station、onboarding有组合含义，具体参见《机智云平台标准接入协议之MCU与WiFi模组通讯v4.x.x.pdf》 4.3. WiFi信号强度WiFi等级分为以下7个等级，最小为0，最大为80，7个级别采用分段式，如下： 1) 第一级：0（当前信号＝0） 2) 第二级：20（0<当前信号<=20） 3) 第三级：40（20<当前信号<=40） 4) 第四级：50（40<当前信号<=50） 5) 第五级：60（50<当前信号<=60） 6) 第六级：70（60<当前信号<=70） 7) 第七级：80（70<当前信号<=100） 当GAgent检测到的WiFi信号的变化范围大于等于10以后，再去进行信号强度的分类和上报；比如当前值为50，如果检测出来51，信号波动为1，如果检测到信号59，信号波动为9，都不会引起信号级别的重新计算，直到检测出60或者40，波动范围大于等于10以后，再将新的信号强度计算级别，并上报。 4.4. WiFi信号上报原则1) WiFi模块的状态变化上报，WiFi信号跳级时视为变化，上报时按照协议，一次上报所有的状态值； 2) 无论状态是否有变化，每10分钟强制上报一次状态； 3) WiFi连接到路由器后，每3分钟扫描一次WiFi热点，获取当前连接的路由器的信号质量，按照分级原则进行上报； 5. 生产模式当产品大规模生产时，需要解决快速检测的问题，不能对产品原有的生产流程造成很大的冲击；生产模式的统一做法如下： 1) 生产车间配备两个检测用路由器，路由器按照如下信息配置： a) 路由器一：SSID：GIZWITS_TEST_1；PASS: GIZWITS_TEST_PASS；加密方式：WPA2PSK； b) 路由器二：SSID：GIZWITS_TEST_2；PASS: GIZWITS_TEST_PASS；加密方式：WPA2PSK； 2) WiFi模块收到MCU的产测命令后，开始打开产测模式，如果某设备不设置产测按键，可以在设备上电时，由MCU主动发出产测命令，让模组打开产测模式，打开产测模式时，模组每10秒搜索一次周边SSID； 3) WiFi模块打开产测模式后，在3分钟内若搜索出含有“GIZWITS_TEST_”的SSID，判断为生产环境，无论当前的工作状态是什么，随机连接一个生产路由器，按照正常启动过程进行，并且需要将模块处于Station模式，关闭SoftAP模式，关闭AirLink，关闭Onboarding，打开Onbinding； 4) 如果在3分钟内，搜不出含有GIZWITS_TEST_的路由器，将产测模式关闭，不影响当前的工作状态； 5) 使用2台APP设备，分别连接两个路由器进行产测，自动搜索并发送测试指令； 6) 测试完成后，产测工具给模组发送路由器断开指令，模组收到后主动断开，并将模组处于SoftAP模式，关闭Station模式，关闭AirLink，关闭Onboarding，关闭Onbinding； 7) 车间配备两台检测路由的原因是路由器需要定期重启来清除已有连接信息，保证检测正常； 6. 配置模式6.1. 概述1) WiFi模块支持四种配置方式，分别是SoftAP、WebConfig、AirLink、AirKiss； 2) 在实验室测试要求配置成功率不低于99%； 3) 配置重启并且成功连接路由器后（不是上电重启），WiFi模块在上电30秒内发送配置成功包，每一秒一个包，共发送30次；SDK收到此包后，认为配置成功； 6.2. SoftAP1) 热点名称（SSID）：XPG-GAgent-XXXX，XXXX是mac地址后四位且大写； 2) 密码：123456789； 3) IP地址：10.10.100.254 4) UDP配置端口：12414 5) 打开SoftAP模式的方法： a) 用户按某触发键后，MCU发送进入指令； b) WiFi模块中无保存的要连接路由器的SSID信息，默认打开SoftAP模式； 6) 退出机制 a) WiFi模块收到了配置信息后关闭SoftAP模式； b) 10分钟未收到配置信息后，关闭onboard监听和webconfig功能（无网模式，只能处理串口事件）； 7) 路由器搜索功能：在SoftAP模式下，每15秒搜索一次当前的路由器信息，包含：SSID和信号强弱，在SDK获取的时候立即返回； 8) 获取WiFi模块的配置信息：按照协议接收配置信息数据，返回确认数据，不进行密码正确性检查，不做字符转义，保存到flash;保存后重启模组。 9) 进入时设置当前WiFi模块的状态为打开SoftAP，并向MCU同步WiFi状态； 10) 退出时设置当前WiFi模块的状态为关闭SoftAP，并向MCU同步WiFi状态； 11) 指示灯按照约定执行； 6.3. WebConfig1) 当WiFi模块进入SoftAP模式时，使用手机或者PC可以连接到WiFi模块，此时，使用浏览器可以登陆WiFi模块，进行网络配置； 2) WiFi模块的SSID、PASS、IP同SoftAP规格； 3) 浏览器服务端口：80； 4) 支持字符：a-z、A-Z、0-9、‘-’（减号）、‘_’（下划线）、‘.’（小数点）；（后期可以支持可见字符转义） 5) 输入SSID和PASS最长32字节； 6) 收到配置信息后，做合法性检查（长度，非法字符），不合法提示错误信息，合法后提示配置成功； 7) 打开WebConfig和退出WebConfig的方法同SoftAP规格； 8) 指示灯和WiFi状态在进入SoftAP时，按照SoftAP规格执行； 9) 将配置信息保存到flash后重启模块； 6.4. AirLink1) 不同的模块提供的AirLink细节不同，WiFi模块调用厂商提供的系统接口进入AirLink模式； 2) AirLink包含SmartLink、EasyLink等模块厂商提供的快速配置方法； 3) 进入方式： a) 用户触发某按键，按照协议发送进入AirLink的指令； b) 当前状态如果是station，且成功连接路由器，不进入AirLink； 4) 退出方式： a) WiFi模块收到了配置信息后关闭AirLink模式； b) 60秒未收到配置信息后，关闭AirLink模式，尝试恢复配置前的状态； 5) 进入时，设置当前的WiFi状态为开启onboarding，并向MCU同步WiFi状态； 6) 退出时，设置当前的WiFi状态为关闭onboarding，并向MCU同步WiFi状态； 7) 指示灯按照对应的状态显示； 6.5. AirKiss1) AirKiss是微信的快速配置标准； 2) AirKiss的规格与AirLink相同，不做单独处理； 3) 需要厂商同时支持AirLink和AirKiss； 7. 工作模式（小循环）7.1. 发现1) WiFi模块上电后，30秒内，每一秒发送一个上电宣告包，此30秒内，模组可以不相应机智云的发现包，但是要相应其他协议的（比如京东）发现包； 2) 上电宣告包采取广播，广播地址：255.255.255.255，端口：2415； 3) 收到SDK发送的搜索包后，立即回复搜索相应包； 4) 搜索的响应，使用UDP单播； 5) 宣告包和搜索相应包按照协议规定严格执行； 7.2. 获取Passcode1) 模块初始化后，自身随机产生Passcode，用于云端注册和APP绑定的安全鉴权； 2) Passcode为10-32个字节的随机字符串； 3) 模组收到进入配置的命令后（进入AirLink和SoftAP等），按照MCU在握手过程中发送模组的bindable time开启bind功能； 4) 若模组当前未处于bindable状态，获取Passcode的时候返回空的Passcode； 7.3. SDK（APP）登陆1) 模块本地使用TCP长连接与SDK建立通讯； 2) 模块是服务端，SDK是客户端，模块TCP监听端口是12416； 3) SDK与模块建立连接后，需要发送Passcode，模块需要验证Passcode是否匹配，匹配后允许SDK登陆和控制，否则只允许获取Passcode，不接收心跳包等命令； 7.4. 控制与状态1) 模组采用透传的策略将控制数据进行转发； 2) 收到SDK的控制命令时，将Hi包头替换成Hd包头后将数据发送给MCU； 3) 收到云端的控制命令时，将He和Hi包头替换成Hd包头后将数据发送给MCU； 4) 收到MCU的主动状态上报时，先回复ACK，再将Hd包头替换成Hi发送给本地SDK，再添加He包头发送给云端； 5) 当收到MCU对某一个查询命令的返回时，模块仅将数据单独回复给查询命令发起者； 6) 当收到MCU对某一个控制命令的返回时，模块仅将MUC的ACK单独回复给控制命令发起者；然后将MCU上报的状态进行广播，包括服务器； 7.5. 模组和SDK心跳1) 在连续4秒未收到模组数据时，SDK主动向模块发送心跳数据，模块收到后返回心跳确认； 2) SDK连续12秒收不到来自于模块的数据（包含心跳和其他数据），认为与模块连接失效，SDK主动断开与模块的连接； 3) 模块连续12秒收不到来自于SDK的数据（包含心跳和其他数据），认为与SDK连接失效，模块主动断开与模块的连接；（汉枫的描述符个数限制，导致即使释放短时间内也无法使用，需要具体测试）； 7.6. 模组和MCU心跳1) 在连续55秒没有收到MCU数据后，模块主动向MCU发送心跳数据，MCU收到后返回心跳确认； 2) 模组连续180秒收不到来自于MCU的数据（包含心跳和其他数据），认为串口通讯异常，模组自己重启； 3) 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. 名字解释1) DID：机智云给每一个设备分配的唯一ID，字符串；22字节； 2) ProductKey：产品型号唯一ID，字符串；32字节； 3) Passcode：模组随机生成的密码；10字节； 8.2. 模组注册1) 模组需要在云端注册后，才能够正常使用，注册协议使用HTTP API接口，参见模组与服务器通讯协议； 2) 当模组无DID时，按照协议向云端发送注册请求； 3) 注册时，需要给云端提供ProductKey和Passcode； 4) 云端根据ProductKey和Passcode以及随机数生成DID后返回给模组，模组收到后保存到flash中，除非模组被reset，否则一直使用此DID； 5) 注册失败，模组获取不到DID，不进行剩余的云端交互； 8.3. 模组注销当模组收到设备的reset指令后，需要将模组已有的DID进行注销； 8.4. 模组Provision1) 模组获取DID后，可向云端获取M2M服务器地址和端口，参见模组与服务器通讯协议； 2) 获取后到地址和端口后，可以进行M2M服务器登陆； 3) 模组无默认M2M服务器地址和端口，无法获取时，不进行剩余云端操作； 4) 模组每次启动都会进行Provision操作； 5) 模组收到HTTP Server返回9016错误后，不注销DID（如果passcode错误，注销会失败）、重新进行以下过程：注册、Provision、登陆、订阅；收到其他错误字后重新尝试Provision过程； 6) 模组从云端获取此ProductKey是否需要连接第三方云，以及第三方云的关键字，模组根据关键字做云适配（比如打开京东的发现、获取UUID等功能）； 8.5. 模组登陆1) 当获取到要登陆的M2M服务器地址和端口后，模组发起向服务器的TCP长连接，本过程无验证； 2) 登陆时需要向云端发送DID和Passcode以及Keep Alive Timer，模组默认Keep Alive Timer为120秒； 3) 此时不能将模组的状态设置成连接云端成功； 8.6. 模组订阅模组按照协议向云端发起订阅，订阅全部完成后，模组的状态设置成连接云端成功； 8.7. 数据转发1) 模组处理来自于M2M服务器的数据时，需要按照MQTT协议去除掉He包头，此时数据与来自于本地APP的数据完全相同，按照Hi+P0数据格式处理； 2) 模组收到来自于MCU的程序后，如果需要发送给服务器，需按照MQTT协议增加He包头，发送给M2M服务器； 3) 转发规则具体参见协议； 8.8. 与M2M服务器心跳1) 模组登陆M2M服务器成功后，在连续55秒未收到服务器数据时，向服务器发送心跳，服务器收到心跳后立即返回心跳确认； 2) 模组连续120秒没有收到服务器的数据时，认为与M2M服务器的连接异常，断开服务器连接，继续使用当前的M2M服务器地址和端口进行重连； 3) 模组与M2M服务器的连接异常断开后，重连服务器时采取递增策略，即断开后立即重连服务器，仍失败后，等待10秒，再次连接，若仍失败，等待10*2秒后尝试，依此类推，每次重连失败后都延长10秒后再重连； 4) 尝试10次仍然失败时，重新进行Provision； 5) 尝试连接2小时仍然失败时，为防止域名失效等异常，模组重启； 6) 如客户端重启后，按照正常流程从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. OTA1) 模组支持上电版本检查升级和M2M服务器推送升级； 2) 模组在Provision后，登陆M2M服务器之前进行升级检查，尝试一次，HTTP GET超时3秒，得不到返回信息时不重试； 3) 上电检查时，模组向M2M服务器上报DID、ProductKey、升级类型、硬件版本号、软件版本号、当前FID； 4) 如果flash中未保存过FID，或者当前FID为0时，检查升级时，将FID提交为1，但是模组不改变当前FID值； 5) 模组支持自身升级和MCU升级，由升级类型区分； 6) 模组判定M2M服务器返回的FID不等于当前FID时，则按照返回的url进行文件下载并写flash，flash写成功以后，更新当前的FID； 7) 模组根据不同平台特性进行自身的升级处理； 8) 模组对MCU的升级暂不实现； 10. 安全性1) 模组根据平台特点，可以选择支持SSL长连接，SSL只用于大循环； 2) 如果小循环登陆后，SDK或者APP未发送正确的Passcode，如果心跳超时，模组主动断开连接； 11. DNS解析原则1) 模组启动，解析API和M2M服务器域名； 2) 若DNS解析成功，在内存中缓存IP地址； 3) DNS解析失败，不进行和此DNS相关的服务器操作； 4) 模组成功登陆到M2M后，正常工作时，一个小时进行一次M2M域名的DNS解析，如果成功，判断IP地址是否变化，若IP变化，内存中缓存新的IP地址； 5) DNS解析尽量不要对主进程进行阻塞； 12. 故障恢复1) 模块自身具有一定的故障恢复能力，在异常情况下需要自身恢复正常。 2) 可发现路由器掉线，且定时重新连接路由器，若路由器恢复工作，模块则能自动重新连接到路由器，若路由器不能恢复工作，模块一直尝试连接路由器。 3) 任何异常导致的系统崩溃，崩溃后可以立即重启系统，恢复正常工作。 4) 任何异常导致的系统阻塞可以自动重启系统，恢复正常工作，需要模组提供硬件看门狗，模组定期喂狗，看门狗连续5分钟收不到数据，重启系统。 13. 日志1) 模组提供小循环网络日志功能，并可以由SDK关闭或者打开； 2) 模组发布时默认关闭网络日志功能； 3) 使用符合日志协议的客户端连接到模组后，模组可以将日志信息输出到客户端； 4) 模组日志级别按照协议定义实施； 5) 模组可以在SoftAP模式和Station模式下提供日志功能；
| 
发新帖
窥视卡
雷达卡
发表于 2016-7-7 15:59:28
收藏
转播
淘帖
赞一个
踩一下
提升卡
置顶卡
沉默卡
喧嚣卡
变色卡
千斤顶
照妖镜
发表于 2016-11-14 15:10:00
楼主
