EEPW论坛

之前使用Gokit3做了一些小项目（完全基于官方提供的程序Demo修改的），现在机智云又推出了“云端代码自动生成工具”，这对开发者来说真是方便了不少，但感觉太依赖自动生成的代码会降低对代码的深入理解，并且在一些情况下：例如已经使用了一次代码自动生成工具，进行了一部分开发，后来又修改了云端数据点，这时就不想再自动生成一次了，因为会影响之前的修改的代码，这时就想用“纯移植的方式”开发了。

  故总结了一下之前的开发经验，使用纯移植的方式来讲讲如何进行Gokit的二次开发。  



1. 前序1.1 总介绍 本文基于Gokit3(S)上的二次开发，开发前需了解：
1) GoKit3(S) 基础版教学课程。 2) GoKit3(S) 开发环境搭建教学课程。
本文将以“植物宝”的开发为例来介绍如何在原有代码基础上完成二次开发。
1.2 相关介绍 1) 什么是植物宝？
“植物宝”是用来监控植物所处的环境，并能控制电机吹风，相关数据点定义：

数据点	数据点类型
控制电机定速转动	可写、布尔型
读取环境温度	只读、数值型
读取环境湿度	只读、数值型
读取土壤湿度	只读、数值型

2) GoKit3(S)源码程序下载地址在哪？
http://site.gizwits.com/zh-cn/developer/resource/hardware?type=GoKit

3) GoKit3(S)的二次开发的顺序是什么样的？
a. 云端定义产品数据点。 b. 查看产品的《机智云接入串口通信协议文档》 c. 根据通信协议修改源码程序。 d. 使用串口日志来调试修改程序。
2. 编辑数据点
1)在云端定义产品：植物宝
选择个人项目、点击硬件接入、创建新产品
2)输入自己的产品信息

注： 此示例产品名称示例为“my_plants”，开发者可自定名称。
3)选择手动定义数据点，新建数据点

4)定义电机功能

5)定义室内温度

6)定义室内湿度

7)定义土壤湿度

8)完成定义，选择下一步、下一步、完成

9)下载通信协议文档
在“产品管理”的“产品开发资源”中下载对应的通信协议文档（《my_plants-机智云接入串口通信协议文档》）。

3. 修改程序3.1 修改程序PK 修改代码位置： app\Gizwits\gizwits_protocol.h 中的宏定义：PRODUCT_KEY 解释： PK的作用是将开发者在云端定义的产品与Gokit上运行的程序联系起来。
修改：

注： 1. 将程序中的”your_product_key”替换为云端的PK 2. 程序中的PK保留英文型双引号
3.2 修改数据结构3.2.1 控制型协议数据结构修改 修改代码位置： app\Gizwits\gizwits_protocol.h 中的gizwits_attr_flags、gizwits_attr_vals结构体。
 
 

解释： 结构体gizwits_attr_flags、gizwits_attr_vals分别对应《通信协议文档》中的“4.10 WiFi模组控制设备”中的：attr_flags(1B) + attr_vals(6B)位：
 

程序修改： 根据协议文档“4.10 WiFi模组控制设备”中的相关说明修改相应程序：
 

特别说明： 1) 位段使用说明 uint8_t motor_switch:1; 是一种位段的使用方式。因为 uint8_t型数据占用 8bit（8位）的空间，协议中motor_switch占用字段bit0（第一位）所以uint8_t motor_switch:1表示使用1位的空间。 uint8_t reserve:7;因为程序中申请内存时的最小单位是byte(字节)，而这里我们是按bit(位，8bit = 1byte)进行了使用，故需补齐不足1byte的剩余bit(使用n bit后需补齐剩余的8-n bit)，否则会造成数据读写错误。
3.2.2 上报型协议数据结构修改 修改代码位置： app\Gizwits\gizwits_protocol.h 中的dev_status_t结构体。
 

解释： 对应《机智云设备串口通讯协议》中“4.9 设备MCU向WiFi模组主动上报当前状态”中的：dev_status(11B) 位：
 
[size=10.5000pt] 
程序修改： 根据协议文档“4.9 设备MCU向WiFi模组主动上报当前状态”中的修改相应程序： [size=10.5000pt] 
 
[size=10.5000pt] 
修改相应程序：
 

3.2.3 枚举事件修改 代码位置： app\Gizwits\gizwits_protocol.h 中 EVENT_TYPE_T 枚举结构： [size=10.5000pt] 
 

说明： 在该枚举结构中定义写类型枚举事件。
程序修改： 根据协议文档“4.10 WiFi模组控制设备”定义写类型数据点枚举事件（电机控制为例）：
 [size=10.5000pt]
