A3-Ultra local resource management currently exposes six types of resources: motions, emoticons, audio, skills, maps, and creative works.
Users can create, delete, query, import, and export these resources to meet robot capability configuration and content customization requirements. For detailed supported features, refer to the resource descriptions below.
The following sections describe each resource module and its related functions in detail.
Workflow:
Creation and storage: Users must first place data in the temporary directory /agibot/data/resources/tmp on the HDU node and trigger synchronization through the RPC interface. The system automatically identifies the resource source and persists it into one of the following directories by category:
Note that the temporary directory /agibot/data/resources/tmp is cleared automatically after the robot restarts. The .gz files generated during export are also part of the tmp directory. Make sure important resources have been synchronized and persisted.
Query and maintenance: The system supports real-time resource queries, including resource lists and detailed resource information. It also provides a delete interface so users can remove resources that are no longer needed and keep resource storage organized and manageable.
Distribution and migration: Users can quickly export and import created resources through the RPC interface, which is suitable for the following scenarios:
Fast resource backup
Batch migration across devices
Efficient reuse of configured resources
Resource description:
Resource Type
Description
Create/Delete
Import/Export
Query
Update
Display Location
Emoticon
Animations displayed on the head LED
✔
✔
✔
✔
AimMaster → Skills → Emoticon
Motion
Mostly upper-body actions such as waving, finger-heart, or thumbs-up
✔
✔
✔
Only resource_name can be modified
AimMaster → Skills → Motion
Audio
Robot voice resources
✔
✖
✔
✖
AimMaster → Skills → Voice
Skill
Full-body robot dances
✖
✖
✔
✖
AimMaster → Skills → Talent
Creative Work
Complex and continuous full-body dances or upper-body action performances created by orchestrating emoticon, motion, audio, and skill modules together.
✔
✔
✔
✖
AimMaster → Skills → My Creations
Map
Maps used for robot navigation and localization
✖
✔
✔
✖
AimMaster → Map
All of the resources above are stored on the HDU. Users can use these RPC interfaces together with AimMaster.
// tmp/xxx means the creation path is /agibot/data/resources/tmp
// HDU paths are used during resource creation
// The comment after each field explains when it can be used. If a field is marked as usable during creation,
// include it when creating the resource. Fields not marked for creation do not need to be provided.
/**
* @brief Emoticon extra information
*/
//resource_type=RESOURCE_TYPE_EMOTICON
"emoticon_extra_info" {
"display_name" {
"zh_CN": "Right-hand heart gesture",
"en_US": "Finger heart_right hand",
}, // Display names in Chinese and English, format: map<string, string> (query)
"emoticon_file_url": "tmp/e.mp4", // Emoticon file URL (create/query/update). tmp/xxx means /agibot/data/resources/tmp on the HDU
"thumbnail_file_url": "tmp/t.mp4", // Thumbnail file URL (create/query/update)
"cover_file_url" = "tmp/1.png", // Cover image URL (create/query/update)
}
/**
* @brief Motion extra information
*/
//resource_type=RESOURCE_TYPE_MOTION
"motion_extra_info":{
"record_file_path":"/agibot/data/home/agi/test/right_hand_thumbs_up_long", // Recording file path on the HDU. "test" is the folder name and "right_hand_thumbs_up_long" is the .macp file name (used only during creation)
"display_name" {
"zh_CN": "Right-hand heart gesture",
"en_US": "Finger heart_right hand",
}, // Display names in Chinese and English (query)
"cover_file_url": "" , // Preview image URL (query)
"preview_video_url":"" ,// Preview video URL (query)
}
/**
* @brief Audio extra information
*/
//resource_type=RESOURCE_TYPE_AUDIO
"audio_extra_info": {
"audio_file_url" :"" // Audio file URL (create/query)
"display_name" {
"zh_CN": "",
"en_US": "",
}, // Display names in Chinese and English (query)
"cover_file_url":"" ,// Preview image URL (query)
}
/**
* @brief Creative work extra information
*/
//resource_type=RESOURCE_TYPE_OFFRING_WORK
"offring_work_extra_info": {
"cover_file_url": "",// Cover file URL (query)
"preview_video_url": "",// Preview file URL (query)
"display_name": {
"display_name_zh": "Test creative work",
"display_name_en": "Test Creative Work"
},// Display names in Chinese and English (query)
"motions": [
{
// Use NormalMotion when the resource in motions.resources is a motion resource.
// Use WholeBodyDance when the resource is a talent/skill resource. An example is shown below as well.
"type": "NormalMotion",
"resources": [
{
"source_type": 1, // 1 means SKILL_DETAIL_SOURCE_TYPE_LOCAL_RESOURCE (local resource), 2 means SKILL_DETAIL_SOURCE_TYPE_SKILL_PACKAGE_RESOURCE (resource included in a skill package)
"path": "/agibot/data/resources/custom/motion/pose_i_am_super_strong/pose_i_am_super_strong.mcap"// Resource file path on the HDU
}
]
}
],
"emoticons": [
{
"resources": [
{
"source_type": 1,
"path": "/agibot/data/resources/custom/emoticon/emoticon_guiding/emoticon.mp4"
}
]
}
],
"audios": [
{
"resources": [
{
"source_type": 1,
"path": "/agibot/data/resources/custom/audio/test/test.wav"
}
]
}
],
}
/**
* @brief Creative work extra information
*/
//resource_type=RESOURCE_TYPE_OFFRING_WORK
"offring_work_extra_info": {
"cover_file_url": "",
"preview_video_url": "",
"display_name": {
"display_name_zh": "Test creative work",
"display_name_en": "Test Creative Work"
},
"motions": [
{
// When the resource in motions is a talent/skill resource, refer to the following example
"type": "WholeBodyDance",
"resources": [
{
"source_type": 1,
"path": "Acceleration Moment"
}
]
}
],
"emoticons": [
{
"resources": [
{
"source_type": 1,
"path": "/agibot/data/resources/custom/emoticon/emoticon_guiding/emoticon.mp4"
}
]
}
],
"audios": [
{
"resources": [
{
"source_type": 1,
"path": "/agibot/data/resources/custom/audio/test/test.wav"
}
]
}
],
}
/**
* @brief Map extra information
*/
//resource_type=RESOURCE_TYPE_MAP
"map_extra_info": {
"map_info": {
"index": 2,
"map_path": "/agibot/data/var/MapManagerModule/1762584133656/",
"width": 1216.0, // Map width and height, in pixels
"height": 1262.0,
"resolution": 20.0, // Actual distance represented by each pixel, in millimeters
"origin": {
"u": 524, // Column index of the world coordinate origin on the map
"v": 594 // Row index of the world coordinate origin on the map
}
},
"topology_info": [ // Topology information, mainly storing robot navigation point information, corresponding to AimMaster → Map → Point settings
{
"topo_msg": {
"cur_path_id": 0,
"cur_point_id": 1,
"cur_region_id": 0,
"hr_points": null,
"navi_points": [
{
"id": 1,
"name": "Waypoint 1",
"pose": {
"x": 7.85, // Unit: meter
"y": -2.15,
"theta": -2.503741636798901 // Unit: radian
},
"type": 1
}
],
"paths": null,
"qr_points": null,
"regions": null,
"rotate_angle": 6.001279822735171,
"user_name": "",
"user_sn": 0
},
"user_name": ""
}
]
},
resource_type: You can provide either the numeric value or the enum name. For example, 2 corresponds to RESOURCE_TYPE_EMOTICON. For the full mapping, refer to section 7.5.2. Using the enum name is recommended; numeric values are kept only for compatibility.
resource_name: Resource name
tags: Tags
The xxxx_extra_info field must match resource_type. See the partial parameter declarations for details.
After a resource is created, it is assigned a resource_id. This field is auto-incremented by the system and does not need to be provided during creation.
The output content is consistent with the Get Resource List interface.
On success, msg is Resource create success.
On failure, msg is Failed to create emoticon. The resource type in the message changes according to the actual resource type, for example motion for motion resources.
Either resource_id or resource_name must be provided.
resource_typemust be provided; otherwise all resources are deleted by default. For example, 2 means RESOURCE_TYPE_EMOTICON. See section 7.5.2 for details.
Except for emoticon resources, motion resources can only update resource_name. Updating other resource types is not currently supported. If you attempt to update other resource types, the output may still indicate success, but the resource information will remain unchanged when queried.
Modifying resource_id or resource_type is not supported.
resource_type: Refer to section 7.5.2 for the available resource_type values.
Output
text
{
"header": {
"code": "0",
"msg": "Resource list get success",
"trace_id": "",
"domin": ""
},
"resources": [
{
"id": 36,
"resource_id": 16,
"resource_key": "",
"resource_version": "",
"resource_name": "emoticon_language_change",
"duration": 3000,
"resource_type": "RESOURCE_TYPE_EMOTICON",
"resource_path": "/agibot/data/resources/default/emoticon/emoticon_language_change/emoticon.mp4",
"source": "default",
"charge_type": "CHARGE_TYPE_FREE",
"is_change": false,
"create_time_stamp": "1767785325",
"update_time_stamp": "1767785325",
"expire_time_stamp": "0",
"last_used_time_stamp": "0",
"md5": "4a605dcb92af92adeaf874e1e4970ea2",
"description": "Emoticon used when switching between Chinese and English",
"tags": [],
"scenes": [],
"emoticon_extra_info": {
"display_name": {
"zh_CN": "Language Switch",
"en_US": "Language switch"
},
"emoticon_file_url": "default/emoticon/emoticon_language_change/emoticon.mp4", // Under /agibot/data/resources/ on ORIN
"thumbnail_file_url": "default/emoticon/emoticon_language_change/thumbnail.mp4",
"cover_file_url": "default/emoticon/emoticon_language_change/cover.png"
},
"usagerights": ["Agent"]
},
{
"id": 51,
"resource_id": 22,
"resource_name": "emoticon_voice_rejection",
"duration": 4000,
"resource_type": "RESOURCE_TYPE_EMOTICON",
"description": "Used when user speech is rejected; intended for voice interaction only",
"emoticon_extra_info": {
"display_name": {
"zh_CN": "Speech Rejection",
"en_US": "Voice rejection"
}
},
"usagerights": ["Agent", "AimMaster"]
}
// ... several resources omitted here
],
"tags": [],
"scenes": [
"normal-emoticon_list",
"task-associated_emoticon"
],
"usagerights": [
"Agent",
"AimMaster"
]
}
resource_id: Resource ID
resource_name: Resource name
double duration: Resource duration in milliseconds. This does not need to be provided when importing or creating through AimMaster, but it must be provided when creating directly through the API without import.
resource_type: Resource type. See section 7.5.2.
resource_path: Resource path
source: Resource source. Currently only custom and default are supported.
is_change: Whether modification is supported
create_time_stamp: Creation timestamp
update_time_stamp: Update timestamp
md5: MD5 of the primary resource file
description: Description
tags: Tags
scenes: Scenes
emoticon_extra_info: One of the xxx_extra_info fields described in section 7.5.2.
usagerights: Usage permissions
The remaining output fields are redundant and can generally be ignored.
resource_type: RESOURCE_TYPE_EMOTICON indicates the emoticon type. The type definition is the same as in Get Resource List.
resource_type: Required.
resource_id: Corresponds to the resource_id returned in the resource list.
resource_name: Corresponds to the resource_name returned in the resource list.
source: Indicates the resource source, either custom or default. Resources created through RPC are generally custom.
Either resource_id or resource_name must be provided. If resource_name is provided, source must also be provided. The default source is default. Resources created through RPC must use source=custom. If resource_id is provided, source is not required. Using resource_id is recommended.
resource_list: Fill in the resource_name values of the resources to export. Multiple names can be provided at once, but they must belong to the same resource category. If not provided, all resources of that category are exported. resource_id is not supported here.
Only motion and emoticon resources can be exported.
pkg_name: Caller identifier string, optional. If provided, it is returned unchanged in the output and can be used for log tracing.
file_name: Audio file name. The server looks for this file under /agibot/data/var/hal_audio/file/.
file_path: File path, optional
priority: Playback priority, optional. Enum names are supported. The default values are 0 and L1(1) to L10(10). A larger value means higher priority. Higher-priority audio interrupts lower-priority audio that is currently playing. Final priority = PlayPriority × 100 + priority_weight.
priority_weight: Priority weight parameter (0-99), optional. Do not use unless required by the product.
channles: Number of channels. Optional when the audio file is a .wav file.
samplerate: Sample rate. Optional when the audio file is a .wav file.
Output
text
{
"pkg_name": "",
"is_success": true
}
pkg_name: Caller identifier, identical to the value passed in the input.
is_success: Whether the request was accepted.
Example Script
examples/agent/PlayFile.py
Remarks
The audio file must be placed in /agibot/data/var/hal_audio/file/ in advance.
Both WAV and PCM formats are supported. WAV files include their own format header and can be played directly. PCM files must provide channles and samplerate, otherwise the error plz update file channels info is returned.
e_path: Directory where the emoticon file is located. An absolute path is required.
e_id: Emoticon resource ID. It can be obtained through the GetResourceList interface and may be left empty.
Repeat: Number of playback repetitions.
Priority: Priority level. Use 440. A smaller value indicates a higher priority.
is_stop: This field is used to start or stop display. It will stop all emoticon playback. When stopping playback, e_path, e_id, repeat, and priority can all be left empty.
Example Script
examples/resource_manager/face_play.py
Notes
The ROS2 message type is ros2_plugin_proto/msg/RosMsgWrapper. Before using it, run source prebuilt/ros2_plugin_proto_aarch64/share/ros2_plugin_proto/local_setup.bash.
This message is transmitted via iceoryx by default. To use ros2 topic data instead, log in to the MDU and modify the communication mode of /skill/pilot/face/play under aimrt/channel/sub_topics_options in /agibot/software/v0/config/skillpilot/skillpilot.yaml to [ mqtt, ros2 ]. Restart the robot after the modification for it to take effect.
