Transmission APIs (Legacy)

Based on tuyaos_robot_sweeper_sdk, this topic describes the process and APIs for transmitting multiple floor maps and the cleaning history of laser robot vacuums.

How it works

Report cleaning history

Report multiple floor maps

APIs

tuya_iot_map_record_upload_buffer

Upload the cleaning history.

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

Parameter description

Parameter	Description
map_id	The ID of the specified local map.
buffer	The content of the reported data. For more information about data formats, see Tuya laser robot vacuum protocol.
len	The length of the reported data.
descript	The description information in the format similar to RecordId_BeginTime_CleanTime_CleanArea_MapLen_PathLen_VirtualLen_CleanMode_WorkMode_CleaningResult_StartMethod. Example: 00011_20221025_130401_050_032_05000_00100_00100_01_01_00_00.

Return value

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

Description of descript

Parameter	Description
RecordId	The ID of the cleaning history, with 5 characters. For example, 00011 means the cleaning history ID is 11.
FinishTime	The completion time of cleaning, with 15 characters. For example, 20221025_130401 means that cleaning was completed on October 25, 2022, at 13:04:01.
CleanTime	The cleaning duration, with 3 characters. For example, 050 means the cleaning duration is 50 minutes.
CleanArea	The cleaning area, with 3 characters. For example, 032 means the cleaning area is 32 square meters.
MapLen	The data length of a cleaning map, with 5 characters. For example, 05000 means the data length of the specified cleaning map is 5,000 bytes.
PathLen	The data length of a cleaning route, with 5 characters. For example, 00100 means the data length of the specified cleaning route is 100 bytes.
VirtualLen	The data length of virtual information, with 5 characters. For example, 00100 means the data length of virtual information is 100 bytes. Virtual information includes virtual walls and no-go areas.
CleanMode	The cleaning mode, with 2 characters. For example, 01, where: 00: Entire house cleaning 01: Selected area cleaning 02: Selected spot cleaning (point and go) 03: Selected zone cleaning 04: Selected in-situ spot cleaning 05: Smart partitioned cleaning 06: Smart partitioned area cleaning 07: Deep global cleaning 08: Cleaning along the edge
WorkMode	The working mode, with 2 characters. For example, 01, where: 00: Sweep and mop 01: Sweep only 02: Mop only 03: Adaptive
CleaningResult	The end status, with 2 characters. For example, 00, where: 00: End with an exception 01: End as expected
StartMethod	The start method, with 2 characters. For example, 00, where: 00: Start via a physical remote control 01: Start via an app (commands are sent from the cloud) 02: Start based on a scheduled task 03: Start by pressing a device button

tuya_iot_map_upload_files

Upload a map file.

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

Parameter description

Parameter	Description
bitmap_file	Upload the map file used for display on the mobile app. The file name must not exceed 16 bytes. For more information about the file content format, see Tuya laser robot vacuum protocol.
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, tuya_iot_get_map_files can be used to download the map to the local device.
descript	The description information. Refer to the format in the mm_bin_mapid_nowtime.bin file. mapid: The local map ID of the file. nowtime: The current time (timestamp). For example, mm_bin_01_1727408748.bin.
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_update_files

Update the map data by map 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);

Parameter description

Parameter	Description
map_id	cloud_map_id. The map ID assigned by the cloud server when uploading the map for the first time.
bitmap_file	The full map file to be updated, used for display on the mobile app.
data_map_file	The file content is user-defined, but the file name must not exceed 16 bytes. After the file is uploaded to the cloud, tuya_iot_get_map_files can be used to download the map to the local device.

Return value

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

tuya_iot_map_delete

Delete map files from the cloud.

/***********************************************************
*  Function: tuya_iot_map_delete
*  Desc: Robot vacuum function. Delete map files in the cloud
*  Input: 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
***********************************************************/
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.

tuya_iot_get_map_files

Download the map file by map_id and store it in the specified directory.

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

Parameter description

Parameter	Description
map_id	cloud_map_id. The map ID assigned by the cloud server.
map_path	The path where the downloaded map file resides.

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_upload_files(/*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_update_files(/*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 3:
                 op_ret = tuya_iot_get_map_files(/*Fill in the request parameters based on the interface description*/); // To get the map download URL, 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 downloaded 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 = tuya_iot_map_record_upload_buffer(/*Fill in request parameters based on the interface description*/); //Report cleaning history.
            break;

            default:
             break;
        }
        if (op_ret == OPRT_OK) {
        } else {
        }
    }
   //Note: The above interfaces are prone to execution failure due to network jitter. You need to implement a retransmission logic, such as retransmitting 3 times, each with an interval of 2 seconds.
    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;
}

Things to note

• In the API for reporting map files, the bitmap_file and datamap_file map files cannot be empty, nor can they be passed in with the same file. Otherwise, the unique index in the cloud will conflict and an error will occur in the database.

  

• In the APIs for updating, deleting, and obtaining specified map files, map_id is an ID assigned by the cloud server. Properly keep this ID.

• When you use the APIs for transmitting multiple floor maps and the cleaning history, implement a retransmission mechanism to avoid unsuccessful data reporting due to network jitter.