Simulation Environment

1. Project Overview

Before deploying on the real robot, you can validate algorithm performance in a simulation environment. DEEPRobotics Simulation is a MuJoCo-based simulation environment that communicates with the SDK via ROS2 Topics, providing virtual robot verification capabilities.

1.1 Repository Structure

run_sim.py              # Product launch entry
simulator.py            # MuJoCo lifecycle (load, step, Viewer, close)
sim_config.py           # YAML config loading and validation
requirements.txt        # Python dependencies
worlds/basic/           # Common ground + lighting
worlds/demo/            # Demo terrain assets
<product>/
├── config.yaml          # Runtime parameters
├── scene.xml            # MJCF scene composition
├── mujoco_simulation.py # ROS 2 ↔ MuJoCo bridge node
└── model/               # MJCF model + mesh

1.2 Runtime Pipeline

python3 run_sim.py <product>
  → load_config(config.yaml)
  → MuJoCoSimulator(scene.xml)     # Load model, create Viewer
  → DR2ProSimulation(Node)         # ROS 2 node
      Sub: /JOINTS_CMD             # SDK → Simulation
      Pub: /JOINTS_DATA            # Joint state feedback
      Pub: /IMU_DATA_HEAD, /IMU_DATA_BASE  # IMU data
  → Main loop: spin → apply_cmd → mj_step → sync_viewer → publish

2. Quick Start

2.1 Environment Requirements

Ubuntu	ROS 2	Python
22.04	Humble	3.10
24.04	Jazzy	3.12

Prerequisites: Install ROS 2 and the drdds message interface library (see deep-robotics-msg).

2.2 Initial Setup

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 Launch

# Terminal 1: Simulation
source /opt/ros/<ros-distro>/setup.bash
source .venv/bin/activate
python3 run_sim.py dr02_pro

# Terminal 2: SDK (see deep-robotics-sdk2 documentation)
ros2 run dr02_pro state_machine

Note: Both sides must use the same ROS 2 distribution, drdds version, and ROS_DOMAIN_ID.

3. Configuration System

The file directory contains config.yaml:

scene: scene.xml                  # MJCF scene path (relative to config.yaml)
simulation:
  timestep_s: 0.001               # Physics timestep
  publish_frequency_hz: 500.0     # Topic publish frequency
  command_timeout_s: 0.3          # Command timeout
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

Parameters are automatically validated at load time, allowing configuration errors to be caught during startup.

4. Control Modes

Mode	Control Scope
whole (default)	Control all 29 actuators
upper	Control only waist + dual arms (17); legs locked by equality constraints

The upper mode fixes the lower body by activating the upper_*_lock constraints in the MJCF.

Command Timeout Handling:

• whole mode: Output zero torque and continue simulation
• upper mode: Pause physics and maintain posture; resume when new commands are received

5. Joint Mapping

The SDK defines 31 DOF, while the MuJoCo model has 29 actuators. The last two are virtual joints with state filled as 0.

IMU Data: IMU data comes from model sensors base_quat, base_omega, base_acc, and is currently published to both HEAD and BASE topics simultaneously.

6. Scene Composition

scene.xml composes components via include:

<include file="model/dr02_pro.xml"/>        <!-- Robot model -->
<include file="../worlds/basic/basic.xml"/>  <!-- Ground + lighting (required) -->
<include file="../worlds/demo/demo.xml"/>    <!-- Demo terrain (optional) -->

Notes:

• Replace the third include to load a custom world
• whole mode requires collision ground
• model/dr02_pro.urdf is for structural reference only and is not loaded

7. Extension Guide

7.1 Adding a New Environment

1. Create a <product>/ directory containing config.yaml, scene.xml, mujoco_simulation.py, model/
2. Add a dispatch branch in run_sim.py:

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

7.2 Custom Worlds

Create assets under worlds/ and include them in scene.xml. Include paths are relative to the XML file that references them.

8. SDK Compatibility

SDK Program	Simulation Support
state_machine	Supported
joints_example / arm_joint_example / arm_action_example	Supported
High-level motion examples	Not supported (does not go through /JOINTS_CMD)
Peripheral / Audio examples	Not supported

Important: BUILD_SIM=ON is for simulation only and must not be used for real robot control. Do not run simulation-compiled builds on the real robot.