Sweeper SDK 开发指南

更新时间：2023-10-19 08:08:32下载pdf

SDK 适用范围

设备需支持 Linux 或 Android 系统
设备需支持 TCP/IP 协议栈

名词解释

名词	释义
配网	建立设备端、手机 App 端和云端之间的通信链路
PID/Productkey	产品 ID，用来标示某一类产品，同一种类型的 IPC 设备共享同一个产品 ID。PID 关联了产品具有的功能点
UUID	Universally Unique Identifier，通用唯一识别码，由一台机器上生成的数字，保证所有机器都具有唯一性
AUTHKEY	设备的授权值，在云上已注册能够使用云服务的服务码
P2P ID	点对点服务 ID，3.0.0 版本以上 SDK 不需要填写 P2P ID，云端自动进行分配
Token	二维码配网过程中，由云服务器生成的标识码，10 分钟有效期
DP	Date Point 设备与服务器数据交互的功能点
OTA	设备在线升级功能

功能概述

扫地机 SDK 提供了基于 Linux 系统的 Wi-Fi 硬件设备、涂鸦 App 和云通信的接口封装，加速开发过程，主要包括以下功能：

提供符合涂鸦标准数据规范的上下行通道：控制指令下发、状态上报、扫地机地图数据上报等
提供数据过滤服务：数据校验、规则上报、上报频率控制等
提供涂鸦标准化服务，例如设备配网、固件升级、本地定时、局域网控制等功能
通信传输过程中的数据安全服务

快速体验

为了能够快速体验 Tuya Sweeper SDK 功能，需要以下几个步骤。

获取 Tuya Sweeper SDK 包。
获取 tuya_Sweeper_demo。
在 App Store 等应用市场下载智能生活 app。
在 Linux 环境下做简单适配。
运行 Demo，手机移动端直观体验。

第一步：获取 SDK

联系对应项目经理获取 SDK 的 GitHub 地址。

第二步：运行 Demo

从 GitHub 下载 Demo 代码到本地。
解压 SDK。

解压 SDK：将解压后的 SDK 中的 sdk 文件夹（包含 include 和 lib 文件夹），复制到 ubuntu_demo/sdk 文件夹下。

将下载的 Demo 文件中的 demo_resource 复制到 ubuntu_demo/components/demo_tuya_ipc/resource 文件夹下。

编译输出可执行产物。
```
./build.sh ubuntu_sweeper
```
产物所在路径 cmake-build/out/demo_ipc。
使用手机下载安装智能生活 App，打开下载的 App，并单击添加设备。
选择小家电 > 扫地机器人（摄像机）。
选择二维码配网后，单击 确认指示灯快闪，并单击 下一步。
输入 Wi-Fi 名称和密码。

此处连接的 Wi-Fi 为 2.4GHz。
生成并识别二维码。

将二维码进行截屏，打开微信，使用 扫一扫 功能的扫码选项进行二维码图片的识别。
将获取到的数据中的 token 提取出来。

获取到的数据：{"p":"test","s":"test","t":"AYYBJt2OGvY2w1"}

t 后的参数即为 Token，有效期：10 分钟，10 分钟后 token 失效，需要按照上诉流程重新获取。

在编译目录下执行命令，运行可执行程序。

#在终端输入以下指令
#./cmake-build/out/demo_ipc -m 2 -r "." -t "TOKEN"
#注：-m 为配网模式的选择 [0,2] 0 为快联配网，1 为 AP 配网，2 为 debug 配网，-r 为地图文件所在位置，此处为当前文件夹，token 是通过扫码二维码解析获取到的。

在执行可执行程序的同时，单击手机 App 上的 听到提示音按钮（实际设备无提示音，只是为了 App 下一步操作）。
等待一段时间即可添加成功。

单击添加成功的设备即可上线。如果不上线，请至第 2 步检查是否操作正确。

在终端中输入下列指令，可以模拟体验扫地机功能。

指令	指令说明
p2p_map	进入扫地机模拟

例如虚拟设备执行过程中，执行：

