Arduino 开发指南

本文介绍如何使用 Tuya_Wifi_MCU_SDK 开发一款智能设备。

背景信息

通过对涂鸦 Arduino 库的安装和使用入门（可参考 Arduino 接入涂鸦云快速入门）有一定的了解之后，我们可以使用该库开发一款自己的智能设备。

准备工作

• 确保已安装 Arduino IDE，并且已下载安装 Tuya_WiFi_MCU_SDK 库，库的安装请参考：Arduino 接入涂鸦云快速入门。

• 确保已经准备了以下硬件物料。

  • 支持数据传输的 Micro-USB线
  • 涂鸦三明治 Wi-Fi 通信板 或涂鸦 Wi-Fi 通用模组。
  • 支持 Arduino 库的开发板，如 ST Nucleo 开发板，Arduino UNO 开发板等。

• 已安装涂鸦智能 App。您可以在 App Store 或其他安卓应用商店中搜索“涂鸦智能”关键字进行安装。

第一步：创建产品

为了实现涂鸦三明治套件中的主控板与涂鸦三明治 Wi-Fi 通信板之间的通信，您需要预先通过涂鸦开发者平台创建产品以获取 PID、DP 等信息。
下面以实现产品球泡灯为例，获取球泡灯产品 PID 的步骤如下：

1. 登录 涂鸦开发者平台。
2. 参考 选品类创建产品 创建一个球泡灯产品，例如创建一款 自定义开发方案 的 Wi-Fi+BLE 协议球泡灯。
   
3. 在 功能定义 页签中，根据功能需求选取对应的 DP 点。
4. 在 App 面板 页签中，选择并体验一款 App 面板。
5. 在 硬件开发 页签中完成设置后，复制上方的 PID。
   

第二步：软件开发

工程创建

在 Arduino IDE 中，选择 文件 > 新建 创建一个工程项目。

重要函数介绍

在 Arduino IDE 中使用该库进行编程开发时，必须在你的 Arduino 工程文件中包含 TuyaWifi.h 头文件。

相关信息初始化

在 unsigned char TuyaWifi::init(unsigned char *pid, unsigned char *mcu_ver) 函数中，

• PID 通过在涂鸦开发者平台上创建产品获取，Wi-Fi 类产品的 PID 长度一般为 16 字节，PID 关联了产品具体的功能点、App 控制面板、出货信息等所有跟这个产品相关的信息
• mcu_ver 参数是软件的版本号，如果 MCU 需要支持 OTA 功能，该信息是非常重要的。

  提示：当前版本的库暂不支持 OTA 功能。

#include <TuyaWifi.h>

TuyaWifi my_device;
...
void setup() 
{   
  Serial.begin(9600);
  ...
  my_device.init("xxxxxxxxxxxxxxxx", "1.0.0");//"xxxxxxxxxxxxxxxx":应为你在Tuya开发者平台上获取的 PID，"1.0.0"应是当前软件的实际版本号
      
  ...
}

void loop()
{
  ...
  my_device.uart_service();
  ...
}

...

DP 信息传入 Tuya_Wifi_MCU_SDK

DP 为 Data Point 的缩写，即数据点，表示智能设备所具备的功能点。在涂鸦开发者平台上创建产品时，可以获取产品 DP 点的信息。涂鸦智能将每个功能点抽象成数据点，数据点定义成 6 种不同的类型：

#define DP_TYPE_RAW     0x00    //RAW type
#define DP_TYPE_BOOL    0x01    //bool type
#define DP_TYPE_VALUE   0x02    //value type
#define DP_TYPE_STRING  0x03    //string type
#define DP_TYPE_ENUM    0x04    //enum type
#define DP_TYPE_BITMAP  0x05    //fault type

数据点具备读写属性。例如，一个两路的开关，可以抽象成两个数据点，每个数据点类型为布尔型，可取值为 True 或 False。
数据点可读写，读表示获取开关目前的值，写表示改变开关目前的值。

具体的 DP 信息通过 void TuyaWifi::set_dp_cmd_total(unsigned char dp_cmd_array[][2], unsigned char dp_cmd_num) 函数传入 Tuya_Wifi_MCU_SDK。
该函数中 dp_cmd_array[][2] 为存储 DP 信息的数组，dp_cmd_num 为 DP 总数。

举例
假设要创建一个有 3 个功能点（也就是有 3个 DP）的灯:

• 开关（DP ID : 20, DP 类型：布尔类型）
• 灯的亮度（DP ID : 21, DP 类型：数值类型）
• 灯光模式（DP ID : 22, DP 类型：枚举类型）

#include <TuyaWifi.h>

TuyaWifi my_device;
...
#define DPID_SWITCH	20	//灯的开关 DP
#define DPID_LIGHT	21	//灯的亮度 DP
#define DPID_MODE	22	//灯的工作模式 DP
    
