仿真环境

1. 项目总览

在进行实机部署前，可以在仿真环境中进行算法性能验证。DEEPRobotics Simulation 是基于 MuJoCo 的仿真环境，通过 ROS2 Topic 与 SDK 通信，为 SDK 提供虚拟机器人验证能力。

1.1 仓库结构

run_sim.py              # 产品启动入口
simulator.py            # MuJoCo 生命周期（加载、步进、Viewer、关闭）
sim_config.py           # YAML 配置加载与校验
requirements.txt        # Python 依赖
worlds/basic/           # 公共地面 + 灯光
worlds/demo/            # 演示地形资源
<product>/
├── config.yaml          # 运行参数
├── scene.xml            # MJCF 场景组合
├── mujoco_simulation.py # ROS 2 ↔ MuJoCo 桥接节点
└── model/               # MJCF 模型 + mesh

1.2 运行链路

python3 run_sim.py <product>
  → load_config(config.yaml)
  → MuJoCoSimulator(scene.xml)     # 加载模型、创建 Viewer
  → DR2ProSimulation(Node)         # ROS 2 节点
      Sub: /JOINTS_CMD             # SDK → 仿真
      Pub: /JOINTS_DATA            # 关节状态反馈
      Pub: /IMU_DATA_HEAD, /IMU_DATA_BASE  # IMU 数据
  → 主循环: spin → apply_cmd → mj_step → sync_viewer → publish

2. 快速开始

2.1 环境要求

Ubuntu	ROS 2	Python
22.04	Humble	3.10
24.04	Jazzy	3.12

前置要求： 安装 ROS 2 和 drdds 消息接口库（见 deep-robotics-msg）。

2.2 首次配置

source /opt/ros/<ros-distro>/setup.bash
python3 -m venv --system-site-packages .venv
source .venv/bin/activate
pip install -r requirements.txt

2.3 启动

# 终端 1：仿真
source /opt/ros/<ros-distro>/setup.bash
source .venv/bin/activate
python3 run_sim.py dr02_pro

# 终端 2：SDK（见 deep-robotics-sdk2 文档）
ros2 run dr02_pro state_machine

注意： 两端须使用相同 ROS 2 发行版、drdds 版本和 ROS_DOMAIN_ID。

3. 配置系统

文件目录下有 config.yaml：

scene: scene.xml                  # MJCF 场景路径（相对于 config.yaml）
simulation:
  timestep_s: 0.001               # 物理步长
  publish_frequency_hz: 500.0     # Topic 发布频率
  command_timeout_s: 0.3          # 命令超时
control:
  mode: default                   # default | whole | upper
viewer:
  enabled: true
  update_frequency_hz: 25.0
  distance: 3.0
  lookat: [0.0, 0.0, 0.8]
  azimuth: 45.0
  elevation: -30.0

加载时自动校验参数合法性，启动阶段即可发现配置错误。

4. 控制模式

模式	控制范围
whole（默认）	控制全部 29 个执行器
upper	仅控制腰部 + 双臂（17 个），腿部由等式约束锁定

upper 模式通过激活 MJCF 中的 upper_*_lock 约束固定下半身。

命令超时处理：

• whole 模式：输出 0 力矩继续仿真
• upper 模式：暂停物理并保持姿态，收到新命令后恢复

5. 关节映射

SDK 定义 31 DOF，MuJoCo 模型 29 个执行器。后两个为虚拟关节，状态填充 0。

IMU 数据： IMU 数据来自模型传感器 base_quat、base_omega、base_acc，当前同时发布到 HEAD 和 BASE 两个 Topic。

6. 场景组合

scene.xml 通过 include 组合各组件：

<include file="model/dr02_pro.xml"/>        <!-- 机器人模型 -->
<include file="../worlds/basic/basic.xml"/>  <!-- 地面 + 灯光（必须） -->
<include file="../worlds/demo/demo.xml"/>    <!-- 演示地形（可选） -->

注意事项：

• 替换第三个 include 可加载自定义世界
• whole 模式必须有碰撞地面
• model/dr02_pro.urdf 仅作结构参考，不参与加载

7. 扩展指南

7.1 新增环境

1. 创建 <product>/ 目录，包含 config.yaml、scene.xml、mujoco_simulation.py、model/
2. 在 run_sim.py 添加分发分支：

elif argv[1] == "<product>":
    from <product>.mujoco_simulation import run
    return run(REPOSITORY_ROOT / "<product>" / "config.yaml")

7.2 自定义世界

在 worlds/ 下创建资源，在 scene.xml 中 include 即可。include 路径相对于引用它的 XML。

8. SDK 兼容范围

SDK 程序	仿真支持
state_machine	支持
joints_example / arm_joint_example / arm_action_example	支持
高层运动示例	不支持（不经过 /JOINTS_CMD）
外设 / 音频示例	不支持

重要： BUILD_SIM=ON 仅用于仿真，不得用于实机控制。仿真编译后不得在实机上运行。