#p2p_map
please input support file type
#63
please input sleep time
#20
please input file pathname(输入各种文件的路径,顺序如之前所示(map.bin cleanPath.bin, navPath.bin))
#./components/demo_tuya_ipc/resource/ipc_sweeper_robot/map.bin1
#./components/demo_tuya_ipc/resource/ipc_sweeper_robot/cleanPath.bin1
#./components/demo_tuya_ipc/resource/ipc_sweeper_robot/navPath.bin1

support file type 及 sleep time 说明

支持的文件类型，目前支持的有
map.bin：（全量地图文件传输）
cleanPath.bin：（清扫路径文件传输）
navPath.bin：（导航路径文件传输）
map.bin.stream：（全量地图流传输）
cleanPath.bin.stream（清扫路径流传输）
navPath.bin.stream（导航路径流传输）
// 输入一个 int 类型的数值，该 int 类型的第 6~1 位分别表示以上类型（map.bin 用第 1 位表示，navPath.bin.stream 用第 6 位表示），0 表示支持，1 表示不支持
// 如果全部都支持，那该数值的二进制为 11 1111（63），如果只支持 map.bin，那该数值的二进制为 00 0001（1），以此类推。

sleep time 休眠时间表示如果传输流文件，多长时间再次传输（如果只传输文件，则该参数不生效）。

正常情况下，在输入上述命令后，再打开智能生活 App，就能够看到上传的地图（如果不展示地图，则需要检查地图文件路径是否正常）。

至此，Demo 体验完成。您可以结合 Demo 开发自己的业务，以下是开发指导说明。

应用开发指导

基本参数填写

您需要在 demo_src/user_main.c 文件中，分别修改 DB 文件、OTA 文件、本地录像文件的保存路径，宏定义如下：

DB 文件中保存设备的配网信息，需要保存至掉电不丢失的路径下。

DB 文件与本地录像文件保存路径需要检查结尾是否有 /，（可以选择实际存在的路径，并不使用）。
```
#define IPC_APP_STORAGE_PATH "/tmp/"
#define IPC_APP_UPGRADE_FILE "/tmp/upgrade.file"
#define IPC_APP_SD_BASE_PATH "/tmp/"
```

PID、UUID 和 AUTHKEY 的传入：（内容可以咨询相关产品经理或者 FAE）。

  #CHAR_T s_ipc_pid[64]="tuya_pid";            //pid
  #CHAR_T s_ipc_uuid[64]="tuya_uuid";            //uuid
  #CHAR_T s_ipc_authkey[64]="tuya_authkey";    //authkey
  #将 PID UUID AUTHKEY 替换即可，可以写入到 flash 文件中保存，掉电不丢失

修改版本号的宏定义：

版本号必需按照格式：xx.xx.xx 进行填写，不超过 20 位字符。
```
#define IPC_APP_VERSION "1.2.3"
```

至此，SDK 基本参数已完成填写，进入配网模式。

SDK 配网开发

涂鸦 SDK 搭建了一套完整的用以引导设备配网的函数框架，此章节主要阐述配网的流程以及各框架函数的用途。建议您按照文档介绍，在对应的框架函数下，实现各功能点的具体操作。

Wi-Fi 快联配网

开发流程

在 main 主函数中找到参数 mode，选择：WIFI_INIT_AUTO 配网模式，token 参数填 NULL。

CHAR_T token[30] = {0};    //token--二维码配网过程中，由云服务器生成的标识码，10min 有效期
WIFI_INIT_MODE_E mode = WIFI_INIT_AUTO;    //mode--配网模式选择

在 TUYA_IPC_SDK_START 函数中，会传入用户设置的配网模式开始配网。可以结合业务需求，在合适时机调用该接口进入配网。
```
TUYA_IPC_SDK_START(mode,token);
```

Wi-Fi 快连流程如下：

//扫描全部信道并将扫描到的信息传输至结构体 AP_IF_S**ap 中
OPERATE_RET tuya_adapter_wifi_assign_ap_scan(IN CONST CHAR_T *ssid,OUT AP_IF_S **ap)
//起线程 func_Sniffer
//setsockopt 绑定指定的网卡设备
//recvfrom 接收混杂模式采集到的数据包
//跳过 radiotap header，得到完整 802.11 数据帧。通过接口 s_pSnifferCall 回传到 SDK 内部
//内部处理后即可获取到 ssid uuid token，关闭 sniffer
//连接路由器 开始 MQTT P2P 连接

