Protocol Control for Boundaryless Lawn Mower

Last Updated on : 2026-05-28 06:11:04Copy for LLMView as MarkdownDownload PDF

This topic describes the protocol features of the boundaryless lawn mower SDK. You can use it to quickly integrate features between the lawn mower app and the device.

Features

The boundaryless lawn mower SDK protocol layer parses feature parameter settings sent from the cloud, and delivers the set or query commands and their parameters to the business application through callbacks.

Supported API commands

Feature	Command type identifier
Mowing task	`IMMEDIATE_MOWING_TASK_REQUEST`
Return-to-charge task	`IMMEDIATE_CHARGE_TASK_REQUEST`
Pause task	`IMMEDIATE_PAUSE_TASK_REQUEST`
Remote control task	`DEV_REMOTE_CONTROL_TASK_REQUEST`
Status subscription	`DEV_SUBSCRIBE_REQUEST`
Vector map: edit	`VECTOR_MAP_EDITING_REQUEST`
Vector map: record elements	`VECTOR_RECORD_ELEMENT_REQUEST`
Vector map: delete elements	`VECTOR_DELETE_ELEMENT_REQUEST`
Vector map: undo recorded points	`VECTOR_UNDO_POINT_REQUEST`
Vector map: start auto-sampling mode	`VECTOR_SAMPLING_REQUEST`
Get map details	`VECTOR_GET_MAP_INFO_REQUEST`
Get mowing record	`VECTOR_GET_RECORD_INFO_REQUEST`
Get map list	`VECTOR_GET_MAP_LIST_REQUEST`
Delete map	`VECTOR_MAP_DELETE_REQUEST`
Get mowing record list	`MOW_RECORD_INFO_LIST_REQUEST`
Get error record list	`ERROR_RECORD_INFO_LIST_REQUEST`
Calendar schedule: get full schedule list	`SCHEDULE_QUERY_REQUEST`
Create schedule	`SCHEDULE_CREATE_REQUEST`
Update schedule	`SCHEDULE_UPDATE_REQUEST`
Delete a specific time period	`SCHEDULE_DELETE_PERIOD_REQUEST`
Enable schedule	`SCHEDULE_ENABLE_REQUEST`
Disable schedule	`SCHEDULE_DISABLE_REQUEST`
Get robot configuration	`CONFIGURATION_GET_REQUEST`
Set rain mode for robot (reserved)	`CONFIGURATION_SET_RAINY_DAY_MODE_REQUEST`
Set mowing switch for robot (reserved)	`CONFIGURATION_SET_CUT_SWITCH_REQUEST`
Set manual speed for robot (reserved)	`CONFIGURATION_SET_SPEED_REQUEST`
Set base station for robot	`CONFIGURATION_SET_BASE_REQUEST`
Set password for robot	`CONFIGURATION_SET_PASSWORD_REQUEST`
Get lawn task settings	`TASK_SETTINGS_GET_REQUEST`
Set lawn task settings	`TASK_SETTINGS_SET_REQUEST`
Get planned path	`PLANNED_PATH_GET_REQUEST`
Get mowing path	`MOWING_PATH_GET_REQUEST`
Set custom shape	`CUSTOM_SHAPE_SET_REQUEST`
Custom shape list	Returned together with `VECTOR_GET_MAP_INFO_REQUEST` in `RLM_MAP_INFO_R.custom_shapes`

Trigger timing

The SDK passes commands to the application through registered callback functions. Commands are triggered in the following scenarios:

Triggered by users’ proactive operation (SET command)

Trigger scenario: The user operates the app panel.

User operation	Triggered command	Trigger timing
Tap Start mowing on the home page	`IMMEDIATE_MOWING_TASK_REQUEST`	After the user confirms the start
Tap Charge on the home page	`IMMEDIATE_CHARGE_TASK_REQUEST`	After the user confirms the charge
Tap Pause or Resume on the home page	`IMMEDIATE_PAUSE_TASK_REQUEST`	After the user taps the button
Operate directions on the remote control page	`DEV_REMOTE_CONTROL_TASK_REQUEST`	Continuous sending during sustained user operation
Enter panel	`DEV_SUBSCRIBE_REQUEST`	When the panel initiates a subscription
Enter or exit map editing	`VECTOR_MAP_EDITING_REQUEST`	After the user confirms entry or exit
Record vector elements, such as fences or boundaries	`VECTOR_RECORD_ELEMENT_REQUEST`	After the user draws and confirms
Delete vector elements	`VECTOR_DELETE_ELEMENT_REQUEST`	After the user confirms the deletion
Undo recorded points	`VECTOR_UNDO_POINT_REQUEST`	After the user taps undo
Start auto-sampling mode	`VECTOR_SAMPLING_REQUEST`	After the user taps start sampling
Delete map	`VECTOR_MAP_DELETE_REQUEST`	After the user confirms map reset
Create schedule	`SCHEDULE_CREATE_REQUEST`	After the user saves the schedule
Update schedule	`SCHEDULE_UPDATE_REQUEST`	After the user saves changes
Delete a specific time period	`SCHEDULE_DELETE_PERIOD_REQUEST`	After the user confirms deletion
Enable schedule	`SCHEDULE_ENABLE_REQUEST`	After the user enables the schedule
Disable schedule	`SCHEDULE_DISABLE_REQUEST`	After the user disables the schedule
Set base station	`CONFIGURATION_SET_BASE_REQUEST`	After the user saves the setting
Set password	`CONFIGURATION_SET_PASSWORD_REQUEST`	After the user saves the setting
Set lawn task settings	`TASK_SETTINGS_SET_REQUEST`	After the user saves the task settings
Set custom shape	`CUSTOM_SHAPE_SET_REQUEST`	After the user saves the shape on the map page

Process:

User operation → app panel → cloud → SDK parsing → FUNC_SET_CB callback → application processing → Call the response API to report results

Panel refresh query (QUERY command)

Trigger scenario: Triggered when the user opens the app panel or performs a pull-to-refresh.

Query command	Trigger timing	Expected response
`VECTOR_GET_MAP_INFO_REQUEST`	Enter the map details page	Return the specified map details, including all custom shapes in `RLM_MAP_INFO_R.custom_shapes`
`VECTOR_GET_MAP_LIST_REQUEST`	Enter the map page	Return the map list summary
`VECTOR_GET_RECORD_INFO_REQUEST`	Enter the mowing record details page	Return the specified record details
`MOW_RECORD_INFO_LIST_REQUEST`	Enter the mowing record list page or pull-to-refresh.	Return the mowing record list
`ERROR_RECORD_INFO_LIST_REQUEST`	Enter the error record list page or pull-to-refresh.	Return the error record list
`SCHEDULE_QUERY_REQUEST`	Open the scheduled task page	Return the full schedule list
`CONFIGURATION_GET_REQUEST`	Enter the device configuration page	Return all current configurations
`TASK_SETTINGS_GET_REQUEST`	Enter the lawn task setting page	Return current task settings
`PLANNED_PATH_GET_REQUEST`	Enter the path preview page	Return the planned path
`MOWING_PATH_GET_REQUEST`	Enter the path playback page	Return the mowing path

The custom shape list is reported by VECTOR_GET_MAP_INFO_REQUEST → ty_rlm_map_info_response() in RLM_MAP_INFO_R.custom_shapes.

Process:

Panel refresh → cloud → SDK parsing → FUNC_QUERY_CB callback → application queries data → Call the response API to report

Device-side APIs

Unless otherwise noted, these APIs return results after the corresponding SET command executes. The device does not need to call these APIs for data synchronization if no SET command is issued by the app panel.

API	Function	Notes
ty_rlm_immediate_mowing_task_response	Mowing task response
ty_rlm_immediate_charge_task_response	Return-to-charge task response
ty_rlm_immediate_pause_task_response	Pause task response
ty_rlm_subscribe_response	Lawn mower status subscription response
ty_rlm_localization_push	Push localization data	When the device data changes, proactively call the API to report the data.
ty_rlm_battery_push	Push battery data	When the device data changes, proactively call the API to report the data.
ty_rlm_task_push	Push task status	When the device data changes, proactively call the API to report the data.
ty_rlm_error_push	Push error message	When the device data changes, proactively call the API to report the data.
ty_rlm_planned_path_push	Push planned path data	When the device data changes, proactively call the API to report the data.
ty_rlm_edit_status_response	Vector map edit status response
ty_rlm_deleted_elements_response	Vector map delete element response
ty_rlm_sampled_point_response	Vector map sampled point response
ty_rlm_undo_info_response	Vector map undo response
ty_rlm_record_status_response	Vector map record command response
ty_rlm_planned_path_response	Planned path data response
ty_rlm_mowing_path_response	Mowing path data response
ty_rlm_schedule_list_timer_response	Scheduled list response
ty_rlm_schedule_status_timer_response	Scheduled status response
ty_rlm_configuration_response	All lawn mower configurations response
ty_rlm_base_station_config_response	Lawn mower base station ID response
ty_rlm_rainy_day_config_response (reserved)	Lawn mower rain mode switch response
ty_rlm_cutting_switch_config_response (reserved)	Lawn mower mowing switch response
ty_rlm_manual_speed_config_response (reserved)	Lawn mower manual speed response
ty_rlm_password_config_response	Lawn mower password response
ty_rlm_task_setting_response	Lawn mower task settings response
ty_rlm_map_info_response	Lawn mower map details report
ty_rlm_record_info_response	Lawn mower record report
ty_rlm_log_record_list_response	Lawn mower record list report
ty_rlm_error_log_record_list_response	Lawn mower error record list report
ty_rlm_map_delete_response	Lawn mower delete map response
ty_rlm_map_list_response	Lawn mower map list summary response
ty_rlm_custom_shape_response	Custom shape data response	Used only for the response after a custom shape setting command is executed.

How it works

Open APIs

Register a protocol handler callback

This API 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 run the business functions. The param variable in the callback is released after the callback returns. If the callback has asynchronous operations, copy the param data to a variable space allocated by your application.

Register callback functions

/**
 * @brief RLM complex feature command set.
 */
