Profile Image of the Author
levek
Hello, I'm levek.
公告
欢迎来到我的博客！
2166 字
11 分钟

灵犀 X2 二次开发指南

2026-09-21
文章
机器人
/
ROS2
/
仿真

1. 环境总览#

表1 环境总览

环境系统路径用途
机器人Ubuntu ARM64，ROS 2 Humble~/aimdk（容器内）真机编译、控制、SLAM
WSL 开发机Ubuntu 22.04 x86_64，ROS 2 Humble~/aimdk_sim_wsMuJoCo 仿真
WindowsWindows 11 22H2+—网络配置、WSL 管理

SDK 版本：v1.1.0

仿真栈：MuJoCo 3.13.0 + onnxruntime 1.23.2 + sim2sim_x2.py

参考： 智元机器人灵犀X2 ROS2官方文档

2. WSL 与 ROS 2 安装（在 Windows PowerShell 管理员模式执行）#

Terminal window
wsl --install -d Ubuntu-22.04

重启电脑后，在弹出的 Ubuntu 终端中设置用户名和密码，然后：

  • 切换清华源
Terminal window
sudo tee /etc/apt/sources.list > /dev/null <<'EOF'
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy main restricted universe multiverse
deb-src https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-updates main restricted universe multiverse
deb-src https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-updates main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-backports main restricted universe multiverse
deb-src https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-backports main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-security main restricted universe multiverse
deb-src https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-security main restricted universe multiverse
EOF
  • 安装底层依赖