以下接口需要您进行实现。具体实现可以参考 Demo 中的实现。

//Wi-Fi 模块模式的获取接口 默认模式为 sniffer 模式
OPERATE_RET tuya_adapter_wifi_get_work_mode(OUT WF_WK_MD_E *mode)
//扫描全部信道并将扫描到的信息传输至结构体 AP_IF_S**ap 中
OPERATE_RET tuya_adapter_wifi_assign_ap_scan(IN CONST CHAR_T *ssid,OUT AP_IF_S **ap)
//设置 Wi-Fi 模式 当 SDK 判断 Wi-Fi 输入的空口包数据正确，将 Wi-Fi 状态设置为 station 模式
OPERATE_RET tuya_adapter_wifi_set_work_mode(IN CONST WF_WK_MD_E mode)
//sniffer 模式回调函数注册
int tuya_adapter_wifi_sniffer_set(const bool en, const SNIFFER_CALLBACK cb)
//根据解析到的数据，进行联网操作
OPERATE_RET tuya_adapter_wifi_station_connect(IN CONST CHAR_T *ssid,IN CONST CHAR_T *passwd)
//配网成功后，通知 sdk 已获取到 IP 地址，此接口为高频调用接口
OPERATE_RET tuya_adapter_wifi_station_get_status(OUT WF_STATION_STAT_E *stat)

传入 Wi-Fi 接收到的空口包信号进行处理，显示信号强度。
```
OPERATE_RET tuya_adapter_wifi_station_get_conn_ap_rssi(OUT SCHAR_T *rssi)
```
如要更改其他接口，可咨询后再进行修改，避免出现未知错误。

直连扫码（手机扫设备二维码）

确认已下载带有直连扫码功能的涂鸦 SDK，涂鸦 UUID 经过后台打标处理。
运行时确保设备已连接到 Internet。
调用 TUYA_IPC_SDK_START 函数进行 SDK 初始化，入参 WIFI_INIT_MODE_E 选择 WIFI_INIT_NULL，token 填写 NULL。
手机单击右上角扫描图标，扫描二维码激活设备。
二维码获取：UUID 打标后，云端会下发短链接，用开源库将短链接转换成二维码即可。

如要更改其他接口，可咨询后再进行修改，避免出现未知错误。

功能点开发

设备功能

涂鸦提供基于 MQTT 网络应用协议，实现设备控制和状态上报，MQTT 是一个轻量的发布订阅模式消息传输协议，专门针对低带宽和不稳定网络环境的物联网应用设计。

tuya_sdk 封装了 MQTT 协议层实现，以功能点（以下称为 DP）的形式呈现，支持数值型、布尔型、枚举型、字符串型、故障型，RAW 型数据，像定义 C 变量一样简单。

您需要根据设备功能，在涂鸦 IoT 开发平台创建对应的功能点。更多信息，参考产品功能。

特点

目前支持每个产品最多创建 35 个 DP，复杂功能请用 raw 型数据实现。

obj 型：布尔型（bool）、数值型（value）、字符串型（string）和枚举（enum）。
故障型（bitmap），tuya_sdk 会对连续上报的数值进行过滤，相同则不予上传。
raw 型：也称为透传型，tuya_sdk 不对连续上报的数值进行过滤，请控制上报频率＞1s 每次。

接口说明

obj 型数据下发接口原型为：

/**
* @brief dev_report_dp_json_async
* @desc report dp info a-synced.
*
* @param[in] dev_id: if sub-device, then devid = sub-device_id
*                if gateway/soc/mcu, then devid = NULL
* @param[in] dp_data: dp array header
* @param[in] cnt: dp array count
*
* @return OPRT_OK: success Other: fail
*/
OPERATE_RET dev_report_dp_json_async(IN CONST CHAR_T *dev_id,IN CONST TY_OBJ_DP_S *dp_data,IN CONST UINT_T cnt);

raw 型数据下发接口原型为：

/**
* @brief dev_report_dp_raw_sync_extend
* @desc report dp raw info synced.
*
* @param[in] dev_id: if sub-device, then devid = sub-device_id
*                if gateway/soc/mcu, then devid = NULL
* @param[in] dpid: raw dp id
* @param[in] data: raw data
* @param[in] len: len of raw data
* @param[in] timeout: function blocks until timeout seconds
*
* @return OPRT_OK: success Other: fail
*/
 dev_report_dp_raw_sync(dev_id, dpid, data, len, timeout)