typedef enum {
    IMMEDIATE_MOWING_TASK_REQUEST = 0, // Mowing task.
    IMMEDIATE_CHARGE_TASK_REQUEST,     // Return-to-charge task.
    IMMEDIATE_PAUSE_TASK_REQUEST,      // Pause or resume task.
    DEV_REMOTE_CONTROL_TASK_REQUEST,   // Remote control task.
    DEV_SUBSCRIBE_REQUEST,             // Status type subscription.
    VECTOR_MAP_EDITING_REQUEST,        // Vector map: Edit.
    VECTOR_RECORD_ELEMENT_REQUEST,     // Vector map: Record elements.
    VECTOR_DELETE_ELEMENT_REQUEST,     // Vector map: Delete vector elements.
    VECTOR_UNDO_POINT_REQUEST,         // Vector map: Undo recorded points.
    VECTOR_SAMPLING_REQUEST,           // Vector map: Enter auto-sampling mode.

    VECTOR_GET_MAP_INFO_REQUEST,       // Get map details.
    VECTOR_GET_RECORD_INFO_REQUEST,    // Get mowing record details.
    VECTOR_GET_MAP_LIST_REQUEST,       // Get map list.
    VECTOR_MAP_DELETE_REQUEST,         // Delete map.

    MOW_RECORD_INFO_LIST_REQUEST,      // Get mowing record list.
    ERROR_RECORD_INFO_LIST_REQUEST,    // Get error record list.

    SCHEDULE_QUERY_REQUEST,                   // Calendar schedule: Get full schedule list.
    SCHEDULE_CREATE_REQUEST,                  // Create schedule.
    SCHEDULE_UPDATE_REQUEST,                  // Update schedule.
    SCHEDULE_DELETE_PERIOD_REQUEST,           // Delete a specific time period.
    SCHEDULE_ENABLE_REQUEST,                  // Enable schedule.
    SCHEDULE_DISABLE_REQUEST,                 // Disable schedule.

    CONFIGURATION_GET_REQUEST,                // Device gets configuration.
    CONFIGURATION_SET_RAINY_DAY_MODE_REQUEST, // Set rain mode (reserved).
    CONFIGURATION_SET_CUT_SWITCH_REQUEST,     // Set mowing switch (reserved).
    CONFIGURATION_SET_SPEED_REQUEST,          // Set manual speed (reserved).
    CONFIGURATION_SET_BASE_REQUEST,           // Set base station.
    CONFIGURATION_SET_PASSWORD_REQUEST,       // Set password.
    TASK_SETTINGS_GET_REQUEST,                // Get lawn task settings.
    TASK_SETTINGS_SET_REQUEST,                // Set lawn task settings.
    PLANNED_PATH_GET_REQUEST,                 // Get planned path.
    MOWING_PATH_GET_REQUEST,                  // Get mowing path.
    CUSTOM_SHAPE_SET_REQUEST,                 // Set custom shape.
    COMPLEX_RLM_CMD_MAX,
} COMPLEX_RLM_CMD_E;

/**
 * @brief rlm complex function setting callback function pointer.
 * @param [COMPLEX_RLM_CMD_E] cmd, 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 COMPLEX_RLM_CMD_E cmd, IN void* param);
/**
 * @brief rlm complex function query callback function pointer.
 * @param [COMPLEX_RLM_CMD_E] cmd, 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.
 */
typedef OPERATE_RET (*FUNC_QUERY_CB)(IN COMPLEX_RLM_CMD_E cmd, IN void* param);
/**
 * @brief Register complex 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_rlm_complex_func_register(IN FUNC_SET_CB sets_handler, IN FUNC_QUERY_CB query_handler);

Parameters

Parameter	Description
sets_handler	SET command handler callback, implemented by the application. The application registers this callback with the SDK. Cast `param` to the struct that matches the command type before use.
query_handler	QUERY command handler callback, implemented by the application. The SDK does not use `param` for QUERY commands, so the application can ignore it.
OPERATE_RET	The return value. `OPRT_OK` means successful execution, and other values mean failed execution. For the meaning of error codes, see definitions in the `TuyaOS SDK` header file.

Data reporting APIs

API list for data reporting:

/**
 * @brief Mowing task response API.
 * @param[in] task_res Mowing task result response.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_immediate_mowing_task_response(IN RLM_IMMEDIATE_MOWING_TASK_R* task_res);

/**
 * @brief Return-to-charge task response API.
 * @param[in] task_res Return-to-charge task result response.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_immediate_charge_task_response(IN RLM_IMMEDIATE_CHARGE_TASK_R* task_res);

/**
 * @brief Pause or resume task response API.
 * @param[in] task_res Pause or resume task result response.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_immediate_pause_task_response(IN RLM_IMMEDIATE_PAUSE_TASK_R* task_res);

/**
 * @brief Status subscription response API.
 * @param[in] subscribe_res Status subscription result response.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_subscribe_response(IN RLM_SUBSCRIBE_STATUS_R* subscribe_res);

/**
 * @brief Push localization data API.
 * @param[in] localization Localization data.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_localization_push(IN RLM_LOCALIZATION_R* localization);

/**
 * @brief Push battery data API.
 * @param[in] battery Battery data.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_battery_push(IN RLM_BATTERY_DATA_R* battery);

/**
 * @brief Push task data API.
 * @param[in] task Task data.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_task_push(IN RLM_TASK_DATA_R* task);

/**
 * @brief Push error message API.
 * @param[in] error Error message.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_error_push(IN RLM_ERROR_DATA_R* error);

/**
 * @brief Push planned path data API.
 * @param[in] planned_path Planned path data.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_planned_path_push(IN RLM_PLANNED_PATH_DATA_R* planned_path);

/**
 * @brief Vector map edit status response API.
 * @param[in] edit_status Vector map edit status.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_edit_status_response(IN RLM_EDIT_STATUS_R* edit_status);

/**
 * @brief Vector map delete elements response API.
 * @param[in] deleted_elements Vector map delete element result.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_deleted_elements_response(IN DELETE_ELEMENT_R* deleted_elements);

/**
 * @brief Vector map sampled point response API.
 * @param[in] sampled_point Vector map sampled point information.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_sampled_point_response(IN SAMPLED_POINT_R* sampled_point);

/**
 * @brief Vector map undo response API.
 * @param[in] undo_info Undo information.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_undo_info_response(IN RLM_REMAINING_POINTS_R* undo_info);

/**
 * @brief Vector map record command response API.
 * @param[in] recording_status Status feedback.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_record_status_response(IN RLM_RECORDING_CONFIG_R *recording_status);

/**
 * @brief Push planned path data response API.
 * @param[in] planned_path Planned path data.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_planned_path_response(IN RLM_PLANNED_PATH_R* planned_path);

/**
 * @brief Mowing path data response API.
 * @param[in] mowing_path Mowing path data.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_mowing_path_response(IN RLM_MOWING_PATHS_R* mowing_path);

/**
 * @brief Schedule list response API.
 * @param[in] list_timer Schedule list.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_schedule_list_timer_response(IN RLM_SCHEDULE_LIST_TIMER_R* list_timer);

/**
 * @brief Schedule status response API.
 * @param[in] status_timer Scheduled response.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_schedule_status_timer_response(IN RLM_SCHEDULE_STATUS_PARAM_R* status_timer);

/**
 * @brief Full configuration response API.
 * @param[in] config Configuration.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_configuration_response(IN RLM_CONFIGURATION_R* config);

/**
 * @brief Base station ID response API.
 * @param[in] config Configuration.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_base_station_config_response(IN RLM_BASE_STATION_CONFIG_R* config);

/**
 * @brief Rain mode response API.
 * @param[in] config Configuration.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_rainy_day_config_response(IN RLM_RAINY_DAY_CONFIG_R* config);

/**
 * @brief Mowing switch response API.
 * @param[in] config Configuration.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_cutting_switch_config_response(IN RLM_CUTTING_SWITCH_CONFIG_R* config);

/**
 * @brief Manual speed response API.
 * @param[in] config Configuration.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_manual_speed_config_response(IN RLM_MANUAL_SPEED_CONFIG_R* config);

/**
 * @brief Password response API.
 * @param[in] config Configuration.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_password_config_response(IN RLM_PASSWORD_CONFIG_R* config);

/**
 * @brief Task settings response API.
 * @param[in] task_setting Task settings.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_task_setting_response(IN RLM_TASK_SETTING_R* task_setting);

/**
 * @brief Map details report API.
 * @param[in] info_info Map details.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_map_info_response(IN RLM_MAP_INFO_R* info_info);

/**
 * @brief Mowing record report API.
 * @param[in] record_info Mowing record.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_record_info_response(IN RLM_RECORD_INFO_R* record_info);

/**
 * @brief Mowing record list report API.
 * @param[in] record_list Mowing record list.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_log_record_list_response(IN RLM_MOW_RECORD_LIST_R* record_list);

/**
 * @brief Error log record list report API.
 * @param[in] error_log_record_list Error log record list.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_error_log_record_list_response(IN RLM_ERROR_LOG_RECORD_LIST_R* error_log_record_list);

/**
 * @brief Delete map details response API.
 * @param[in] map_delete Delete map details.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_map_delete_response(IN RLM_MAP_DELETE_R* map_delete);

/**
 * @brief Map list summary response API.
 * @param[in] map_list Map summary.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_map_list_response(IN RLM_MAP_LIST_INFO_R* map_list);
/**
 * @brief Custom shape data response API.
 * @param[in] shape_res Custom shape data.
 * @return OPERATE_RET 0 indicates success. Other error codes indicate failure.
 */
OPERATE_RET ty_rlm_custom_shape_response(IN RLM_CUSTOM_SHAPE_R* shape_res);

Data structures

Enumeration types

Task enumerations

/* Task status enum. */
typedef enum {
    // Standard status (0–99)
    TASK_STATUS_UNKNOWN = 0,    // Unknown.
    TASK_STATUS_STANDBY,        // Standby.
    TASK_STATUS_CHARGING,       // Charging.
    TASK_STATUS_MOWING,         // Mowing.
    TASK_STATUS_PAUSED,         // Paused.
    TASK_STATUS_RETURNING,      // Returning to charge.
    TASK_STATUS_UPDATING,       // Updating.
    TASK_STATUS_SELF_CHECKING,  // Self-checking.
    TASK_STATUS_MAPPING,        // Mapping.
    // Custom status range, from 100 to 255.
    //
    // Enums are inherently integers and accept values that are not declared in the enum.
    // Therefore, the device can use any integer from 100 to 255 as a custom status.
    // These values can still be parsed normally even if not defined in the enum.
    //
    // Rules:
    // - Reserve values from 100 to 255 for custom device-side use.
    // - Define the meaning of these statuses as needed on the device side.
    // - Record the meaning of each custom status value in the device documentation.
    //
    // Example. Record this only in device documentation. Do not modify this file.
    //   101 = Device initialization.
    //   102 = Waiting for user confirmation.
    //   103 = Sensor calibration.
    //   104 = Connecting to the network.
    //   ...
    TASK_STATUS_CUSTOM_START = 100, // Start marker for custom status values. Reserved range, from 100 to 255.
    TASK_STATUS_CUSTOM_END = 255,   // End marker for custom status values.
} TASK_STATUS_E;

// Mowing mode.
typedef enum {
    MODE_GLOBAL_MOWING = 0, // Global mowing.
    MODE_AREA_MOWING,       // Area mowing.
    MODE_EDGE_MOWING,       // Edge mowing.
    MODE_REMOTE_MOWING,     // Remote control mowing.
    MODE_ALIGN_EDGE_MOWING, // Edge alignment mowing (aligned with protocol TaskControlRequest. MowingMode value 4).
    MODE_CUSTOM_SHAPE_MOWING, // Custom shape mowing (aligned with protocol value 5).
} OPERATION_MOW_MODE_E;

