Chapter 0: Overview and Development Preparation

1 ROS2 Interface Positioning

The robot's "external standard interface" enables any ROS2 developer to quickly access robot capabilities.

Target users: ROS2 ecosystem developers, rapid prototyping/integration engineers, and external system integrators.

Typical scenarios: Quick teleoperation, SLAM/navigation integration, and upper-layer application development.

2 Document Scope and ROS Version

This document applies to the ROS2 secondary development of EngineAI PM01 series and T800 series humanoid robots, based on ROS2 Humble Version.

This document integrates the original ROS2 Protocol Specification and merges it with the content of various example documents, organized by interface characteristics into chapters. Developers can follow the chapter order to get started gradually, or jump to reference as needed.

3 Development Environment Setup

EngineAI ROS2 Interface provides a set of ROS2 messages. Benefiting from the ROS2 ecosystem, users only need a standard ROS2 development environment plus some configuration to call the robot services provided by EngineAI. ROS2 repository address: engineai_ros2_workspace.

Developers can set up the development environment in the following two ways.

3.1 Method 1: Use the Built-in Robot Development Environment (Recommended)

EngineAI has a built-in Web IDE on the robot's application compute unit. Users do not need to configure any environment; they only need to access the Web service to start running examples and developing.

Connect to the robot's built-in Wi-Fi (password e12345678), access the onboard Web IDE (address is usually http://192.168.0.162, see the robot's body label or product manual for details) to start using it.

3.2 Method 2: Set Up a PC Development Environment

System Environment Requirements:

Item	Requirement
Operating System	Ubuntu 22.04
ROS Version	ROS2 Humble
Compiler	GCC >= 11
Build Tool	CMake >= 3.22
Python	>= 3.10

Install Software Dependencies:

Bash

sudo apt update
sudo apt install rsync sshpass openssh-client libglfw3-dev libxinerama-dev libxcursor-dev
sudo apt install ros-dev-tools ros-humble-rmw-cyclonedds-cpp ros-humble-ros-base

ROS2 Communication Configuration:

The following environment variables must be configured correctly; otherwise communication with the robot will not work:

Bash

# ROS_DOMAIN_ID must match
export ROS_DOMAIN_ID=69
# Set up multi-machine communication
export ROS_LOCALHOST_ONLY=0
# Use rmw_cyclonedds_cpp
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp

You can write the configuration to ~/.bashrc with one command using the following script:

Bash

echo -e '\nexport ROS_DOMAIN_ID=69\nexport ROS_LOCALHOST_ONLY=0\nexport RMW_IMPLEMENTATION=rmw_cyclonedds_cpp' >> ~/.bashrc && source ~/.bashrc

3.3 Accessing the Robot

Clone the repository: Once the environment is ready, you can directly clone the ROS2 repository and enter the workspace:

Bash

git clone https://github.com/engineai-robotics/engineai_ros2_workspace.git
cd engineai_ros2_workspace

Hardware Connection: Connect to the robot via the network port on the back of the robot, then you can communicate with the robot through ROS2 multi-machine.

Gamepad remote control tip: The PM01 robot body has two USB slots. The gamepad's USB receiver must be plugged into the lower port to work properly for remote control; plugging into the upper port has no effect.

SSH Login Information: The robot has two built-in compute units, which users can access via SSH login:

Compute Unit	IP Address	Username	Password
Application Compute Unit	192.168.0.162	ubuntu	ubuntu
Motion Control Compute Unit	192.168.0.163	user	1

Pre-development Checklist:

ROS2 Humble environment is available, ros2 topic list can properly list system topics
engineai_ros2_workspace has been built, interface_protocol and interface_example packages can be found
The robot hardware interface node has been started (can be verified via ros2 topic echo /hardware/joint_state )

3.4 Build and Deployment

Install Third-party Dependencies: Before building nodes or the simulation environment, run the provided third-party dependency installation script first, otherwise some message packages/examples may lack dependencies.

Bash

# Run in the engineai_ros2_workspace root directory
./src/third_party/install.sh

Build workspace(from ROS2 repository):

Bash

# Build all nodes and examples on the host
./scripts/build_nodes.sh example

# Build the simulation environment
./scripts/build_nodes.sh sim

# Build on the robot side (install third-party deps → build → configure environment)
./src/third_party/install.sh
./scripts/build_nodes.sh
source install/setup.bash

Sync Code to the Robot Orin Mainboard:

Bash

./scripts/sync_src.sh orin

After syncing, log into the Orin mainboard via SSH, enter the workspace directory and build it; the usage is the same as on the host.

4 Message File Locations

