历史传输接口

更新时间：2025-02-06 01:58:29下载pdf

本文基于 tuyaos_robot_sweeper_sdk，详细介绍激光扫地机的多楼层地图、清扫记录传输的流程及 API。

流程说明

清扫记录上报

多楼层地图上报

由于上述接口都是阻塞模式上报，应用上需要创建独立线程，并异步调用楼层地图及清扫记录传输接口。

API 接口

tuya_iot_map_record_upload_buffer

上传清扫记录。

/**
 * @brief tuya_iot_map_record_upload_buffer
 * @desc Robot vacuum function. Upload record map info
 *
 * @param[in] map_id
 * @param[in] buffer
 * @param[in] len
 * @param[in] descript
 *
 * @return OPERATE_RET
 */
OPERATE_RET tuya_iot_map_record_upload_buffer(IN CONST INT_T map_id, IN CONST BYTE_T *buffer, IN CONST UINT_T len, IN CONST CHAR_T *descript);

参数说明

参数名称	说明
map_id	本地地图 ID
buffer	上报的数据内容，数据格式参考涂鸦激光协议
len	上报的数据长度
descript	描述信息：`RecordId_BeginTime_CleanTime_CleanArea_MapLen_PathLen_VirtualLen_CleanMode_WorkMode_CleaningResult_StartMethod` 例如：`00011_20221025_130401_050_032_05000_00100_00100_01_01_00_00`

返回值

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

descript 描述说明

参数名称	说明
RecordId	清扫记录 ID ：5 个字符，如 `00011`，表示清扫记录 ID 为 `11`
FinishTime	清扫完成时间：15 个字符，如 `20221025_130401`，表示清扫完成时间 `2022 年 10 月 25 日 13:04:01`
CleanTime	清扫时长：3 个字符，如 `050`，表示清扫时长 50 分钟
CleanArea	清扫面积：3 个字符，如 `032`，表示清扫面积 32 平米
MapLen	清扫地图长度：5 个字符，如 `05000`，表示清扫地图数据长度 5000 字节
PathLen	清扫路径长度：5 个字符，如 `00100`，表示清扫路径数据长度 100 字节
VirtualLen	虚拟信息长度：5 个字符，如 `00100`，表示虚拟信息长度 100 字节，虚拟信息包括虚拟墙和禁区
CleanMode	清扫模式：2 个字符，如 `01`，其中： `00`：全屋清扫 `01`：选区清扫 `02`：定点清扫（指哪扫哪） `03`：划区清扫 `04`：原地定点清扫 `05`：智能分区清扫 `06`：智能分区区域清扫 `07`：深度全局清扫 `08`：沿边清扫
WorkMode	工作模式：2 个字符，如 `01`，其中： `00`：扫拖 `01`：仅扫 `02`：仅拖 `03`：自适应
CleaningResult	结束状态：2 个字符，如 `00` ，其中： `00`：异常结束 `01`：正常结束
StartMethod	启动方式：2 个字符，如 `00`，其中： `00`：物理遥控器启动 `01`：App 启动（云端发送指令） `02`：预约任务启动 `03`：设备按键启动

tuya_iot_map_upload_files

上传地图。

/***********************************************************
*  Function: tuya_iot_map_upload_files
*  Desc: Robot vacuum function. Upload cleaning map info
*  Input: bitmap_file& datamap_file & descript
*  output: 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 字节，该文件上传到云端后，可通过`tuya_iot_get_map_files`接口下载到设备本地。
descript	描述信息，格式参考 `mm_bin_mapid_nowtime.bin`，其中： `mapid`：拼接该文件的本地地图 ID `nowtime`：拼接当前时间（时间戳）例如，`mm_bin_01_1727408748.bin`
map_id	上报成功后，云端返回的地图 ID

返回值

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

tuya_iot_map_update_files

更新云端分配地图 ID 对应的地图文件。

/***********************************************************
*  Function: tuya_iot_map_update_files
*  Desc: Robot vacuum function. Update cleaning map info
*  Input: map_id
*  Input: bitmap & data_map_file
*  Return: OPERATE_RET
***********************************************************/
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);

参数说明

参数名称	说明
map_id	`cloud_map_id` 第一次上传地图，由云端分配的地图 ID
bitmap_file	需要更新的用于 App 显示的地图文件，全路径
data_map_file	客户自定义文件内容，文件名不能超过 16 字节，该文件上传到云端后，可通过 `tuya_iot_get_map_files` 接口下载到设备本地。

返回值

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

tuya_iot_map_delete

删除云端保存的地图文件。

/***********************************************************
*  Function: tuya_iot_map_delete
*  Desc: Robot vacuum function. Delete map files in cloud
*  Input: map_id
*  Return: OPERATE_RET
***********************************************************/
OPERATE_RET tuya_iot_map_delete(IN CONST UINT_T map_id);

参数说明

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

返回值

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

tuya_iot_get_all_maps_info

获取楼层地图文件列表信息。