/**
 * @brief End reason of a mowing record.
 */
typedef enum {
    MOWING_RESULT_OK = 0,           // Ended normally.
    MOWING_RESULT_MANUAL_STOP,      // Stopped manually.
    MOWING_RESULT_LOW_BATTERY,      // Low battery.
    MOWING_RESULT_RAIN_DETECTED,    // Rain detected.
    MOWING_RESULT_OBSTACLE_BLOCKED, // Blocked by an obstacle.
    MOWING_RESULT_SYSTEM_ERROR,     // System error.
    MOWING_RESULT_SCHEDULED_RETURN, // Scheduled return to charge.
    MOWING_RESULT_MAX
} MOWING_RESULT_E;

Map enumerations

// Map edit status.
typedef enum {
    START_EDITING = 0, // Start editing.
    EXIT_EDITING,      // Exit editing.
    CANCEL_EDITING,    // Cancel editing.
} MAP_EDIT_STATUS_E;

/* Map element type. */
typedef enum {
    ELEMENT_UNKNOWN = 0,
    ELEMENT_BOUNDARY,      // Work area boundary.
    ELEMENT_OBSTACLE,      // Obstacle.
    ELEMENT_CHARGING_PATH, // Return-to-charge path.
    ELEMENT_TRANSFER_PATH, // Transfer path.
} ELEMENT_TYPE_E;

/* Map element status. */
typedef enum {
    ELEMENT_STATUS_UNKNOWN = 0, // Unknown.
    ELEMENT_STATUS_STABLE,      // Stable.
    ELEMENT_STATUS_MAPPING,     // Mapping.
} ELEMENT_STATUS_E;

// Recording work status.
typedef enum {
    START_RECORDING_STATUS = 0, // Start recording.
    STOP_RECORDING_STATUS,      // Stop recording.
} MAP_RECORDING_WORK_STATUS_E;

// Recording mode.
typedef enum {
    MANUAL_SAMPLING = 0,    // Manual point recording mode.
    AUTO_SAMPLING,          // Auto-sampling mode.
    VISUAL_SAMPLING,        // Visual sampling mode.
} RECORD_MODE_E;

// Sampling mode.
typedef enum {
    START_AUTO_SAMPLING = 0, // Start auto-sampling.
    STOP_AUTO_SAMPLING,      // Stop auto-sampling.
    MANUAL_SAMPLE_POINT,     // Manually trigger sampling for one point.
} MAP_SAMPLE_MODE_E;

// Undo mode.
typedef enum {
    START_START_AUTO_UNDO = 0, // Start auto-undo.
    STOP_START_AUTO_UNDO,      // Stop auto-undo.
    LAST_POINT_UNDO,           // Undo last point.
} MAP_UNDO_MODE_E;

Path enumerations

/* Path type. */
typedef enum {
    PATH_TYPE_UNKNOWN = 0, // Unknown.
    PATH_TYPE_STRAIGHT,    // Straight.
    PATH_TYPE_CURVED,      // Curve.
    PATH_TYPE_SPIRAL,      // Spiral.
} PATH_TYPE_E;

// Path pattern.
typedef enum {
    PATH_PATTERN_UNKNOWN = 0, // Unknown pattern.
    PATH_PATTERN_PARALLEL,    // Parallel pattern.
    PATH_PATTERN_SPIRAL,      // Spiral pattern.
    PATH_PATTERN_RANDOM       // Random pattern.
} PATH_PATTERN_E;

Configuration enumerations

/* Device configuration request work mode. */
typedef enum {
    CONFIG_UNKNOWN = 0, // Unknown type. Pass this value for GET, and the device returns all configurations.
    BASE_STATION,       // Base station setting.
    RAINY_DAY_MODE,     // Rain mode setting.
    MANUAL_SPEED,       // Manual speed setting.
    CUTTING_SWITCH,     // Mowing switch setting.
    PASSWORD,           // Password setting.
} ROBOT_CONFIG_MODE_E;

// Manual speed.
typedef enum {
    SPEED_SLOW = 0,   // Slow.
    SPEED_NORMAL,     // Normal.
    SPEED_QUICK,      // Fast.
} MANUAL_SPEED_E;

// Work mode.
typedef enum {
    MODE_UNKNOWN = 0,   // Unknown mode.
    MODE_ECONOMY,       // Economy mode.
    MODE_STANDARD,      // Standard mode.
    MODE_INTENSIVE,     // Intensive mode.
} TASK_SET_MODE_E;

Schedule enumerations

// Day of week enum.
typedef enum {
    MONDAY = 0,    // Monday.
    TUESDAY,       // Tuesday.
    WEDNESDAY,     // Wednesday.
    THURSDAY,      // Thursday.
    FRIDAY,        // Friday.
    SATURDAY,      // Saturday.
    SUNDAY,        // Sunday.
    ST_MAX_DAY,    // Maximum number of days.
} DAYOFWEEK_E;

/* Calendar operation type. */
typedef enum {
    TIMER_QUERY = 0, // Query calendar.
    TIMER_CREATE,    // Create scheduled record.
    TIMER_UPDATE,    // Update scheduled record.
    TIMER_DELETE,    // Delete event.
    TIMER_ENABLE,    // Enable time period.
    TIMER_DISABLE,   // Disable time period.
} CALENDAR_OPERATION_E;

/* Schedule WorkPeriod mowing mode. */
typedef enum {
    RLM_SCHEDULE_MOW_MODE_STANDARD = 0,      // Standard mode.
    RLM_SCHEDULE_MOW_MODE_EDGE = 1,          // Edge mode.
    RLM_SCHEDULE_MOW_MODE_ALIGN_EDGE = 2,    // Edge alignment.
    RLM_SCHEDULE_MOW_MODE_CUSTOM_SHAPE = 3,  // Custom shape.
} RLM_SCHEDULE_MOWING_MODE_E;

// Direction switch period.
typedef enum {
    PERIOD_WEEKLY,   // Switch by week.
    PERIOD_DAILY,    // Switch by day.
    PERIOD_MONTHLY   // Switch by month.
} DIRECTION_SWITCH_PERIOD_E;

Subscription enumerations

// Subscription status type.
typedef enum {
    SUBSCRIBE_UNKNOWN = 0,  // Unknown.
    SUBSCRIBE_LOCALIZATION, // Localization status.
    SUBSCRIBE_BATTERY,      // Battery status.
    SUBSCRIBE_TASK,         // Task status.
    SUBSCRIBE_PLANNED_PATH, // Planned path status.
    SUBSCRIBE_ERROR,        // Error status.
    SUBSCRIBE_MAX,
} ROBOT_SUBSCRIBE_STATUS_E;

Severity level enumerations

// Severity level.
typedef enum {
    LEVEL_UNKNOWN = 0,  // Unknown.
    LEVEL_INFO,         // Information.
    LEVEL_WARNING,      // Warning.
    LEVEL_ERROR,        // Error.
    LEVEL_CRITICAL,     // Critical.
} SEVERITY_LEVEL_E;

Fault type enumerations

// Fault type (fixed codes defined on the device side).
typedef enum  {
    FAULT_NONE = 0,                                  // No fault.
    FAULT_LEFT_MOTOR_STALL = 1,                      // Left motor stall.
    FAULT_RIGHT_MOTOR_STALL = 2,                     // Right motor stall.
    FAULT_CUTTER_MOTOR_STALL = 3,                    // Cutter motor stall.
    FAULT_LEFT_MOTOR_HALL_FAULT = 4,                 // Left motor Hall fault.
    FAULT_RIGHT_MOTOR_HALL_FAULT = 5,                // Right motor Hall fault.
    FAULT_MOTOR_HALL_ERROR = 6,                      // Cutter motor Hall fault.
    FAULT_MOTOR_COMM_FAILURE = 7,                    // Motor driver communication fault.
    FAULT_BATTERY_DISCHARGE_FAILURE = 8,             // Battery discharge communication fault.
    FAULT_BATTERY_LOW_POWER = 9,                     // Low battery voltage.
    FAULT_BATTERY_DISCHARGE_OVER_CURRENT = 10,       // Battery discharge overcurrent.
    FAULT_BATTERY_DAMAGED = 11,                      // Battery abnormal.
    FAULT_BATTERY_NEED_RESET = 12,                   // Battery abnormal, needs reset.
    FAULT_IMU_FAILURE = 13,                          // IMU failure.
    FAULT_TILTING = 14,                              // Tilted.
    FAULT_OUTSIDE = 15,                              // Out of bounds.
    FAULT_LIFT = 16,                                 // Lifted.
    FAULT_TRAPPED = 17,                              // Trapped.
    FAULT_OVERTURNED = 18,                           // Overturned.
    FAULT_AI_INVALID = 19,                           // AI error.
    FAULT_CROSS_FAILED = 20,                         // Cross-area operation failed.
    FAULT_MAPPING_FAILED = 21,                       // Mapping failed.
    FAULT_SOC_DISCONNECT = 22,                       // SOC communication error.
    FAULT_RETURN_CHARGE_POLE_CONNECT = 23,           // Charge-pole connection failed.
} ROBOT_FAULT_TYPE_E;

To carry a variable-length string, set both the length and the content pointer.

Basic data types

String type

/* String element. */
typedef struct {
    int len;    // String length.
    char* name; // String memory pointer.
} RLM_STR_ELEMENT_S;

All response APIs include this unified error handling struct to return operation results.

Error status struct

/* Error parameter response. */
typedef struct {
    // Developer-defined error code categories:
    // 0-999: Success and common errors.
    // 1000–1999: Parameter validation errors.
    // 2000–2999: Business logic errors.
    // 3000–3999: Device status errors.
    // 4000–4999: Network communication errors.
    // 5000–5999: Internal system errors.
    int code;                   // Error code. Use ROBOT_FAULT_TYPE_E by default. Coordinate extensions with the panel.
    SEVERITY_LEVEL_E level;     // Error level.
    RLM_STR_ELEMENT_S message;  // Error reason.
    RLM_STR_ELEMENT_S solutions;// Solution.
    bool success;               // Success flag.
} DEV_ERROR_STATUS;

Coordinate types

// Two-dimensional coordinate.
typedef struct {
    float x; // X-axis coordinate.
    float y; // Y-axis coordinate.
} RLM_POINT2D_S;

// Three-dimensional coordinate.
typedef struct {
    float x; // X-axis coordinate.
    float y; // Y-axis coordinate.
    float z; // Z-axis coordinate.
} RLM_POINT3D_S;

// Quaternion definition.
typedef struct {
    float x; // X-axis coordinate.
    float y; // Y-axis coordinate.
    float z; // Z-axis coordinate.
    float w; // Angle component.
} RLM_POINT4D_S;