All custom ROS2 message definitions are located in interface_protocol package. The directory structure is as follows:

PLAIN

src/interface_protocol/msg/(total 19 types, core 9 types as follows)
├── BodyVelCmd.msg
├── JointCommand.msg
├── JointMotionPlanRequest.msg
├── JointMotionPlanState.msg
├── JointOverrideCommand.msg
├── JointState.msg
├── LedControl.msg
├── MotionState.msg
└── MotionStateRequest.msg

Source links for the core message definitions (click a filename to view it on GitHub): BodyVelCmd.msg · JointCommand.msg · JointMotionPlanRequest.msg · JointMotionPlanState.msg · JointOverrideCommand.msg · JointState.msg · LedControl.msg · MotionState.msg · MotionStateRequest.msg

The remaining sensor / debug messages (Alert, GamepadKeys, Heartbeat, ImuInfo, MotorCommand, MotorDebug, MotorState, ParallelParserType, PowerInfo, Tts) complete definitions can be found at GitHub Message Directory. During development, you can import the required message types via from interface_protocol.msg import XxxMsg in your code.

5 General Conventions

The following conventions apply to all interfaces and are not repeated in individual chapters:

Convention	Description
Unit System	Angles uniformly use radians (rad), velocity uses m/s, angular velocity uses rad/s. Angle to radians:`rad = deg × π / 180`
Joint Index	Joints are numbered sequentially starting from 0; the number of joints can be viewed via `/hardware/joint_state`
Array Length	The length of all joint-related arrays must equal the robot's total number of joints (`num_total_joints`)
QoS Policy	Different interfaces use different QoS: joint command types are recommended to use Best Effort to reduce latency; state transition types must match the Reliable configuration, otherwise message reception fails
Control Frequency	Each interface has a recommended frequency; too low a frequency may cause discontinuous motion or unstable control
Motion Mode Prerequisite	Most interfaces need to be switched to a specified motion state first to take effect; see Chapter 1

6 Interface Overview

The table below summarizes all ROS2 interfaces' topic, message type, and direction for quick reference:

Interface Module	Topic	Message Type	Direction
Joint Command	`/hardware/joint_command`	`JointCommand.msg`	Client → Joint Controller
Joint State	`/hardware/joint_state`	`JointState.msg`	Joint Controller → Client
Motion State	`/motion/motion_state`	`MotionState.msg`	Motion Management Service → Client
Motion State Transition	`/motion/set_motion_state`	`MotionStateRequest.msg`	Client → Motion Management Service
LED Control	`/hardware/led_control`	`LedControl.msg`	Client → Lighting Control Service
Joint Motion Planning-Request	`/motion/joint_motion_plan/request`	`JointMotionPlanRequest.msg`	Client → Planner
Joint Motion Planning-State	`/motion/joint_motion_plan/state`	`JointMotionPlanState.msg`	Planner → Client
Joint Override Control	`/motion/joint_override_command`	`JointOverrideCommand.msg`	Client → Planner
Body Velocity Control	`/motion/body_vel_cmd`	`BodyVelCmd.msg`	Client → Walking Service
Gamepad Keys	`/hardware/gamepad_keys`	`GamepadKeys.msg`	Sensor → Client
IMU Data	`/hardware/imu_info`	`ImuInfo.msg`	Sensor → Client
Power/battery data	`/hardware/power_info`	`PowerInfo.msg`	Sensor → Client
Motor Debug Data	`/hardware/motor_debug`	`MotorDebug.msg`	Sensor → Client

7 QoS Configuration Reference

Different interfaces' QoS configuration requirements differ; a mismatched configuration will cause message reception to fail. The table below summarizes QoS requirements of each interface, with information from GitHub example scripts' QoSProfile definitions:

Topic	Publish/Subscribe	Reliability	Durability
`/motion/set_motion_state`	Publish	RELIABLE	VOLATILE
`/motion/motion_state`	Subscribe	BEST_EFFORT	VOLATILE
`/hardware/joint_command`	Publish	BEST_EFFORT	VOLATILE
`/hardware/joint_state`	Subscribe	BEST_EFFORT	VOLATILE

The publisher for motion state transition must use RELIABLE, while subscribing to motion state uses BEST_EFFORT. If QoS does not match, messages will not be received.

8 Model Specification Comparison

The table below compares the key specification differences among the three models, with information from the Feishu wiki pages "About PM01", "About T800 (Development Edition)", "About T800 (Pro Edition)":

