1 X2 MuJoCo 运控仿真

本页用于在 x86_64 Ubuntu 22.04 电脑上启动 MuJoCo、MC 和 AimDK 示例。支持本地部署和 Docker 部署两种方式。

1.1 目录

1. 软件组成

2. 前置条件

3. 准备软件目录

4. 方案一：本地部署

5. 方案二：Docker 部署

6. 验证运动控制

7. 停止环境

8. 常见问题

1.2 软件组成

组件	作用	启动入口
sim_mujoco	基于 MuJoCo 的物理仿真，模拟机器人本体（HAL 层）	start_sim.sh
mc	运动控制模块，运行步态和动作并输出关节命令	em_run.sh
SDK（aimdk）	发送控制指令，提供 py_examples 示例和 aimdk_msgs 消息类型	ros2 run py_examples <工具>

控制链路如下：

SDK（py_examples）──高层指令──▶ MC ──关节命令──▶ sim_mujoco
set_mc_action / 速度 / 动画       │               /aima/hal/joint/*/command
                                  └──◀──关节和 IMU 状态── /aima/hal/joint/*/state, imu

1.3 前置条件

项目	要求
电脑	x86_64，建议 16 GiB 或以上内存
系统	Ubuntu 22.04，带图形桌面
网络	首次部署需要下载镜像或 Ubuntu 软件包
GPU	可选，无 NVIDIA GPU 也可使用

选择一种部署方式：

方式	适用条件
本地部署	电脑已安装 ROS 2 Humble，并允许在宿主机安装依赖
Docker 部署（推荐）	电脑已安装 Docker；宿主机无需安装 ROS 2

在宿主机确认 xhost 已安装：

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

1.4 准备软件目录

将交付文件放到同一工作目录，目录名称和所在路径可自行选择：

x2_simulation/
├── aimdk/
├── sim_mujoco/
├── mc/
├── Dockerfile       # 仅 Docker 部署需要
└── run_docker.sh    # 仅 Docker 部署需要

进入工作目录：

cd <x2_simulation所在路径>/x2_simulation

1.5 方案一：本地部署

本方案不使用 Docker，MuJoCo、MC 和 AimDK 全部直接运行在 Ubuntu 22.04 宿主机上。

配置国内软件源

中国大陆网络建议先将 Ubuntu 和 ROS 2 软件源配置为阿里云镜像。先备份 Ubuntu 原软件源并替换下载地址：

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

添加 ROS 2 软件源：

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

安装依赖

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

创建 MC 运行时目录

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

构建 AimDK

cd <x2_simulation所在路径>/x2_simulation/aimdk
source /opt/ros/humble/setup.bash
colcon build
source install/local_setup.bash

终端 1：启动 MuJoCo

cd <x2_simulation所在路径>/x2_simulation
source /opt/ros/humble/setup.bash
export RMW_IMPLEMENTATION=rmw_fastrtps_cpp
cd sim_mujoco/bin
./start_sim.sh -s

MuJoCo 窗口显示机器人后，保持终端运行。

终端 2：启动 MC

新开一个宿主机终端：

cd <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

终端 3：检查通信

再新开一个宿主机终端：

cd <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

返回 Mode name 和 Mode status 即表示通信正常。

1.6 方案二：Docker 部署

请先确认电脑已安装 Docker。

配置 Docker 镜像加速（宿主机）

中国大陆网络建议先配置 Docker 镜像加速。以下配置优先使用 DaoCloud 镜像代理，docker.1ms.run 作为备用：

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

下载 ROS 2 基础镜像（宿主机）

FROM osrf/ros:humble-desktop-full 表示以 ROS 2 Humble 官方镜像为基础创建新镜像。客户电脑不需要提前拥有该镜像，执行：

docker pull osrf/ros:humble-desktop-full

出现 Downloaded newer image 或 Image is up to date 即表示成功。

创建 MC 运行时目录（宿主机）

创建 MC 运行时所需目录：

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

创建 Dockerfile（宿主机）

在工作目录创建 Dockerfile，内容如下：

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"]

创建启动脚本（宿主机）

在工作目录创建 run_docker.sh，内容如下：

#!/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 "缺少目录：${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

赋予执行权限：

chmod +x run_docker.sh

构建镜像（宿主机）

docker build -t x2-simulation:latest .

构建成功后检查：

docker images x2-simulation

能看到 x2-simulation 和 latest 即表示成功。

启动容器（宿主机）

./run_docker.sh

命令执行后会直接进入容器。保留该终端，后续用作终端 1。

构建 AimDK（容器内）

如果 /workspace/aimdk/install/local_setup.bash 已存在，跳过本节。否则在终端 1 的容器内执行：

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

没有 Failed 即表示构建成功。

启动仿真与 MC

必须按以下顺序启动。

终端 1：启动 MuJoCo

在 ./run_docker.sh 进入的容器中执行：

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

按提示选择与交付包配套的机器人型号。MuJoCo 窗口显示机器人后，保持终端运行。

终端 2：启动 MC

新开一个宿主机终端，进入容器：

docker exec -it x2-sim bash -l

进入容器后执行：

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

MC 持续运行且没有崩溃即可继续。

终端 3：检查通信

再新开一个宿主机终端，进入容器：

docker exec -it x2-sim bash -l

进入容器后执行：

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

返回 Mode name 和 Mode status 即表示通信正常。

1.7 验证运动控制

以下命令均在终端 3 执行。

站立

ros2 run py_examples set_mc_action SD

前进

ros2 run py_examples set_mc_action LD
ros2 run py_examples mc_locomotion_velocity

依次输入：

0.2
0
0

机器人应前进约 5 秒并停止。

转向

再次运行 mc_locomotion_velocity，依次输入：

0.2
0
0.5

机器人应边前进边左转。当前 MC 步态不保证纯角速度原地启步。

1.8 停止环境

本地部署

先在终端 3 停止示例，再依次在终端 2 和终端 1 按 Ctrl+C。

Docker 部署

先在终端 3 停止示例，再在终端 2 和终端 1 按 Ctrl+C。最后在宿主机执行：

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

1.9 常见问题

基础镜像下载失败

先重试：

docker pull osrf/ros:humble-desktop-full

仍失败时，检查客户网络、DNS 或按前文配置 Docker 镜像加速。

MuJoCo 窗口没有打开

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

确认宿主机已进入图形桌面，然后重新执行 ./run_docker.sh。

MC 启动后崩溃

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

重新执行 ./run_docker.sh，确保宿主机 /agibot 已挂载到容器内的 /agibot。

AimDK 与 MC 无法通信

三个终端都应输出 rmw_fastrtps_cpp：

echo "$RMW_IMPLEMENTATION"

如果不是，执行：

export RMW_IMPLEMENTATION=rmw_fastrtps_cpp