// Geodetic coordinates.
typedef struct {
    float latitude;  // Latitude in radians.
    float longitude; // Longitude in radians.
    float height;    // Height in meters.
} RLM_GEODETICPOINT_S;

Use different coordinate types for different scenarios. Use two-dimensional coordinates for planar paths, three-dimensional coordinates for map elements, and geodetic coordinates for GPS positioning.

Task control structs

Mowing task struct

// Mowing task setting.
typedef struct {
    bool ctrl_switch_go;           // Start or stop control. TRUE = start. FALSE = stop.
    OPERATION_MOW_MODE_E mow_mode; // Mowing mode.
    int area_num;                  // Number of areas.
    int *area_id;                  // Pointer to the area ID array.
} RLM_IMMEDIATE_MOWING_TASK_S;

// Mowing task response.
typedef struct {
    bool ctrl_switch_go;           // Start or stop control.
    OPERATION_MOW_MODE_E mow_mode; // Mowing mode.
    int area_num;                  // Number of areas.
    int *area_id;                  // Pointer to the area ID array.
    DEV_ERROR_STATUS code_error;   // Error message.
} RLM_IMMEDIATE_MOWING_TASK_R;

Usage notes:

ctrl_switch_go: TRUE means start mowing. FALSE means stop mowing.
mow_mode supports the following modes:
- Global mowing: MODE_GLOBAL_MOWING
- Area mowing: MODE_AREA_MOWING
- Edge mowing: MODE_EDGE_MOWING
- Remote control mowing: MODE_REMOTE_MOWING
- Edge alignment mowing: MODE_ALIGN_EDGE_MOWING
- Custom shape mowing: MODE_CUSTOM_SHAPE_MOWING
area_num: Number of areas.
area_id: Area ID list. Global mowing (MODE_GLOBAL_MOWING) does not carry this field. All other modes do.

Return-to-charge task struct

// Return-to-charge task setting.
typedef struct {
    bool ctrl_switch_charge; // Start or stop return-to-charge. TRUE = start. FALSE = stop.
} RLM_IMMEDIATE_CHARGE_TASK_S;

// Return-to-charge task response.
typedef struct {
    bool ctrl_switch_charge;       // Start or stop return-to-charge.
    DEV_ERROR_STATUS code_error;   // Error message.
} RLM_IMMEDIATE_CHARGE_TASK_R;

Pause task struct

// Pause task setting.
typedef struct {
    bool ctrl_pause; // Pause or resume. TRUE = pause. FALSE = resume.
} RLM_IMMEDIATE_PAUSE_TASK_S;

// Pause task response.
typedef struct {
    bool ctrl_pause;               // Pause or resume.
    DEV_ERROR_STATUS code_error;   // Error message.
} RLM_IMMEDIATE_PAUSE_TASK_R;

Remote control task struct

/* Immediate remote control task struct for the lawn mower. */
typedef struct {
    float linear_x;  // Linear velocity scale factor. Range: [-1, 1]. Actual linear velocity = value x configured remote control driving speed.
    float angular_z; // Angular velocity. Range: [-1, 1]. Unit: rad/s.
} RLM_REMOTE_CTRL_TASK_S;

Usage notes:

linear_x > 0: Move forward. linear_x < 0: Move backward.
angular_z > 0: Turn left. angular_z < 0: Turn right.

Status push structs

Subscription status struct

// Subscription request.
typedef struct {
    int num;             // Number of subscription types.
    int* Subscribe_type; // Subscription type array from ROBOT_SUBSCRIBE_STATUS_E.
    int timeout_sec;     // Subscription timeout, in seconds.
} RLM_SUBSCRIBE_STATUS_S;

// Subscription response.
typedef struct {
    bool status;                 // Response status. TRUE = subscription succeeded. FALSE = subscription failed.
    DEV_ERROR_STATUS code_error; // Error message.
} RLM_SUBSCRIBE_STATUS_R;

Usage notes: After the device receives a subscription request, push the corresponding status data within timeout_sec.

Localization data push struct

/* Latest device pose. */
typedef struct {
    RLM_POINT3D_S pose;        // Robot position.
    RLM_POINT4D_S orientation; // Quaternion orientation.
} RLM_POSE_S;

/* Latest charging station pose. */
typedef struct {
    RLM_POINT3D_S pose;        // Charging station position.
    RLM_POINT4D_S orientation; // Quaternion orientation.
} RLM_CHARGE_POSE_S;

/* Localization status push struct. */
typedef struct {
    RLM_GEODETICPOINT_S position;     // Robot geodetic position (GPS coordinates).
    RLM_POSE_S robot_pose;            // Latest robot position (Local coordinates).
    RLM_CHARGE_POSE_S charge_station; // Charging station position.
    bool ready;                       // Whether localization is ready.
    bool satellite_signal_detecting;  // Whether satellite signal detection is in progress.
} RLM_LOCALIZATION_R;

Usage notes: Control the reporting frequency for localization data. Do not report unchanged data. If data changes, report it no more than once every two seconds.

Battery data push struct

/* Battery status data. */
typedef struct {
    float voltage;      // Voltage in volts (V).
    float current;      // Current in amperes (A).
    int battery_level;  // Remaining battery percentage, from 0 to 100.
    bool is_charging;   // Charging status.
} RLM_BATTERY_DATA_R;

Usage notes: Trigger an active push of battery data whenever the battery data changes.

Task status push struct

/* Task status push. */
typedef struct {
    // Basic task data.
    TASK_STATUS_E state;   // Task status.
    int task_id;           // Unique task ID.
    // Current active area list.
    int n_active_areas;
    int *active_areas;
    int n_worked_boundary_uuid; // Number of IDs of completed work areas.
    int *worked_boundary_uuid;  // ID array of completed work areas.
    // Mowing order.
    int n_work_sequence;
    int *work_sequence;
    OPERATION_MOW_MODE_E mow_mode;    // Mowing mode.
    bool cutting_switch;        // Mowing switch state.
    int progress;   // Mowing progress.
    int maparea;    // Mowing area.
    int total_distance; // Total distance in km.
    int total_time; // Total duration in h.
} RLM_TASK_DATA_R;

Error message push struct

/* Error status push. */
typedef struct {
    int num;                    // Number of errors.
    DEV_ERROR_STATUS* code_error; // Error message array.
} RLM_ERROR_DATA_R;

Planned path push struct

/* Planned path status push. */
typedef struct {
    int n_path_points;              // Number of path points.
    RLM_POINT2D_S *path_points;     // Path point coordinate array.
    int current_point_index;        // Current point index.
} RLM_PLANNED_PATH_DATA_R;

Map management structs

Map edit status struct

/* Edit session parameter struct. */
typedef struct {
    int map_id;                      // Map ID to edit.
    MAP_EDIT_STATUS_E edit_status;   // Edit status.
} RLM_EDIT_SESSION_S;

/* Vector map edit status response struct. */
typedef struct {
    MAP_EDIT_STATUS_E edit_status;      // Edit status.
    bool ready_to_sample;               // Whether ready for sampling.
    bool auto_sampling_active;          // Whether auto-sampling is active.
    bool is_auto_sampling_complete;     // Whether auto-sampling is complete.
    int point_count;                    // Number of points currently recorded.
    ELEMENT_TYPE_E current_element_type;// Current recorded element type.
    bool is_editing;                    // Whether editing is in progress.
    bool is_auto_undo_active;           // Whether automatic undo is active.
    DEV_ERROR_STATUS code_error;        // Error message.
} RLM_EDIT_STATUS_R;

Recording configuration struct

/* Recording configuration parameter struct. */
typedef struct {
    MAP_RECORDING_WORK_STATUS_E status; // Work status: start or stop.
    RECORD_MODE_E mode;                 // Recording mode: manual, automatic, or visual.
    ELEMENT_TYPE_E element_type;        // Map element type.
} RLM_RECORDING_CONFIG_S;

/* Recording configuration parameter response struct. */
typedef struct {
    MAP_RECORDING_WORK_STATUS_E status; // Work status.
    RECORD_MODE_E mode;                 // Recording mode.
    ELEMENT_TYPE_E element_type;        // Map element type.
    DEV_ERROR_STATUS code_error;        // Error message.
} RLM_RECORDING_CONFIG_R;

Sampling structs

/* Automatic sampling configuration parameter struct. */
typedef struct {
    MAP_SAMPLE_MODE_E mode; // Sampling mode.
} RLM_SAMPLING_CONFIG_S;

/* Vector map sampled point response struct. */
typedef struct {
    MAP_SAMPLE_MODE_E mode;      // Sampling mode.
    RLM_POINT3D_S point;         // Sampled point coordinate.
    DEV_ERROR_STATUS code_error; // Error message.
} SAMPLED_POINT_R;

Undo operation struct

/* Map operation: undo recorded point struct. */
typedef struct {
    MAP_UNDO_MODE_E undo_mode; // Undo mode.
} MAP_UNDO_POINT_S;

/* Undo response struct. */
typedef struct {
    MAP_UNDO_MODE_E undo_mode;   // Undo mode.
    int remaining_points;        // Number of remaining points after undo.
    DEV_ERROR_STATUS code_error; // Error message.
} RLM_REMAINING_POINTS_R;

Delete element struct

/* Delete element parameter struct. */
typedef struct {
    int n_element_ids;     // Number of elements.
    int *element_ids;      // Element ID list to delete.
    ELEMENT_TYPE_E element_type; // Element type.
} DELETE_ELEMENT_S;

/* Delete element parameter response struct. */
typedef struct {
    int n_area_ids;              // Number of elements.
    int *area_ids;               // Area or element ID list after deletion.
    DEV_ERROR_STATUS code_error; // Error message.
} DELETE_ELEMENT_R;

Map element struct

/* Map element property struct. */
typedef struct {
    RLM_STR_ELEMENT_S key;   // Property key.
    RLM_STR_ELEMENT_S value; // Property value.
} PROPERTIES_ENTRY;

/* Map element struct. */
typedef struct {
    int element_id;               // Element ID.
    ELEMENT_TYPE_E element_type;  // Map element type.
    int n_points;                 // Number of points.
    RLM_POINT3D_S *points;        // Sampled point coordinate collection.
    int n_properties;             // Number of properties.
    PROPERTIES_ENTRY *properties; // Property collection.
    ELEMENT_STATUS_E status;      // Map element status.
} MAP_ELEMENT_S;

Map details struct

/* Map details response struct. */
typedef struct {
    int map_id;                     // Map ID.
    RLM_STR_ELEMENT_S map_name;     // Map name.
    int element_num;                // Number of map elements.
    MAP_ELEMENT_S* elements;        // Map element array.
    DEV_ERROR_STATUS code_error;    // Error message.
    int n_custom_shapes;            // Number of custom shapes.
    RLM_CUSTOM_SHAPE_S *custom_shapes; // Set to NULL when the value is 0. Corresponds to protocol field 4.
} RLM_MAP_INFO_R;

