传输 RVC v1.0

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

流程说明

清扫记录上报

多楼层地图上报

API

ty_rvc_map_record_upload_v2

上传清扫记录。

/**
 * @brief Supported working modes for cleaning records
 */
typedef enum {
    RVC_CLEAN_BOTH = 0,    // Sweeping and mopping mode
    RVC_CLEAN_ONLY_SWEEP,  // Sweeping mode
    RVC_CLEAN_ONLY_MOP,    // Mopping mode
    RVC_CLEAN_ADAPTIVE,    // Adaptive mode
    RVC_CLEAN_MODE_MAX
} RVC_CLEAN_WORK_MODE_E;

/** 
 * @brief Supported cleaning modes for cleaning records
 */
typedef enum {
    RVC_CLEAN_MODE_SMART = 0,       // Whole house cleaning
    RVC_CLEAN_MODE_SELECT_ROOM,     // Selective room cleaning
    RVC_CLEAN_MODE_POSE,            // Point cleaning
    RVC_CLEAN_MODE_ZONE,            // Zoned cleaning
    RVC_CLEAN_MODE_STAND_POSE,      // Stationary point cleaning
    RVC_CLEAN_MODE_SMART_PART,      // Smart partition cleaning  
    RVC_CLEAN_MODE_SMART_PART_AREA, // Smart partition area cleaning
    RVC_CLEAN_MODE_DEPTH_GLOBAL,    // Deep global cleaning
    RVC_CLEAN_MODE_EDGE,            // Edge cleaning
    RVC_CLEAN_MODE_MAX
} RVC_RECORDS_CLRAN_MODE_E;

/**
 * @brief Cleaning end reasons identified in cleaning records
 */
typedef enum {
    RVC_CLEAN_RESULT_ERR = 0, // Abnormal end
    RVC_CLEAN_RESULT_OK,      // Normal end
    RVC_CLEAN_RESULT_MAX
} RVC_CLEAN_RESULT_E;

/**
 * @brief Machine Start Method
 */
typedef enum {
    RVC_START_METHOD_REMOTE = 0, // Physical remote control start
    RVC_START_METHOD_APP,        // APP start
    RVC_START_METHOD_RESERVED,   // Scheduled task start
    RVC_START_METHOD_BUTTON,     // Button start
    RVC_START_METHOD_SELF,       // Self-start (e.g., automatic recharging)
    RVC_START_METHOD_MAX,
} RVC_START_METHOD_E;

/**
 * @brief map data structer
 */
typedef struct{
    RVC_MAP_HEAD_INFO_S header;  // Parameters for the map protocol header of the vacuum cleaner
    unsigned char** map_buff;  // Pixel data on the map
    int room_polygons_count;   // Number of Room Zones
    RVC_ROOM_POLYGON_S* room_polygons_data;  // Area polygon parameters
}RVC_MAP_DATA_S;

/**
 * @brief  clean data structer
 */
typedef struct {
    int total_area_size;      // Coverage area, in square meters.
    int covered_time;         // Coverage time, in minutes.
    int total_clean_count;    // The number of cleanings (can be used as cleaning record ID).
    TIME_T end_stamp;        // Cleaning end time (UTC, in seconds)

    RVC_CLEAN_MODE_E clean_mode;      // The cleaning mode
    RVC_WORK_MODE_E work_mode;        // The sweeping mode
    RVC_CLEAN_RESULT_E end_status;    // The cleaning end status
    RVC_START_METHOD_E start_method;  // The cleaning start method

    int all_clean_area_size;    // Total cleaning area
    int all_clean_time;     // Total cleaning time
    int all_clean_count;    // Total cleaning count
    RVC_PATH_INFO_S path_info; // The cleaning path data
} RVC_CLEAN_DATA_S;

/**
 * @brief map additional data
 */
typedef struct{
    VIRTUAL_WALL_S  virtual_wall;        //Virtual wall structure
    RESTRICTED_AREA_S restricted_area;  //Restricted area structure
    ROOM_PROPERTY_S  room_proper;  //Room property structure
}RVC_MAP_ADDITIONAL_DATA_S;

/**
 * @brief ty_rvc_map_record_upload_v2
 * @desc Robot vacuum function. Upload record map info
 * @param[in] current_map_id Current map ID
 * @param[in] map_data  Current map data
 * @param[in] clean_data Cleaning record parameters
 * @param[in] map_addition Information about virtual walls, restricted areas, and room attributes
 * @return OPERATE_RET
 */
OPERATE_RET ty_rvc_map_record_upload_v2(IN CONST INT_T current_map_id, 
                                        IN CONST RVC_MAP_DATA_S* map_data, 
                                        RVC_CLEAN_DATA_S* clean_data, 
                                        IN CONST RVC_MAP_ADDITIONAL_DATA_S* map_addition)

参数说明

参数名称	说明
current_map_id	当前本地地图 ID
map_data	当前地图数据
clean_data	清扫记录参数
map_addition	虚拟墙、禁区及房间属性信息

