1 X2 MuJoCo Motion-Control Simulation

This page explains how to run MuJoCo, MC, and AimDK examples on an x86_64 computer running Ubuntu 22.04. Both local and Docker deployment are supported.

1.1 Contents

1. Software Components

2. Prerequisites

3. Prepare the Software Directory

4. Option 1: Local Deployment

5. Option 2: Docker Deployment

6. Verify Motion Control

7. Stop the Environment

8. Troubleshooting

1.2 Software Components

Component	Role	Launch Entry
sim_mujoco	MuJoCo-based physics simulation that represents the robot body (HAL layer)	start_sim.sh
mc	Motion-control module that runs gaits and motions and outputs joint commands	em_run.sh
SDK (aimdk)	Sends control commands and provides py_examples examples and aimdk_msgs message types	ros2 run py_examples <tool>

The control pipeline is as follows:

SDK (py_examples) ──high-level command──▶ MC ──joint command──▶ sim_mujoco
set_mc_action / velocity / animation  │                /aima/hal/joint/*/command
                                      └──◀──joint & IMU state── /aima/hal/joint/*/state, imu

1.3 Prerequisites

Item	Requirement
Computer	x86_64, with 16 GiB or more memory recommended
Operating system	Ubuntu 22.04 with a graphical desktop
Network	The initial deployment requires downloading an image or Ubuntu packages
GPU	Optional; an NVIDIA GPU is not required

Choose one deployment method:

Method	When to use
Local deployment	ROS 2 Humble is installed, and dependencies can be installed on the host
Docker deployment (recommended)	Docker is installed; ROS 2 is not required on the host

Make sure xhost is installed on the host:

if ! command -v xhost >/dev/null 2>&1; then
  sudo apt update
  sudo apt install -y x11-xserver-utils
fi

1.4 Prepare the Software Directory

Place all delivered files in one working directory. You may choose its name and location:

x2_simulation/
├── aimdk/
├── sim_mujoco/
├── mc/
├── Dockerfile       # Required only for Docker deployment
└── run_docker.sh    # Required only for Docker deployment

Enter the working directory:

cd <path-to-x2_simulation>/x2_simulation

1.5 Option 1: Local Deployment

This option does not use Docker. MuJoCo, MC, and AimDK all run directly on the Ubuntu 22.04 host.

Configure Mirrors in Mainland China

For networks in mainland China, configure the Ubuntu and ROS 2 package sources to use Aliyun mirrors. First back up the original Ubuntu source and replace its download URLs:

sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak
sudo sed -i -E \
  -e 's@https?://archive\.ubuntu\.com/ubuntu@https://mirrors.aliyun.com/ubuntu@g' \
  -e 's@https?://security\.ubuntu\.com/ubuntu@https://mirrors.aliyun.com/ubuntu@g' \
  -e 's@https?://cn\.archive\.ubuntu\.com/ubuntu@https://mirrors.aliyun.com/ubuntu@g' \
  /etc/apt/sources.list
sudo apt update
sudo apt install -y curl gnupg2 dirmngr lsb-release ca-certificates

Add the ROS 2 package source:

sudo mkdir -p /root/.gnupg
sudo chmod 700 /root/.gnupg
sudo gpg --no-default-keyring \
  --keyring /usr/share/keyrings/ros-archive-keyring.gpg \
  --keyserver hkp://keyserver.ubuntu.com:80 \
  --recv-keys F42ED6FBAB17C654
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] https://mirrors.aliyun.com/ros2/ubuntu jammy main" | sudo tee /etc/apt/sources.list.d/ros2.list >/dev/null

Install Dependencies

sudo apt update
sudo apt install -y \
  build-essential \
  cmake \
  libcurl4-openssl-dev \
  libeigen3-dev \
  libgflags-dev \
  libgl1 \
  libgl1-mesa-dri \
  libglx-mesa0 \
  libncurses-dev \
  liboctomap1.9 \
  libopencv-dev \
  libscrypt0 \
  libyaml-cpp-dev \
  mesa-utils \
  pkg-config \
  python3-colcon-common-extensions \
  ros-humble-desktop-full \
  ros-humble-grid-map-msgs \
  ros-humble-grid-map-ros \
  ros-humble-rmw-fastrtps-cpp

Create the MC Runtime Directory