/* Map list response struct. */
typedef struct {
    int n_maps;
    MAP_SUMMARY *maps; // Available map list.
    DEV_ERROR_STATUS code_error; // Error message.
} RLM_MAP_LIST_INFO_R;

/* Delete map details struct. */
typedef struct {
    int map_id;              // Delete the corresponding map by map_id.
} RLM_MAP_DELETE_S;

/* Delete map details response struct. */
typedef struct {
    int map_id;              // Map ID.
    DEV_ERROR_STATUS code_error; // Error message.
} RLM_MAP_DELETE_R;

Path structs

Planned path struct

/* Planned path segmentation struct. */
typedef struct {
    PATH_TYPE_E path_type;    // Path type.
    int n_waypoints;          // Number of waypoints.
    RLM_POINT2D_S* waypoints; // Planned waypoint coordinates.
} MOWER_PLANNED_PATH;

/* Planned path segmentation struct. */
typedef struct {
    int n_paths;                // Number of path segments.
    MOWER_PLANNED_PATH* paths;  // Multi-segment planned path data.
    DEV_ERROR_STATUS code_error; // Error message.
} RLM_PLANNED_PATH_R;

Mowing path struct

/* Path point parameter struct. */
typedef struct {
    RLM_POINT3D_S position; // Position coordinate.
} PATH_POINT_S;

/* Path point collection struct. */
typedef struct {
    int n_points;          // Number of path points.
    PATH_POINT_S* points;  // Path point parameters.
} RLM_MOWING_PATH_S;

/* Area mowing path struct. */
typedef struct {
    int area_id;                   // Area ID.
    int n_paths;                   // Number of paths.
    RLM_MOWING_PATH_S* paths;      // Path parameters.
} RLM_AREA_MOWING_PATH_S;

/* Mowing path response struct. */
typedef struct {
    int n_area_paths;                  // Number of area paths.
    RLM_AREA_MOWING_PATH_S* area_paths;// Area path data.
    DEV_ERROR_STATUS code_error;       // Error message.
} RLM_MOWING_PATHS_R;

Calendar schedule structs

#define RLM_SCHEDULE_PLAN_NAME_MAX 72   /* Max bytes of the plan name buffer (UTF-8, aligned with the header file). */

Scheduled time period struct

/* Scheduled time period struct. */
typedef struct {
    int start_minute;     // Start time, from 0 to 1,440 minutes.
    int end_minute;       // End time, up to 1,440 minutes.
    bool enabled;         // Whether the period is enabled.
    int period_id;        // ID automatically generated by the device.
    bool edge_mowing;     // Whether edge mowing is enabled.
    int area_ids_count;   // Number of area IDs.
    int* area_ids;        // Area ID list.
    /* v1.1 optional fields ("empty" convention). */
    char name[RLM_SCHEDULE_PLAN_NAME_MAX]; // Plan name. name[0]=='\0' means not set.
    int plan_id;                           // Plan group ID. 0 means no group.
    RLM_SCHEDULE_MOWING_MODE_E mowing_mode; // Schedule mowing mode. Invalid online values are normalized to STANDARD by the SDK.
} SCHEDULE_TIMER_PERIOD;

/* Single-day schedule list struct. */
typedef struct {
    DAYOFWEEK_E week;                   // Day of week.
    int time_num;                       // Number of time periods.
    SCHEDULE_TIMER_PERIOD* time_period; // Scheduled time period array.
} SCHEDULE_ALONE_PARAM;

Scheduled operation struct

 // Create schedule.
typedef struct {
    DAYOFWEEK_E week;     // Day of week.
    int start_minute;     // Start time, from 0 to 1,440 minutes.
    int end_minute;       // End time, up to 1,440 minutes.
    bool enabled;         // Whether the period is enabled.
    bool edge_mowing;     // Whether edge mowing is enabled.
    int area_ids_count;   // Number of area IDs.
    int* area_ids;        // Area ID list.
    /* v1.1 optional. name[0]=='\0' means no name. plan_id==0 means no group. mowing_mode: see RLM_SCHEDULE_MOWING_MODE_E. */
    char name[RLM_SCHEDULE_PLAN_NAME_MAX];
    int plan_id;
    RLM_SCHEDULE_MOWING_MODE_E mowing_mode;
} RLM_SCHEDULE_CREATE_PARAM_S;

 // Update schedule.
typedef struct {
    DAYOFWEEK_E week;                  // Day of week.
    SCHEDULE_TIMER_PERIOD time_period; // Scheduled time period.
} RLM_SCHEDULE_UPDATE_PARAM_S;

 // Delete schedule.
typedef struct {
    int period_id;    // Period ID.
    DAYOFWEEK_E week; // Day of week.
} RLM_SCHEDULE_DELETE_PARAM_S;

// Scheduled switch.
typedef struct {
    int period_id;     // Period ID.
    DAYOFWEEK_E week;  // Day of week.
    bool switch_state; // Switch state.
} RLM_SCHEDULE_SWITCH_PARAM_S;

Scheduled response struct

// Scheduled list response.
typedef struct {
    int day_num;                 // Number of days. Usually seven.
    SCHEDULE_ALONE_PARAM* timer; // Scheduled parameters for all days.
    DEV_ERROR_STATUS code_error; // Error message.
} RLM_SCHEDULE_LIST_TIMER_R;

/* Scheduled status response struct. */
typedef struct {
    CALENDAR_OPERATION_E op; // Operation type.
    DAYOFWEEK_E week;        // Day of week.
    int period_id;           // ID automatically generated by the device.
    int start_minute;        // Start time, from 0 to 1,440 minutes.
    int end_minute;          // End time, up to 1,440 minutes.
    bool enabled;            // Whether the period is enabled.
    bool edge_mowing;     // Whether edge mowing is enabled.
    int area_ids_count;   // Number of area IDs.
    int* area_ids;        // Area ID list.
    char name[RLM_SCHEDULE_PLAN_NAME_MAX];
    int plan_id;
    RLM_SCHEDULE_MOWING_MODE_E mowing_mode;
    DEV_ERROR_STATUS code_error; // Error message.
} RLM_SCHEDULE_STATUS_PARAM_R;

Robot configuration structs

Base station ID configuration

// Base station ID setting.
typedef struct {
    RLM_STR_ELEMENT_S base_station_id; // Base station ID.
} RLM_BASE_STATION_CONFIG_S;

// Base station ID response.
typedef struct {
    RLM_STR_ELEMENT_S base_station_id; // Base station ID.
    DEV_ERROR_STATUS code_error;       // Error message.
} RLM_BASE_STATION_CONFIG_R;

Rain mode configuration

// Rain mode setting (reserved).
typedef struct {
    bool rainy_day_enabled; // Rain mode switch.
} RLM_RAINY_DAY_CONFIG_S;

// Rain mode response (reserved).
typedef struct {
    bool rainy_day_enabled;      // Rain mode switch.
    DEV_ERROR_STATUS code_error; // Error message.
} RLM_RAINY_DAY_CONFIG_R;

Mowing switch configuration

// Mowing switch setting (reserved).
typedef struct {
    bool cutting_switch; // Mowing switch settings.
} RLM_CUTTING_SWITCH_CONFIG_S;

// Mowing switch response (reserved).
typedef struct {
    bool cutting_switch;         // Mowing switch.
    DEV_ERROR_STATUS code_error; // Error message.
} RLM_CUTTING_SWITCH_CONFIG_R;

Manual speed configuration

// Manual speed setting (reserved).
typedef struct {
    MANUAL_SPEED_E speed; // Manual speed setting.
} RLM_MANUAL_SPEED_CONFIG_S;

// Manual speed response (reserved).
typedef struct {
    MANUAL_SPEED_E speed;        // Manual speed.
    DEV_ERROR_STATUS code_error; // Error message.
} RLM_MANUAL_SPEED_CONFIG_R;

Password configuration

// Password setting.
typedef struct {
    bool password_enabled;              // Password setting enabled.
    RLM_STR_ELEMENT_S password;         // Password.
    RLM_STR_ELEMENT_S password_hint;    // Password hint.
} RLM_PASSWORD_CONFIG_S;

// Password response.
typedef struct {
    bool is_password_set;               // Whether password is set.
    bool password_enabled;              // Password setting enabled.
    RLM_STR_ELEMENT_S password;         // Password.
    RLM_STR_ELEMENT_S password_hint;    // Password hint.
    DEV_ERROR_STATUS code_error;        // Error message.
} RLM_PASSWORD_CONFIG_R;

Full configuration response

/* Device configuration response struct. */
typedef struct {
    RLM_STR_ELEMENT_S base_station_id;  // Base station ID.
    bool rainy_day_enabled;             // Rain mode switch (reserved).
    bool cutting_switch;                // Mowing switch settings (reserved).
    MANUAL_SPEED_E speed;               // Manual speed setting (reserved).
    bool is_password_set;               // Whether password is set.
    bool password_enabled;              // Password setting enabled.
    RLM_STR_ELEMENT_S password;         // Password.
    RLM_STR_ELEMENT_S password_hint;    // Password hint.
    DEV_ERROR_STATUS code_error;        // Error message.
} RLM_CONFIGURATION_R;

Usage notes: Use this struct to query all configuration information at once.

Task settings structs

Task settings parameters

/*
 * Mowing direction switching configuration.
 */
typedef struct
{
    bool enabled;  // Whether direction switching is enabled.
    DIRECTION_SWITCH_PERIOD_E period;  // Switch period.
    int interval_value;   // Interval value, in weeks, days, or months.
}MOW_DIRECTIONSWITCH;

/* Task parameter struct. */
typedef struct {
    int area_num; // Number of areas.
    int *area_id; // Area ID.
    TASK_SET_MODE_E mode; // Work mode.
    PATH_PATTERN_E path_mode; // Path pattern.
    int cutting_height; // Work width in mm.
    bool edge_cutting;  // Whether edge mowing is enabled.
    int direction; // Work direction, from 0 to 360 degrees.
    int speed; // Speed, in m/s.
    int overlap_percentage; // Overlap percentage, from 0 to 100.
    MOW_DIRECTIONSWITCH direction_switch;  // Direction switching configuration.
} TASK_SETTING_PARAM;

/* Device configuration response struct. */
typedef struct {
    REQUEST_TYPE_E request_type; // Request type: set or get.
    int task_num;                // Number of tasks.
    TASK_SETTING_PARAM* param;   // Task settings parameter array.
    DEV_ERROR_STATUS code_error; // Error message.
} RLM_TASK_SETTING_R;

Mowing record structs

Mowing record details