Specification	PM01	T800 Development Edition	T800 Pro
Total DOF	24	25	43 (including dexterous hands)
Single-leg DOF	6	6	6
Waist DOF	1	1	1
Single-arm DOF	5	5	7 (including wrist)
Dexterous Hand	None	None	Yes (per hand 7 DOF)
Head DOF	1 (yaw)	2 (pitch + yaw)	2 (pitch + yaw)
Motion Planning Joint Index	[12~23]	[12~24]	[12,13,14,15,16,17,27,28,29,30,31,41,42]
Application Compute Unit	Jetson Orin NX (16G)	Jetson Orin NX	Jetson Orin NX
Motion Control Compute Unit	Nezha N97	Nezha N97	Nezha N97

9 Joint Index Reference Table

Joint indices start from 0 with the naming format J[number]_[part]_[action]_[side]. The indices used in control interfaces (e.g., joint_indices, YAML configs) are the J numbers in the joint names, i.e., the ROS joint indices. The "No." column in the tables below is the original document/hardware numbering, which may differ from the J number. Always use the J number from the joint name. The following is the PM01 complete joint index table, from the Feishu wiki "About PM01" page. The following are, in order, the PM01, T800 Development Edition, and T800 Pro complete joint index tables.

9.1 PM01 Joint Index (24 DOF)

No.	Joint Name	Part	Motor Model	Motion Lower Limit (rad)	Motion Upper Limit (rad)
0	J00_HIP_PITCH_L	Left Hip Pitch	Q90H	-3.141	2.443
1	J01_HIP_ROLL_L	Left Hip Roll	Q90H	-0.436	2.094
2	J02_HIP_YAW_L	Left Hip Yaw	Q25H-L	-1.57	4.014
3	J03_KNEE_PITCH_L	Left Knee Pitch	Q90H	-0.2618	2.3562
4	J04_ANKLE_PITCH_L	Left Ankle Pitch	Q25H	-0.6807	0.7243
5	J05_ANKLE_ROLL_L	Left Ankle Roll	Q25H	-0.2618	0.2618
6	J06_HIP_PITCH_R	Right Hip Pitch	Q90H	-3.141	2.443
7	J07_HIP_ROLL_R	Right Hip Roll	Q90H	-2.094	0.436
8	J08_HIP_YAW_R	Right Hip Yaw	Q25H-L	-4.014	1.57
9	J09_KNEE_PITCH_R	Right Knee Pitch	Q90H	-0.2618	2.3562
10	J10_ANKLE_PITCH_R	Right Ankle Pitch	Q25H	-0.6807	0.7243
11	J11_ANKLE_ROLL_R	Right Ankle Roll	Q25H	-0.2618	0.2618
12	J12_WAIST_YAW	Waist Yaw	Q25H-L	-4.014	1.57
13	J13_SHOULDER_PITCH_L	Left Shoulder Pitch	Q25H	-2.9671	2.7925
14	J14_SHOULDER_ROLL_L	Left Shoulder Roll	Q25H	-0.6108	2.3562
15	J15_SHOULDER_YAW_L	Left Shoulder Yaw	Q25H	-2.618	2.618
16	J16_ELBOW_PITCH_L	Left Elbow Pitch	Q25H	-2.1948	0.7374
17	J17_ELBOW_YAW_L	Left Elbow Yaw	Q25H	-2.618	2.618
18	J18_SHOULDER_PITCH_R	Right Shoulder Pitch	Q25H	-2.9671	2.7925
19	J19_SHOULDER_ROLL_R	Right Shoulder Roll	Q25H	-2.3562	0.6108
20	J20_SHOULDER_YAW_R	Right Shoulder Yaw	Q25H	-2.618	2.618
21	J21_ELBOW_PITCH_R	Right Elbow Pitch	Q25H	-2.1948	0.7374
22	J22_ELBOW_YAW_R	Right Elbow Yaw	Q25H	-2.618	2.618
23	J23_HEAD_YAW	Head Yaw	Q25H	-0.6109	0.6109

9.2 T800 Development Edition (25 DOF) Joint Index

