Motion Control and Status Interface

TCP Motion Control

Send motion control commands to the navigation host (192.168.1.106:30000) via the TCP body monitoring protocol.

Type Field Value	Message Type
2	Motion control

Command Field Value	Message Command
1	Move forward
2	Move backward
3	Turn left
4	Turn right
6	Zero velocity
11	Strafe left
12	Strafe right
13	Soft emergency stop
14	Stop motion
15	Lie down
16	Stand up
18	Start motion
20	Switch gait

Note: When controlling robot motion using this protocol, the robot will automatically switch to the required mode (navigation mode). Some commands support step-skipping: for example, when the robot is in the lying down state, sending a start motion command will cause the robot to automatically stand up and start moving.

Request

<?xml version="1.0" encoding="UTF-8"?>
<PatrolDevice>
  <Type>2</Type>
  <Command>1</Command>
  <Time>2023-01-01 00:00:00</Time>
  <Items>
    <Value>-1</Value>
  </Items>
</PatrolDevice>

Parameter	Precondition	Meaning	Value Description
Value	Command=1	Set forward velocity (m/s)	{-1}∪[0,1.50], default 0.50 when -1
	Command=2	Set backward velocity (m/s)	{-1}∪[0,1.30], default 0.50 when -1
	Command=3	Set left turn angular velocity (rad/s)	{-1}[0,0.45], default 0.35 when -1
	Command=4	Set right turn angular velocity (rad/s)	{-1}∪[0,0.45], default 0.35 when -1
	Command=11	Set left strafe velocity (m/s)	{-1}∪[0,0.15], default 0.10 when -1
	Command=12	Set right strafe velocity (m/s)	{-1}∪[0,0.15], default 0.10 when -1
	Command=20	Switch gait	Walking gait=0, Normal stair gait=1, Slope/anti-slip gait=2, Perception stair gait=4, L-walking gait=100, Mountain gait=101, L-stair gait=102

Note: Axis commands (Command=1, 2, 3, 4, 6, 11, 12) and gait switch commands (Command=20) are only supported when the robot is in stepping state or RL state. The request message frequency for controlling translation or rotation is 3Hz~5Hz.

Basic State Transitions

Robot basic states are switched via UDP commands, with the target address 192.168.1.103:43893.

The following diagram shows the robot basic state transition diagram. Dashed arrows indicate that in any basic state, the robot may transition to the soft emergency stop/fall state due to an unexpected accident.

Command Name	Command Code	Command Function
Stand up / Lie down	0x21010202	Toggle between lying down and initial standing state
Force control mode	0x2101020A	Switch from initial standing to force-controlled standing
Start motion / Stop motion	0x21010201	Toggle between force-controlled standing and stepping state
Soft emergency stop	0x21010C0E	Immediately lie down, enter joint protection state

Basic motion state values (obtained via RcsData or ROS topic /robot_basic_state):

State Value	Status
0	Lying down
1	Standing up
2	Initial standing
3	Force-controlled standing
4	Stepping
5	Lying down
6	Soft emergency stop / Fall
16	RL state

Note: Sending state switch commands cannot override the original control logic. For example, when the robot is in the lying down state, sending a start motion command will not take effect. The control logic follows the robot’s own motion logic.

Control Mode

The control mode determines the source of velocity commands the robot responds to:

Command Name	Command Code	Command Function
Manual mode	0x21010C02	Robot responds to joystick velocity commands (joystick axis commands)
Non-manual mode	0x21010C03	Distinguish between assist mode and navigation mode based on height map velocity input source

Get the current control mode via ROS topic /control_mode: 0 = Manual mode, 1 = Non-manual mode.

Gait

The robot can switch gaits while in stepping state to adapt to different terrains.

Gait	Command Code
Walking gait	0x21010300
Slope gait	0x21010402
Obstacle-clearing gait	0x21010401
Stair gait (solid ground / hollow ground / stairs without risers mode)	0x21010405
Stair gait (accumulated frame mode)	0x2101040A
45° stair gait (accumulated frame mode)	0x2101040B
L-walking gait	0x21010420
Mountain gait	0x21010421
Silent gait	0x21010422
L-stair gait	0x21010424

Get the current gait value via ROS topic /robot_gait_state.

Note: Each stair gait can only be used in its corresponding height map mode. When the robot body height is at crawl height, only walking gait and slope gait are supported. When using L-walking, mountain, silent, or L-stair gait, changing the robot body height and height map mode is not supported.

Velocity Commands