[size=10.5000pt] 3.2.3 宏定义修改
代码位置： app\Gizwits\gizwits_protocol.h 中 “数据点相关定义”部分：
 [size=10.5000pt] 

说明： 根据“数值型”数据点的“分辨率、增量”的值添加对应的宏定义（会在之后的数据转换中用到）。
代码修改： 根据云端定义的数值型数据点： [size=10.5000pt] 

添加相应的宏定义
 [size=10.5000pt]

3.3 修改“可写类型”相关代码 与控制型协议相关的函数调用关系如下：
 [size=10.5000pt]
[size=10.5000pt] 函数调用说明：

函数	说明
giziIssuedProcess	该函数被gagent调用，接收来自云端或app端下发的相关协议数据
ACTION_CONTROL_DEVICE	进行“控制型协议”的相关处理
dataPoint2Event	根据协议生成“控制型事件”
gizEventProcess	根据已生成的“控制型事件”进行相应处理（包括相应的驱动函数）

3.3.1 写类型事件的生成 相关代码位置1： app\Gizwits\gizwits_protocol.c 中 dataPoint2Event() 函数：
 [size=10.5000pt] 
位置1功能说明： 在该函数中完成了写类型外设事件的生成。
位置1程序修改： 根据协议文档“4.10 WiFi模组控制设备”中的数据值(attr_flagss)相关说明：
 [size=10.5000pt] 
位置1修改相应程序：
 [size=10.5000pt] 
3.3.2 写类型事件的处理 相关代码位置2： app\Gizwits\gizwits_product.c 中 gizEventProcess() 函数：
 [size=10.5000pt] 
位置2功能说明： 在该函数中完成了写类型外设的相关处理。
位置2程序修改： 根据协议文档“4.10 WiFi模组控制设备”中的数据值(attr_vals)相关说明：
 [size=10.5000pt] 
[size=10.5000pt] 
位置2修改相应程序： [size=10.5000pt] 
 [size=10.5000pt] 
[size=10.5000pt] 
特别说明： 2) 控制型数据点数据转换 可写、数值型数据点在使用前要转化为可用的数据类型（即使用X2Y()函数），以LED颜色控制为例：
 [size=10.5000pt] 

说明： int32 X2Y(uint32 ratio, int32 addition, uint32 pre_value); Parameters： [in]        ratio         被转换数据点的分辨率。 [in]        addition        被转换数据点的增量。 [in]        pre_value 无符号型的传输数据。 [out] 有符号的原值数据。 [size=10.5000pt] 
3) 网络字节序转化 uint16、uint32型的数据要考虑网络字节序转化（uint16即使用exchangeBytes()函数），以电机控制为例： [size=10.5000pt] 
 [size=10.5000pt] 

3.4 修改“只读类型”相关代码 与上报型协议相关的函数调用关系如下：

函数调用说明：

函数	说明
user_handle	获取上报型数据，并转化为相应的数据类型
gizReportData	按协议类型上报数据
checkReport	判断是否上报当前状态的数据
gagentUploadData	将上报数据发送给Gagent模块

3.4.1 只读类型数据获取 相关代码:   app\user\user_main.c 中 user_handle() 函数：

功能说明： 该函数中完成了只读类型外设的数据获取，并转化为对应的上报型协议数据。
程序修改： 调用只读类型数据的驱动程序接口获取相应数据值，并将数据转化为文档“4.9 设备MCU向WiFi模组主动上报当前状态”中设备状态(dev_status)所对应的上报数据格式（温湿度为例）：



特别说明： 4) 上报型数据点数据转换 只读、数值型数据点在上报前要使用数据传输转化函数Y2X() 转化后直接赋值到对应数据位，及： 说明： int32 Y2X(uint32 ratio, int32 addition, uint32 pre_value); Parameters： [in]        ratio         被转换数据点的分辨率。 [in]        addition        被转换数据点的增量。 [in]        pre_value 有符号的原值数据。 [out] 无符号型的传输数据。
详情请查看《机智云数据点编辑指南》： http://club.gizwits.com/forum.php?mod=viewthread&tid=696&extra=

3.4.2 数据主动上报 相关代码:   app\Gizwits\gizwits_protocol.c 中 checkReport() 函数：

功能说明： 根据协议(“4.9 设备MCU向WiFi模组主动上报当前状态”)相关说明：

在该函数中会判断是否上报当前状态的数据，判断逻辑如下： 1. 控制型数据发生状态变化，立刻主动上报当前状态。 2. 用户触发或环境变化所产生的数据变化，其发送的频率不能快于6秒每次。
程序修改：


3.4.3 可写型数据获取 与上报型协议相关的函数调用关系如下：