返回值

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

tuya_iot_map_files_upload_v2

上传地图。

/**
 * @brief map data structer
 */
typedef struct{
    RVC_MAP_HEAD_INFO_S header;  //Parameters for the map protocol header of the vacuum cleaner
    unsigned char** map_buff;  //Pixel data on the map
    int room_polygons_count;   //Number of Room Zones
    RVC_ROOM_POLYGON_S* room_polygons_data;  //Area polygon parameters
}RVC_MAP_DATA_S;
/**
 * @brief map additional data
 */
typedef struct{
    VIRTUAL_WALL_S  virtual_wall;        //Virtual wall structure
    RESTRICTED_AREA_S restricted_area;  //Restricted area structure
    ROOM_PROPERTY_S  room_proper;  //Room property structure
}RVC_MAP_ADDITIONAL_DATA_S;
/**
 * @brief upload type
 */
typedef struct {
    int uploader_type;  //Upload type 0 indicates uploading a map; upload type 1 indicates updating a map.
    int upload_cloud_id[1];  //cloud id results
}UPLOAD_TYPE_S;

/**
 * @brief tuya_iot_map_files_upload_v2
 * @desc Robot vacuum function. Upload cleaning map information
 * @param[in] current_map_id Current map ID
 * @param[in] map_data Current map data
 * @param[in] map_addition Information about virtual walls, restricted areas, and room attributes
 * @param[out]map_id  Cloud feedback on results
 * @return OPERATE_RET
 */
OPERATE_RET tuya_iot_map_files_upload_v2(IN CONST CHAR_T* custom_datamap_file, 
                                         IN CONST INT_T current_map_id, 
                                         IN CONST RVC_MAP_DATA_S* map_data, 
                                         IN CONST RVC_MAP_ADDITIONAL_DATA_S* map_addition,  
                                         OUT CONST UINT_T* map_id)

参数说明

参数名称	说明
custom_datamap_file	客户自定义文件内容，文件名不能超过 16 字节。该文件上传到云端后，可通过面板端使用地图功能将该地图下载到设备本地
current_map_id	当前地图 ID
map_data	当前地图数据
map_addition	虚拟墙、禁区及房间属性信息
map_id	上报成功后，云端返回的地图 ID

返回值

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

tuya_iot_map_files_update_v2

更新地图。

/***********************************************************
 *@function: tuya_iot_map_files_update_v2
 *@brief:  sweeper function. update floor map info
 *@param[in] cloud_map_id: update map file to cloud map id
 *@param[in] datamap update customize map file
 *@param[in] current_map_id Current map ID
 *@param[in] map_data Current map data
 *@param[in] map_addition Information about virtual walls, restricted areas, and room attributes
 *@return OPERATE_RET: 0 for success, other error codes indicate failure
 ***********************************************************/
OPERATE_RET tuya_iot_map_files_update_v2(IN CONST UINT_T cloud_map_id, 
                                         IN CONST CHAR_T* custom_datamap_file, 
                                         IN CONST INT_T current_map_id, 
                                         IN CONST RVC_MAP_DATA_S* map_data, 
                                         IN CONST RVC_MAP_ADDITIONAL_DATA_S* map_addition);

参数说明

参数名称	说明
cloud_map_id	上传地图后，由云端分配的地图 ID
custom_datamap_file	客户自定义文件内容，文件名不能超过 16 字节 ，该文件上传到云端后，可通过面板端使用地图功能将该地图下载到设备本地。
current_map_id	当前地图 ID
map_data	当前地图数据
map_addition	虚拟墙、禁区及房间属性信息

返回值

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

tuya_iot_map_delete

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

/*
 * @brief tuya_iot_map_delete
 * @desc Robot vacuum function. Delete map files in cloudn
 * @param[in] map_id Current 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
***********************************************************/
/*
 * @brieftuya_iot_get_all_maps_infoe
 * @desc Robot vacuum function. Get map files
 * @param[in] map_info cloud map list info
 * @param[in] info_len cloud map num
 * @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	操作成功
错误码	失败返回错误码

实现示例

/**
 * @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_files_upload_v2(/*根据接口说明填写入参*/); // 地图上报，一般是新建地图完成之后调用该接口上报，存在云端。
            break;
            case 1:
                 op_ret = tuya_iot_map_files_update_v2(/*根据接口说明填写入参*/); // 地图更新，是需要之前上报过该地图到云端，云端并分配了 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 4:
                op_ret = get_all_map_info(); // 地图云端列表获取，一般调用该接口去云端获取地图列表，与本地的地图做对比，来检查设备端与云端地图是否对齐。
            break;  
            case 5:
                op_ret = ty_rvc_map_record_upload_v2(/*根据接口说明填写入参*/); //清扫记录上报接口
            break; 
                                                                      
            default:
            break;
        }
        if (op_ret == OPRT_OK) {
        } else {
        }
    }
    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;
}