扫地机业务概述

目前扫地机文件（地图、路径等）传输支持 3 种模式：流服务传输模式、P2P 传输模式和 OSS 传输模式。

流服务传输模式：使用 MQTT 传输文件，特点：数据量小，速度慢，一般惯导可以使用该方案。
P2P 传输模式：使用 P2P 方式传输文件，用来传输实时地图、导航图、清扫路径。
OSS 传输模式：使用第三方 OSS 服务保存地图，费用高，需要占用服务器，一般多地图时使用。

扫地机流服务传输模式

利用 MQTT 满足一些小数据的流式传输服务，采用增量传输数据的方法，将数据挤牙膏式的发送到云端并推送到 App。含起始通知、结束通知服务。
协议通信可靠性保障依赖于 MQTT QoS = 1 机制保障，短点数据发送均采用 QoS =1 模式。

接口说明

同步上报接口 tuya_iot_media_data_report。

/***********************************************************
* Function: tuya_iot_media_data_report
* Input: dt_body->media data
        timeout->need report time
* Output: none
* Return: OPERATE_RET
***********************************************************/
OPERATE_RET tuya_iot_media_data_report(IN CONST FLOW_BODY_ST *dt_body,IN CONST UINT_T timeout);

参考代码

OPERATE_RET op_ret;
    unsigned char data_buf[] = {"iot.tuya.com"}; // 示例数据
    FLOW_BODY_ST*flow_data=(FLOW_BODY_ST*)malloc(sizeof(FLOW_BODY_ST)+sizeof(data_buf));
    if(flow_data == NULL){
        PR_ERR("malloc flow_data");
        return OPRT_MALLOC_FAILED;
    }
    memset(flow_data, 0, sizeof(FLOW_BODY_ST)+sizeof(data_buf));

    flow_data->id = map_id;
    flow_data->posix = uni_time_get_posix();
    flow_data->step = TS_TRANSFER;
    flow_data->offset = 0;
    flow_data->len = sizeof(data_buf);
    memcpy((unsigned char *)flow_data->data, data_buf, flow_data->len);
    op_ret = tuya_iot_media_data_report(flow_data, 5);
    if (op_ret != OPRT_OK){
        PR_ERR("tuya_iot_media_data_report->TS_TRANSFER is error %d\n", op_ret);
    }
    free(flow_data);
    return op_ret;

tuya_iot_media_data_report_v2

/***********************************************************
* Function: tuya_iot_media_data_report_v2
* Input: dt_body->media data
        timeout->need report time
* Output: none
* Return: OPERATE_RET
***********************************************************/
OPERATE_RET tuya_iot_media_data_report_v2(IN CONST FLOW_BODY_V2_ST *dt_body,IN CONST UINT_T timeout);

扫地机 P2P 传输模式

目前 P2P 扫地机业务支持 3 种文件操作：

查询扫地机地图
下载扫地机地图
取消下载扫地机地图。

对于扫地机的地图目前支持 3 种文件：

全量地图
导航路径图
清扫路径图

对于 3 种文件类型，各有 2 中传输模式：

文件传输。一个会话只用于发送文件，文件发送结束后（文件都会有长度），会再发送一个结束的信令告知对端。
流传输。一个会话会只用于发送流文件，不会关闭，直到收到对方取消下载的命令后才会关闭会话（关闭会话前也会发送一个信令告知对端）。

基于上面提到的 3 种文件类型和 2 种传输模式，P2P 内部支持扫地机地图总共有 6 种：

map.bin（全量地图文件传输）
cleanPath.bin（清扫路径文件传输）
navPath.bin（导航路径文件传输）
map.bin.stream（全量地图流传输）
cleanPath.bin.stream（清扫路径流传输）
navPath.bin.stream（导航路径流传输）

如果手机 App 需要设备只上传一次全量地图，则下载文件时只需要将文件名称设置为 map.bin。如果需要设备不断地上传全量地图，则下载文件时需要将文件名设置为 map.bin.stream。对于清扫路径与导航路径也是同理。