Axis commands are the X-axis and Y-axis outputs from the left and right joysticks, with a value range of $[-32767, 32767]$. The axis command frequency is 50Hz.

Axis Commands in Force-Controlled Standing State

In force-controlled standing state, sending axis commands to the motion host can control the robot to change body posture. If the command times out, the robot will return to normal standing posture.

Command Name	Command Code	Command Type	Command Function
Left joystick X-axis	0x21010131	0	Adjust Roll angle; positive raises left shoulder, negative raises right shoulder
Left joystick Y-axis	0x21010130	0	Adjust body height; positive raises body, negative lowers body
Right joystick X-axis	0x21010135	0	Adjust Yaw angle; positive turns head right, negative turns head left
Right joystick Y-axis	0x21010102	0	Adjust Pitch angle; positive tilts head up, negative tilts head down

Axis Commands in Stepping State

When the robot is in stepping state, axis commands can adjust its speed and direction. After receiving axis commands, the robot maps them from the joystick frame to the robot body frame.

If the command times out, the robot will stop moving. The function of each axis command is defined as follows:

Left Joystick Y-Axis Command

Command Code	Command Type	Command Function
0x21010130	0	Specify desired linear velocity on the robot X-axis; positive for forward translation, negative for backward translation

The relationship between desired linear velocity on the body frame X-axis and left joystick Y-axis value:

$$v_{x} = \begin{cases} 0, & -655 < y < 655 \\ \frac{y}{32767} \times v_{\max}, & 655 \leq |y| \leq 32767 \end{cases}$$

Where $v_{x}$ is the desired linear velocity on the body frame X-axis, $v_{max}$ is the maximum velocity under the current gait limit, and $y$ is the left joystick Y-axis command value.

Left Joystick X-Axis Command

Command Code	Command Type	Command Function
0x21010131	0	Specify desired linear velocity on the robot Y-axis; positive for right strafe, negative for left strafe

The relationship between desired linear velocity on the body frame Y-axis and left joystick X-axis value:

$$v_{y} = \begin{cases} 0, & -655 < x < 655 \\ (-1) \times \frac{x}{32767} \times v_{\max}, & 655 \leq |x| \leq 32767 \end{cases}$$

Right Joystick X-Axis Command

Command Code	Command Type	Command Function
0x21010135	0	Specify desired angular velocity for robot Yaw; positive for right turn, negative for left turn

The relationship between desired yaw angular velocity and right joystick X-axis value:

$$\omega = \begin{cases} 0, & -655 < x < 655 \\ (-1) \times \frac{x}{32767} \times \omega_{\max}, & 655 \leq |x| \leq 32767 \end{cases}$$

Where $\omega$ is the desired Yaw angular velocity, $\omega_{max}$ is the maximum turning speed under the current gait limit, and $x$ is the right joystick X-axis command value.

Maximum Velocity Limits per Gait (Normal Body Height)

Gait (Normal Height)	Max Forward Speed	Max Backward Speed	Max Lateral Speed	Max Turning Speed
Walking gait	1.5 m/s	0.75 m/s	0.15 m/s	0.45 rad/s
Slope gait	0.7 m/s	0.75 m/s	0.25 m/s	0.5 rad/s
Obstacle-clearing gait	0.3 m/s	0.4 m/s	0.1 m/s	0.5 rad/s
Stair gait (solid ground mode)	0.3 m/s	0.3 m/s	0.2 m/s	0.8 rad/s
Stair gait (hollow ground mode)	0.3 m/s	0.3 m/s	0.2 m/s	0.8 rad/s
Stair gait (stairs without risers mode)	0.3 m/s	0.3 m/s	0.2 m/s	0.8 rad/s
Stair gait (accumulated frame mode)	0.6 m/s	0.3 m/s	0.2 m/s	0.8 rad/s
45° stair gait (accumulated frame mode)	0.3 m/s	0.2 m/s	0.2 m/s	0.8 rad/s
L-walking gait	1.5 m/s	1.0 m/s	0.5 m/s	1.2 rad/s
Mountain gait	1.5 m/s	1.0 m/s	0.5 m/s	1.2 rad/s
L-stair gait	0.6 m/s	0.3 m/s	0.2 m/s	0.5 rad/s

Velocity Command Topics

The perception host contains three velocity-related topics:

Topic Name	Description	Message Type
/handle_state	Joystick velocity commands	geometry_msgs/Twist
/cmd_vel	Navigation module planned velocity	geometry_msgs/Twist
/cmd_vel_corrected	Corrected velocity from height map	geometry_msgs/Twist