/* Mowing record response struct. */
typedef struct {
    int record_id;              // Mowing record ID.
    RLM_MAP_INFO_R map_info;    // Map details.
    int n_paths; // Number of path segments.
    MOWER_PLANNED_PATH* paths; // Planned path point data.
    DEV_ERROR_STATUS code_error; // Error message.
} RLM_RECORD_INFO_R;

Mowing record list

/*
 * Mowing record summary.
 */
typedef struct
{
    int record_id;     // Record ID.
    int start_time;    // Start time.
    int end_time;      // End time.
    OPERATION_MOW_MODE_E mow_mode;    // Mowing mode.
    MOWING_RESULT_E stop_reason;   // End reason.
    int n_area_names;    // Number of area names.
    RLM_STR_ELEMENT_S *area_names;     // Area name list.
    int mow_area;    // Mowing area, in square meters.
}MOW_RECORD_SUMMARY;

/* Mowing record list struct. */
typedef struct {
    int n_mow_records;
    MOW_RECORD_SUMMARY *mow_records;  // Mowing record list.
    DEV_ERROR_STATUS code_error; // Error message.
} RLM_MOW_RECORD_LIST_R;

Error record list

/*
 * Error record summary.
 */
typedef struct
{
    int record_id;     // Record ID.
    int error_time;    // Error occurrence time.
    RLM_STR_ELEMENT_S error_reason;  // Error reason.
    bool is_resolved;    // Whether the error is resolved.
    int error_code; // Error code.
    RLM_STR_ELEMENT_S error_description; // Error description.
}ERROR_LOG_RECORD_SUMMARY;

/* Error record list struct. */
typedef struct {
    int n_error_log_records;
    ERROR_LOG_RECORD_SUMMARY *error_log_records;  // Error record list.
    DEV_ERROR_STATUS code_error; // Error message.
} RLM_ERROR_LOG_RECORD_LIST_R;

Custom shape structs

Custom shape type and basic structure

/* Custom shape type. */
typedef enum {
    CUSTOM_SHAPE_UNKNOWN = 0,
    CUSTOM_SHAPE_HEART,       // Heart.
    CUSTOM_SHAPE_CIRCLE,      // Circle.
    CUSTOM_SHAPE_TRIANGLE,    // Triangle.
    CUSTOM_SHAPE_STAR,        // Star.
    CUSTOM_SHAPE_RECTANGLE,   // Rectangle.
    CUSTOM_SHAPE_OTHER,       // Custom type. Align with the app.
} CUSTOM_SHAPE_TYPE_E;

/* Custom shape transform data. */
typedef struct {
    RLM_POINT2D_S center;  // Shape center point in the map coordinate system.
    int width;             // Width in mm.
    int height;            // Height in mm.
    int rotation;          // Rotation angle in 0.1 degrees. Range: from 0 to 3,599.
} RLM_SHAPE_TRANSFORM_S;

/* Custom shape struct. */
typedef struct {
    int shape_id;                    // Unique shape ID.
    CUSTOM_SHAPE_TYPE_E shape_type;  // Shape type.
    RLM_SHAPE_TRANSFORM_S transform; // Transform data: position, size, and rotation.
    int n_contour_points;            // Reserved for irregular shapes: number of contour points.
    RLM_POINT2D_S *contour_points;   // Reserved for irregular shapes: contour points calculated by the app.
    int map_id;                      // Map ID that the shape belongs to.
    int n_local_points;              // Internal app data. The device only passes through and stores this data.
    RLM_POINT2D_S *local_points;     // Internal app data. Normalized local points, from -5,000 to 5,000.
} RLM_CUSTOM_SHAPE_S;

Custom shape request and response structures

/* SET_SHAPES full-list replacement payload. */
typedef struct {
    int map_id;                 // Target map ID.
    int n_shapes;               // Number of shapes. 0 clears all custom shapes for this map.
    RLM_CUSTOM_SHAPE_S *shapes; // Full shape list.
} RLM_CUSTOM_SHAPE_SET_S;

/* Custom shape response struct (used for SET_SHAPES echo). */
typedef struct {
    int n_shapes;                  // Number of shapes.
    RLM_CUSTOM_SHAPE_S *shapes;    // Shape list.
    DEV_ERROR_STATUS code_error;   // Error message.
} RLM_CUSTOM_SHAPE_R;

Feature details

Task control

How it works

Feature description

Purpose: The app sends a task control command. The device runs the action and replies with the matching *_response() API.
Triggers and processing:
- IMMEDIATE_MOWING_TASK_REQUEST: Controls a mowing task. The mow_mode field distinguishes global, area, edge, remote control, and edge alignment mowing. The command supports start and stop.
- IMMEDIATE_CHARGE_TASK_REQUEST: Controls a return-to-charge task. The command supports start and stop.
- IMMEDIATE_PAUSE_TASK_REQUEST: Pauses or resumes a task.
- DEV_REMOTE_CONTROL_TASK_REQUEST: Controls a remote control task. This command usually triggers in mapping or editing scenarios.
Status reporting: During task execution, report the latest status through push APIs when task status, localization data, or other data changes.
Things to note: Report localization data when the position changes, and keep the interval no shorter than two seconds.
Response structs:
- ty_rlm_immediate_mowing_task_response() returns RLM_IMMEDIATE_MOWING_TASK_R:
  - code_error: Error message. success=true indicates success. If the operation fails, fill in code, level, message, and solutions.
  - ctrl_switch_go: Start or stop control. TRUE = start. FALSE = stop.
  - mow_mode: Mowing mode. See OPERATION_MOW_MODE_E.
  - area_num: Number of areas. This field does not apply to global mowing.
  - area_id: Pointer to the area ID list. The length is area_num. Global mowing does not support this field.
- ty_rlm_immediate_charge_task_response() returns RLM_IMMEDIATE_CHARGE_TASK_R:
  - code_error: Error message.
  - ctrl_switch_charge: Start or stop return-to-charge. TRUE = start. FALSE = stop.
- ty_rlm_immediate_pause_task_response() returns RLM_IMMEDIATE_PAUSE_TASK_R:
  - code_error: Error message.
  - ctrl_pause: Pause or resume. TRUE = pause. FALSE = resume.

Status subscription

How it works

Feature description

Purpose: The app uses DEV_SUBSCRIBE_REQUEST(types, timeout_sec) to declare the push types that it wants to receive.
Effective rule: The device can push only types for which ty_rlm_subscribe_response() returns success. Pushes for unsubscribed or failed types are discarded.
Timeout: The device side manages timeout_sec. After the timeout, the subscription becomes invalid, and the device stops pushing.
RLM_SUBSCRIBE_STATUS_R contains:
- code_error: Error message (Fill in the failure reason if subscription fails.)
- status: Subscription result. TRUE = success. FALSE = failure.

Status push

How it works

Feature description

Purpose: The device pushes task, localization, battery, error, and path updates in real time so the app can display them.
Precondition: The push type must stay within a valid subscription window. For more information, see Basic data types.
Push policy: Push data only when the data actually changes. Do not repeatedly report the same type with the same content.
Frequency recommendation: Do not report changes of the same type too frequently. Keep the interval no shorter than two seconds.
Push structs:
- ty_rlm_localization_push() reports RLM_LOCALIZATION_R:
  - position: Robot geodetic position (RLM_GEODETICPOINT_S), including:
    - latitude: Latitude in radians.
    - longitude: Longitude in radians.
    - height: Height in meters.
  - robot_pose: Robot local pose (RLM_POSE_S), including:
    - pose: Position (RLM_POINT3D_S: x/y/z).
    - orientation: Orientation (RLM_POINT4D_S: x/y/z/w).
  - charge_station: Charging station pose (RLM_CHARGE_POSE_S), including:
    - pose: Position (RLM_POINT3D_S: x/y/z).
    - orientation: Orientation (RLM_POINT4D_S: x/y/z/w).
  - ready: Whether the localization is ready.
  - satellite_signal_detecting: Whether satellite signal detection is in progress.
- ty_rlm_task_push() reports RLM_TASK_DATA_R:
  - state: Task status. See TASK_STATUS_E.
  - task_id: Unique task ID.
  - n_active_areas: Number of current active areas.
  - active_areas: Current active area ID array. The length is n_active_areas.
  - n_worked_boundary_uuid: Number of IDs of the completed work areas.
  - worked_boundary_uuid: ID array of completed work areas. The length is n_worked_boundary_uuid.
  - n_work_sequence: Number of work sequence orders.
  - work_sequence: Work sequence array. The length is n_work_sequence.
  - mow_mode: Mowing mode. See OPERATION_MOW_MODE_E.
  - cutting_switch: Mowing switch status.
  - progress: Mowing progress.
  - maparea: Mowing area.
  - total_distance: Total distance in km.
  - total_time: Total duration in hours.
- ty_rlm_error_push() reports RLM_ERROR_DATA_R:
  - num: Number of error codes.
  - code_error: Error message array (DEV_ERROR_STATUS). The length is num.
- ty_rlm_battery_push() reports RLM_BATTERY_DATA_R:
  - voltage: Voltage in V.
  - current: Current in A.
  - battery_level: Remaining battery percentage, from 0 to 100.
  - is_charging: Whether the device is charging.
- ty_rlm_planned_path_push() reports RLM_PLANNED_PATH_DATA_R:
  - n_path_points: Number of path points.
  - path_points: Path point coordinate array (RLM_POINT2D_S). The length is n_path_points.
  - current_point_index: Current point index.

Map management

Business flow

The SDK forwards application-side data to the app. For the names in the process, see the following feature description.

Status diagram

Feature description

Purpose: This section describes key status fields, message types, and typical processes for vector map editing, recording, sampling, undo, and deletion.
API mapping for device-side reporting:
- Edit status: ty_rlm_edit_status_response()
- Record command result: ty_rlm_record_status_response()
- Sampled point data: ty_rlm_sampled_point_response()
- Undo result: ty_rlm_undo_info_response()
- Delete element result: ty_rlm_deleted_elements_response()
Report structures carried by device-side API calls:
- ty_rlm_edit_status_response() reports RLM_EDIT_STATUS_R:
  - code_error: Error message.
  - edit_status: Edit status. See MAP_EDIT_STATUS_E.
  - ready_to_sample: Whether the device is ready to sample points.
  - auto_sampling_active: Whether automatic sampling is active.
  - is_auto_sampling_complete: Whether automatic sampling is complete and whether the closure condition is met.
  - point_count: Number of currently recorded points.
  - current_element_type: Current recorded element type. See ELEMENT_TYPE_E.
  - is_editing: Whether editing is in progress.
  - is_auto_undo_active: Whether automatic undo is active.
- ty_rlm_record_status_response() reports RLM_RECORDING_CONFIG_R:
  - code_error: Error message.
  - status: Work status, start or stop. See MAP_RECORDING_WORK_STATUS_E.
  - mode: Recording mode, manual, automatic, or visual. See RECORD_MODE_E.
  - element_type: Map element type. See ELEMENT_TYPE_E.