Terminal window
sudo apt update && sudo apt upgrade -y
sudo apt install -y python3-colcon-common-extensions build-essential curl gnupg lsb-release
sudo apt install python3-colcon-common-extensions -y
# ROS 2 密钥与源
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(. /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null
sudo apt update && sudo apt install -y ros-humble-desktop
mkdir -p ~/aimdk_sim_ws/src
  • 安装python3.10.11
Terminal window
curl -LsSf https://astral.sh/uv/install.sh | sh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
uv --version
# 安装 Python 3.10.11
uv python install 3.10.11
# 加 --system-site-packages
cd ~/aimdk_sim_ws/src
uv venv --python 3.10.11 --system-site-packages .venv
source .venv/bin/activate
python --version   # 应该显示 Python 3.10.11
# 验证 ROS 2 依赖可见（关键一步，不通过就说明 venv 方式没生效）
python -c "import catkin_pkg; print('catkin_pkg ok')"
python -c "import empy; print('empy ok')"

3. 工作空间与代码同步#

3.1 从机器人同步代码到 WSL（机器人无 scp，用 SSH 管道）#

在 WSL 终端执行：

Terminal window
# 把机器人上的 extra 目录拉取到 WSL 工作空间
ssh agi@<机器人IP> "tar -czf - -C ~/aimdk/extra ." | tar -xzf - -C ~/aimdk_sim_ws/src/
# 把 src 目录也拉一份
ssh agi@<机器人IP> "tar -czf - -C ~/aimdk/src ." | tar -xzf - -C ~/aimdk_sim_ws/src/

如果机器人上有 ~/.ssh/authorized_keys 配置了免密，可以直接执行；否则按提示输入机器人 agi 用户密码。

  • 或者直接下载SDK包- 直接下载: SDKv1.1.0

3.2 清理重复包#

如果 colcon build 报 Duplicate package names，进入 src 删除多余副本：

Terminal window
cd ~/aimdk_sim_ws/src
# 示例：删除 x2_rl_deploy 里重复的 aimdk_msgs
rm -rf x2_rl_deploy/aimdk_msgs
# 删除无关的宇树第三方机器人控制器
rm -rf mc-rl/third_party/unitree_rl_lab/

4. 安装依赖#

Terminal window
sudo sed -i 's|http://packages.ros.org/ros2/ubuntu|https://mirrors.tuna.tsinghua.edu.cn/ros2/ubuntu|g' /etc/apt/sources.list.d/ros2-latest.list
sudo apt install -y libgflags-dev libgl1-mesa-dri libglfw3 libglew-dev libx11-dev libncurses-dev
sudo apt install -y libcurl4-openssl-dev
sudo apt install -y ros-humble-grid-map* ros-humble-rmw-cyclonedds-cpp
  • ONNX Runtime（后面虚拟仿真mujoco会用，选择性安装）
Terminal window
pip3 install onnxruntime mujoco

5. 编译与自动环境加载#

Terminal window
#安装第三方库
cd ~/aimdk_sim_ws
source ~/aimdk_sim_ws/src/.venv/bin/activate
uv pip install --python ~/aimdk_sim_ws/src/.venv/bin/python3 catkin_pkg  lark
uv pip install --python ~/aimdk_sim_ws/src/.venv/bin/python3 empy==3.3.4
#去除windows自带的curl影响
unset CMAKE_PREFIX_PATH
unset CURL_DIR CURL_ROOT CURL_INCLUDE_DIR CURL_LIBRARY


colcon build
# 写入 .bashrc 实现自动加载
echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
echo "[ -f ~/aimdk_sim_ws/install/local_setup.bash ] && source ~/aimdk_sim_ws/install/local_setup.bash" >> ~/.bashrc
source ~/.bashrc

5.1 如果修改了 aimdk_msgs 或其他 ROS 包#

Terminal window
cd ~/aimdk_sim_ws
colcon build --packages-select aimdk_msgs --allow-overriding aimdk_msgs
source install/local_setup.bash

6. 网络配置（WSL2）—对网线连接机器人无用！仅对网络连接有效#

6.1 前提条件#

  • Windows 11 22H2 或更高版本
  • WSL2 已安装 Ubuntu 22.04
  • 建议为 WSL 放行 Windows 防火墙

6.2 启用镜像网络模式#

在 Windows 用户目录（如 C:\Users\lenovo\）创建或编辑 .wslconfig：

[wsl2]
networkingMode=mirrored
dnsTunneling=true
firewall=true
autoProxy=true

PowerShell（管理员）执行：

Terminal window
wsl --shutdown

重新打开 Ubuntu 终端。

6.3 验证镜像网络是否生效#

Terminal window
ip addr show
ping 192.168.88.88

如果 ping 通，说明 WSL 与 Windows 在同一网络平面。

6.4 Windows 端静态 IP#

打开 ncpa.cpl，找到连接机器人的“以太网”网卡 → 属性 → IPv4：

  • IP 地址：192.168.88.88
  • 子网掩码：255.255.255.0
  • 网关/DNS：留空

6.5 机器人连接#

Terminal window
ping 10.0.1.41
ssh agi@10.0.1.41   # 密码通常为 1

如需本地查看机器人状态：

Terminal window
export ROS_DOMAIN_ID=0
export ROS_LOCALHOST_ONLY=0
export ROS_STATIC_PEERS=192.168.88.88

7. 机器人端开发（SSH + 宿主机编译）#

注意：容器方案在机器人上因内核限制不可用（cannot clone: Operation not permitted），以下均为宿主机直接编译。

Terminal window
ssh agi@10.0.1.41   # 密码通常为 1
# 进入 SDK 目录
cd ~/aimdk
source /opt/ros/humble/setup.bash
colcon build          # 非首次可跳过
source install/local_setup.bash

7.1 每次新终端只需#

Terminal window
cd ~/aimdk
source install/local_setup.bash

因为 local_setup.bash 会自动带出 ROS 2 基础环境。

7.2 自动加载（写入 ~/.bashrc）#

Terminal window
echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
echo "[ -f ~/aimdk/install/local_setup.bash ] && source ~/aimdk/install/local_setup.bash" >> ~/.bashrc
source ~/.bashrc

8. 常用机器人指令#

py_examples 里可直接运行的示例脚本如下（部分功能可能未配备，请谨慎运行）：

py_examples 目录下的示例脚本

Terminal window
ros2 run py_examples get_mc_action          # 获取运动模式
ros2 run py_examples set_mc_action SD       # 切换模式（PD/DD/JD/SD/LD）
ros2 run py_examples preset_motion_client   # 预设动作
ros2 run py_examples mc_locomotion_velocity # 速度控制
ros2 run py_examples play_linkcraft         # 播放灵犀工坊作品

8.1 获取运动模式 get_mc_action#

Terminal window
ros2 run py_examples get_mc_action

get_mc_action 的输出

输出中的 Mode name 就是当前运动状态，可在最后的运动模式对照表里查对应名称。

8.2 切换运动模式 set_mc_action#

Terminal window
ros2 run py_examples set_mc_action SD

可用的模式缩写：

set_mc_action 可用缩写

出现下面的输出即视为切换成功：

set_mc_action 切换成功

8.3 预设动作 preset_motion_client#

Terminal window
ros2 run py_examples preset_motion_client

动作—代码对照表：

动作名称motionarea说明动作名称motionarea说明
右手挥手10022稳定站立模式下执行拥抱300811同上
左手挥手10021同上加油301111同上
右手握手10032同上双手平举10103同上
左手握手10031同上右手平举10102同上
右手举手10012同上左手平举10101同上
左手举手10011同上拜拜303111同上
右手飞吻10042同上动感光波300711同上
左手飞吻10041同上右手击掌10082同上
鼓掌301711同上左手击掌10081同上
右手敬礼10132同上双手打叉300911同上
左手敬礼10131同上胸前右手挥手10112同上
双手比心10073同上胸前左手挥手10111同上
右手比心10072同上鞠躬300111同上
双手比心10073同上挠头302411同上
右手比心10072同上抓屁股302511同上
左手比心10071同上

按提示输入 arm area ID 与 preset motion ID，出现下面输出即为下发成功：

preset_motion_client 下发成功

8.4 速度控制 mc_locomotion_velocity#

Terminal window
ros2 run py_examples mc_locomotion_velocity

三个数值按需求填写（0.0—1.0，单位 m/s），数值不要太大，防止机器人误伤：

mc_locomotion_velocity 的输出

8.5 播放灵犀工坊作品 play_linkcraft#

Terminal window
ros2 run py_examples play_linkcraft

先列出机器人上已有的作品资源：

play_linkcraft 资源列表

在提示符处按索引选择作品，出现 Play success 即为播放成功：

play_linkcraft 播放成功

8.6 运动模式对照#

表2 运动模式对照

缩写模式名说明
PDPASSIVE_DEFAULT零力矩
DDDAMPING_DEFAULT阻尼模式
JDJOINT_DEFAULT位置控制站立（关节锁定）
SDSTAND_DEFAULT稳定站立（自动平衡）
LDLOCOMOTION_DEFAULT行走/奔跑

官方文档里的完整版本（含使用场景）：

运动模式表

9. WSL 图形显示配置（MuJoCo 必需）#

9.1 Windows 11（推荐）#

WSLg 自带图形支持，直接运行即可弹窗。验证：

Terminal window
xeyes
glxgears

9.2 Windows 10#

需要安装 X Server（VcXsrv 或 Xming），然后在 ~/.bashrc 添加：

Terminal window
export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0

10. 仿真空间#

10.1 手动进入#

Terminal window
cd ~/aimdk_sim_ws
source install/local_setup.bash
cd ~/aimdk/extra/mc-rl/rl/sim2sim/
python3 sim2sim_x2.py

10.2 一键启动脚本#

cat > ~/run_sim.sh << 'EOF'
#!/bin/bash
cd ~/aimdk_sim_ws
source install/local_setup.bash
cd ~/aimdk/extra/mc-rl/rl/sim2sim/
python3 sim2sim_x2.py
EOF
chmod +x ~/run_sim.sh

以后只需：

Terminal window
~/run_sim.sh

10.3 仿真按键#

表3 仿真按键说明

按键功能
回车 / 空格从 DAMPING 启动状态机
W / S前进 / 后退
A / D左移 / 右移
Q / E左转 / 右转
空格原地站立
Backspace回到 DAMPING
?显示帮助
Ctrl+C退出

11. 已知问题与故障排查#

11.1 编译相关#

表4 编译问题排查

报错原因解决
Duplicate package namessrc 下存在同名包删除多余副本（备份目录移出 src）
cannot find …/urdfx2_description 缺少 urdf 目录在 X2_URDF-v1.3.0/ 下 mkdir urdf && cp *.urdf urdf/
Undefined symbol: ProcessInfoaimdk_msgs 版本缺消息用 x2_rl_deploy/aimdk_msgs 替换并补全
ImportError: McLocomotionVelocity替换后缺原 SDK 消息从备份恢复 aimdk_msgs，合入 6 个 HDS 消息

11.2 仿真相关#

现象：进入 RL_ACTIVE 后机器人持续抽搐或直接躺倒，无法站立。

已尝试：

  • 补全 DEFAULT_JOINT_POS 为 31 个关节
  • 重置时显式设置 pelvis 完整位姿（位置+四元数）
  • 调整 pelvis 高度（0.40 / 0.50 / 0.55）
  • 调整稳定步数（500 / 3000）
  • 切换 PD 增益（standup_gains / rl_gains）
  • 放宽 GRAVITY_PITCH_LIMIT

结论：策略在 IsaacLab 训练，与 MuJoCo 物理环境存在差异，需官方提供 sim2sim 对齐配置。

12. 安全注意事项#

  • 停止 mc 模块前必须确保机器人有吊挂或安全支撑。
  • 真机控制夹爪/灯带前，先确认当前运动模式，避免冲突。
  • sudo 权限受限，不要随意安装系统包。
  • 容器方案在机器人上不可用，请使用宿主机直接编译。

13. 版本与备份#

  • 机器人 SDK：v1.1.0
  • WSL 工作空间：~/aimdk_sim_ws
  • 备份目录：~/aimdk_msgs_bak（已移出 src）
灵犀 X2 二次开发指南
https://blog.levek.top/posts/linix/灵犀x2二次开发指南/
作者
levek
发布于
2026-09-21
许可协议
CC BY-NC-SA 4.0
最后更新于 2026-09-21，距今已过 1 天

部分内容可能已过时

记账软件
© 2026 levek. All Rights Reserved. / RSS / Sitemap
Powered by Astro & Firefly

目录

封面
Loading ...
Loading ...
0:00 / 0:00