Complex Protocol Control

To reduce development costs and facilitate the interaction between robot vacuums and app panels, the laser robot vacuum SDK encapsulates complex controls such as virtual walls and room properties into different APIs. You can use the APIs to easily complete data communication.

Overview

The APIs support the following features:

• Complete the protocol parsing for functional parameter settings sent by the cloud, and deliver the set/query commands and their parameters to the business application through the callback interface.
• Encapsulate device functional parameter reporting APIs. If the device has data synchronized with the cloud, the reporting can be completed by calling the specified functional reporting interface.

The following table shows the commands currently supported by the APIs:

How it works

• The device can synchronize data with the Tuya-enabled app in the following three ways:
  • When the device data status changes, the device proactively calls the interface to report the data.
  • When the panel initiates a data query command, the device responds passively to complete data reporting.
  • When the panel initiates a data setting command, the device completes the functional processing and calls the interface to report and synchronize data.
• After the application receives the processing command corresponding to the FUNC_SET_CB callback, it needs to handle the event asynchronously to ensure that frequent clicks on the panel for sending command do not block subsequent command parsing. During asynchronous processing, the command parameters should be copied first, and then the copied data should be used for command event processing.

APIs

Register a protocol handler callback

This interface is used to register command handler callback functions. After the callback is successfully registered, the SDK receives and parses the command protocol sent by the cloud, and then calls the registered callback to execute the business functionalities. Note that the param variable in the callback will be released after the callback is invoked. If the callback has asynchronous operations, you need to copy the param data to the variable space requested by your application.

/**
 * @brief Sweeper advanced function setting callback function pointer
 * @param [ADVANCE_CMD_E] cmd, protocol command, the SDK uses this parameter to notify the application of the current setting command to be processed, see the list for setting commands, all ending with SET
 * @param [void *] param, parameters corresponding to the command, the application converts the param parameter into the command corresponding parameter structure based on the cmd command field, the structure correspondence can refer to the accompanying demo
 */
typedef OPERATE_RET (*FUNC_SET_CB)(IN ADVANCE_CMD_E cmd, IN void* param);

/**
 * @brief Sweeper advanced function query callback function pointer
 * @param [ADVANCE_CMD_E] cmd, protocol command, the SDK uses this parameter to notify the application of the current query command to be processed, see the list for query commands, all ending with QUERY
 * @param [void *] param, parameters corresponding to the command, current query command, its parameters are meaningless and do not need to be processed
 * @note  When the application gets the corresponding command parameters in the query callback function and needs to report, please call the corresponding response reporting function, for example, after processing the VIRTUAL_WALL_QUERY command, when needing to report parameters, use the ty_rvc_virtual_wall_data_response interface to report
 */
typedef OPERATE_RET (*FUNC_QUERY_CB)(IN ADVANCE_CMD_E cmd, IN void* param);

/**
 * @brief Register advanced capability setting and query callback functions
 * @param[in] sets_handler: Command setting callback function that the application needs to implement
 * @param[in] query_handler: Command query callback function that the application needs to implement
 * @return OPERATE_RET: 0 success, other error codes indicate failure
 */
OPERATE_RET ty_rvc_advance_func_register(IN FUNC_SET_CB sets_handler, IN FUNC_QUERY_CB query_handler);

Data reporting interfaces

The device data reporting interfaces are used to complete data synchronization with Tuya-enabled apps. The following table lists the data reporting features provided by each interface:

/**
 * @brief Report virtual wall information
 * @param[in] p_virtual_wall: Virtual wall data, passed in by the application, parameters are defined in the structure
 * @param[in] errcode: Command execution result, 0 for success, other values for failure
 * @return OPERATE_RET: 0 success, other error codes indicate failure
 */
OPERATE_RET ty_rvc_virtual_wall_data_response(VIRTUAL_WALL_S* p_virtual_wall, int errcode);

/**
 * @brief Report restricted area data
 * @param[in] p_restricted_area: Restricted area data input parameter, passed in by the application, parameters are defined in the structure
 * @param[in] errcode: Execution result corresponding to the parameter setting, 0 for success, other values for failure
 * @return OPERATE_RET: 0 success, other error codes indicate failure
 */
OPERATE_RET ty_rvc_restricted_area_data_response(RESTRICTED_AREA_S* p_restricted_area, int errcode);

/**
 * @brief Report room property data
 * @param[in] p_room_clean: Room property data, passed in by the application, parameters are defined in the structure
 * @param[in] errcode: Execution result corresponding to the parameter setting, 0 for success, other values for failure
 * @return OPERATE_RET: 0 success, other error codes indicate failure
 */