- ty_rlm_sampled_point_response() reports SAMPLED_POINT_R:
  - code_error: Error message.
  - mode: Sampling mode. See MAP_SAMPLE_MODE_E.
  - point: Sampled point coordinate (RLM_POINT3D_S: x/y/z).
- ty_rlm_undo_info_response() reports RLM_REMAINING_POINTS_R:
  - code_error: Error message.
  - undo_mode: Undo mode. See MAP_UNDO_MODE_E.
  - remaining_points: Number of remaining points after undo.
- ty_rlm_deleted_elements_response() reports DELETE_ELEMENT_R:
  - code_error: Error message.
  - n_area_ids: Number of area or element IDs after deletion.
  - area_ids: Pointer to the area or element ID list after deletion. The length is n_area_ids.

Key status fields

Status field	Initial value	Change trigger	Description
`is_active`	`false`	After `START_EDITING`	Whether the edit session is active
`ready_to_sample`	`false`	After the device is ready	Whether the device is ready to sample points
`auto_sampling_active`	`false`	After automatic sampling starts	Whether automatic sampling is active
`point_count`	`0`	After each point is recorded	Number of currently recorded points
`is_auto_sampling_complete`	`false`	After the closure condition is met	Whether the area can close automatically

Message types
- Requests from app to device:
  - START_EDITING: Enter edit mode.
  - RECORD_ELEMENT: Start recording elements and enable automatic sampling.
- Push messages from device to app:
  - EditStatus: Edit status update.
  - SampledPoint: Sampled point data (API: ty_rlm_sampled_point_response).
Process steps
- Start editing: The app sends START_EDITING, and the device enters edit mode.
- Record elements: The app sends RECORD_ELEMENT, and the device enters record mode.
- Prepare the device: The device pushes ready_to_sample = true, and the app can start remote control.
- Auto-record points: The device performs auto-sampling and pushes SampledPoint.
- Update status: The device pushes EditStatus to update point_count.
- Auto-close: After the condition is met, the device pushes is_auto_sampling_complete = true.
- Manual undo: The app sends UNDO_LAST_POINT, and the device returns remaining_points.
- Auto-undo: The app sends START_AUTO_UNDO. The device rolls back automatically and keeps pushing status.
- Update localization: The device pushes StatusPush to update localization coordinates.
- Record points again: The device samples again and pushes SampledPoint.
- Finish the area: The app sends STOP_AUTO_SAMPLING and FINISH_RECORD.
- Start the next area: The app sends RECORD_ELEMENT to start drawing a new area.
How to undo
- The app sends START_AUTO_UNDO to start auto-undo.
- The device rolls back automatically and pushes EditStatus to update the point count.
- The device pushes StatusPush to update localization coordinates.
- The app sends STOP_AUTO_UNDO to stop auto-undo.
Multi-area drawing process
- Finish the current area: Tap finish mapping.
- Stop sampling: Send STOP_AUTO_SAMPLING.
- Stop recording: Send FINISH_RECORD.
- Start a new area: Send RECORD_ELEMENT and set a new element type.
- Repeat the process: Continue point recording, undo, and finish operations.

Calendar schedule

How it works

Feature description

Purpose: The app queries, creates, updates, deletes, enables, and disables calendar schedules for the lawn mower.
Triggers and processing:
- SCHEDULE_QUERY_REQUEST: Query the full schedule list. The device replies through ty_rlm_schedule_list_timer_response().
- SCHEDULE_CREATE_REQUEST: Create a schedule. The device returns the result through ty_rlm_schedule_status_timer_response().
- SCHEDULE_UPDATE_REQUEST: Update a schedule. The device returns the result through ty_rlm_schedule_status_timer_response().
- SCHEDULE_DELETE_PERIOD_REQUEST: Delete a specified time period. The device returns the result through ty_rlm_schedule_status_timer_response().
- SCHEDULE_ENABLE_REQUEST/SCHEDULE_DISABLE_REQUEST: Enable or disable a schedule. The device returns the result through ty_rlm_schedule_status_timer_response().
Things to note: The device side must maintain week, period_id, and time period information for schedules, and trigger local scheduled tasks within valid slots. Starting from v1.1, SCHEDULE_TIMER_PERIOD and RLM_SCHEDULE_CREATE_PARAM_S contain name, plan_id, and mowing_mode: if no name is provided, set name[0] to \0; if no group is assigned, set plan_id to 0; for mowing_mode values, see RLM_SCHEDULE_MOWING_MODE_E.
Response structs:
- ty_rlm_schedule_list_timer_response() returns RLM_SCHEDULE_LIST_TIMER_R for SCHEDULE_QUERY_REQUEST:
  - code_error: Error message. 0 indicates success. Other values indicate failure.
  - day_num: Number of days. Usually seven.
  - timer: Single-day scheduled list array (SCHEDULE_ALONE_PARAM). The length is day_num. Each includes:
    - week: Day of week. See DAYOFWEEK_E.
    - time_num: Number of time periods.
    - time_period: Time period array (SCHEDULE_TIMER_PERIOD). Each period contains:
      - start_minute: Start time, from 0 to 1,440 minutes.
      - end_minute: End time, up to 1,440 minutes.
      - enabled: Whether the period is enabled.
      - period_id: ID automatically generated by the device.
      - edge_mowing: Whether edge mowing is enabled.
      - area_ids_count: Number of area IDs.
      - area_ids: Pointer to the area ID list. The length is area_ids_count.
      - name: Plan name (UTF-8 buffer. name[0]=='\0' means not set).
      - plan_id: Plan group ID (0 means no group).
      - mowing_mode: Schedule mowing mode (RLM_SCHEDULE_MOWING_MODE_E).
- The response API ty_rlm_schedule_status_timer_response() for SCHEDULE_CREATE_REQUEST/SCHEDULE_UPDATE_REQUEST/SCHEDULE_DELETE_PERIOD_REQUEST/SCHEDULE_ENABLE_REQUEST/SCHEDULE_DISABLE_REQUEST returns the struct RLM_SCHEDULE_STATUS_PARAM_R:
  - op: Operation type. See CALENDAR_OPERATION_E.
  - week: Day of week. See DAYOFWEEK_E.
  - period_id: ID automatically generated by the device.
  - start_minute: Start time, from 0 to 1,440 minutes.
  - end_minute: End time, up to 1,440 minutes.
  - enabled: Whether the period is enabled.
  - edge_mowing: Whether edge mowing is enabled.
  - area_ids_count: Number of area IDs.
  - area_ids: Pointer to the area ID list. The length is area_ids_count.
  - name: Plan name (per the convention of SCHEDULE_TIMER_PERIOD.name in the query response).
  - plan_id: Plan group ID (0 means no group).
  - mowing_mode: Schedule mowing mode (RLM_SCHEDULE_MOWING_MODE_E).
  - code_error: Error message. 0 indicates success. Other values indicate failure.

Task settings

How it works

Feature description

Purpose: The app queries or sets lawn task settings.
Trigger: The app sends TaskSettingsRequest(GET or SET). After parsing, the SDK converts it into the following commands and delivers them to the app:
- TASK_SETTINGS_GET_REQUEST: Query lawn task settings.
- TASK_SETTINGS_SET_REQUEST: Configure lawn task settings.
Return: After the device finishes processing, call ty_rlm_task_setting_response() to return the current settings or result.
RLM_TASK_SETTING_R contains:
- code_error: Error message. 0 indicates success. Other values indicate failure. On failure, task_num may be 0.
- request_type: Request type. See REQUEST_TYPE_E to distinguish set and get requests.
- task_num: Number of tasks.
- param: Task settings parameter array (TASK_SETTING_PARAM). Each item contains:
  - area_num: Number of areas.
  - area_id: Area ID list.
  - mode: Work mode. See TASK_SET_MODE_E.
  - path_mode: Path mode. See PATH_PATTERN_E.
  - cutting_height: Work width in mm.
  - edge_cutting: Whether edge mowing is enabled.
  - direction: Work direction. Range: 0 to 360 degrees.
  - speed: Speed. Unit is subject to the panel convention.
  - overlap_percentage: Overlap percentage. Range: 0 to 100.
  - direction_switch: Direction switching configuration (MOW_DIRECTIONSWITCH), including:
    - enabled: Whether the direction switching is enabled.
    - period: Switching cycle. See DIRECTION_SWITCH_PERIOD_E.
    - interval_value: Interval value, in weeks, days, or months.

Robot configuration

How it works

Feature description

Purpose: The app queries or sets robot configuration. The device side returns results through ty_rlm_configuration_response().
Operation types for ConfigurationRequest GET or SET:
- CONFIGURATION_GET_REQUEST: Get configuration.
- CONFIGURATION_SET_BASE_REQUEST: Set base station.
- CONFIGURATION_SET_PASSWORD_REQUEST: Set password.
- CONFIGURATION_SET_RAINY_DAY_MODE_REQUEST: Rain mode (reserved).
- CONFIGURATION_SET_CUT_SWITCH_REQUEST: Mowing switch (reserved).
- CONFIGURATION_SET_SPEED_REQUEST: Manual speed (reserved).
RLM_CONFIGURATION_R contains:
- code_error: Error message. 0 indicates success. Other values indicate failure.
- base_station_id: Base station ID (RLM_STR_ELEMENT_S, including len + name).
- rainy_day_enabled: Rain mode switch (reserved).
- cutting_switch: Mowing switch (reserved).
- speed: Manual speed (reserved). See MANUAL_SPEED_E.
- is_password_set: Whether password is set.
- password_enabled: Password setting enabled.
- password: Password (RLM_STR_ELEMENT_S).
- password_hint: Password hint (RLM_STR_ELEMENT_S).

Get map details

How it works

Feature description

Purpose: The app pulls details and element data for a specified map to display or edit the map.
Trigger: The app sends VECTOR_GET_MAP_INFO_REQUEST.
Return: The device side organizes map data and calls ty_rlm_map_info_response() to reply.
RLM_MAP_INFO_R contains:
- code_error: Error message. 0 indicates success. Other values indicate failure. On failure, element_num may be 0.
- map_id: Map ID.
- map_name: Map name (RLM_STR_ELEMENT_S).
- element_num: Number of map elements.
- elements: Map element array (MAP_ELEMENT_S). Each element contains:
  - element_id: Element ID.
  - element_type: Element type. See ELEMENT_TYPE_E.
  - n_points: Number of points.
  - points: Point coordinate array (RLM_POINT3D_S).
  - n_properties: Number of properties.
  - properties: Property array (PROPERTIES_ENTRY). Each property contains key and value, and both are of type RLM_STR_ELEMENT_S.
  - status: Element status. See ELEMENT_STATUS_E.
