5.1.2 Locomotion Control

The locomotion control interfaces provide the core functions for controlling the robot’s walking and running velocities.

Control Functions

• Supports locomotion control based on lateral velocity, forward velocity, and yaw rate (angular velocity around the vertical axis).

• Supports dynamic management and priority arbitration of multiple control input sources.

Attention

The locomotion control interface is an open-loop, velocity-level control. Developers send target-velocity commands, which the motion-control module converts into joint motion.

• Limited command-tracking accuracy: the commanded forward_velocity/lateral_velocity/angular_velocity are target values. The robot’s actual linear/angular velocity deviates from them and cannot be tracked precisely; the deviation is affected by gait, terrain, payload, and other factors.

• No trajectory or endpoint accuracy: this interface cannot precisely control the robot’s motion trajectory or the point it reaches.

For high-precision positioning (e.g. reaching an exact point), use the navigation interface.

Locomotion Control Topic

Topic Name	Data Type	Description	QoS	Frequency
/aima/mc/locomotion/velocity	McLocomotionVelocity	Locomotion control (switch to Stable Stand first)	BEST_EFFORT+VOLATILE	User (recommended 50 Hz)

• McLocomotionVelocity ros2-msg @ mc/motion/msg/McLocomotionVelocity.msg

  # Locomotion control
  # Topic: /aima/mc/locomotion/velocity
  
  MessageHeader header             # Message header
  string source                    # Input source name, custom for secondary development. Do not reuse names used by other modules; see notes below.
  float64 forward_velocity         # Forward/backward velocity (m/s), forward is positive
  float64 lateral_velocity         # Lateral velocity (m/s), left is positive
  float64 angular_velocity         # Yaw rate (rad/s), counterclockwise is positive
  

  Note that here the developer is the publisher of locomotion control messages, which may conflict with locomotion commands from other native system modules (such as the remote controller).

  While the remote controller is in use, its priority is higher than most secondary-development input sources, and SDK locomotion commands will be dropped by the motion-control arbitration mechanism. After the remote controller stops operating, its input source must time out (see Input Source Arbitration) before SDK commands can regain control. Query the currently active input source via GetCurrentInputSource.

  The motion control system provides a multi-input management mechanism that arbitrates conflicting commands in real time based on priority.

  Developers must register a custom input source and use it in the source field of locomotion commands.

  For details, see the next section MC Control Signal Configuration.

Speed Mode and Speed Bounds

Velocity commands sent by the user are limited by the speed bounds corresponding to the current speed mode (SpeedMode). The speed mode can be switched by the mobile app via the SetMcLocomotionSpeedMode service, or automatically by the system.

Typical bounds for each speed mode are shown in the table below (subject to the actual robot):

Speed mode	Value	forward bounds (m/s)	lateral bounds (m/s)	angular bounds (rad/s)
NONE (none)	0	0 ~ 0	0 ~ 0	0 ~ 0
LOW (low speed, default)	1	-1.0 ~ +0.8	-1.0 ~ +1.0	-1.0 ~ +1.0
MEDIUM (medium speed)	2	-1.0 ~ +1.2	-1.0 ~ +1.0	-1.0 ~ +1.0
HIGH (high speed)	3	-1.0 ~ +1.8	-1.0 ~ +1.0	-1.0 ~ +1.0
STEP (off-road)	4	-2.0 ~ +2.0	-1.0 ~ +1.0	-1.0 ~ +1.0

Attention

The off-road mode (STEP, value 4) cannot be switched directly via the SetMcLocomotionSpeedMode service. The off-road speed mode is auto-selected only when entering off-road mode (LOCOMOTION_STEP), and the previous speed mode is automatically restored after exiting off-road mode. During off-road mode, any manual speed mode switch request is rejected.

The speed mode can be auto-switched in the following scenarios:

• Safety protection triggered: automatically switches to low speed when the robot detects an anomaly (e.g. falling), and restores the original mode on recovery

• Off-road mode: automatically switches to the off-road speed mode (STEP) when entering off-road mode (LOCOMOTION_STEP), and restores on exit

• Linkswarm swarm control (linkswarm input source): automatically switches to high speed when the linkswarm input source is enabled, and restores on exit

Warning

Do not add, modify, delete, enable, or disable any built-in input source (especially linkswarm, which is Linkswarm-dedicated), nor use a built-in input source in the input source field of control messages. Directly operating or using built-in input sources may cause control conflicts, robot loss of control, and other unpredictable behavior. Users bear all consequences. See Input Source Configuration.

The current speed mode and bounds can be queried by subscribing to the speed_status field of the /aima/mc/common/state topic. See Motion Control Status Query.

Command timeout mechanism:

• If no new locomotion command is received within 200 ms, the command is automatically zeroed (velocity resets to zero) and the robot stops moving.

• While walking/running, if no locomotion command is received within 2000 ms, the robot automatically switches back to stable standing mode.

Locomotion start threshold constraints:

When the robot is stationary, the first step requires the commanded target velocity to exceed a certain threshold. After the robot is already moving, smaller target velocities can be used. The target velocity is composed from forward_velocity, lateral_velocity, and angular_velocity. Reference threshold values for using a single control component are given in the table below.

Target velocity type	Start threshold (approximate range)	Notes
forward_velocity	~0.1 m/s order of magnitude	Absolute value; forward/backward
lateral_velocity	~0.5-0.7 m/s order of magnitude	Absolute value; left/right both valid
angular_velocity	~0.03-0.05 rad/s order of magnitude	Absolute value; clockwise/counterclockwise both valid

Important

Startup thresholds and other characteristics are determined by the base model and may vary across firmware versions; always refer to real device testing. The values in the table are approximate references only; all threshold values are learned internally by the base model and are not constants.

Programming Examples

For detailed programming examples and code explanations, refer to:

• C++ Examples:

  • Robot Locomotion Control

  • Register Secondary Development Input Source

  • Keyboard Robot Control

• Python Examples:

  • Robot Locomotion Control

  • Register Secondary Development Input Source

  • Keyboard Robot Control

Safety Notes

Warning

Motion Control Constraints

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

• An input source must be registered before performing locomotion control.

• Test locomotion control code in a simulation environment first.

Note

Best Practices

• Implement motion state monitoring and exception handling.

• Implement safety checks around locomotion control.

• Ensure velocity commands are smooth and continuous.