/***********************************************************
*  Function: tuya_iot_get_all_maps_info
*  Desc: Robot vacuum function. Get map files
*  Input: map_info
*  Input: info_len
*  Output: get all map info (Maximum 5 sets of data)
*  Return: OPERATE_RET
***********************************************************/
OPERATE_RET tuya_iot_get_all_maps_info(OUT M_MAP_INFO *map_info, INOUT UINT8_T *info_len);

参数说明

参数名称	说明
map_info	地图信息列表，具体可参考 `M_MAP_INFO` 结构体
info_len	要获取的地图信息个数，最大 5 个

返回值

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

tuya_iot_get_map_files

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

/***********************************************************
*  Function: tuya_iot_get_map_files
*  Desc: Robot vacuum function. Get map files
*  Input: map_id
*  Input: map_path
*  Output: map files under map_path path.
*  Return: OPERATE_RET
***********************************************************/
OPERATE_RET tuya_iot_get_map_files(IN CONST UINT_T map_id, IN CONST CHAR_T *map_path);

参数说明

参数名称	说明
map_id	云端分配的地图 ID，`cloud_map_id`
map_path	下载地图文件保存的路径

返回值

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

实现示例

/**
 * @brief  业务楼层地图启动的逻辑
 * @param  [void*] arg
 * @return [*]
 */
void* thread_floor_map_send(void* arg)
{
    PR_DEBUG("floor map send thread start...");
    OPERATE_RET op_ret = 0;

    while (1) {
        op_ret = tuya_hal_semaphore_waittimeout(g_sweeper_floor_map_ctrl.floor_map_sem, 0xffffff); //最长无限等待
        //外部触发楼层地图及清扫记录的信号量后，里面可以执行相关的楼层地图操作。
        switch (floor_map_type) {
            case 0:
                op_ret = tuya_iot_map_upload_files(/*根据接口说明填写入参*/); // 地图上报,一般是新建地图完成之后调用该接口上报，存在云端。
            break;
            case 1:
                 op_ret = tuya_iot_map_update_files(/*根据接口说明填写入参*/); // 地图更新，这里需要之前上报过地图到云端，云端返回的cloud_map_id；这里要注意更新地图数据，是根据cloud_map_id来，而不是本地的地图id
            break; 
            case 2:
                 op_ret = tuya_iot_map_delete(/*根据接口说明填写入参*/); // 地图删除，这里需要之前上报过地图到云端，云端返回的cloud_map_id；这里要注意删除地图数据，是根据cloud_map_id来，而不是本地的地图id
            break;  
            case 3:
                 op_ret = tuya_iot_get_map_files(/*根据接口说明填写入参*/); // 地图下载地址获取，这里需要之前上报过地图到云端，云端返回的cloud_map_id；这里要注意下载地图数据，是根据cloud_map_id来，而不是本地的地图id
            break;   
            case 4:
                op_ret = get_all_map_info(); // 地图云端列表获取，一般调用该接口去云端获取地图列表，与本地的地图做对比，来检查设备端与云端地图是否对齐。
            break;  
            case 5:
                op_ret = tuya_iot_map_record_upload_buffer(/*根据接口说明填写入参*/); //清扫记录上报接口
            break; 
                                                                      
            default:
            break;
        }
        if (op_ret == OPRT_OK) {
        } else {
        }
    }
   //注意：以上接口由于网络波动，容易导致执行失败，开发者需要做好重传的逻辑处理，如重传 3 次，每次间隔 2 秒。
    PR_DEBUG("floor map send thread end...");
}
VOID_T floor_map_main(VOID_T)
{
    OPERATE_RET ret = OPRT_OK;
    
    /*第一步：设备相关接口初始化完成且设备在线*/
    user_main();
    /*第二步：创建独立线程*/
    THRD_PARAM_S thrd_param;
    THRD_HANDLE thrd; /* 任务句柄 */

    /* 创建楼层地图的线程任务 */
    thrd_param.stackDepth = 1024 * 1024;
    thrd_param.thrdname = "floor_map_trans_thrd";
    thrd_param.priority = TRD_PRIO_1;
    /* 创建机器状态管理任务 */
    ret = CreateAndStart(&thrd, NULL, NULL, (void*)thread_floor_map_send, NULL, &thrd_param);
    if (OPRT_OK != ret) {
        PR_ERR("floor_map_trans_thrd create failed!");
        return ret;
    }
    ret = tuya_hal_semaphore_create_init(&g_sweeper_floor_map_ctrl.floor_map_sem, 0, 1); //创建信号量
    if (OPRT_OK != ret) {
        PR_ERR("floor map sem create err!");
        return ret;
    }
    return ret;
}

常见注意事项

上报地图文件接口中 bitmap_file 和 datamap_file 的地图文件不能为空，也不可以用同一个路径文件传入，否则会导致云端唯一索引冲突，导致入库报错。
地图更新、删除地图及获取指定地图文件接口中 map_id 都是云端分配的 ID，需要自行将云端分配的 ID 保存起来。
在使用多楼层地图及清扫记录传输接口时，完善补报的机制，避免因为网络抖动原因导致数据上报不成功。

上一篇传输 RVC v1.0

下一篇实时地图与路径传输