5.1.7 LinkCraft Actions

Note

X2 EDU does not support the features in this section. This section applies only to X2 Ultra and X2 Ultra(new version).

About LinkCraft

LinkCraft is AgiBot’s action creation and management platform for creating, editing, debugging, and deploying robot actions. After actions created on LinkCraft are deployed to the robot, you can use the ROS interfaces described in this section to retrieve the deployed resource list and trigger single-robot or multi-robot group playback.

For platform-side usage, refer to the LinkCraft User Manual.

Interface Description

Service Name	Data Type	Description
`/aimdk_5Fmsgs/srv/GetRobotResources`	`GetRobotResources`	Retrieve the list of resources on the robot
`/aimdk_5Fmsgs/srv/ExecuteActionResource`	`ExecuteActionResource`	Play the specified LinkCraft action resource
`/aimdk_5Fmsgs/srv/GroupControlTimeSync`	`GroupControlTimeSync`	Group control time synchronization

GetRobotResources ros2-srv @ app_proxy/srv/GetRobotResources.srv

# Retrieve the list of resources on the robot
# Service name: /aimdk_5Fmsgs/srv/GetRobotResources

# Request
CommonRequest header         # Request header

---

# Response
CommonResponse header        # Response header
RobotResource[] robot_resources  # List of on-robot resources

RobotResource ros2-msg @ app_proxy/msg/RobotResource.msg

string resource_key            # Unique resource identifier
CurrentVersion current_version    # Current version info

CurrentVersion ros2-msg @ app_proxy/msg/CurrentVersion.msg

string version               # Version number
string name                  # Resource name
string[] files               # Resource file list
uint64 download_timestamp_seconds         # Resource download timestamp

ExecuteActionResource ros2-srv @ app_proxy/srv/ExecuteActionResource.srv

# Play a LinkCraft action
# Service name: /aimdk_5Fmsgs/srv/ExecuteActionResource

# Request
CommonRequest header         # Request header
string resource_key          # Unique resource identifier (from GetRobotResources)
string resource_version      # Resource version
SlaveDevice[] slaves         # Slave device list (fill in slave IPs for group control; may be empty for single-robot playback)
string meta                  # Extension parameters in JSON format

---

CommonResponse header        # Response header; header.header.code == 0 means success

SlaveDevice ros2-msg @ app_proxy/msg/SlaveDevice.msg

string ip                    # Slave device IP address

meta field format:

Scenario	meta Value
Single-robot full-body action (onnx)	`{"resource_type": "BODY_MONTION"}`
Single-robot arm action	`{"resource_type": "ARM_MONTION"}`
Group-control full-body action (onnx)	`{"control_type": "GROUP_CONTROL","resource_type": "BODY_MONTION"}`
Group-control arm action	`{"control_type": "GROUP_CONTROL","resource_type": "ARM_MONTION"}`

When resource_key contains onnx, it is a full-body action; otherwise, it is an arm action.

Optional fields the meta may also carry in group-control scenarios:

if_play_master (bool, default true): whether to play on the master device. When set to false, only the slave devices play; the master device does not act.

Check header.message for the actual result. header.status.value is always FAILURE(2) in the current firmware due to an implementation issue and cannot be used to determine success.

Single-robot playback:

`header.message`	Interface Description
`Play success`	Playback succeeded
`No valid resource files found`	No valid resource files found in resource directory
`The robot is playing`	Robot is playing; cannot trigger a new task
`The robot is in a faulty state`	Robot is in a faulty state
`The robot is not in ready posture`	Robot is not in ready posture
`MC ROS service not ready`	Motion control ROS service not ready
`Audio ROS service not ready`	Audio ROS service not ready
`Face ROS service not ready`	Face ROS service not ready
`Trigger MC ROS service error: <exception_desc>`	Motion control ROS service call exception (`<exception_desc>` is the runtime-specific exception message)
`Trigger Audio ROS service error: <exception_desc>`	Audio ROS service call exception (same as above)
`Trigger Face ROS service error: <exception_desc>`	Face ROS service call exception (same as above)
`Trigger interaction error`	Failed to call interaction playback interface
`Bad request`	Invalid request parameters
`Error processing play item <N>: <exception_desc>`	Internal exception while processing play item (`<N>` is the play item index, `<exception_desc>` is the runtime-specific exception message)
`No time sync result for slave device <ip>`	Slave device has not completed time sync during group control (`<ip>` is the slave IP)
`<exception_desc>`	Unexpected exception during processing (content is the string representation of a Python exception; depends on the specific exception type and cannot be enumerated)

Group-control playback (partial slave failure):

header.message is a JSON string containing details of each failed slave device, in the following format:

{
  "10.0.1.41": {
    "sn": "robot_serial_number",
    "error_code": 412,
    "error_msg": "The robot is playing"
  }
}

where the key is the failed slave device’s IP (as provided by the user in the slaves field), sn is the device’s serial number, and error_code and error_msg are the specific error code and description for that device’s playback failure.

Possible values of error_code in the JSON:

`error_code`	Interface Description
400	Invalid request parameters
401	Failed to call interaction playback interface
402	Robot is not in ready posture
403	Dangerous/damaging robot motion (reserved)
404	Resource not found (reserved)
405	Robot is in a faulty state
406	Motion control ROS service not ready
407	Audio ROS service not ready
408	Face ROS service not ready
409	Motion control ROS service call exception
410	Audio ROS service call exception
411	Face ROS service call exception
412	Robot is playing
413	Slave device without time sync (reserved)
450	Group control task failure (reserved)
500	Internal server error
503	Service unavailable (reserved)

Parsing example:

import json
if header.message == "Play success":
    print("Playback succeeded")
else:
    try:
        details = json.loads(header.message)
        for ip, info in details.items():
            print(f"Slave {ip}: error_code {info['error_code']}, {info['error_msg']}")
    except json.JSONDecodeError:
        print(f"Playback failed: {header.message}")

GroupControlTimeSync ros2-srv @ app_proxy/srv/GroupControlTimeSync.srv

# Group control time synchronization
# Service name: /aimdk_5Fmsgs/srv/GroupControlTimeSync

# Request
CommonRequest header         # Request header
SlaveDevice[] slaves         # Group-control slave node list

---

# Response
CommonResponse header        # Response header
int32 error_code             # Error code; 0 means success
string error_msg             # Error message

Call this interface before group-control playback to complete multi-robot time synchronization. error_code 0 means synchronization succeeded; 1 means failure (error_msg contains details of the failed slave devices).

Programming Examples

For detailed programming examples and code descriptions, see:

C++ Examples:
- Play LinkCraft Action
- Play LinkCraft Action (Multi-Robot)
Python Examples:
- Play LinkCraft Action
- Play LinkCraft Action (Multi-Robot)

Caution

As standard ROS DO NOT handle cross-host service (request-response) well, please refer to SDK examples to use open interfaces in a robust way (with protection mechanisms e.g. exception safety and retransmission)

While the robot is in Stable Standing Mode or Locomotion Mode, DO NOT launch ROS nodes in rapid bulk (no more than 2 nodes per second is recommended), as a large number of nodes joining DDS discovery within a short period causes communication congestion and degrades motion control real-time performance, which may cause the robot to lose balance and fall