No.	Part	Link Name	Joint Name	Motion Range (rad)
1	Left Hip Pitch	LINK_HIP_PITCH_L	J00_HIP_PITCH_L	-2.88 ~ 2.181
2	Left Hip Roll	LINK_HIP_ROLL_L	J01_HIP_ROLL_L	-0.2618 ~ 1.7444
3	Left Hip Yaw	LINK_HIP_YAW_L	J02_HIP_YAW_L	-1.4137 ~ 3.8921
4	Left Knee Pitch	LINK_KNEE_PITCH_L	J03_KNEE_PITCH_L	-0.261667 ~ 2.355
5	Left Ankle Pitch	LINK_ANKLE_PITCH_L	J04_ANKLE_PITCH_L	-0.68068 ~ 0.68068
6	Left Ankle Roll	LINK_ANKLE_ROLL_L	J05_ANKLE_ROLL_L	-0.3491 ~ 0.1745
7	Right Hip Pitch	LINK_HIP_PITCH_R	J06_HIP_PITCH_R	-2.879 ~ 2.181
8	Right Hip Roll	LINK_HIP_ROLL_R	J07_HIP_ROLL_R	-1.7444 ~ 0.2618
9	Right Hip Yaw	LINK_HIP_YAW_R	J08_HIP_YAW_R	-3.8921 ~ 1.4137
10	Right Knee Pitch	LINK_KNEE_PITCH_R	J09_KNEE_PITCH_R	-0.261667 ~ 2.355
11	Right Ankle Pitch	LINK_ANKLE_PITCH_R	J10_ANKLE_PITCH_R	-0.68068 ~ 0.68068
12	Right Ankle Roll	LINK_ANKLE_ROLL_R	J11_ANKLE_ROLL_R	-0.1745 ~ 0.3491
13	Waist Yaw	LINK_TORSO_YAW	J12_TORSO_YAW	-2.81 ~ 2.81
14	Left Shoulder Pitch	LINK_SHOULDER_PITCH_L	J13_SHOULDER_PITCH_L	-3.229 ~ 2.443
15	Left Shoulder Roll	LINK_SHOULDER_ROLL_L	J14_SHOULDER_ROLL_L	-0.436 ~ 2.487
16	Left Shoulder Yaw	LINK_SHOULDER_YAW_L	J15_SHOULDER_YAW_L	-2.618 ~ 2.618
17	Left Elbow Pitch	LINK_ELBOW_PITCH_L	J16_ELBOW_PITCH_L	-2.295 ~ 0.288
18	Left Elbow Yaw	LINK_ELBOW_YAW_L	J17_ELBOW_YAW_L	-2.618 ~ 2.618
19	Right Shoulder Pitch	LINK_SHOULDER_PITCH_R	J18_SHOULDER_PITCH_R	-3.229 ~ 2.443
20	Right Shoulder Roll	LINK_SHOULDER_ROLL_R	J19_SHOULDER_ROLL_R	-2.487 ~ 0.436
21	Right Shoulder Yaw	LINK_SHOULDER_YAW_R	J20_SHOULDER_YAW_R	-2.618 ~ 2.618
22	Right Elbow Pitch	LINK_ELBOW_PITCH_R	J21_ELBOW_PITCH_R	-2.295 ~ 0.288
23	Right Elbow Yaw	LINK_ELBOW_YAW_R	J22_ELBOW_YAW_R	-2.618 ~ 2.618
24	Head Pitch	LINK_HEAD_PITCH	J23_HEAD_PITCH	-0.523 ~ 0.523
25	Head Yaw	LINK_HEAD_YAW	J24_HEAD_YAW	-1.222 ~ 1.222

9.3 T800 Pro (43 DOF, including dexterous hands) Joint Index