In assist mode or navigation mode, the motion program executes the velocity commands published in /cmd_vel_corrected. When there are no raw velocity commands from the joystick or navigation module, developers can also directly publish messages on the /cmd_vel_corrected topic to have the motion program execute velocity commands without height map collision detection processing.

Runtime Status Information Interface

The motion host reports status information and joint information via UDP to the communication addresses listed in network.toml. Users can add their own communication addresses as described in the application manual “Communication Parameter Configuration”.

Command Code	Command Type	Data Content	Send Frequency
0x1008	1	RcsData struct	200Hz

struct RcsData{
  char robot_name[15];
  int32_t current_mileage;//Unit : cm
  int32_t total_mileage;//Unit : cm
  long current_run_time;//Unit : s
  long total_run_time;//Unit : s
  long current_motion_time;//Unit : s
  long total_motion_time;//Unit : s
  float joystick[4];
  union {
    struct {
      uint8_t is_nav_mode;
      uint8_t emergency_source;
      uint8_t mode_reserved[8];
    }rcs_state_list;
    uint8_t rcs_state[10];
  };
  union{
    struct{
      uint32_t imu_error : 1;
      uint32_t wifi_error : 1;
      uint32_t driver_heat_warn : 1;
      uint32_t driver_error: 1;
      uint32_t motor_heat_warn : 1;
      uint32_t battery_low_warn : 1;
      uint32_t battery_heat_warn : 1;
      uint32_t gpio_error : 1;
      uint32_t cpu_heat_warn : 1;
      uint32_t cpu_freq_warn : 1;
      uint32_t reserved : 22;
    }error_state_bit;
    uint32_t error_state;
  };
};

Field	Type	Meaning
robot_name	char[15]	Robot name
current_mileage	int32_t	Distance since last boot (cm)
total_mileage	int32_t	Cumulative distance (cm)
current_run_time	long	Runtime since last boot (s)
total_run_time	long	Cumulative runtime (s)
current_motion_time	long	Motion time since last boot (s)
total_motion_time	long	Cumulative motion time (s)
joystick	float[4]	Axis values scaled to [-1.0,1.0]
rcs_state	uint8_t[10]	Status feedback
error_state	uint32_t	Error status

Parameters in the joystick field:

Parameter	Type	Range	Meaning
LX	float	[-1.0,1.0]	Left joystick X-axis value
LY	float	[-1.0,1.0]	Left joystick Y-axis value
RX	float	[-1.0,1.0]	Right joystick X-axis value
RY	float	[-1.0,1.0]	Right joystick Y-axis value

Parameters in the rcs_state field:

Parameter	Type	Value Meaning
is_nav_mode	uint8_t	0=Manual mode, 1=Non-manual mode
emergency_source	uint8_t	1=Rear soft emergency stop triggered, 2=Auto-triggered during motion, 3=Auto-triggered during navigation, 4=Auto-triggered during autonomous charging, 5=Client-triggered soft emergency stop, 6=RAS auto-triggered soft emergency stop

Each bit of error_state corresponds to a parameter, from LSB to MSB:

Parameter	Type	Value Meaning
imu_error	bool	0=Normal, 1=IMU update timeout
wifi_error	bool	0=Normal, 1=Heartbeat update timeout
driver_heat_warn	bool	0=Normal, 1=Driver over-temperature
driver_error	bool	0=Normal, 1=Driver fault
motor_heat_warn	bool	0=Normal, 1=Motor over-temperature
battery_low_warn	bool	0=Normal, 1=Low battery
battery_heat_warn	bool	0=Normal, 1=Battery over-temperature
gpio_error	bool	0=Normal, 1=GPIO fault
cpu_heat_warn	bool	0=Normal, 1=CPU over-temperature
cpu_freq_warn	bool	0=Normal, 1=CPU frequency too low

Motion Status Information Interface

Command Code	Command Type	Data Content	Send Frequency
0x1009	1	MotionStateData struct	200Hz

struct MotionStateData{
  uint8_t basic_state;
  uint8_t gait_state;
  float max_forward_vel;
  float max_backward_vel;
  float leg_odom_pos[3];
  float leg_odom_vel[3];
  float robot_distance;
  unsigned touch_state;
  union {
    struct{
      uint32_t narrow_walk : 1;
      uint32_t pose_safe_flag : 1;
      uint32_t joint_limit_flag: 1;
      uint32_t state_reserved : 29;
    }control_state_bit;
    uint32_t control_state;
  };
  union{
    struct{
      uint8_t auto_charge_state;
      uint8_t pos_ctrl_state;
      uint8_t task_reserved[8];
    }task_state_list;
    uint8_t task_state[10];
  };
};