查询扫地机地图

Sweeper SDK 开发指南

下载扫地机地图

Sweeper SDK 开发指南

取消下载扫地机地图

Sweeper SDK 开发指南

对外接口说明

SWEEPER_ALBUM_FILE_TYPE_E 结构体

该结构体列举了 SDK 支持的扫地机文件类型（6 种）

map.bin（全量地图文件传输）
cleanPath.bin（清扫路径文件传输）
navPath.bin（导航路径文件传输）
map.bin.stream（全量地图流传输）
cleanPath.bin.stream（清扫路径流传输）
navPath.bin.stream（导航路径流传输）

typedef enum {
    SWEEPER_ALBUM_FILE_TYPE_MIN = 0,
    SWEEPER_ALBUM_FILE_MAP = SWEEPER_ALBUM_FILE_TYPE_MIN,//map file
    SWEEPER_ALBUM_FILE_CLEAN_PATH = 1,
    SWEEPER_ALBUM_FILE_NAVPATH = 2,
    SWEEPER_ALBUM_FILE_TYPE_MAX = SWEEPER_ALBUM_FILE_NAVPATH,

    SWEEPER_ALBUM_STREAM_TYPE_MIN = 3,
    SWEEPER_ALBUM_STREAM_MAP = SWEEPER_ALBUM_STREAM_TYPE_MIN, // map stream , devcie should send map file to app continue
    SWEEPER_ALBUM_STREAM_CLEAN_PATH = 4,
    SWEEPER_ALBUM_STREAM_NAVPATH = 5,
    SWEEPER_ALBUM_STREAM_TYPE_MAX = SWEEPER_ALBUM_STREAM_NAVPATH,

    SWEEPER_ALBUM_FILE_ALL_TYPE_MAX = SWEEPER_ALBUM_STREAM_TYPE_MAX, //最大值 5
    SWEEPER_ALBUM_FILE_ALL_TYPE_COUNT, //个数 6
} SWEEPER_ALBUM_FILE_TYPE_E;

tuya_ipc_sweeper_convert_file_info

/**
* \fn tuya_ipc_sweeper_convert_file_info
* \brief transfer file info into buff pointered by pIndexFile by tuya SDK
* \param[in] fileArray: arr[0] means SWEEPER_ALBUM_FILE_TYPE_MIN, refer to SWEEPER_ALBUM_FILE_TYPE_E
* \param[inout] pIndexFileInfo: file infomation
* \param[inout] fileInfoLen: file infomation len
* \return ret
*/
INT_T tuya_ipc_sweeper_convert_file_info(IN INT_T* fileArray, OUT VOID** pIndexFileInfo, OUT INT_T* fileInfoLen);

该接口将支持的地图文件转换成固定格式，目前 p2p 扫地机支持的文件类型有 6 种。

如果设备支持所有的地图，则调用该接口时，第一个参数可以填：

int g_file_arr[SWEEPER_ALBUM_FILE_ALL_TYPE_COUNT] = { 1, 1, 1, 1, 1, 1 };
tuya_ipc_sweeper_convert_file_info(g_file_arr, &(pSrcType->pIndexFile), &(pSrcType->fileLen));

如果只支持全量地图文件传输和全量地图流传输，则应该修改为：

int g_file_arr[SWEEPER_ALBUM_FILE_ALL_TYPE_COUNT] = { 1, 0, 0, 1, 0, 0 };
tuya_ipc_sweeper_convert_file_info(g_file_arr, &(pSrcType->pIndexFile), &(pSrcType->fileLen));

该接口用户也可以自行实现，并非一定要使用 SDK 提供的这个接口，只要按照格式返回查询的结果既可以。

tuya_ipc_sweeper_parse_file_info

/**
* \fn tuya_ipc_sweeper_parse_file_info
* \brief parse download file info into file Array
* \param[in] srcfileInfo: download info
* \param[inout] fileArray: array of file infomation
* \param[in] arrSize: array size
* \return ret
*/
INT_T tuya_ipc_sweeper_parse_file_info(IN C2C_CMD_IO_CTRL_ALBUM_DOWNLOAD_START* srcfileInfo, INOUT INT_T* fileArray, IN INT_T arrSize);

