2. Development Environment and Quick Start

1 Container Environment

Install Docker and Docker Compose

Docker provides an auto-configuration and installation script that supports installation on Debian, RHEL, SUSE series, and derivative systems.
- Note that Docker officially does not recommend using this script to install Docker CE in production environments.

Bash

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Chinese users can use a mirror source (here Tsinghua source is used)
export DOWNLOAD_URL="https://mirrors.tuna.tsinghua.edu.cn/docker-ce"
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

Set up passwordless sudo execution (recommended) Otherwise you would have to use sudo docker every time and then re-login to the shell
Bash
sudo usermod -aG docker $USER
Bash
newgrp docker

Verify installation

Verify docker

Bash

docker --version

PLAIN

Docker version 26.1.1

Verify docker compose

Bash

docker compose version

PLAIN

Docker Compose version v2.27.0

Generate the container development environment; after execution, a shortcut entry engineai_robotics_env is generated

Bash

cd native_sdk
./docker/generate.sh

$test\.jpg$

Success Page

This command automatically creates a container and maps the current repository path into the container, so you can build and run the program inside the container.

Launch a new terminal and enter the development environment via the shortcut command engineai_robotics_env

$test\.jpg$

2 Build

Bash

# Enter container
engineai_robotics_env
./build.sh

3 Run

Bash

# Enter container
engineai_robotics_env
./run.sh

$test\.jpg$

Run for a specific robot model:

Bash

./run.sh pm01_edu

Clean up the container environment

If you need to clean up the container environment, you can run

PLAIN

#in host
engineai_robotics_env clean

4 Motion State Transition

4.1 Input Methods

The Native SDK currently supports two control input methods for triggering robot state transitions:

4.1.1 1) Physical Gamepad (Logitech F710)

Use Logitech Wireless Gamepad F710 (Xbox mode)
The system automatically recognizes it after plugging in the USB receiver
All state transitions are triggered via gamepad buttons

4.1.2 2) Virtual Gamepad (Virtual Gamepad UI)

Provides a graphical virtual gamepad interface
Supports simulating gamepad input via keyboard keys and sliders
Uses a consistent control mapping relationship with the F710 (XBox mode), and the control logic is fully compatible

$test\.jpg$

Launch method

Enter the virtual gamepad tool directory and run the startup script:

PLAIN

# Enter container
engineai_robotics_env
python3 tools/virtual_gamepad/virtual_gamepad.py

Connection and enablement

The virtual gamepad requires LCM connection and manual enablement before use:

Launch Virtual Gamepad UI
Connect LCM communication (ensure normal communication with the robot control process)
Check Enable or press F5 to start virtual gamepad input
Notes
- After enabling the virtual gamepad:
- The system takes over the input source
- Physical Logitech F710 gamepad input will be blocked
- To switch back to the physical gamepad:
- Close the virtual gamepad or cancel the Enable state

4.1.3 3) Control Mapping (F710 ↔ Virtual Gamepad)

Function	F710 Button	Virtual Gamepad UI (Mouse Operation)	Keyboard
Left Stick	Left Stick	L (Arrow)	↑ ↓ ← →
Right Stick	Right Stick	R (Shift+Arrow)	Shift + ↑ ↓ ← →
LT	LT	LT Slider	Mouse Drag
RT	RT	RT Slider	Mouse Drag
LB	LB	LB(q)	Q
RB	RB	RB(e)	E
A	A	A(j)	J
B	B	B(k)	K
X	X	X(u)	U
Y	Y	Y(i)	I
BACK	BACK	BACK(F1)	F1
START	START	START(F2)	F2

4.2 State Transition Reference

After the program starts, the robot switches between different motion states according to gamepad commands. The Native SDK uses a Finite State Machine (FSM) mechanism to manage motion states:

Each state defines explicit entry conditions and allowed state transition paths; switching is only permitted when conditions are met, to ensure the safety and stability of motion control
State transitions are uniformly scheduled by the state machine, avoiding illegal or unreasonable state jumps
State machine configuration:assets/config/<robot>/task_motion/default.yaml

The state transition relationships are as follows:

$image\.png$

System startup
- After executing ./run.sh (for simulation) or ./run_robot.sh (for real robot), the system enters the idle state by default
- idle is the initial safe state after the robot is powered on; the controller does not activate active motion control
State switching overview

Current State	Allowed Transition To	Trigger Key	Description
idle	passive	LB + RB	Transition from inactive state to damped state
passive	idle	LB + START	Return to inactive state
	pd_stand	LB + A	Enter stable standing control task
pd_stand	walk	LB + B	After establishing stable standing, enter walking task
	dance	LB + CROSS_X_DOWN	After establishing stable standing, enter dancing task
walk	pd_stand	LB + A	Return from walking task to stable standing control task
	dance	LB + CROSS_X_DOWN	Switch from walking task to dancing task
dance	pd_stand	LB + A	Return from dancing task to stable standing control task
	walk	LB + B	Switch from dancing task to walking task