Field	Type	Meaning
basic_state	uint8_t	Robot basic state
gait_state	uint8_t	Gait information
leg_odom_pos	float[3]	Robot pose in world frame {x, y, yaw}
leg_odom_vel	float[3]	Robot velocity in body frame {x_vel, y_vel, yaw_vel}
robot_distance	float	Distance since last boot (cm)
task_state	uint8_t[10]	Task status

basic_state values:

Value	Robot Basic State
0	Lying down
1	Standing up
2	Initial standing
3	Force-controlled standing
4	Stepping
5	Lying down
6	Soft emergency stop / Fall
16	RL state

gait_state values:

Value	Gait
0	Walking gait
1	Obstacle-clearing gait
2	Slope gait
3	Running gait
6	Stair gait (solid ground / hollow ground / stairs without risers mode)
7	Stair gait (accumulated frame mode)
8	45° stair gait (accumulated frame mode)
32	L-walking gait
33	Mountain gait
34	Silent gait
36	L-stair gait

Note: The origin of the world frame is the robot’s position at the time of this boot, and its axis orientation is consistent with the robot body frame orientation at boot time.

Real-Time Basic Status Interface

Send a request to the navigation host (192.168.1.106:30000) via the TCP body monitoring protocol to get the robot’s current basic status information.

Type Field Value	Message Type	Command Field Value	Message Command
1002	Get real-time basic status	1	Default

Request

<?xml version="1.0" encoding="UTF-8"?>
<PatrolDevice>
  <Type>1002</Type>
  <Command>1</Command>
  <Time>2023-01-01 00:00:00</Time>
  <Items/>
</PatrolDevice>

Response

<?xml version="1.0" encoding="UTF-8"?>
<PatrolDevice>
  <Type>1002</Type>
  <Command>1</Command>
  <Time>2023-01-01 00:00:01</Time>
  <Items>
    <MotionState>0</MotionState>
    <PosX>0.0</PosX><PosY>0.0</PosY><PosZ>0.0</PosZ>
    <Roll>0.0</Roll><Pitch>0.0</Pitch><Yaw>0.0</Yaw>
    <Speed>0.0</Speed>
    <CurOdom>0.0</CurOdom><SumOdom>0.0</SumOdom>
    <Res>0.0</Res><X0>0.0</X0><Y0>0.0</Y0><H>1000</H>
    <Electricity>50</Electricity>
    <Location>0</Location>
    <GaitState>0</GaitState>
    <MotorState>0</MotorState>
    <ChargeState>0</ChargeState>
    <ControlMode>0</ControlMode>
    <OnDockState>0</OnDockState>
  </Items>
</PatrolDevice>

Parameters in the Items field of the response:

Parameter	Meaning	Data Type	Unit	Value Description
MotionState	Robot motion state	int	/	Lying down=0, Standing up=1, Initial standing=2, Force-controlled standing=3, Stepping=4, Lying down=5, Soft emergency stop=6, Fall=7, RL=16
PosX/PosY/PosZ	Robot coordinates in map frame	float	m
Roll/Pitch/Yaw	Robot orientation in map frame	float	rad
Speed	Robot forward moving speed	float	m/s
CurOdom	Odometer since last boot	float	km
SumOdom	Cumulative odometer	float	km
Res	Physical length of map image pixels	float	m
X0	X-axis coordinate of map image lower-left corner in map frame	float	m
Y0	Y-axis coordinate of map image lower-left corner in map frame	float	m
H	Number of pixels in map image height	int	/
Electricity	Robot battery level	int	/	[0,100]
Location	Robot localization status	int	/	Normal=0, Lost=1
GaitState	Robot gait	int	/	Walking=0, Obstacle-clearing=1, Slope/anti-slip=2, Perception stair=6, Accumulated frame stair=7, Accumulated frame 45° stair=8, L-walking=32, Mountain=33, Silent=34, L-stair=36
MotorState	Robot motor status	int	/	Normal=0, Over-temperature=1
ChargeState	Robot autonomous charging status	int	/	Not charging=0, Charging=1
ControlMode	Robot control mode	int	/	Manual=0, Auto=1
OnDockState	Robot lying on charging dock	int	/	Not on dock=0, On dock=1

Note: When all parameter values in Items are 0, it indicates that getting the robot’s real-time basic status failed or the localization/navigation program has not started.