OPERATE_RET ty_rvc_room_property_data_response(ROOM_PROPERTY_S* p_room_clean, int errcode);

/**
 * @brief Report selected area cleaning parameter values
 * @param[in] p_room_clean: Cleaning parameter input parameter, passed in by the application, parameters are defined in the structure
 * @param[in] errcode: Execution error code, no error, input parameter is 0
 * @return OPERATE_RET: 0 success, other error codes indicate failure
 */
OPERATE_RET ty_rvc_room_clean_data_response(ROOM_CLEAN_S* p_room_clean, int errcode);

/**
 * @brief Report spot cleaning data
 * @param[in] spot_clean_data: Spot cleaning data input parameter, passed in by the application, parameters are defined in the structure
 * @param[in] errcode: Execution error code, input 0 when no error
 * @return OPERATE_RET: 0 success, other error codes indicate failure
 */
OPERATE_RET ty_rvc_spot_clean_data_response(SPOT_CLEAN_S* spot_clean_data, int errcode);

/**
 * @brief Report zone cleaning data
 * @param[in] p_zone_area: Zone cleaning data input parameter, passed in by the application, parameters are defined in the structure
 * @param[in] errcode: Execution error code, input 0 when no error
 * @return OPERATE_RET: 0 success, other error codes indicate failure
 */
OPERATE_RET ty_rvc_zone_clean_data_response(ZONE_CLEAN_S* p_zone_area, int errcode);

/**
 * @brief Partition setting reply
 * @param[in] p_part_division: Partition parameters, passed in by the application, parameters are defined in the structure
 * @param[in] errcode: Execution error code, input 0 when no error
 * @return OPERATE_RET: 0 success, other error codes indicate failure
 */
OPERATE_RET ty_rvc_part_division_data_response(PART_DIVI_S* p_part_division, PART_DIV_ST_E errcode);

/**
 * @brief Partition merge command reply
 * @param[in] p_part_merge: Partition setting reply parameters, passed in by the application, parameters are defined in the structure
 * @param[in] errcode: Execution error code, input 0 when no error
 * @return OPERATE_RET: 0 success, other error codes indicate failure
 */
OPERATE_RET ty_rvc_part_merge_data_response(PART_MERGE_S* p_part_merge, PART_MERGE_ST_E errcode);

/**
 * @brief Partition restore default command response
 * @param[in] p_part_merge: Structure parameters, passed in by the application, parameters are defined in the structure
 * @param[in] errcode: Execution error code
 * @return OPERATE_RET: 0 success, other error codes indicate failure
 */
OPERATE_RET ty_rvc_map_part_default_data_response(MAP_PART_RESET_S* p_part_merge, PART_RESET_ST_E errcode);

/**
 * @brief Clear home map reply
 * @param[in] p_map_reset: Map reset structure, passed in by the application, parameters are defined in the structure
 * @param[in] errcode: Execution error code
 * @return OPERATE_RET: 0 success, other error codes indicate failure
 */
OPERATE_RET ty_rvc_map_clear_data_response(CURRENT_MAP_RESET_S* p_map_reset, MAP_RESET_ST_E errcode);

/**
 * @brief Map save command reply
 * @param[in] p_map_save: Map save reply parameter input, passed in by the application, parameters are defined in the structure
 * @param[in] errcode: Error code
 * @return OPERATE_RET: 0 success, other error codes indicate failure
 */
OPERATE_RET ty_rvc_map_save_data_response(MAP_SAVE_S* p_map_save, MAP_SAVE_ST_E errcode);

/**
 * @brief Map delete command reply
 * @param[in] p_map_delete: Map delete reply parameters, passed in by the application, parameters are defined in the structure
 * @param[in] errcode: Error code
 * @return OPERATE_RET: 0 success, other error codes indicate failure
 */
OPERATE_RET ty_rvc_map_delete_data_response(DELETE_CLOUD_MAP_S* p_map_delete, MAP_DELETE_ST_E errcode);

/**
 * @brief Use map command reply
 * @param[in] p_map_use_set: Use map reply parameters, passed in by the application, parameters are defined in the structure
 * @param[in] errcode: Error code
 * @return OPERATE_RET: 0 success, other error codes indicate failure
 */
OPERATE_RET ty_rvc_map_use_data_response(USE_CLOUD_MAP_S* p_map_use_set, MAP_USE_ST_E errcode);

/**
 * @brief Scheduled data report
 * @param[in] p_schedule: Scheduled data, passed in by the application, parameters are defined in the structure
 * @param[in] current_map_id:
 * @param[in] errcode:
 * @return OPERATE_RET: 0 success, other error codes indicate failure
 */