该接口用于解析 App 需要下载文件的文件类型，返回值是需要下载的文件数组（数组大小为 6），也是按照

map.bin（全量地图文件传输）
cleanPath.bin（清扫路径文件传输）
navPath.bin（导航路径文件传输）
map.bin.stream（全量地图流传输）
cleanPath.bin.stream（清扫路径流传输）
navPath.bin.stream（导航路径流传输）

这样的顺序，如果需要下载该文件，则返回的值为 1，否则为 0。当然用户也可以不使用该接口，自行解析需要下载的文件名称。

tuya_ipc_sweeper_send_data_with_buff

/**
* \fn simple_album_send_data_with_buff
* \brief send file to app by p2p
* \param[in] client: handle
* \param[in] type: file type, refer SWEEPER_ALBUM_FILE_TYPE_E
* \param[in] fileLen: file len
* \param[in] fileBuff: file buff
* \return ret
*/
INT_T tuya_ipc_sweeper_send_data_with_buff(IN INT_T client, SWEEPER_ALBUM_FILE_TYPE_E type , IN INT_T fileLen, IN CHAR_T* fileBuff);

该接口通过 P2P 通道将地图数据发送给 App，

第一个参数是 P2P 通道的会话句柄，在下载地图时，从回调函数中能拿到。

第二个参数是地图的类型，可以参考 SWEEPER_ALBUM_FILE_TYPE_E 枚举类型。

第三个参数是地图文件的长度。

第四个参数是地图文件的内容。

如果是文件类型的地图，需要在传输结束后，调用接口 tuya_ipc_sweeper_send_finish_2_app。如果是流文件类型地图则不需要（因为流文件类型，会一直传输，直到用户手动停止）。

tuya_ipc_sweeper_send_finish_2_app

/**
* \fn simple_album_send_finish_2_app
* \brief tell app sending is finished
* \param[in] client: session client
* \return ret
*/
INT_T tuya_ipc_sweeper_send_finish_2_app(IN INT_T client);

该接口用户通知 App 文件传输结束，参数与 tuya_ipc_sweeper_send_data_with_buff 接口第一个参数相同

地图事件回调

由于使用 P2P 传输数据与接收信令，因此需要实现以下 4 种事件：

地图查询
开始下载地图
停止下载地图
删除地图（可以空实现）

typedef enum
{
  ……
    TRANS_ALBUM_QUERY = 203,                // 地图查询
    TRANS_ALBUM_DOWNLOAD_START = 204,        // 开始下载地图
    TRANS_ALBUM_DOWNLOAD_CANCEL = 205,        // 停止下载地图
    TRANS_ALBUM_DELETE = 206,                // 删除地图
}TRANSFER_EVENT_E;

扫地机 OSS 传输模式

此服务目前用于激光扫地机品类，用来上报数据量较大的全量激光地图数据。

云存储

Sweeper SDK 开发指南

tuya_iot_map_record_upload_buffer

/***********************************************************
* Function: tuya_iot_map_record_upload_buffer
* Desc: sweeper function. upload record map info
* Input: map_id
* Input: buffer
* Input: len
* Input: cloud_file_name
* Input: extend
* Return: OPERATE_RET
***********************************************************/
#define tuya_iot_map_record_upload_buffer(map_id,buffer,len,cloud_file_name,extend)\
    upload_map_custom_buffer(map_id,buffer,len,cloud_file_name,0,FALSE,extend,TRUE)

OPERATE_RET upload_map_custom_buffer(IN CONST INT_T map_id, IN CONST BYTE_T *buf,IN CONST UINT_T len, \
                                     IN CONST CHAR_T *cloud_file_name, \
                                     IN CONST INT_T map_type, IN CONST BOOL_T send_mqtt, \
                                     IN CONST CHAR_T *extend_msg, IN CONST BOOL_T http_update);

该接口用于上传清扫记录，保存在 OSS 服务器中。

多地图

地图管理交互图

Sweeper SDK 开发指南

