MCU SDK使用说明

MCU SDK使用说明

1.简介

MCU SDK是根据《涂鸦串口通讯协议》、产品功能数据点自动生成的MCU程序架构。工程师可在此基础上进行快速开发。

2.如何获取

打开开发者后台网址 https://iot.tuya.com/

如已建立完产品,在“硬件调试”处 点击下载MCU 开发包

如果您没有贵公司的账号,请与贵司相关领导联系

3.移植须知

MCU SDK包对MCU硬件资源需求Flash 4Kbyte、RAM由DP点数据定义最长长度决定(OTA功能需大于260byte)。函数嵌套级数9级,若资源不足的用户,可自行对接协议。

4.文件结构

文件包括:

执行文件 头文件 说明
mcu_api.c mcu_api.h 内含WiFi相关函数,客户可按需调用
protocol.c protocol.h 协议文件,用户根据项目需求, 需修改这个2个文件,内含数据处理函数
system.c system.h 串口通讯协议的具体实现,可以不做了解
wifi.h WiFi相关宏定义

5.移植流程

5.1 基本移植步骤

1. 将MCU SDK .c.h文件导入单片机工程

2. protocol.h文件移植

​ 1).确认产品信息PID、软件版本、配网方式

​ 2).确认MCU固件是否需要支持固件升级(默认关闭)

​ 3).根据DP点数据,定义收发缓存

​ 4).定义模块工作方式(默认配合处理)

​ 5).确认MCU是否支持校时功能

​ 6).确认是否开启WiFi产测功能(建议开启)

3. protocol.c文件移植及调用

​ 1).在需要使用到wifi相关文件的文件中include "wifi.h"文件

​ 2).在MCU外设初始化后调用mcu_api.c文件中的wifi_protocol_init()函数

​ 3).将串口单字节发送函数填入protocol.c文件中uart_transmit_output函数内,并删除#error

​ 4).在串口接收函数里面调用mcu_api.c文件内的uart_receive_input函数,并将接收到的字符作为参数传入

​ 5).单片机进入while循环后调用mcu_api.c文件内的wifi_uart_service()函数

5.2 移植步骤详解

5.2.1 确认产品信息

打开protocol.h 在开发者后台找到“产品Key” ,请确保代码与网站所列两者一致,该PID为每个产品的唯一标识,必须检查清楚是否为您所对应的产品ID,如果不是,修改为正确的ID;或重新下载最新SDK开发包,重新进行代码移植。版本默认1.0.0,配网方式默认“默认配网”方式。

5.2.2 确认MCU是否需要支固件升级

如需要支持MCU固件OTA升级,请开启该宏

#define         SUPPORT_MCU_FIRM_UPDATE

5.2.3 定义收发缓存(可选)

修改缓冲区大小,根据DP点定义,接收缓存大小要大于数据最长的DP数据长度。默认大小24。需要做MCU OTA升级的用户缓存大小建议大于260字节。

#ifndef SUPPORT_MCU_FIRM_UPDATE
#define WIFI_UART_QUEUE_LMT 16 //数据接收队列大小,如MCU的RAM不够,可缩小
#define WIFI_UART_RECV_BUF_LMT 24 //根据用户DP数据大小量定,必须大于24
#else
#define WIFI_UART_QUEUE_LMT 128 //数据接收队列大小,如MCU的RAM不够,可缩小
#define WIFI_UART_RECV_BUF_LMT 300 //固件升级缓冲区,需大缓存,必须大于260
#endif

5.2.4 定义模块工作方式(必要)

1.如果配网触发及指示由MCU控制(按键和LED接在MCU端),选择“模块和MCU配合处理”工作模式,请保持 define 被注释状态

//#ifdef          WIFI_CONTROL_SELF_MODE

2.如果wifi指示灯和按键是接在wifi模块上的(模块自处理工作模式),那么请开启

#ifdef          WIFI_CONTROL_SELF_MODE

然后根据实际的硬件连接,将指示灯和按键所连接的GPIO脚位填入下面两行