Global safety mechanism (Emergency Fallback)
- In any running state, the LB + RB combination command can be used to force a switch to the passive safe state
- This mechanism is equivalent to a soft emergency stop:
  - Immediately terminates the current motion control logic
  - Switches the system to a controlled safe state (no active motion output)
- This mechanism serves as a key safeguard during debugging and actual operation, reducing the risk of loss of motion control
Suggestions for integrating a new Runner
- A newly added motion control module (runner) is recommended to be entered only after pd_stand
- Reason:
  - pd_stand provides a stable standing foundation
  - Ensures stable posture and normal contact state
  - Avoids the safety risks of entering dynamic motion directly while passive or not yet stably standing

5 Mujoco Simulation

5.1 Build

Bash

# Enter container
engineai_robotics_env
./scripts/build_mujoco.sh

5.2 Run

Ensure assets/config/<robot>/mode.yaml has active_mode: sim

Bash

# Enter container
engineai_robotics_env
./scripts/run_mujoco.sh

Run for a specific robot model:

Bash

./scripts/run_mujoco.sh pm01_edu

After running, you can use the remote controller to switch states:

2026-03-06 14-28-19.mkv

5.3 Simulation Performance Improvement

If you have an NVIDIA discrete GPU with the corresponding graphics driver installed, you can use GPU passthrough in docker to improve the rendering frame rate during simulation
- Run the following command to install NVIDIA's docker toolchain

Bash

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
  && curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
    sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
    sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Change NVIDIA_GPU_AVAILABLE in docker/generate.sh to y
Re-execute docker/generate.sh to enable GPU passthrough

$test\.jpg$

6 Real-Robot Deployment

6.1 Configure Install Target and Deploy

Edit install.sh

Bash

remote_user="user"
remote_host="192.168.0.163"
remote_dir="~/projects/engineai_robotics"

Run the installation

Bash

cd native_sdk

# ./install.sh <robot_model> <mode>
./install.sh pm01_edu robot

6.2 Real-Robot Run

Safety notice:
- Ensure all personnel keep a safe distance from the robot
- If the robot moves abnormally, stop it quickly at any time (press the emergency stop button or switch back to passive mode)
- It is recommended to first lift the robot with a hoist, place it on the ground after entering PD Stand mode, then switch to walking mode
Preparation before running
- Enable the robot's motor system using the emergency-stop remote
- Need to connect to the robot's hotspot or connect the robot via Ethernet cable

Bash

# SSH connect to Nezha
ssh user@192.168.0.163

# Stop the auto-started motion control program
sudo systemctl stop robotics.service

# Launch native_sdk
cd ~/projects/engineai_robotics
sudo ./run_robot.sh pm01_edu

Run in the background:

Bash

nohup sudo ./run_robot.sh pm01_edu > nohup.out 2>&1 &
tail -f nohup.out

After running, you can switch actions using the remote controller buttons according to the state transition reference

7 Data Monitoring and ROS2 Integration

The current Native SDK supports publishing robot runtime data via the ROS2 interface and enables real-time visualization with PlotJuggler.

7.1 ROS2 Environment Initialization

The Native SDK automatically generates ROS2 message interfaces (msg) during the build process for external data communication.

Before subscribing to data using ROS2 tools (such as PlotJuggler), you need to load the environment first:

Bash

# Enter container
engineai_robotics_env

# Build (generate ROS2 msg and environment)
./build.sh

# Load ROS2 environment
source build/ros2_env/install/setup.bash

7.2 ROS2 Topic List

The current Native SDK exposes the following ROS2 Topics for state retrieval and control interaction:

Topic Name	Message Type	Direction	Description
/hardware/joint_state	interface_protocol/msg/JointState	Subscribe	Receive current state of all joints (position, velocity, torque)
/hardware/joint_command	interface_protocol/msg/JointCommand	Publish	Send joint control commands to move all joints
/hardware/gamepad_keys	interface_protocol/msg/GamepadKeys	Subscribe	Gamepad data
/hardware/imu_info	interface_protocol/msg/ImuInfo	Subscribe	IMU data
/hardware/power_info	interface_protocol/msg/PowerInfo	Subscribe	Power/battery data
/hardware/motor_debug	interface_protocol/msg/MotorDebug	Subscribe	Motor debug data

7.3 Data Visualization (PlotJuggler)

The ROS2 Topics published by the current Native SDK can be visualized in real time via PlotJuggler:

Typical workflow:

Launch Native SDK (./run.sh or ./run_robot.sh)

Launch PlotJuggler

Bash

# Enter container
engineai_robotics_env

# Launch PlotJuggler
./scripts/run_plotjuggler.sh


# Launch PlotJuggler, add multi-machine debugging environment
./scripts/run_plotjuggler.sh remote

Select ROS2 data source
Select the layout provided by Native SDK
- layout file at: scripts/plotjuggler/common_data_display.xml

$test\.jpg$