RVC Transmission v1.0

Last Updated on : 2025-02-05 06:32:04download

Based on tuyaos_robot_rvc_sdk, this topic describes the process and APIs for transmitting multiple floor maps and the cleaning history of laser robot vacuum cleaners (RVC).

How it works

Report cleaning history

DeviceTuyaOS SDKCloudTuya-enabled Mobile Appty_rvc_map_record_upload_v2Report data to the serverSuccessPUBLISH(Qos0,Msg601)Delete(Msg)PUBLISH(Qos0,Msg601)Download cleaning history dataSuccessDeviceTuyaOS SDKCloudTuya-enabled Mobile App

Report multiple floor maps

DeviceTuyaOS SDKCloudTuya-enabled Mobile Apptuya_iot_map_files_upload_v2Report floor map data to theserverSuccessPUBLISH(Qos0,Msg601)Download floor map dataSuccesstuya_iot_map_files_update_v2Update map data to the serverSuccessPUBLISH(Qos0,Msg601)Update the mapSuccessUser deletes maptuya_iot_map_deleteReport data to the serverSuccesstuya_iot_get_all_maps_infoRead map information from thecloudSuccessDeviceTuyaOS SDKCloudTuya-enabled Mobile App

The above APIs are all reported in blocking mode. The application shall create a separate thread and asynchronously call the APIs for floor maps and cleaning history transmission.

API name

ty_rvc_map_record_upload_v2

Upload the cleaning history.

/**
 * @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_/**
 * @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;RESULT_MAX
} RVC_CLEAN_RESULT_E;

/**
 * @brief map data structure
 */
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 path data structure
 */
typedef struct {
    int total_area_size; // Total coverage area, unit: square meters
    int covered_time; // Coverage time, unit: minutes
    int total_clean_count; // Total number of cleanings (can be used as cleaning record ID)
    time_t end_stamp; // Cleaning end time (UTC, unit: seconds)

    RVC_RECORDS_CLRAN_MODE_E clean_mode; // Cleaning mode
    RVC_CLEAN_WORK_MODE_E work_mode; // Work mode
    RVC_CLEAN_RESULT_E end_status; // End status
    RVC_START_METHOD_E start_method; // Start method

    int all_clean_area_size;   // Total cleaning area
    int all_clean_time;        // Total cleaning time
    int all_clean_count;       // Total number of cleanings
    int path_len;              // Path data length
    char* path_buf;            // Path data content
} RVC_PATH_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,
                                        IN CONST RVC_PATH_DATA_S* clean_data,
                                        IN CONST RVC_MAP_ADDITIONAL_DATA_S* map_addition)

Parameter description

Parameter Description
current_map_id The ID of the specified local map.
map_data The map data.
clean_data The parameters of the cleaning history.
map_addition Information about virtual walls, restricted areas, and room attributes.

Return value

Return value Description
OPRT_OK The operation succeeded.
Error code The error code on a failed operation.

The format of the current map data in map_data should be filled out according to the RVC_MAP_DATA_S structure. You can refer to the splicing logic of the map reporting interface in the Map and route data structure.

tuya_iot_map_files_upload_v2

Upload a map file.

/**
 * @brief map data structure
 */
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)

Parameter description

Parameter Description
custom_datamap_file The file content is user-defined, but the file name must not exceed 16 bytes. After the file is uploaded to the cloud, the map feature on the app panel can be used to download the map to the local device.
current_map_id The ID of the specified map.
map_data The map data.
map_addition Information about virtual walls, restricted areas, and room attributes.
map_id The returned map ID after the data is reported.

Return value

Return value Description
OPRT_OK The operation succeeded.
Error code The error code on a failed operation.

tuya_iot_map_files_update_v2

Update a map file.

/***********************************************************
 *@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);

Parameter description

Parameter Description
cloud_map_id The returned map ID after the map is uploaded.
custom_datamap_file The file content is user-defined, but the file name must not exceed 16 bytes. After the file is uploaded to the cloud, the map feature on the app panel can be used to download the map to the local device.
current_map_id The ID of the specified map.
map_data The map data.
map_addition Information about virtual walls, restricted areas, and room attributes.

Return value

Return value Description
OPRT_OK The operation succeeded.
Error code The error code on a failed operation.

The format of the current map data in map_data should be filled out according to the RVC_MAP_DATA_S structure. You can refer to the splicing logic of the map reporting interface in the Map and route data structure.

tuya_iot_map_delete

Delete map files from the cloud.

/*
 * @brief tuya_iot_map_delete
 * @desc Robot vacuum function. Delete map files in cloud
 * @param[in] map_id Current map ID
 * @return OPERATE_RET
*/
OPERATE_RET tuya_iot_map_delete(IN CONST UINT_T map_id);

Parameter description

Parameter Description
map_id cloud_map_id. The map ID assigned by the cloud server.

Return value

Return value Description
OPRT_OK The operation succeeded.
Error code The error code on a failed operation.

tuya_iot_get_all_maps_info

Get a list of floor map files.

/***********************************************************
*  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);

Parameter description

Parameter Description
map_info The list of map information. For more information, see the M_MAP_INFO structure.
info_len The number of maps to be obtained. Maximum value: 5.

Return value

Return value Description
OPRT_OK The operation succeeded.
Error code The error code on a failed operation.

Example

/**
 * @brief The logic for starting the floor map
 * @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); // Maximum infinite wait
        // After the floor map and cleaning history semaphores are externally triggered, the relevant floor map operations can be performed.
        switch (floor_map_type) {
             case 0:
                op_ret = tuya_iot_map_files_upload_v2(/*Fill in request parameters based on the interface description*/); // Map reporting. Generally, after a new map is created, this interface is called to report the map and store it in the cloud.
            break;
             case 1:
                 op_ret = tuya_iot_map_files_update_v2(/*Fill in the request parameters based on the interface description*/); // To update the map, the map must have been reported to the cloud before, and the cloud has assigned a cloud_map_id. Note that the map data is updated based on the cloud_map_id, not the local map ID.
            break;
            case 2:
                 op_ret = tuya_iot_map_delete(/*Fill in the request parameters based on the interface description*/); // To delete the map, the map must have been reported to the cloud before, and the cloud has assigned a cloud_map_id. Note that the map data is deleted based on the cloud_map_id, not the local map ID.
            break;    
            case 4:
                op_ret = get_all_map_info(); // Get the map list from the cloud. This interface is usually called to get the map list from the cloud and compare it with the local map to check whether the maps in the device and cloud are aligned.
            break;  
             case 5:
                op_ret = ty_rvc_map_record_upload_v2(/*Fill in request parameters based on the interface description*/); //Report cleaning history.
            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;

    /*Step 1: Initialize device interfaces and make the device online*/
     user_main();
    /*Step 2: Create a separate thread*/
    THRD_PARAM_S thrd_param;
    THRD_HANDLE thrd; /* Task handle. */

    /* Thread task to create a floor map. */
     thrd_param.stackDepth = 1024 * 1024;
    thrd_param.thrdname = "floor_map_trans_thrd";
    thrd_param.priority = TRD_PRIO_1;
    /* Create a device status management task. */
    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); //Create a semaphore.
if (OPRT_OK != ret) { PR_ERR("floor map sem create err!");         return ret;
    }
    return ret;
}