No.	Part	Link Name	Joint Name	Motion Range (rad)
1	Left Hip Pitch	LINK_HIP_PITCH_L	J00_HIP_PITCH_L	-2.88 ~ 2.181
2	Left Hip Roll	LINK_HIP_ROLL_L	J01_HIP_ROLL_L	-0.2618 ~ 1.7444
3	Left Hip Yaw	LINK_HIP_YAW_L	J02_HIP_YAW_L	-1.4137 ~ 3.8921
4	Left Knee Pitch	LINK_KNEE_PITCH_L	J03_KNEE_PITCH_L	-0.261667 ~ 2.355
5	Left Ankle Pitch	LINK_ANKLE_PITCH_L	J04_ANKLE_PITCH_L	-0.68068 ~ 0.68068
6	Left Ankle Roll	LINK_ANKLE_ROLL_L	J05_ANKLE_ROLL_L	-0.3491 ~ 0.1745
7	Right Hip Pitch	LINK_HIP_PITCH_R	J06_HIP_PITCH_R	-2.879 ~ 2.181
8	Right Hip Roll	LINK_HIP_ROLL_R	J07_HIP_ROLL_R	-1.7444 ~ 0.2618
9	Right Hip Yaw	LINK_HIP_YAW_R	J08_HIP_YAW_R	-3.8921 ~ 1.4137
10	Right Knee Pitch	LINK_KNEE_PITCH_R	J09_KNEE_PITCH_R	-0.261667 ~ 2.355
11	Right Ankle Pitch	LINK_ANKLE_PITCH_R	J10_ANKLE_PITCH_R	-0.68068 ~ 0.68068
12	Right Ankle Roll	LINK_ANKLE_ROLL_R	J11_ANKLE_ROLL_R	-0.1745 ~ 0.3491
23	Waist Yaw	LINK_TORSO_YAW	J12_TORSO_YAW	-2.81 ~ 2.81
26	Left Shoulder Pitch	LINK_SHOULDER_PITCH_L	J13_SHOULDER_PITCH_L	-3.229 ~ 2.443
27	Left Shoulder Roll	LINK_SHOULDER_ROLL_L	J14_SHOULDER_ROLL_L	-0.436 ~ 2.487
28	Left Shoulder Yaw	LINK_SHOULDER_YAW_L	J15_SHOULDER_YAW_L	-2.618 ~ 2.618
29	Left Elbow Pitch	LINK_ELBOW_PITCH_L	J16_ELBOW_PITCH_L	-2.295 ~ 0.288
30	Left Elbow Yaw	LINK_ELBOW_YAW_L	J17_ELBOW_YAW_L	-2.618 ~ 2.618
31	Left Wrist Pitch	LINK_WRIST_PITCH_L	J18_WRIST_PITCH_L	-0.436 ~ 0.436
32	Left Wrist Roll	LINK_WRIST_ROLL_L	J19_WRIST_ROLL_L	-1.047 ~ 0.611
34	Left Hand Thumb Base Joint	LINK_THUMB_BASE_L	J20_THUMB_BASE_L	-2.007 ~ 0
35	Left Hand Thumb Middle Segment	LINK_THUMB_MID_L	J21_THUMB_MID_L	0 ~ 1.5708
36	Left Hand Thumb Tip	LINK_THUMB_TIP_L	J22_THUMB_TIP_L	0 ~ 1.5708
37	Left Hand Index Base Joint	LINK_INDEX_BASE_L	J23_INDEX_BASE_L	-1.6929 ~ 0
38	Left Hand Index Tip	LINK_INDEX_TIP_L	J24_INDEX_TIP_L	-1.85 ~ 0
39	Left Hand Middle Base Joint	LINK_MIDDLE_BASE_L	J25_MIDDLE_BASE_L	-1.6929 ~ 0
40	Left Hand Middle Tip	LINK_MIDDLE_TIP_L	J26_MIDDLE_TIP_L	-1.85 ~ 0
41	Right Shoulder Pitch	LINK_SHOULDER_PITCH_R	J27_SHOULDER_PITCH_R	-3.229 ~ 2.443
42	Right Shoulder Roll	LINK_SHOULDER_ROLL_R	J28_SHOULDER_ROLL_R	-2.487 ~ 0.436
43	Right Shoulder Yaw	LINK_SHOULDER_YAW_R	J29_SHOULDER_YAW_R	-2.618 ~ 2.618
44	Right Elbow Pitch	LINK_ELBOW_PITCH_R	J30_ELBOW_PITCH_R	-2.295 ~ 0.288
45	Right Elbow Yaw	LINK_ELBOW_YAW_R	J31_ELBOW_YAW_R	-2.618 ~ 2.618
46	Right Wrist Pitch	LINK_WRIST_PITCH_R	J32_WRIST_PITCH_R	-0.436 ~ 0.436
47	Right Wrist Roll	LINK_WRIST_ROLL_R	J33_WRIST_ROLL_R	-0.611 ~ 1.047
49	Right Hand Thumb Base Joint	LINK_THUMB_BASE_R	J34_THUMB_BASE_R	0 ~ 2.007
50	Right Hand Thumb Middle Segment	LINK_THUMB_MID_R	J35_THUMB_MID_R	0 ~ 1.5708
51	Right Hand Thumb Tip	LINK_THUMB_TIP_R	J36_THUMB_TIP_R	0 ~ 1.5708
52	Right Hand Index Base Joint	LINK_INDEX_BASE_R	J37_INDEX_BASE_R	0 ~ 1.6929
53	Right Hand Index Tip	LINK_INDEX_TIP_R	J38_INDEX_TIP_R	0 ~ 1.85
54	Right Hand Middle Base Joint	LINK_MIDDLE_BASE_R	J39_MIDDLE_BASE_R	0 ~ 1.6929
55	Right Hand Middle Tip	LINK_MIDDLE_TIP_R	J40_MIDDLE_TIP_R	0 ~ 1.85
56	Head Pitch	LINK_HEAD_PITCH	J41_HEAD_PITCH	-0.523 ~ 0.523
58	Head Yaw	LINK_HEAD_YAW	J42_HEAD_YAW	-1.222 ~ 1.222