tuya_iot_map_upload_files

    /***********************************************************
    * Function: tuya_iot_map_upload_file
    * Desc: sweeper function. upload cleaner map info
    * Input: bitmap_file
    * Input: datamap_file
    * Input: descript
    * Output: cloud_map_id
    * Return: OPERATE_RET
   ***********************************************************/
    OPERATE_RET tuya_iot_map_upload_files(IN CONST CHAR_T *bitmap_file,
                                          IN CONST CHAR_T *datamap_file,
                                          IN CONST CHAR_T *descript,
                                          OUT CONST UINT_T *map_id);

功能说明：上传地图。

参数说明：

参数名称	说明
bitmap_file	需要上传用于 App 显示的地图文件，文件名不能超过 16 字节，文件格式参照涂鸦激光协议
datamap_file	需要上传用于重定位的地图文件，涂鸦无要求，客户自定义，文件名不能超过 16 字节
descript	描述信息，格式参照：mm_bin_mapid_nowtime.txt
map_id	上报成功后，云端返回的地图 ID

返回值

返回值	说明
OPRT_OK	操作成功
错误码	失败返回错误码

tuya_iot_map_update_files

    OPERATE_RET tuya_iot_map_update_files(IN CONST UINT_T map_id,
                                          IN CONST CHAR_T *bitmap_file,
                                          IN CONST CHAR_T *data_map_file);

功能说明：更新云端分配地图 ID 对应的地图文件。

参数说明

参数名称	说明
map_id	cloud_map_id
bitmap_file	需要更新的用于 App 显示的地图文件，全路径
datamap_file	需要更新的用于重定位的地图文件，全路径

返回值

返回值	说明
OPRT_OK	操作成功
错误码	失败或者返回错误码

tuya_iot_map_delete

OPERATE_RET tuya_iot_map_delete(IN CONST UINT_T map_id);

功能说明：删除云端保存的地图文件。

参数说明

参数名称	说明
map_id	云端分配的地图 ID，cloud_map_id

返回值

返回值	说明
OPRT_OK	操作成功
错误码	失败返回错误码

tuya_iot_get_map_files

PERATE_RET tuya_iot_get_map_files(IN CONST UINT_T map_id, IN CONST CHAR_T *map_path)

功能说明：获取指定 map_id 的地图文件，下载后保存在指定的路径下。

参数说明

参数名称	说明
map_id	地图 ID
map_path	下载地图文件保存的路径

返回值

返回值	说明
OPRT_OK	操作成功
错误码	失败返回错误码

OTA 功能开发

OTA 作为设备升级与维护的最重要途径之一，将在本章节进行具体介绍。当有固件需要升级时，SDK 将通过回调的形式告知设备，进行 OTA 操作。

业务基本链路

设备升级过程涉及手机 App、设备和云端。

手机 App：升级进度结果的展示或者升级消息的发起者。
云端：升级过程中的管理者，负责升级固件的存储，设备升级状态的更新，升级文案推送。
设备：负责接收固件，固件升级的执行者。

固件包配置说明

网关或子设备配网成功后，从 App 上获取设备信息里的虚拟 ID，作为固件升级的白名单。
编译出要升级的固件包，固件版本要高于设备中运行的固件版本。
登录涂鸦 IoT 开发平台，到对应创建的产品下，上传配置固件包。
Wi-Fi 设备的固件升级时，固件类型选择 SDK 固件。
Wi-Fi 设备的 MCU 固件升级时，固件类型选择 MCU 固件。

升级开始方式

设备固件上传到云端后，设备不会立即收到升级消息，目前涂鸦支持以下几种方式：

App 提醒升级：用户首次打开设备面板时，会收到升级提醒弹框，可选择升级或不升级。
App 静默升级：即设备静默升级，设备重启后，会向云端请求一次是否有静默升级任务，有的话直接进行升级。如果用户打开设备面板，此时会有进度框显示，此时设备是无法操作的。
App 强制升级：用户首次打开设备面板时，会收到升级提醒弹框，只有确定可选，否则设备无法操作。
App 检测升级：即 App 用户主动单击对应设备的面板，然后单击右上角进入设备信息界面，检测设备固件版本，主动更新。

OTA 开发流程

OTA 请求回调函数：IPC_APP_Upgrade_Inform_cb（），传入参数包含固件下载的 url（下载链接）以及 size（文件的大小）。
释放系统资源（优化内存）：调用 tuya_ipc_ss_set_write_mode（） 函数，关闭本地录像功能，然后调用 tuya_ipc_ss_uninit（）、tuya_ipc_tranfser_close（） 函数，uninit 与 close 函数主要用以 SDK 本地存储与 P2P 功能的反初始化，尽可能释放内存资源。

