RT-Thread-packages/GAgent

flyingcys c279a877d5 upate README && demo		8 anni fa
..
images	c8d8bf2002 update source && READMME	8 anni fa
README.md	c279a877d5 upate README && demo	8 anni fa

GAgent of Gizwits in RT-Thread使用手册

1. GAgent package获取：

GAgent of Gizwits in RT-Thread是运行在RT-Thread上的机智云接入package，代码已开源在https://github.com/RT-Thread-packages/GAgent 上。

1.1 RT-Thread env工具：

强烈推荐使用RT-Thread env工具下载配置package。env请在RT-Thread官网->资源->下载处获取。
下载地址：https://www.rt-thread.org/page/download.html

env使用手册请参照RT-Thread官网->文档->用户手册->RT-Thread工具手册
手册地址：https://www.rt-thread.org/document/site/zh/5chapters/01-chapter_env_manual/#env

1.2 GAgent package下载：

运行env工具，进入RT-Thread已支持menuconfig配置的bsp目录，如stm32f429-apollo（也可自行配置Kconfig，方法参照RT-Thread工具手册），运行pkgs --upgrade更新packages list，成功后运行menuconfig命令。

进入RT-Thread online packages菜单，选择IoT -internet of things菜单，进入后选中GAgent： GAgent of Gizwits in RT-Thread。
GAgent有example和debug选项可配置：
> 选中example，package内含GAgent运行demo，可通过finsh或msh启动。
> 选中debug，将打印GAgent运行期间全部日志。

GAgent版本选择：当前GAgent不断优化升级中，推荐使用latest版本。

GAgent package依赖IoT -internet of things中的WebClient、Paho MQTT这2个package，当GAgent被选中，这2个package已自动选中。
由于GAgent使用了2个subscribe topic，所以必须配置Paho MQTT中的Max pahomqtt subscribe topic handlers为2。

同时GAgent还用到了security packages中的TinyCrypt中的AES加解密，该package也被自动选中。其他加密算法暂时没有用到，可手工关闭。

在env工具下输入pkgs --update下载package，等待下载完成后，当前stm32f429-apollo目录下的packages下已经有GAgent及其他相关packages。

2. 运行前准备：

2.1 开发者账号注册：

前往机智云开发者中心https://dev.gizwits.com/zh-cn/developer/ 注册开发者账号

2.2 产品创建与定义：

2.2.1 产品创建：
在开发者中心创建新产品页面创建新产品https://dev.gizwits.com/zh-cn/developer/

2.2.2 产品功能定义：
2.2.2.1 在开发向导中定义数据点：

2.2.2.2 创建并修改数据点：

数据点创建/修改请参照机智云相关文档

2.2.3 通讯协议下载：
在开发向导页面下载当前定义产品的通讯协议文档，后续开发会用到。

2.2.4. 获取产品基本信息：
Product_key及Product_Secret是2个创建产品的唯一标识，在GAgent初始化时需要输入，请记录。

2.3 `机智云`APP下载：

在下载中心->开发与调试工具下载机智云Wi-Fi/移动产品调试APP

3. 运行GAgent：

3.1 GAgent example：

如在menuconfig中选中Enable GAgent Example,在编译过程中会加入GAgent package包中example目录下的gagent_cloud_demo.c。该文件完成GAgent初始化、参数读取/写入、命令下发等功能，可通过finsh/msh启动运行。

int gagent_cloud(void)
{
int rc = RT_EOK;

rt_memset(&gagent_param, 0, sizeof(gagent_param));
//
strcpy(gagent_param.product_key, DEMO_PRODUCT_KEY);
strcpy(gagent_param.product_secret, DEMO_PRODUCT_KEY_SECRET);
strcpy(gagent_param.mac, DEMO_MAC);
gagent_param.read_param_callback = gagent_read_param;
gagent_param.write_param_callback = gagent_write_param;
gagent_param.recv_packet_callback = gagent_recv_packet;
//
gagent_cloud_start(&gagent_param);
    
return rc;
}
#ifdef RT_USING_FINSH
MSH_CMD_EXPORT(gagent_cloud, gagent cloud demo);