#ifdef          WIFI_CONTROL_SELF_MODE
#define WF_STATE_KEY 14 //wifi模块状态指示按键,请根据实际GPIO管脚设置
#define WF_RESERT_KEY 0 //wifi模块重置按键,请根据实际GPIO管脚设置
#endif

5.2.5 确认MCU是否需要支持校时功能

如需要支持校时功能,请开启该宏

//#ifdef         SUPPORT_MCU_RTC_CHECK //开启校时功能

并在Protocol.c文件内mcu_write_rtctime 实现代码

mcu在wifi模块正确联网后可调用mcu_get_system_time() 函数发起校时功能

####5.2.6 确认是否开启WiFi产测功能(开启)

为保证最终量产效率及品质,建议开启该宏。具体产测功能实现,见文档产测部分。

#define         WIFI_TEST_ENABLE                //开启WIFI产测功能

5.2.7 protocol.c 文件移植及调用

  1. 在需要使用到wifi相关文件的文件中include "wifi.h"文件。如main.c

  2. 在MCU外设初始化后调用mcu_api.c文件中的wifi_protocol_init()函数

  3. 将MCU串口单字节发送函数填入protocol.c文件中uart_transmit_output函数内,并删除#error。例如:

  4. 在串口接收中断服务函数里面调用mcu_api.c文件内的uart_receive_input函数,并将接收到的字符作为参数传入。例如:

  5. 单片机进入while循环后调用mcu_api.c文件内的wifi_uart_service()函数

    main.c中示例代码结构如下:

    include "wifi.h"
    ...

    void main(void)

    {

    wifi_protocol_init();

    ...

    while(1)

    {

    wifi_uart_service();

    ...

    }

    }

    注意:

    MCU必须在while中直接调用mcu_api.c 内的wifi_uart_service() 函数程序正常初始化完成后,建议不进行关串口中断,如必须关中断,关中断时间必须短,关中断会引起串口数据包丢失,请勿在中断/定时器中断内调用上报函数。

6.DP点数据上报和下发函数处理

###6.1 所有DP数据上报

在模块重启或者重新配网后,WiFi模块主动下发状态查询指令,此时需要MCU上报设备所有DP状态 给WiFi模块进行同步

​ 1.打开protocol.c 找到函数wifi_uart_service()

​ 2.把所有需要上报的DP点初值填入相应上报函数,为面板显示提供初值。

用户请勿随意调用all_data_update()函数,该函数会在特定时间主动调用

###6.2 单个DP数据上报

在某DP点状态发生变化时,mcu需要主动上报,APP会更新显示。上报格式为 mcu_dp_xxxx_updata(DPID_X,n),DPID_X为状态改变的DP点。

例如:

mcu_dp_bool_update(DPID_SWITCH,1);                      //BOOL型数据上报
mcu_dp_value_update(DPID_TEMPER_SET,25); //VALUE型数据上报
mcu_dp_string_update(DPID_DAY,"1234",4); //STRING型数据上报
mcu_dp_raw_update(DPID_SWITCH,1); //RAW型数据上报
mcu_dp_bitmap_update(DPID_TEMPER_SET,25); //故障型数据上报
mcu_dp_enum_update(DPID_DAY,"1234",4); //枚举型数据上报

6.3 DP 数据下发处理函数

在protocol.c文件中,每个可下发的DP点,都有一个单独下发数据处理函数。格式为dp_download_``DPX``_handle()DPX为可下发DP点。函数解析功能点之后,用户需映射到相关执行函数,完成具体动作函数。

以接收到开关DP为例:

MCU_ON_switch1()和MCU_OFF_switch1()为MCU控制开关函数,完成具体动作。当设备状态在非APP控制下发生变化,MCU中需要调用mcu_dp_bool_update(DPID_SWITCH_1,switch_1);上传功能点(开关)状态实时状态,形成反馈,一般接收处理函数已经自动调用该函数;

7.移植调试验证

1.连接单片机的串口和电脑的串口

2.打开涂鸦云串口调试助手.exe

