5.1.1 Motion Mode Switching

The mode-switch and locomotion interfaces provide core capabilities for switching motion modes and controlling walking/running.

Core Functions

Supports switching into the following basic motion modes:

Mode

Value

Description

Use cases

Zero-Torque Mode

PASSIVE_DEFAULT

Robot joints zero torque, free state (excluding end-effector)

System startup, maintenance, soft e-stop

Damping Mode

DAMPING_DEFAULT

Joints have damping (excluding end-effector)

Safe movement

Position-controlled Stand

JOINT_DEFAULT

Position-controlled stand

Precise joint position control

Stable Stand

STAND_DEFAULT

Active force to ensure standing

Dynamic balance control, walking/action ready state

Locomotion Mode

LOCOMOTION_DEFAULT

Normal walking/running

Daily movement

Head Control

HEAD_ONLY

Head joints only

Independent head motion (Ultra only)

Upper Body Control

UPPERBODY_REMOTE_SPLIT

Controls head, arms, and hands

Teleoperation, upper body teaching

Note: Starting from v0.8.0, the stable-stand mode and Locomotion Mode are unified and will switch internally based on the current motion commands.

Motion Mode Query Service

Service Name

Data Type

Description

/aimdk_5Fmsgs/srv/GetMcAction

GetMcAction

Query current motion mode

  • GetMcAction ros2-srv @ mc/action/srv/GetMcAction.srv

    # Get current motion mode
# Service: /aimdk_5Fmsgs/srv/GetMcAction

# Request
CommonRequest request            # Common request

---

# Response
ResponseHeader header            # Response header
McActionInfo info                # Information about the current motion mode

    • McActionInfo ros2-msg @ mc/action/McActionInfo.msg

      # Motion mode information
McAction current_action  # Current motion mode (not used since v0.8.2)
string action_desc       # Description
McActionStatus status    # Status of the motion mode (status.value: 0 (IDLE idle), 100 (RUNNING running), 200 (TRANSITION transitioning))

Motion Mode Set Service

Service Name

Data Type

Description

/aimdk_5Fmsgs/srv/SetMcAction

SetMcAction

Set motion mode

  • SetMcAction ros2-srv @ mc/action/srv/SetMcAction.srv

    # Set motion mode
# Service: /aimdk_5Fmsgs/srv/SetMcAction

# Request
RequestHeader header             # Request header
string source                    # Input source
McActionCommand command          # Motion command

---

# Response
CommonResponse response          # Generic response; response.status.value = 1 indicates success

    response.header.code is the action switch result code: 0 means success, non-0 means rejected; see the table below for the specific reason.

    code

    enum name

    meaning

    0

    None

    success

    2

    InvalidRequest

    invalid request (e.g. source is empty)

    3

    UnknownAction

    action not registered in config

    4

    InvalidPosture

    current posture does not allow this action

    5

    InRecovery

    system is in recovery mode

    6

    SecureLevelForbid

    Safety protection forbids state transition (e.g., fall detected)

    7

    Starting

    system is starting up; motion/stable actions not accepted

    8

    MovingBusy

    currently moving; cannot switch to non-stable actions

    9

    MotionBusy

    an action is currently playing

    10

    NoTransitionPath

    action exists but no reachable path from current state

    100

    PositionControlPrepare

    position-control preparing (MotionBusy sub-reason)

    101

    ForceControlPrepare

    force-control preparing (MotionBusy sub-reason)

    102

    Walking

    walking (MotionBusy sub-reason)

    103

    Offroad

    off-road (MotionBusy sub-reason)

    104

    VrTeleop

    VR teleoperation in progress (MotionBusy sub-reason)

    105

    LieUp

    lying-up recovery in progress (MotionBusy sub-reason)

    106

    ProneUp

    prone-up recovery in progress (MotionBusy sub-reason)

    107

    SitDown

    sitting down (MotionBusy sub-reason)

    108

    SitUp

    sitting up (MotionBusy sub-reason)

    109

    DataCollection

    data collection in progress (MotionBusy sub-reason)

    110

    WholeBodyTeleop

    whole-body teleoperation in progress (MotionBusy sub-reason)

    • McActionCommand ros2-msg @ mc/action/McActionCommand.msg

      # McActionCommand
McAction action      # Abandoned since v0.8.2
string action_desc   # Mode name, e.g. "STAND_DEFAULT"

Safety protection mechanism

Warning

Motion mode commands are not protected by input-source priority, but are constrained by the safety protection mechanism. When the robot detects an anomaly (e.g., a fall), it automatically enters safety protection and forbids state transitions; all motion mode requests are rejected with SecureLevelForbid. Safety protection is triggered automatically by the system and cannot be actively triggered or cleared via the SDK.

Cases where switching is allowed:

  • Switching to zero-torque or damping mode (PASSIVE_DEFAULT/DAMPING_DEFAULT): always allowed (the operator switching to a safe state is treated as a takeover signal; the system automatically clears safety protection)

  • Switching to position-controlled stand (JOINT_DEFAULT): allowed, but with posture constraints (e.g., cannot switch while seated)

  • Other modes: if the robot is under safety protection, all requests are rejected

Note: The safety protection mechanism and input-source priority are two independent mechanisms. Safety protection focuses on system safety, while priority focuses on control authority management.

Programming Examples

For detailed programming examples and code explanations, see:

Safety Notes

Warning

  • Do not use motion modes or mode descriptions that are not explicitly documented in this section.

  • Ensure the robot is in a safe state before switching motion modes.

  • Test motion-control code in a simulation environment first.

  • Do not deploy SDK applications on the Motion Control Computing Unit (PC1) to avoid interfering with high real-time motion tasks.

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

Note

Best Practices

  • Implement motion state monitoring and exception handling.

  • Implement additional safety checks around motion control where possible.