sudo mkdir -p /agibot/data/var/
sudo chown "$USER:$USER" -R /agibot

Build AimDK

cd <path-to-x2_simulation>/x2_simulation/aimdk
source /opt/ros/humble/setup.bash
colcon build
source install/local_setup.bash

Terminal 1: Start MuJoCo

cd <path-to-x2_simulation>/x2_simulation
source /opt/ros/humble/setup.bash
export RMW_IMPLEMENTATION=rmw_fastrtps_cpp
cd sim_mujoco/bin
./start_sim.sh -s

When the robot appears in the MuJoCo window, keep the terminal running.

Terminal 2: Start MC

Open another host terminal:

cd <path-to-x2_simulation>/x2_simulation
source /opt/ros/humble/setup.bash
export RMW_IMPLEMENTATION=rmw_fastrtps_cpp
cd mc/bin
unset AGIBOT_SOFTWARE_HOME
./em_run.sh

Terminal 3: Check Communication

Open one more host terminal:

cd <path-to-x2_simulation>/x2_simulation/aimdk
source /opt/ros/humble/setup.bash
source install/local_setup.bash
export RMW_IMPLEMENTATION=rmw_fastrtps_cpp
ros2 run py_examples get_mc_action

Communication is working if Mode name and Mode status are returned.

1.6 Option 2: Docker Deployment

Make sure Docker is installed on the computer.

Configure Docker Registry Mirrors (Host)

For networks in mainland China, configure Docker registry mirrors first. The following configuration uses the DaoCloud mirror first and docker.1ms.run as a fallback:

sudo mkdir -p /etc/docker
sudo cp /etc/docker/daemon.json /etc/docker/daemon.json.bak 2>/dev/null || true
echo '{"registry-mirrors":["https://docker.m.daocloud.io","https://docker.1ms.run"]}' | sudo tee /etc/docker/daemon.json >/dev/null
sudo systemctl restart docker

Download the ROS 2 Base Image (Host)

FROM osrf/ros:humble-desktop-full creates a new image from the official ROS 2 Humble image. The customer computer does not need to have this image in advance. Run:

docker pull osrf/ros:humble-desktop-full

The download succeeded when Downloaded newer image or Image is up to date appears.

Create the MC Runtime Directory (Host)

Create the directory required by the MC runtime:

sudo mkdir -p /agibot/data/var/
sudo chown "$USER:$USER" -R /agibot

Create the Dockerfile (Host)

Create a Dockerfile in the working directory with the following content:

FROM osrf/ros:humble-desktop-full

ENV DEBIAN_FRONTEND=noninteractive
ENV RMW_IMPLEMENTATION=rmw_fastrtps_cpp