内存资源优化需要在 tuya_ipc_upgrade_sdk 函数前进行。
```
VOID IPC_APP_Upgrade_Inform_cb(IN CONST FW_UG_S *fw)
{
  PR_DEBUG("Rev Upgrade Info");
  PR_DEBUG("fw->fw_url:%s", fw->fw_url);
  PR_DEBUG("fw->sw_ver:%s", fw->sw_ver);
  PR_DEBUG("fw->file_size:%u", fw->file_size);

  FILE *p_upgrade_fd = fopen(s_mgr_info.upgrade_file_path, "w+b");
  //此处优化内存资源
  tuya_ipc_upgrade_sdk(fw, __IPC_APP_get_file_data_cb, __IPC_APP_upgrade_notify_cb, p_upgrade_fd);
}
```
函数：tuya_ipc_upgrade_sdk 中第一个回调函数 __IPC_APP_get_file_data_cb 是用于获取文件分片数据（下载）。函数中有入参与出参，入参主要提供给您使用，出参由您获取到数据后，需要返回是否已完成数据的写入，写入成功返回 0。

第二个回调函数 __IPC_APP_upgrade_notify_cb 是用于显示 OTA 升级整体进度。
在函数 __IPC_APP_upgrade_notify_cb 中替换新固件，具体实现参考 tuya_ipc_sdk_upgrade_demo.c 文件。

固件下载完成后，需要客户在函数中实现固件的具体替换过程，替换成功后，需要在此函数内进行设备的重启操作。

固件替换前，需要备份 DB 文件，固件替换成功后，对比 DB 文件替换固件前后的 MD5 值，若相同，则可以直接重启。若不相同，则将备份的 DB 文件替换现有的 DB 文件再重启设备。
```
  VOID __IPC_APP_upgrade_notify_cb(IN CONST FW_UG_S *fw, IN CONST INT_T download_result, IN PVOID_T pri_data)
```
若 OTA 升级失败，需要在函数：__IPC_APP_upgrade_notify_cb 中加入重启操作。

反初始化的操作不可逆，若 OTA 失败，设备必须进行重启。

OTA 自定义进度上报开发

设备端通过 URL 开始下载固件，调用 tuya_ipc_upgrade_progress_report 函数，上报 OTA 下载的进度。

上报的进度值建议小于 99%。

/*
\fn OPERATE_RET tuya_ipc_upgrade_progress_report
\brief 发送升级进度到 cloud 和 app
\param[in] percent: 升级进度百分比，有效值[0,100]
\return SUCCESS – OPERATE_RET , FAIL – COMM ERROR
*/
OPERATE_RET tuya_ipc_upgrade_progress_report(IN UINT_T percent);

固件升级时，手机 App 进度显示会暂停在 98%，此时，固件已完成下载，App 正在等待设备重启并上报新固件版本。版本号上报成功后，App 将显示 升级成功。
App 等待设备替换固件与上报新版本号的时间为 1 分钟。若设备流程超过此时间，需要告知项目经理 PID 后台进行配置。

设备解绑与复位

本章节主要简述设备通过 App 解绑与按复位键，这两种复位方式，开发中的流程与区别。

设备解绑开发流程

App 删除设备 按键，SDK 将清除 DB 文件中的配网信息并执行回调函数：IPC_APP_Reset_System_CB 重启设备，函数如下所示：

需要在函数内，实现设备的重启与对 DP 数据文件进行重置操作，不需要删除 DB 文件。

VOID IPC_APP_Reset_System_CB(GW_RESET_TYPE_E type)
{
  printf("reset ipc success. please restart the ipc %d\n", type);
  IPC_APP_Notify_LED_Sound_Status_CB(IPC_RESET_SUCCESS);
  //TODO
  /* Developers need to restart IPC operations */
}

设备复位开发流程

设备检测到复位键被按下，存在复位操作，删除三个 db 文件：tuya_user.db_bak、tuya_user.db 与 tuya_enckey.db。
设备对 DP 数据文件进行重置操作并重启。

硬件交互定义