- n_custom_shapes / custom_shapes: Full custom shape list for this map. If the map has no shapes, n_custom_shapes = 0 and custom_shapes can be NULL.

Get map list

How it works

Feature description

Purpose: The app pulls summaries of maps available on the device side.
Trigger: The app sends VECTOR_GET_MAP_LIST_REQUEST.
Return: The device side organizes map data and calls ty_rlm_map_list_response() to reply.
RLM_MAP_LIST_INFO_R contains:
- code_error: Error message. 0 indicates success. Other values indicate failure. On failure, n_maps may be 0.
- n_maps: Number of maps.
- maps: Map summary array (MAP_SUMMARY). Each item contains:
  - map_id: Map ID.
  - last_modified: Last modified time (UTC timestamp in seconds).
  - element_count: Number of map elements.
  - is_editing: Whether editing is in progress.
  - version: Map version (RLM_STR_ELEMENT_S).

Mowing record

How it works

Feature description

Purpose: The app pulls details of one mowing record for display on the record detail page.
Trigger: The app sends VECTOR_GET_RECORD_INFO_REQUEST (record_id).
Return: The device side combines the map, path, and required fields, and calls ty_rlm_record_info_response() to reply.
RLM_RECORD_INFO_R contains:
- code_error: Error message. 0 indicates success. Other values indicate failure.
- record_id: Mowing record ID that matches the requested record_id.
- map_info: Map details (RLM_MAP_INFO_R).
- n_paths: Number of path segments.
- paths: Planned path segment array (MOWER_PLANNED_PATH). Each segment contains:
  - path_type: Path type. See PATH_TYPE_E.
  - n_waypoints: Number of waypoints.
  - waypoints: Waypoint array (RLM_POINT2D_S).

Mowing record list

How it works

Feature description

The app uses this feature to pull a summary of historical mowing tasks on the Mowing Record List page at once.
After the app sends MOW_RECORD_INFO_LIST_REQUEST, the device side organizes list data and calls ty_rlm_log_record_list_response() to reply.
RLM_MOW_RECORD_LIST_R contains:
- code_error: Error message. 0 indicates success. Other values indicate failure. On failure, n_mow_records may be 0.
- n_mow_records: Number of mowing records.
- mow_records: Mowing record summary array (MOW_RECORD_SUMMARY). Each item contains:
  - record_id: Record ID. Use it later with VECTOR_GET_RECORD_INFO_REQUEST to pull details of this record.
  - start_time: Start time (Unix timestamp).
  - end_time: End time (Unix timestamp).
  - mow_mode: Mowing mode. See OPERATION_MOW_MODE_E.
  - stop_reason: Stop reason. See MOWING_RESULT_E.
  - n_area_names: Number of area names.
  - area_names: Area name list (RLM_STR_ELEMENT_S array, including len + name).
  - mow_area: Mowing area in square meters.

Error record list

How it works

Feature description

The app uses this feature to pull a summary of historical error logs on the Error Record List page at once.
After the app sends ERROR_RECORD_INFO_LIST_REQUEST, the device side organizes list data and calls ty_rlm_error_log_record_list_response() to reply.
RLM_ERROR_LOG_RECORD_LIST_R contains:
- code_error: Error message. 0 indicates success. Other values indicate failure. On failure, n_error_log_records may be 0.
- n_error_log_records: Number of error records.
- error_log_records: Error record summary array (ERROR_LOG_RECORD_SUMMARY). Each item contains:
  - record_id: Record ID.
  - error_time: Error occurrence time (Unix timestamp).
  - error_reason: Error cause (RLM_STR_ELEMENT_S, including len + name).
  - is_resolved: Whether the error is resolved.
  - error_code: Error code.
  - error_description: Error description (RLM_STR_ELEMENT_S, including len + name).

Custom shape

Feature description

Set: The app sends CUSTOM_SHAPE_SET_REQUEST. The device obtains RLM_CUSTOM_SHAPE_SET_S (full-list semantics) in FUNC_SET_CB, and after processing returns CustomShapeResponse (SET_SHAPES echo) through ty_rlm_custom_shape_response().
List query: The app sends VECTOR_GET_MAP_INFO_REQUEST. The device handles the map query in FUNC_QUERY_CB and fills in n_custom_shapes and custom_shapes in RLM_MAP_INFO_R, then reports through ty_rlm_map_info_response(). The protocol field is RLM_MAP_INFO_R.custom_shapes.
Key fields in RLM_CUSTOM_SHAPE_R (used by ty_rlm_custom_shape_response):
- code_error: Execution result. success=true indicates success. If the operation fails, fill in code, level, message, and solutions.
- n_shapes: Number of shapes.
- shapes: Shape array (RLM_CUSTOM_SHAPE_S). Each item must contain at least:
  - shape_id: Unique shape ID.
  - shape_type: Shape type. See CUSTOM_SHAPE_TYPE_E.
  - transform: Center point, width, height, and rotation data (RLM_SHAPE_TRANSFORM_S).
  - map_id: Map ID that the shape belongs to.
  - n_contour_points + contour_points: Contour points. Optional for irregular shapes.
  - n_local_points + local_points: app internal point set. The device stores and reads it as is.
When SET succeeds with no shapes echoed, set n_shapes = 0, shapes = NULL, and code_error.success = TRUE.
When the map details contain no custom shapes, set n_custom_shapes = 0 and custom_shapes = NULL.

Example

/**
 * @brief Callback function pointer for lawn mower protocol function settings.
 */
OPERATE_RET rlm_advance_function_set(IN COMPLEX_RLM_CMD_E cmd, IN void* param)
{
    OPERATE_RET ret = OPRT_OK;
    switch (cmd) {
case VECTOR_DELETE_ELEMENT_REQUEST: {  // Vector map: delete vector elements.
            DELETE_ELEMENT_S *trans_data = (DELETE_ELEMENT_S*)param;
            PR_DEBUG("rlm delete area num:%d", trans_data->n_area_ids);
            for(int i = 0; i < trans_data->n_area_ids; i++) {
                PR_DEBUG("rlm delete area id:%d", trans_data->area_ids[i]);
            }
            DELETE_ELEMENT_R deleted_elements = { 0 };
            int deleted_ids [10] = { 1,2,3,4,5,6,7,8,9,10};   // Test data.
            deleted_elements.n_area_ids = 10;
            deleted_elements.area_ids = deleted_ids;
            deleted_elements.code_error.success = TRUE;
            ty_rlm_deleted_elements_response(&deleted_elements);
        } break;
...
default: {
            break;
        }
    }
    return 0;
} 
/**
 * @brief Callback function pointer for lawn mower protocol function queries.
 */
OPERATE_RET rlm_advance_function_query(IN COMPLEX_RLM_CMD_E cmd, IN void* param)
{
    OPERATE_RET ret = OPRT_OK;
    switch (cmd) {
        case CONFIGURATION_GET_REQUEST: {    // Robot gets configuration.
            PR_DEBUG("config request");
            int *trans_data = (int*)param;
            if(trans_data[0] == CONFIG_UNKNOWN) {   // Query all configuration items.
                RLM_CONFIGURATION_R config_result = {0};
                config_result.speed = robot_param.configuration.speed;
                config_result.rainy_day_enabled = robot_param.configuration.rainy_day_enabled;
                config_result.cutting_switch = robot_param.configuration.cutting_switch;
                config_result.base_station_id.name = robot_param.configuration.base_station_id;
                config_result.base_station_id.len = strlen(robot_param.configuration.base_station_id);
                config_result.is_password_set = robot_param.configuration.is_password_set;
                config_result.password_enabled = robot_param.configuration.password_enabled;
                if (robot_param.configuration.is_password_set && robot_param.configuration.password[0] != '\0') {
                    config_result.password.name = robot_param.configuration.password;
                    config_result.password.len = strlen(robot_param.configuration.password);
                } else {
                    config_result.password.name = "1234";
                    config_result.password.len = 4;
                    config_result.is_password_set = TRUE;
                }
                config_result.password_hint.name = robot_param.configuration.password_hint;
                config_result.password_hint.len = strlen(robot_param.configuration.password_hint);
                config_result.code_error.success = TRUE;
                ty_rlm_configuration_response(&config_result);
            } else if(trans_data[0] == RAINY_DAY_MODE){    // Query rain mode settings.
                RLM_RAINY_DAY_CONFIG_R config_result = {0};
                config_result.rainy_day_enabled = robot_param.configuration.rainy_day_enabled;
                config_result.code_error.success = TRUE;
                ty_rlm_rainy_day_config_response(&config_result);
            } else if(trans_data[0] == MANUAL_SPEED){      // Query manual speed settings.
                RLM_MANUAL_SPEED_CONFIG_R config_result = {0};
                config_result.speed = robot_param.configuration.speed;
                config_result.code_error.success = TRUE;
                ty_rlm_manual_speed_config_response(&config_result);
            } else if(trans_data[0] == BASE_STATION){      // Query base station settings.
                RLM_BASE_STATION_CONFIG_R config_result = {0};
                config_result.base_station_id.name = robot_param.configuration.base_station_id;
                config_result.base_station_id.len = strlen(robot_param.configuration.base_station_id);
                config_result.code_error.success = TRUE;
                ty_rlm_base_station_config_response(&config_result);
            } else if(trans_data[0] == CUTTING_SWITCH){      // Query mowing switch settings.
                RLM_CUTTING_SWITCH_CONFIG_R config_result = {0};
                config_result.cutting_switch = robot_param.configuration.cutting_switch;
                config_result.code_error.success = TRUE;
                ty_rlm_cutting_switch_config_response(&config_result);
            } else if(trans_data[0] == PASSWORD){      // Query password settings.
                RLM_PASSWORD_CONFIG_R config_result = {0};
                config_result.is_password_set = robot_param.configuration.is_password_set;
                config_result.password_enabled = robot_param.configuration.password_enabled;
                if (robot_param.configuration.is_password_set && robot_param.configuration.password[0] != '\0') {
                    config_result.password.name = robot_param.configuration.password;
                    config_result.password.len = strlen(robot_param.configuration.password);
                } else {
                    config_result.password.name = "1234";
                    config_result.password.len = 4;
                    config_result.is_password_set = TRUE;
                }
                config_result.password_hint.name = robot_param.configuration.password_hint;
                config_result.password_hint.len = strlen(robot_param.configuration.password_hint);
                config_result.code_error.success = TRUE;
                ty_rlm_password_config_response(&config_result);
            }
        } break;
        default: {
            PR_ERR("cmd data query not support now:%d", cmd);
            ret = OPRT_NOT_SUPPORTED;
        } break;
    }
    return ret;
}
// Main power-on initialization flow.
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_rlm_complex_func_register(rlm_advance_function_set,rlm_advance_function_query);  // Register advanced lawn mower protocol callbacks.
}

Prev DocDPs and Interaction Logic of Robot Vacuum

Next DocPet Detection, Profile, and Audio