从零搭建lerobot_so100仿真环境：Mujoco配置与实机联动避坑指南

在机器人开发领域，仿真环境的重要性不言而喻。它不仅能大幅降低硬件损耗成本，还能加速算法验证周期。对于lerobot_so100这类开源机器人项目而言，Mujoco物理引擎提供了高精度的动力学仿真能力，但配置过程往往让初学者望而生畏。本文将手把手带你完成从环境搭建到实机联动的全流程，重点解析那些官方文档未曾提及的"坑点"。

1. 基础环境配置

1.1 系统与依赖准备

推荐使用Ubuntu 20.04/22.04 LTS系统，这是大多数机器人框架官方支持的环境。在开始前，请确保已安装：

bash复制sudo apt update && sudo apt install -y \
    git curl build-essential \
    libgl1-mesa-dev libgl1-mesa-glx \
    libglew-dev libosmesa6-dev \
    patchelf

关键组件版本要求：

注意：避免使用Python 3.10+版本，部分依赖库可能存在兼容性问题

1.2 Conda环境创建

使用conda可以避免依赖冲突问题：

bash复制conda create -n lerobot_so100 python=3.9 -y
conda activate lerobot_so100

安装核心依赖包时，建议按以下顺序执行：

bash复制pip install mujoco==2.3.3
pip install gym==0.26.2
pip install git+https://github.com/perezjln/gym-lowcostrobot.git

2. 项目部署与验证

2.1 克隆与初始化

从gitee获取项目代码：

bash复制git clone https://gitee.com/mrqiguan/lerobot_so100_sim.git
cd lerobot_so100_sim

项目结构解析：

• assets/：包含so100的URDF模型和Mujoco配置文件
• scripts/：核心控制脚本
• config/：参数配置文件

2.2 模型加载测试

运行基础测试脚本验证环境：

bash复制python scripts/check_model.py

常见报错解决方案：

• GLFW初始化失败：安装sudo apt install libglfw3-dev
• Missing mjkey.txt：将Mujoco许可证文件放入~/.mujoco/目录
• ImportError：检查conda环境是否激活，建议重启终端

3. 仿真控制核心技巧

3.1 基础运动控制

1_so100_feetech_mujoco_control_sim.py脚本实现了基本的关节控制：

python复制# 典型控制代码片段
model = mujoco.MjModel.from_xml_path("so100.xml")
data = mujoco.MjData(model)

while True:
    # 设置目标位置
    data.ctrl[0] = 0.5  # 关节1位置控制
    mujoco.mj_step(model, data)

参数调试要点：

• 关节限位检查：在so100.xml中确认<joint range="">设置
• 控制频率匹配：仿真步长建议设置为0.002s
• 力矩限制：避免设置过大导致数值不稳定

3.2 实机联动配置

2_so100_feetech_mujoco_control_realTosim.py实现硬件在环控制，关键配置项：

python复制# 串口初始化
ser = serial.Serial('/dev/ttyACM0', 115200, timeout=1)

# 位姿映射参数
POSITION_OFFSETS = [
    -0.838,  # 关节1
    -1.81,   # 关节2
    1.1,     # 关节3
    -1.413,  # 关节4
    -2.23,   # 关节5
    -0.626   # 关节6
]

校准流程：

1. 将实机移动到零位姿势
2. 运行python scripts/read_actual_positions.py获取当前关节角度
3. 计算仿真模型与实际读数的差值，更新POSITION_OFFSETS
4. 反复测试直到仿真模型与实机动作完全同步

4. 高级调试与优化

4.1 动力学参数调整

在so100.xml中优化动力学表现：

xml复制<!-- 典型电机参数配置 -->
<actuator>
    <motor name="joint1" joint="joint1" gear="100" ctrlrange="-3.14 3.14"/>
    <position name="joint1_pos" joint="joint1" kp="500"/>
    <velocity name="joint1_vel" joint="joint1" kv="50"/>
</actuator>

参数调优策略：

• 先调kp使系统稳定
• 再调kv抑制振荡
• 最后调整gear匹配实际减速比

4.2 可视化调试技巧

启用Mujoco可视化调试工具：

python复制viewer = mujoco_viewer.MujocoViewer(model, data)
while viewer.is_alive:
    mujoco.mj_step(model, data)
    viewer.render()

调试功能：

• 按Space暂停/继续仿真
• 右键拖动查看不同视角
• 按V切换可视化模式（线框/实体）

遇到机械臂异常抖动时，可以：

1. 降低控制频率
2. 检查碰撞检测设置
3. 增加数值积分器步数

5. 性能优化实战

5.1 实时性保障措施

在/etc/security/limits.conf中添加：

code复制* soft rtprio 99
* hard rtprio 99

使用实时内核并设置CPU隔离：

bash复制sudo apt install linux-rt
sudo isolcpus=2,3  # 将CPU2/3隔离用于实时任务

5.2 多线程控制架构

推荐的控制程序结构：

python复制from threading import Thread

def sim_loop():
    while True:
        mujoco.mj_step(model, data)

def comm_loop():
    while True:
        read_serial_data()
        send_control_cmd()

Thread(target=sim_loop).start()
Thread(target=comm_loop).start()

同步机制：

• 使用threading.Lock保护共享数据
• 控制周期建议10ms（100Hz）
• 优先保证仿真线程的CPU资源

6. 常见问题速查手册

6.1 启动阶段问题

Q：无法加载模型文件

• 检查XML文件路径是否为相对路径
• 确认assets/目录包含所有依赖的mesh文件
• 运行mj_print so100.xml验证模型有效性

Q：权限拒绝访问/dev/ttyACM0

bash复制sudo usermod -aG dialout $USER
sudo chmod 666 /dev/ttyACM0

需要重新登录生效

6.2 运行时报错

关节超限警告：

1. 检查URDF中的关节限位定义
2. 确认控制指令是否超出物理范围
3. 在控制代码中添加限幅处理：

python复制target_pos = np.clip(target_pos, -3.14, 3.14)

数值不稳定现象：

• 降低仿真步长（如0.001s）
• 增加<option timestep="0.001">
• 检查质量/惯性参数是否合理

7. 扩展开发指南

7.1 添加新传感器

以力传感器为例，修改so100.xml：

xml复制<sensor>
    <force name="ft_sensor" site="tool_center"/>
    <torque name="torque_sensor" site="tool_center"/>
</sensor>

数据读取方式：

python复制force = data.sensor('ft_sensor').data
torque = data.sensor('torque_sensor').data

7.2 ROS集成方案

创建ROS包并安装依赖：

bash复制catkin_create_pkg lerobot_sim rospy mujoco

典型ROS节点结构：

python复制import rospy
from sensor_msgs.msg import JointState

def callback(msg):
    # 将ROS指令转换为Mujoco控制
    data.ctrl = msg.position

rospy.Subscriber('/joint_command', JointState, callback)
pub = rospy.Publisher('/joint_states', JointState, queue_size=10)

8. 最佳实践总结

经过多个项目的实践验证，这些技巧能显著提升开发效率：

1. 版本冻结：使用pip freeze > requirements.txt保存完整依赖
2. 配置分离：将调参部分抽离到config.yaml文件
3. 日志记录：实现数据实时保存功能
4. 可视化调试：开发自定义的调试覆盖层

在实机联动调试时，建议先用低速模式验证基本功能，再逐步提高运行速度。记得定期备份调好的参数配置文件，这些经验值往往比理论计算更可靠。