GoKit3 8266版 程序移植开发（非代码自动生成方式）

true

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

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

  文章写得正式了些，还请各位海涵


目录

1. 前序        
1.1 总介绍        
1.2 相关介绍        
2. 编辑数据点        
3. 修改程序        
3.1 修改程序PK        
3.2 修改数据结构        
3.2.1 控制型协议数据结构修改        
1) 位段使用说明        
3.2.2 上报型协议数据结构修改        
3.2.3 枚举事件修改        
3.2.3 宏定义修改        
3.3 修改“可写类型”相关代码        
3.3.1 写类型事件的生成        
3.3.2 写类型事件的处理        
2) 控制型数据点数据转换        
3) 网络字节序转化        
3.4 修改“只读类型”相关代码        
3.4.1 只读类型数据获取        
4) 上报型数据点数据转换        
3.4.2 数据主动上报        
3.4.3 可写型数据获取        
3.5 配置入网相关程序        
3.6 外设驱动相关代码        
3.6.1 外设驱动介绍        
3.6.2 外设驱动使用方法        
4. 调试程序        
4.1 使用串口输出工具打印LOG信息        
4.2 使用Demo APP进行配置与测试        
5. 相关支持

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版 程序移植开发的讲解，希望大家看在楼主辛苦导图片的份上多多点赞，谢谢！

true

先占个沙发

tesla

写得好详细，感谢楼主！

bigfanofloT

goodgood

晕船海盗

很好的教程，楼主辛苦了

bigfanofloT

szuser

很好的教材, 学习了。
请教楼主,  你能用 手机 APP 找到 ESP8266设备吗?   我编译过这个 SOC，  下载到ESP8266 后, 可以上传数据, 但手机没法找到设备(手机可以给ESP8266 设置路由的SSID, 但就是看不到设备)

BlueTaro

太长啦，看不懂，不过话说，在8266上开发，要不要看8266的硬件数据手册啊~用来驱动我的外设~

追随梦想

才开始搞机智云，很多东西都不清楚，这个文章学习了，慢慢研究

DDDDDDDD

很好的教程，楼主辛苦了

true

szuser 发表于 2016-11-3 11:09
很好的教材, 学习了。
请教楼主,  你能用 手机 APP 找到 ESP8266设备吗?   我编译过这个 SOC，  下载到ESP8 ...

你修改PK了吗？ 新版的示例程序默认没有PK，你需要在云端自己的账号内创建一个一模一样的“微信宠物屋”产品，并将对应的PK 修改到自己的代码中，然后重新烧录8266，才能正常运行。

true

BlueTaro 发表于 2016-11-3 18:32
太长啦，看不懂，不过话说，在8266上开发，要不要看8266的硬件数据手册啊~用来驱动我的外设~ ...

当然可以啦，这样才能开发出好玩的产品。

BlueTaro

true 发表于 2016-11-16 19:31
当然可以啦，这样才能开发出好玩的产品。

要？？？我不懂的，你来上传一些资料~

true

BlueTaro 发表于 2016-11-16 23:50
要？？？我不懂的，你来上传一些资料~

这个在"官网文档中心"就有详细的资料：
http://docs.gizwits.com/zh-cn/de ... 89%8B%E5%86%8C.html

true

BlueTaro 发表于 2016-11-3 18:32
太长啦，看不懂，不过话说，在8266上开发，要不要看8266的硬件数据手册啊~用来驱动我的外设~ ...

看不懂这种详细开发也不要紧，可以先用官方的“代码自动生成工具”：
http://docs.gizwits.com/zh-cn/de ... B7%A5%E5%85%B7.html
先把代码自动生成出来，然后再看我这篇详解试着修改源代码,这样更容易理解。

true

DDDDDDDD 发表于 2016-11-7 17:26
很好的教程，楼主辛苦了

谢谢啦希望能帮到大家

engcyh

好文章，谢谢分享，留个脚印！