FINSH_FUNCTION_EXPORT(gagent_cloud, "gagent cloud test");
#endif

3.2 GAgent流程

3.2.1 将新产品注册时候product_key和product_secret填入gagent_param.product_key和gagent_param.product_secret。
3.2.2. gagent_param.mac填入当前产品的mac地址，每个产品下的mac地址不能重复。
3.2.3. 设置read_param_callback、write_param_callback回调函数，分别对应读参数、写参数；这2个回调函数必须实现正确的参数读取与写入。

int gagent_read_param(struct gagent_config *param, rt_uint32_t len)
{
    /* read param */
#ifdef RT_USING_DFS
    int fd;

    fd = open("/sdcard/demo", O_RDONLY, 0);
    if(fd >= 0)
    {
        read(fd, param, len);
        close(fd);
    }
    else
        return -RT_EOK;
#endif
    return RT_EOK;
}

int gagent_write_param(struct gagent_config *param, rt_uint32_t len)
{
    /* write param */

    rt_kprintf("mac:%s", param->mac);
    rt_kprintf("did:%s", param->did);
    rt_kprintf("passcode:%s", param->passcode);
    rt_kprintf("pk:%s", param->pk);
    rt_kprintf("pk_secret:%s", param->pk_secret);
    rt_kprintf("hard_version:%s", param->hard_version);
    rt_kprintf("soft_version:%s", param->soft_version);
    
#ifdef RT_USING_DFS
    int fd;

    fd = open("/sdcard/demo", O_WRONLY | O_CREAT |O_TRUNC | O_BINARY, 0);
    if(fd >= 0)
    {

        write(fd, param, len);
        close(fd);
    }
#endif
    return RT_EOK;

3.2.4. 设置recv_packet_callback回调函数，该回调为APP下发数据包处理函数。

数据包协议请参照2.2.3 通讯协议文档。

设备收到APP下发ACTION_CONTROL命令完成处理后，需使用ACTION_REPORT_STATUS同步状态。

int gagent_recv_packet(rt_uint8_t from, rt_uint8_t action, rt_uint8_t *kv, rt_uint16_t kv_len)
{
/* please read product protocol */
    
static uint8_t power;
    
switch(action)
{
    case ACTION_CONTROL: 
        rt_kprintf("ACTION_CONTROL\r\n");
        power = *(kv + 1);
        rt_kprintf("power:%d\n", power);
        gagent_cloud_send_packet(ACTION_REPORT_STATUS, &power, 1);
    break;

    case ACTION_READ_STATUS:
        rt_kprintf("ACTION_READ_STATUS\r\n");
        gagent_cloud_send_packet(ACTION_READ_STATUS_ACK, &power, 1);
    break;

    case ACTION_TRANS_RECV:
        rt_kprintf("this is your raw data from app\r\n");
    break;
        
    case ACTION_PUSH_OTA:
        rt_kprintf("ACTION_PUSH_OTA\r\n");
    break;
}
    
return RT_EOK;
}

3.2.5. 调用gagent_cloud_start启动GAgent。

3.3 设备主动上报：

设备主动上报使用gagent_cloud_send_packet函数。
int gagent_cloud_send_packet(rt_uint8_t action, rt_uint8_t *buf, rt_uint16_t buf_len);

3.5 设备发现与绑定:

设备正常运行GAgent后，需要与APP正常绑定后才能通过APP控制设备，初始状态APP绑定设备需确保APP与设备处于同一在局域网，否则APP将无法发现设备，发现设备后点击即可绑定。

设备控制

3.6 注意事项:

3.4.1 请关注设备内存大小，内存过小会导致GAgent运行失败。
3.4.2 运行GAgent前请确保设备已连接互联网，并且dns设置正确。
3.4.3 请正确输入product_key和product_secret，否则将导致GAgent连接MQTT服务器失败。
3.4.4 请正确完成GAgent参数保存与读取，否则GAgent将每次都重新注册设备；重新注册设备后，APP上将找不到该设备，需重新绑定。

README.md