灵犀 X2 二次开发指南

1. 环境总览#

表1 环境总览

环境	系统	路径	用途
机器人	Ubuntu ARM64，ROS 2 Humble	~/aimdk（容器内）	真机编译、控制、SLAM
Windows	Windows 11	—	网络配置

SDK 版本：v1.1.0

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

2.1 Windows 端静态 IP#

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

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

2.2 机器人连接#

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

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

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

1
ssh agi@10.0.1.41   # 密码通常为 1
2
# 进入 SDK 目录
3
cd ~/aimdk

4. 常用机器人指令#

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

1
ros2 run py_examples get_mc_action          # 获取运动模式

1
ros2 run py_examples preset_motion_client   # 预设动作

1
ros2 run py_examples mc_locomotion_velocity # 速度控制

1
ros2 run py_examples play_linkcraft         # 播放灵犀工坊作品

4.1 获取运动模式 get_mc_action#

1
ros2 run py_examples get_mc_action

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

4.2 切换运动模式 set_mc_action#

1
ros2 run py_examples set_mc_action SD

可用的模式缩写：

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

4.3 预设动作 preset_motion_client#

1
ros2 run py_examples preset_motion_client

动作—代码对照表：

动作名称	motion	area	说明	动作名称	motion	area	说明
右手挥手	1002	2	稳定站立模式下执行	拥抱	3008	11	同上
左手挥手	1002	1	同上	加油	3011	11	同上
右手握手	1003	2	同上	双手平举	1010	3	同上
左手握手	1003	1	同上	右手平举	1010	2	同上
右手举手	1001	2	同上	左手平举	1010	1	同上
左手举手	1001	1	同上	拜拜	3031	11	同上
右手飞吻	1004	2	同上	动感光波	3007	11	同上
左手飞吻	1004	1	同上	右手击掌	1008	2	同上
鼓掌	3017	11	同上	左手击掌	1008	1	同上
右手敬礼	1013	2	同上	双手打叉	3009	11	同上
左手敬礼	1013	1	同上	胸前右手挥手	1011	2	同上
双手比心	1007	3	同上	胸前左手挥手	1011	1	同上
右手比心	1007	2	同上	鞠躬	3001	11	同上
双手比心	1007	3	同上	挠头	3024	11	同上
右手比心	1007	2	同上	抓屁股	3025	11	同上
左手比心	1007	1	同上

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

4.4 速度控制 mc_locomotion_velocity#

1
ros2 run py_examples mc_locomotion_velocity

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

4.5 播放灵犀工坊作品 play_linkcraft#

1
ros2 run py_examples play_linkcraft

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

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

4.6 运动模式对照#

表2 运动模式对照

缩写	模式名	说明
PD	PASSIVE_DEFAULT	零力矩
DD	DAMPING_DEFAULT	阻尼模式
JD	JOINT_DEFAULT	位置控制站立（关节锁定）
SD	STAND_DEFAULT	稳定站立（自动平衡）
LD	LOCOMOTION_DEFAULT	行走/奔跑

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

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

5.1 编译相关#

表4 编译问题排查

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

5.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 对齐配置。

音乐

音乐