//注意：array[][0]为DPID, array[][1]为DP type
unsigned char dp_id_array[][2] = {
    /*  DPID     |  DP type  */
    {DPID_SWITCH, DP_TYPE_BOOL},  
    {DPID_LIGHT, DP_TYPE_VALUE},
    {DPID_MODE, DP_TYPE_ENUM},
};
...
void setup() 
{
    ...
    my_device.set_dp_cmd_total(dp_id_array, 3);	
    ...
}

配网模式设置

调用 void TuyaWifi::mcu_set_wifi_mode(unsigned char mode) 进入配网模式。

/**
 * @description: MCU set wifi working mode
 * @param {unsigned char} mode : enter mode 
 *                               0(SMART_CONFIG):enter smartconfig mode
 *                               1(AP_CONFIG):enter AP mode
 * @return {*}
 */
void TuyaWifi::mcu_set_wifi_mode(unsigned char mode);

下发 DP 数据处理

当云端下发数据后，需要对下发的数据进行解析，通过 unsigned char TuyaWifi::mcu_get_dp_download_data(unsigned char dpid, const unsigned char value[], unsigned short len) 函数进行解析。
该函数目前只支持 DP_TYPE_BOOL、DP_TYPE_VALUE、DP_TYPE_ENUM 这 3 种数据类型；DP_TYPE_BITMAP 为故障型一般只上报处理，不会下发，对该类型不用处理；DP_TYPE_RAW 、DP_TYPE_STRING 这两种类型需要用户自己进行处理。

/**
 * @description: mcu gets bool,value,enum type to send dp value. (raw, string type needs to be handled at the user's discretion. fault only report)
 * @param {unsigned char} dpid : data point ID 
 * @param {const unsigned char} value : dp data buffer address 
 * @param {unsigned short} len : data length
 * @return {unsigned char} Parsed data
 */
unsigned char TuyaWifi::mcu_get_dp_download_data(unsigned char dpid, const unsigned char value[], unsigned short len);

DP 下发处理与函数注册

当 App 控制设备的时候，会从云端下发对应的 DP 命令到设备。设备对数据进行解析后，对下发的命令执行相应的动作。

对下发命令的处理，通过回调函数来调用，所以我们需要调用 void TuyaWifi::dp_process_func_register(tuya_callback_dp_download _func) 对回调函数进行注册。

#include <TuyaWifi.h>

TuyaWifi my_device;
...

void setup() 
{
    ...
  //register DP download processing callback function
  my_device.dp_process_func_register(dp_process);
    ...
}

/**
 * @description: DP download callback function.
 * @param {unsigned char} dpid
 * @param {const unsigned char} value
 * @param {unsigned short} length
 * @return {unsigned char}
 */
unsigned char dp_process(unsigned char dpid,const unsigned char value[], unsigned short length)
{
  switch(dpid) {
    case DPID_SWITCH:
      switch_value = my_device.mcu_get_dp_download_data(dpid, value, length);
      if (switch_value) {
        //Turn on 

      } else {
        //Turn off

      }
      //Status changes should be reported.
      my_device.mcu_dp_update(dpid, value, length);
    break;

    default:break;
  }
  return SUCCESS;
}

上报设备状态

上报设备状态也就是上报所有 DP 的值，也是通过注册函数的方式进行的。

DP 上报函数接受 6 种不同的数据类型定义：

/**
 * @description: dp data upload
 * @param {unsigned char} dpid
 * @param {const unsigned char} value
 * @param {unsigned short} len
 * @return {*}
 */
unsigned char mcu_dp_update(unsigned char dpid, const unsigned char value[], unsigned short len);//update raw, string type
unsigned char mcu_dp_update(unsigned char dpid, unsigned long value, unsigned short len);
unsigned char mcu_dp_update(unsigned char dpid, unsigned int value, unsigned short len);

上报设备状态函数注册示例：

#include <TuyaWifi.h>

TuyaWifi my_device;

#define DPID_SWITCH 20
//Record the current status of the led
unsigned char switch_value = 0;
...
void setup() 
{
    ...
  //register DP download processing callback function
  my_device.dp_update_all_func_register(dp_update_all);
    ...
}

/**
 * @description: Upload all DP status of the current device.
 * @param {*}
 * @return {*}
 */
void dp_update_all(void)
{
  my_device.mcu_dp_update(DPID_SWITCH, switch_value, 1);
}

第三步：烧录下载

注意：烧录下载时，Arduino 开发板不要和通信板连接。

在 工具 栏中，选择对应的开发板和端口后，单击烧录图标进行烧录。

第四步：配网

将 Arduino 开发板上的引脚 7 拉低 1 秒左右，开发板上的 LED 灯开始闪烁，此时设备进入配网模式。

• 如果通信板使用了 WiFi+BLE 双模芯片，在 App 上选择自动发现方式，发现设备后按照提示进行配网。

• 如果通信板使用了 Wi-Fi 芯片，在 App 上选择手动添加方式，选择一个 Wi-Fi 产品进行配网。
  

配网成功后便可通过涂鸦智能 App 对 Arduino 上的 LED 进行控制。

相关文档

• 本文中出现的专业名称，请参考 名词解释。

• 云模组串口协议，请参考 Wi-Fi 通用方案 - 串口协议。