3.点击浏览,导入资料包中的json文件,点击启动

8.实现配网功能

当移植协议成功后,要想设备配网,还需要将配网指令及指示完善。模组自处理工作模式的,无需关注此小节。

配合处理模式的MCU,配网触发方式和指示方式,可以根据实际情况自行决定。通常为按键触发和LED快闪/慢闪指示。

配网有两种模式,建议产品都要做上:

smart模式(快闪):操作简便,通常以灯快闪做指示

AP模式(慢闪):配网可靠,通常以灯慢闪做指示

8.1 配网指令

配网指令有两个函数可以实现:mcu_reset_wifi()和mcu_set_wifi_mode()。

**mcu_reset_wifi()**调用后复位wifi模组,复位后以前的配网信息全部清除。

**mcu_reset_wifi()**调用一次切换一次配网模式,在AP和smart之间切换。

**mcu_set_wifi_mode()**参数:SMART_CONFIG、AP_CONFIG。调用后清除配网信息,明确进入SMART模式或者AP模式。

8.2 配网指示

通常在while(1)调用mcu_get_reset_wifi_flag()函数返回wifi状态,根据WiFi状态,写入相应闪灯的模式。

LED 显示分别为:1 间隔闪烁 250ms;2间隔闪烁 1500ms;3或6 长暗状态;4或5 长亮状态

调用函数mcu_get_wifi_work_state() 获取连接状态,通常使用方法如下:

void main(void)
{
...

while(1)
{
switch(mcu_get_wifi_work_state())
{
case SMART_CONFIG_STATE:
//smart config 配置状态 LED快闪 ,led闪烁请用户完成
break;
case AP_STATE:
//AP配置状态 LED慢闪
break;
case WIFI_CONNECTING:
//WIFI配置完成,正在连接路由器,LED常暗
break;
case WIFI_CONNECTING:
//路由器连接成功 LED常亮
break;
default:break;
}
...

}
}

9.MCU 在线升级

若要支持MCU在线升级,打开protocol.h,开启宏定义,设置MCU版本号

#define         SUPPORT_MCU_FIRM_UPDATE                 //开启MCU固件升级功能(默认关闭)
#define MCU_VER "1.0.0" //用户的软件版本,用于MCU固件升级,MCU升级版本需修改

如果数据包较大请根据实际需求调整缓冲区大小:

WIFI_UART_RECV_BUF_LMT          300            //固件升级缓冲区,需大缓存,必须大于260

相应的升级函数为protocol.c中:

/*****************************************************************************
函数名称 : mcu_firm_update_handle

功能描述 : MCU进入固件升级模式

输入参数 : value:固件缓冲区

position:当前数据包在于固件位置

length:当前固件包长度(固件包长度为0时,表示固件包发送完成)

返回参数 : 无

使用说明 : MCU需要自行实现该功能
*****************************************************************************/
unsigned char mcu_firm_update_handle(const unsigned char value[],unsigned short position,unsigned short length)
{
#error "请自行完成MCU固件升级代码,完成后请删除该行"
if(length == 0)
{
//固件数据发送完成

}
else
{
//固件数据处理
}

return SUCCESS;
}

MCU可调用mcu_api.c 文件内的mcu_firm_update_query() 函数获取当前MCU固件更新情况。

注:升级过程由手机发起,调试时可使用涂鸦串口调试助手点击升级启动,协助调试

10.产测

1.MCU需要支持wifi功能测试,打开protocol.h 开启下面的define

#define         WIFI_TEST_ENABLE                //开启WIFI产测功能

2.MCU在需要wifi功能测试处调用mcu_api.c文件内 mcu_start_wifitest()

3.在protocol.c文件wifi_test_result 函数内查看测试结果

产测功能指令需在模组上电初始化完成后才能调用,建议5s后调用,触发条件可用户自行设定。开启产测后,模组会自动搜索名称为tuya_mdev_test无线信号,并返回信号强度。因此无线热点名称需改为tuya_mdev_test。

400-881-8611