Custom Widgets
Overview
Custom Widgets is a feature that encapsulates payload functions into UI widgets such as buttons, switches, and sliders. A mobile app developed by Autel Robotics or based on MSDK can recognize the widget configuration within the payload and generate corresponding UI controls, allowing users to quickly configure payload parameters and trigger specific actions. Additionally, these apps can display payload status in real time via a floating window.
Users can also map payload functions to reserved buttons on the remote controller as needed, enabling more convenient control of the payload via the physical remote.
Basic Concepts
Main Interface Widgets
- Action Bar Widgets: The action bar supports four types of widgets — buttons, switches, sliders, and selection lists. A maximum of 9 custom widgets can be configured.
- Floating Window: Displays real-time status information from the payload.
Configuration Interface Widgets
Users can interact with various widget types in the configuration interface, such as buttons, switches, sliders, selection lists, and integer input fields.
Widget Configuration File
Note:
- Path to the widget configuration file:
example/widget_file- When the Autel Robotics system language is set to Chinese, the configuration file is
cn_big_screen- When the system language is set to English, the configuration file is
en_big_screen- Configuration details such as widget ID, quantity, and type must remain consistent across different languages.
Important: The widget configuration includes both static configuration files and UI icons. It is recommended to first define widget properties in the static file, and then design the widget icons.
Configuring Widget Properties
widget_config.json is a configuration file used to define the static properties of UI widgets. When editing the widget_config.json file, be sure to strictly adhere to proper JSON syntax; otherwise, the configuration file will become invalid and unusable.
Tips:
- Configuration items in a JSON file are enclosed in
{}and expressed as key-value pairs;- The Key in JSON must be enclosed in double quotation marks. Do not omit the quotes around the key;
- JSON values only support numbers (including integers and floating-point), strings, Boolean values (e.g.
trueandfalse), arrays (must be enclosed in[]), and objects (must be enclosed in{}).
Note: The content after
//in the code below is a comment. Do not include such comments in the actual JSON configuration file.
{
"version": { // This is a version number of custom widget configuration file, it must not be modified by users.
"major" : 1,
"minor" : 0
},
"main_interface": { // Main interface widget settings
"floating_window": {// Floating window configuration
"is_enable": true // Whether to display the floating window; true: visible, false: hidden
},
"widget_list": [ // List of widgets in the main interface action bar
{
"widget_index": 0, // Widget ID
"widget_type": "button", // Widget type. Main interface action widgets support: "button": button, "switch": toggle, "range": slider, "list": selection list
"widget_name": "button1", // Widget name
"icon_file_set": { // Icon file set for the widget
"icon_file_name_selected" : "button.png", // Icon file name when selected
"icon_file_name_unselected" : "button.png" // Icon file name when unselected
}
},
{
"widget_index": 1,
"widget_type": "button",
"widget_name": "button2",
"icon_file_set": {
"icon_file_name_selected" : "button2.png",
"icon_file_name_unselected" : "button2.png"
}
},
{
"widget_index": 2,
"widget_type": "list",
"widget_name": "List",
"list_item": [
{
"item_name": "item1",
"icon_file_set": {
"icon_file_name_selected" : "item1.png",
"icon_file_name_unselected" : "item1.png"
}
},
{
"item_name": "item2",
"icon_file_set": {
"icon_file_name_selected" : "item2.png",
"icon_file_name_unselected" : "item2.png"
}
}
]
},
{
"widget_index": 3,
"widget_type": "switch",
"widget_name": "switch1",
"icon_file_set": {
"icon_file_name_selected" : "select.png",
"icon_file_name_unselected" : "unselect.png"
}
},
{
"widget_index": 4,
"widget_type": "scale",
"widget_name": "scale1",
"icon_file_set": {
"icon_file_name_selected" : "scale.png",
"icon_file_name_unselected" : "scale.png"
}
}
]
},
"config_interface": {
"text_input_box": { // Text input box
"widget_name":"TextInputBox1", //Name of the text input box
"placeholder_text":"Input message: ", //Placeholder text for the input box
"is_enable":false // Whether the text input box is visible; false: hidden, true: visible
},
"widget_list": [
{
"widget_index": 5,
"widget_type": "button",
"widget_name": "Button_5"
},
{
"widget_index": 6,
"widget_type": "scale",
"widget_name": "Scale_6"
},
{
"widget_index": 7,
"widget_type": "input_box",
"widget_name": "Input_Box_7",
"int_input_box_hint": "unit:s"
},
{
"widget_index": 8,
"widget_type": "switch",
"widget_name": "Switch_8"
},
{
"widget_index": 9,
"widget_type": "list",
"widget_name": "List_9",
"list_item": [
{
"item_name": "Item1"
},
{
"item_name": "Item2"
},
{
"item_name": "Item3"
},
{
"item_name": "Item4"
}
]
}
]
}
Using the Custom Widget Feature
To develop the custom widget functionality for a payload, you must first initialize the custom widget module, retrieve the path to the widget configuration file, configure the widget display settings for different system languages, and define the callback handler list to apply the custom widget functionality. This process ultimately enables full support for custom widgets.
1. Widget Initialization
Before using the "Custom Widget" feature, you need to initialize the payload's widget system with the following code:
uavStat = UavWidget_Init();
if (uavStat != UAV_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("UAV test widget init error, stat = {}", uavStat);
return uavStat;
}
2. Setting Widget Configuration Information
When developing a payload, you need to set the configuration information for the widgets, such as the default widget configuration file and the localized configuration files corresponding to different system languages. This ensures that Autel Robotics can retrieve the widget configuration and display it correctly on the Autel Robotics platform.
Set widget parameters for the payload
uavStat = UavWidget_RegDefaultUiConfigByDirPath(defaultWidgetPath.c_str());
if (uavStat != UAV_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("UavWidget_RegDefaultUiConfigByDirPath failed, stat = {}", uavStat);
} else {
USER_LOG_INFO("UavWidget_RegDefaultUiConfigByDirPath succeeded, path = {}", defaultWidgetPath);
}
uavStat = UavWidget_RegUiConfigByDirPath(UAV_MOBILE_APP_LANGUAGE_ENGLISH,
UAV_MOBILE_APP_SCREEN_TYPE_BIG_SCREEN,
englishBigScreenPath.c_str());
if (uavStat != UAV_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("UavWidget_RegUiConfigByDirPath failed, stat = {}", uavStat);
} else {
USER_LOG_INFO("UavWidget_RegUiConfigByDirPath succeeded, language = ENGLISH, screen = BIG_SCREEN, path = {}",
englishBigScreenPath);
}
uavStat = UavWidget_RegUiConfigByDirPath(UAV_MOBILE_APP_LANGUAGE_CHINESE,
UAV_MOBILE_APP_SCREEN_TYPE_BIG_SCREEN,
chineseBigScreenPath.c_str());
if (uavStat != UAV_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("UavWidget_RegUiConfigByDirPath failed, stat = {}", uavStat);
} else {
USER_LOG_INFO("UavWidget_RegUiConfigByDirPath succeeded, language = CHINESE, screen = BIG_SCREEN, path = {}",
chineseBigScreenPath);
}
3. Registering the Widget Handler List
Use the UavWidget_RegHandlerList API to register a specific payload function along with the corresponding widget parameters. This binds the payload functionality to the designated widget.
uavStat = UavWidget_RegHandlerList(s_widgetHandlerList, s_widgetHandlerListCount);
if (uavStat != UAV_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("UAV test widget register handler list error, stat = {}", uavStat);
}