函数调用说明：

函数	说明
gizEventProcess	将改变后的“控制型数据”同步给上报型数据的结构体，以便同步数据点的最新状态
checkReport	判断是否上报当前状态数据
gizwitsReportData	完成数据上报的组包操作
UartWrite	将上报数据通过串口发送给WiFi模块

相关代码:   app\Gizwits\gizwits_product.c 中 gizEventProcess() 函数：

功能说明： 获取可写型外设的数据状态，并转化为对应的上报型协议数据。
程序修改： 将可写类型的数据转化为文档“4.9 设备MCU向WiFi模组主动上报当前状态”中设备状态(dev_status)所对应的上报数据格式（电机为例）：


3.5 配置入网相关程序 代码工程默认使用按键检测进入相应的配置模式，分别是：
1) 短按key2键进入：SoftAp配置模式
2) 长按key2键进入：AirLink配置模式
代码位置：         app\user\user_main.c
AirLink模式接口代码: gizSetMode(2);

SoftAp模式接口代码: gizSetMode(1);


注： 开发者可以调用对应模式的接口代码实现自定义的配置入网操作。

3.6 外设驱动相关代码
3.6.1 外设驱动介绍
1) 驱动代码存放位置： app\driver
说明： 相关外设的驱动代码以 ‘.c’ 的型式存放于此处，每个 ‘.c’ 文件实现了一种外设驱动功能，用户可以调用对应驱动接口函数实现相应的功能。Gokit3(S) 提供的默认外设，即相关接口函数有：

外设硬件名称	接口函数说明
hal_motor.c	motorInit() 初始化电机控制 motorControl(0 )表示电机关闭 motorControl(-5~0) 表示电机正传 motorControl(0~5) 表示电机反转
hal_rgb_led.c	rgbGpioIni() 初始化RGB LEDt rgbControl(1~255,0,0) 表示亮红灯 rgbControl(0,1~255,0) 表示亮绿灯 rgbControl(0,0,1~255) 表示亮蓝灯
hal_infrared.c	irInit() 初始化红外传感器 irUpdateStatus() 获取红外状态
hal_temp_hum.c	dh11Init() 初始化温湿度传感器 dh11Read() 获取温湿度传感器数值
hal_key.c	keyParaInit() 按键初始化 keyStateRead() 获取按键按当前状态

注：使用外设驱动前确保已初始化相应驱动模块。
开发者可将其它自定义的外设驱动.c文件的放置于此目录下。
2) 驱动头文件位置： app\include\driver
说明： 相关外设的驱动代码对应的头文件以 ‘.h’ 的型式存放于此处，每个 ‘.h’ 文件中存放了对应外设硬件的相关宏定义（如管脚定义、默认参数、函数**等），故开发者使用某外设驱动时要在user_main.c中引用对应的头文件 。
以xx.h为例：#include "driver/xx.h"

3.6.2 外设驱动使用方法
下面以温湿度传感器为例介绍如何使用外设驱动代码：
1) 引用头文件：
代码位置： app\user\user_main.c

2) 驱动初始化：
代码位置： app\user\user_main.c 中的user_init()函数

3) 调用驱动接口函数
代码位置： app\user\user_main.c 中的user_handle()函数

file:///C:\Users\shu\AppData\Local\Temp\ksohtml\wps9E82.tmp.jpg 4. 调试程序 4.1 使用串口输出工具打印LOG信息 1) 程序中的串口初始化
位置： app\user\user_main.c 中的user_init()函数



说明： i. uart_init_3(UartBautRate uart0_br, UartBautRate uart1_br) Parameters： [in]        uart0_br        设置uart0的波特率，用于数据通信。 [in]        uart1_br        设置uart1的波特率，用于日志输出。
ii. UART_SetPrintPort(uint8 uart_no) Parameters： [in]        uart_no        格式化输出，打印字符串（uart_no = 1 开启日志输出功能）。
2) Gokit连接电脑后确认其对应COM口（不一定是COM4）


注：若不能正常显示需安装驱动( 开发环境工具\CP210x_VCP_Windows.zip )
3) 启动串口工具,选择波特率115200后点击“打开串口”



4.2 使用Demo APP进行配置与测试 1) 设备配置成功后，点击未绑定的设备，会自动绑定成功，此时设备进入可操作设备列表（如下图）

   
您可以对GoKit进行各种控制，也可以收到GoKit返回的各种状态。点击设备，进入设备的操作页面（如下图），可查看串口日志进一步分析。






  至此，便完成了GoKit3 8266版 程序移植开发的讲解，希望大家看在楼主辛苦导图片的份上多多点赞，谢谢！