开发文档

平台公告

常见问题

硬件接入

开放平台

统计分析

Gokit开发套件

文章标题：《GAgent白皮书》 ［下载］ 更新时间：2015.05.28

术语：

  • GAgent： 运行在可入网模组（WIFI、GPRS）上的应用程序，使模组接入机智云服务器，并上传/接收数据。

  • 业务指令（payload）： 和客户相关，客户定义的产品数据。客户在**开发者中心**上“创建新产品”编辑数据点后，数据点相关的数据，指导请见《数据点编辑指南》。

  • Hi： APP和GAgent间通信协议头。

  • He： APP/GAgent与云端M2M服务器通信协议头。

  • Hd： GAgent与设备间通信协议头。

一、怎么使用demo

说明：该白皮书以x86为平台进行说明。

1.编译

1) [root@localhost gagent2-0]# cd arch/linux/

2) [root@localhost linux]# make clean

3) [root@localhost linux]# make

编译生成的目标文件为：

[root@localhost linux]# ls target/GAgent_linux

target/GAgent_linux

[root@localhost linux]#

以后每次编译重复第2、3步即可。

2.运行

[root@localhost linux]# ./target/GAgent_linux

…………………………

3.硬件连接

该程序运行需要同gokit II代底板进行串口通信。

二、结构框图

IMG_20150528_1

如上图，为GAgent输入输出框图，绿色部分为GAgent在机智云整体方案中所处位置。GAgent在Cloud、APP、MCU三方间做payload数据透传，APP、MCU非必须模块，可根据实际使用场景进行裁剪。

开发者不用关心GAgent内部逻辑，机智云会实时维护该部分代码，如想了解，可详细查看源代码。

三、GAgent参数

  • product key： 重要！产品标识码，32字节。开发者在www.gizwits.com网站定义产品后，由服务器分配，保证唯一性。在网站“产品信息”栏可以得到该信息。GAgent运行需要正确获取该信息，在demo 源码中默认通过和MCU通信获取该信息。需要上传给服务器。

  • passcode： GAgent首次运行时生成的随机数，生成后保存在非易失性存储器上。需要上传给服务器。

  • UDP/TCP socket资源使用： GAgent同服务器建立常连接，占用1个tcp socket通道资源。GAgent创建udp server，占用1个UDP socket通道，并可能再动态分配1个UDP 通道。同APP通信使用TCP socket，GAgent 做server，最大支持8个APP Clietn建立通信。

  • 绑定时间： APP和GAgent建立绑定关系的有效时间。 1.上电后该时间后效； 2.GAgent收到命令要求开启绑定后（MCU发送命令），该绑定时间有效； 3.GAgent切换接入路由器后（如果是通过路由器的话），该绑定时间有效； 4.如果绑定时间为0，代表永久有效；5、默认是通过MCU获取的。

  • 设备属性： 目前支持中控设备（网关）、普通设备、。需要发送给APP。

重要数据结构：

struct GAGENT_CONFIG
{
. int8 wifipasscode[PASSCODE_MAXLEN+1]; /* gagent passcode +1 for printf*/
}
struct _XPG_MCU
{
. uint16  passcodeEnableTime;
. uint16  passcodeTimeout;
. uint8   product_key[PK_LEN+1];
. uint8   mcu_attr[MCU_MCUATTR_LEN];
}
  • 硬件版本号： 见宏WIFI_HARDVER，应满足规格书定义原则。
  • 软件版本号： 见宏WIFI_SOFTVAR，应满足规格书定义原则。版本号大版本、中版本号建议不要修改。
  • Gservice： 建立HTTP短连接，获取设备唯一ID及M2M服务器域名和端口号。
  • M2M服务器： payload业务数据通过M2M服务器发送给GAgent。使用mqtt协议。需要建立一个TCP常连接。

四、目录结构

IMG_20150528_04

五、资源统计

六、API列表说明

详见api接口详细说明：《Gizwits Open API》

重点关注WIFI接口部分。

七、GAgent验证与调试

提供的日志是日志级别为DEBUG级别的日志。修改日志级别见：

GAgent_logevelSet( /*GAGENT_DUMP*/GAGENT_WARNING );

IMG_20150528_02

1.GAgent正常接入GService服务器

获取到GService服务器分配的唯一DID

首次注册需要获取，以后不会再获取。

INFO Need to get did!!!---- 1.请求did

INFO Register got did :BDaJpn3wUXoxPZXivzVRb3 len=22----1.获取到did

或者通过机智云开发者网站进入建立的产品可以查看运行状态：

IMG_20150528_03

获取到M2M服务器的域名和端口号信息

INFO M2M host:m2m.gizwits.com port:1883 ----1.2获取到M2M服务器域名和端口号

2.GAgent正常连接M2M服务器

◎连接M2M服务器，获取到M2M服务器响应

INFO Req to connect m2m !-----2、请求连接m2m服务器

DEBUG GAgent do req connect m2m OK !----2、连接m2m服务器成功

◎成功订阅三个主题：

接收服务器的消息响应： ser2cli_res/ (指代设备的DID)；

接收服务器的消息推送： ser2cli_noti/

接收远程控制指令： app2dev//#(指代设备的DID)

INFO MQTT_STATUS_LOGINTOPIC1----订阅主题1

DEBUG Go to MQTT_STATUS_RES_LOGINTOPIC2. ----主题1定于成功，订阅主题2

DEBUG  Go to MQTT_STATUS_RES_LOGINTOPIC3. ----主题2订阅成功，订阅主题3

CRITICAL GAgent Cloud Working...----主题3订阅成功

◎同服务器心跳正常（55秒一次心跳）

CRITICAL GAgent Cloud Ping ...----GAgent向云端服务器发送心跳包

CRITICAL GAgent Cloud Pong ... ----云端回复心跳包

1） APP可发现GAgent

  • 确保GAgent正常连接路由器；
  • 确保GAgent同APP连接的是同一路由器；
  • 打开APP，点击刷新列表，可在“设备列表”页面正常显示设备名称和设备的MAC地址（即设备列表下方小字体部分）

2） APP正常绑定GAgent

  • 确保第3点正常；
  • 点击设备列表，出现绑定成功消息
APP GAgent
绑定设备请求 -----TCP--- > 请求命令
获取到passcode < ---TCP----- 回复绑定设备请求 
INFO Send passcode(MXRWFRJEPB) to client[6][send data len:20] ----GAgent回复passcode给APP

3. APP在局域网下可登录控制GAgent

APP GAgent
登录设备 ---TCP（发送passcode）--- > 登录命令
登录结果 < ----TCP----- 回复登录设备结果（成功/失败） 
INFO LAN login success! clientid[0]---------APP登录成功

4. APP在广域网下可登录控制GAgent

切换APP到与GAgent不同网络，登录设备并控制。