OPERATE_RET ty_rvc_schedule_data_response(SCHEDULE_S* p_schedule, int errcode);

/**
 * @brief Do not disturb scheduled data report
 * @param[in] p_quiet_hours: Do not disturb scheduled data input, passed in by the application, parameters are defined in the structure
 * @param[in] errcode: Error code
 * @return OPERATE_RET: 0 success, other error codes indicate failure
 */
OPERATE_RET ty_rvc_quiet_hours_data_response(QUIET_HOURS_S* p_quiet_hours, int errcode);

/**
 * @brief Voice use parameter report
 * @param[in] p_voice_language_set: Voice use parameter report, passed in by the application, parameters are defined in the structure
 * @param[in] errcode: Execution error code
 * @param[in] download_status: Voice file download status
 * @param[in] schedule: File download progress, value range 0~100, representing 0%~100%
 * @return OPERATE_RET: 0 success, other error codes indicate failure
 */
OPERATE_RET ty_rvc_voice_language_data_response(USE_VOICE_LANGUAGE_S* p_voice_language_set, VOICE_USE_ST_E errcode, VOICE_DOWNLOAD_ST_E download_status, int schedule);

/**
 * @brief Device information report, info field is concatenated by the customer in key:value format in JSON, when the app panel displays device information, it shows each value in the order of the key list
 * The panel needs to correctly configure multilingual support for each key value
 * This interface is responsible for completing data reporting via the MQTT channel
 *
 * @param[char*] info: Application's JSON format string
 * @param [int] len: String length
 * @return OPERATE_RET, OPRT_OK indicates success, other error codes indicate failure
 */
OPERATE_RET ty_rvc_device_info_data_response(char* info, int len);

Example

static OPERATE_RET __sweeper_advance_function_set(OUT ADVANCE_CMD_E cmd, OUT void *param)
{
    OPERATE_RET ret = 0;
    int i=0,j=0;
    switch (cmd) {
        case VIRTUAL_WALL_SET: {
            VIRTUAL_WALL_S* p_virtual_wall = (VIRTUAL_WALL_S*)param;
            PR_DEBUG("virtual wall num:%d", p_virtual_wall->num);
            for(i = 0; i < p_virtual_wall->num;i++){
                PR_DEBUG("mode:%d", p_virtual_wall->line[i].mode);
                PR_DEBUG("line:%d", p_virtual_wall->line[i].points[0].x);
                PR_DEBUG("line:%d", p_virtual_wall->line[i].points[0].y);
                PR_DEBUG("line:%d", p_virtual_wall->line[i].points[1].x);
                PR_DEBUG("line:%d", p_virtual_wall->line[i].points[1].y);
            }

            ........
            //This section only shows how to call the interface. In actual use, the actual device data should be obtained in the asynchronous event processing function and reported.
            current_map_id = 8;
            errcode = 0;
            ty_rvc_virtual_wall_data_response(p_virtual_wall, current_map_id, errcode);  

            }break;
            .......
            default:
                PR_DEBUG("cmd not support now");
                break;
    }

}


static OPERATE_RET __sweeper_advance_function_query(OUT ADVANCE_CMD_E cmd, OUT void *param)
{
    OPERATE_RET ret = OPRT_OK;
    uint16_t cmd_index = 0;
    switch(cmd){
        case VIRTUAL_WALL_QUERY:{
	//Use test data to show data reporting
            VIRTUAL_WALL_S test_virtual_wall;
            VIRTUAL_LINE_S virtual_line[10] = {0};
            OPERATE_RET ret = OPRT_OK;

            test_virtual_wall.num = 1;
            for (int i = 0; i < test_virtual_wall.num; i++) {
                virtual_line[i].mode = FORBIT_ALL;
                virtual_line[i].points[0].x = 100;
                virtual_line[i].points[0].y = 200;
                virtual_line[i].points[1].x = 50;
                virtual_line[i].points[1].y = 60;
            }
            test_virtual_wall.line = virtual_line;
            int current_map_id = 7;
            ty_rvc_virtual_wall_data_response(&test_virtual_wall, current_map_id, errcode);          
        }break;
        default:
        PR_DEBUG("cmd not support now");
        break;
    }
    return ret;
}


//Power on main process
int main(int argc, char* argv[])
{
    OPERATE_RET ret = 0;
    ....
    ret = ty_sys_start();
    if (ret != OPRT_OK) {
        PR_ERR("[%s, %d] sys start failed", __FUNCTION__, __LINE__);
        return ret;
    }

    ty_rvc_advance_func_register(__sweeper_advance_function_set, __sweeper_advance_function_query);
	....
}