RUN apt-get update && apt-get install -y --no-install-recommends \
      build-essential \
      ca-certificates \
      cmake \
      curl \
      libcurl4-openssl-dev \
      libeigen3-dev \
      libgflags-dev \
      libgl1 \
      libgl1-mesa-dri \
      libglx-mesa0 \
      libncurses-dev \
      liboctomap1.9 \
      libopencv-dev \
      libscrypt0 \
      libyaml-cpp-dev \
      mesa-utils \
      pkg-config \
      python3-colcon-common-extensions \
      python3-pip \
      ros-humble-cv-bridge \
      ros-humble-grid-map-msgs \
      ros-humble-grid-map-ros \
      ros-humble-joy \
      ros-humble-rmw-fastrtps-cpp \
    && rm -rf /var/lib/apt/lists/*

RUN printf '%s\n' \
      'source /opt/ros/humble/setup.bash' \
      'export RMW_IMPLEMENTATION=rmw_fastrtps_cpp' \
      'if [ -f /workspace/aimdk/install/local_setup.bash ]; then source /workspace/aimdk/install/local_setup.bash; fi' \
      >> /root/.bashrc

WORKDIR /workspace
CMD ["bash"]

Create the Launch Script (Host)

Create run_docker.sh in the working directory with the following content:

#!/usr/bin/env bash
set -euo pipefail

ROOT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
IMAGE_NAME=x2-simulation:latest
CONTAINER_NAME=x2-sim

for dir in aimdk sim_mujoco mc; do
  test -d "${ROOT_DIR}/${dir}" || {
    echo "Missing directory: ${ROOT_DIR}/${dir}" >&2
    exit 1
  }
done

xhost +si:localuser:root >/dev/null
docker rm -f "${CONTAINER_NAME}" >/dev/null 2>&1 || true

DOCKER_ARGS=(
  run -it
  --name "${CONTAINER_NAME}"
  --network host
  --ipc host
  -e "DISPLAY=${DISPLAY:-:0}"
  -e QT_X11_NO_MITSHM=1
  -e RMW_IMPLEMENTATION=rmw_fastrtps_cpp
  -v "${ROOT_DIR}/aimdk:/workspace/aimdk:rw"
  -v "${ROOT_DIR}/sim_mujoco:/workspace/sim_mujoco:rw"
  -v "${ROOT_DIR}/mc:/workspace/mc:rw"
  -v /agibot:/agibot:rw
  -v /tmp/.X11-unix:/tmp/.X11-unix:rw
  -w /workspace
)

if [[ -d /dev/dri ]]; then
  DOCKER_ARGS+=(--device /dev/dri)
fi

docker "${DOCKER_ARGS[@]}" "${IMAGE_NAME}" bash

Grant execute permission:

chmod +x run_docker.sh

Build the Image (Host)

docker build -t x2-simulation:latest .

After the build succeeds, check the image:

docker images x2-simulation

The build succeeded if x2-simulation and latest are displayed.

Start the Container (Host)

./run_docker.sh

The command opens a shell in the container. Keep this terminal open and use it as Terminal 1.

Build AimDK (Inside the Container)

If /workspace/aimdk/install/local_setup.bash already exists, skip this section. Otherwise, run the following in the Terminal 1 container:

cd /workspace/aimdk
source /opt/ros/humble/setup.bash
colcon build
source install/local_setup.bash

The build succeeded if no Failed result is reported.

Start the Simulation and MC

Start the components in the following order.

Terminal 1: Start MuJoCo

In the container opened by ./run_docker.sh, run:

cd /workspace/sim_mujoco/bin
./start_sim.sh -s

When prompted, select the robot model that matches the delivered package. When the robot appears in the MuJoCo window, keep the terminal running.

Terminal 2: Start MC

Open another host terminal and enter the container:

docker exec -it x2-sim bash -l

After entering the container, run:

cd /workspace/mc/bin
unset AGIBOT_SOFTWARE_HOME
./em_run.sh

Continue when MC remains running without crashing.

Terminal 3: Check Communication

Open one more host terminal and enter the container:

docker exec -it x2-sim bash -l

After entering the container, run:

source /workspace/aimdk/install/local_setup.bash
ros2 run py_examples get_mc_action

Communication is working if Mode name and Mode status are returned.

1.7 Verify Motion Control

Run all commands below in Terminal 3.

Stand

ros2 run py_examples set_mc_action SD

Move Forward

ros2 run py_examples set_mc_action LD
ros2 run py_examples mc_locomotion_velocity

Enter the following values in order:

0.2
0
0

The robot should move forward for about 5 seconds and then stop.

Turn

Run mc_locomotion_velocity again and enter the following values in order:

0.2
0
0.5

The robot should move forward while turning left. The current MC gait does not guarantee starting an in-place turn using angular velocity alone.

1.8 Stop the Environment

Local deployment

Stop the example in Terminal 3, then press Ctrl+C in Terminal 2 and Terminal 1 in that order.

Docker Deployment

Stop the example in Terminal 3, then press Ctrl+C in Terminal 2 and Terminal 1. Finally, run the following on the host:

docker rm -f x2-sim
xhost -si:localuser:root 2>/dev/null || true

1.9 Troubleshooting

Base Image Download Fails

Retry first:

docker pull osrf/ros:humble-desktop-full

If it still fails, check the customer network and DNS, or configure the Docker registry mirrors described above.

The MuJoCo Window Does Not Open

echo "$DISPLAY"
xhost +si:localuser:root

Make sure the host is running a graphical desktop, then run ./run_docker.sh again.

MC Crashes After Startup

sudo mkdir -p /agibot/data/var/
sudo chown "$USER:$USER" -R /agibot

Run ./run_docker.sh again and make sure the host /agibot directory is mounted at /agibot inside the container.

AimDK Cannot Communicate with MC

All three terminals should output rmw_fastrtps_cpp:

echo "$RMW_IMPLEMENTATION"

If not, run:

export RMW_IMPLEMENTATION=rmw_fastrtps_cpp