Run a simulation
How to Run the Simulation with a ROS 2 Launch File
A ROS 2 Launch File is a powerful tool for automating the startup and configuration of nodes. It allows you to run complex applications with a single, reproducible command.
This page breaks down a sample launch file to explain how it works and provides the steps to run your simulation.
Understanding the Launch File
Below is a typical launch file for starting the simulation. Let’s break down what each part of the code does.
your_launch_file.launch.py
:
import os
from ament_index_python.packages import get_package_share_directory
from launch import LaunchDescription
from launch.actions import IncludeLaunchDescription, DeclareLaunchArgument
from launch.launch_description_sources import PythonLaunchDescriptionSource
from launch.substitutions import LaunchConfiguration
def generate_launch_description():
mujoco_pkg_share = get_package_share_directory('dr_mujoco')
simulation_launch_path = os.path.join(
mujoco_pkg_share, 'launch', 'default.launch.py'
)
package_path = get_package_share_directory('<your_package_name>')
robot_model_path_arg = DeclareLaunchArgument(
'robot_model',
default_value=os.path.join(package_path, 'mujoco', '<your_robot_model>.xml')
)
simulation_include = IncludeLaunchDescription(
PythonLaunchDescriptionSource(simulation_launch_path),
launch_arguments={
'robot': LaunchConfiguration('robot_model')
}.items()
)
return LaunchDescription([
robot_model_path_arg,
simulation_include,
])
1. Defining a Launch Argument (DeclareLaunchArgument
)
This part is the key to the launch file’s flexibility.
robot_model_path_arg = DeclareLaunchArgument(
'robot_model',
default_value=os.path.join(package_path, 'mujoco', '<your_robot_model>.xml')
)
DeclareLaunchArgument
defines an argument that can be passed from the command line when you runros2 launch
.- Here, we define an argument named
robot_model
. - The
default_value
is the value used automatically if no argument is provided. This lets you set a commonly used model as the default. - This feature allows you to change which model is loaded by simply adding
robot_model:=/path/to/another.xml
to your launch command.
2. Including Another Launch File (IncludeLaunchDescription
)
Launch files can call, or “include,” other launch files to reuse functionality.
simulation_include = IncludeLaunchDescription(
PythonLaunchDescriptionSource(simulation_launch_path),
launch_arguments={
'robot': LaunchConfiguration('robot_model')
}.items()
)
IncludeLaunchDescription
is an action that starts another launch file (in this case, the main simulator,default.launch.py
).- The most important part is
launch_arguments
. This specifies the arguments to pass to the included launch file. - The line
'robot': LaunchConfiguration('robot_model')
means: “Take the value of our localrobot_model
argument and pass it to therobot
argument thatdefault.launch.py
expects.”
This makes your launch file act as a “configuration bridge” between the main simulator and your specific robot model.
Steps to Run the Simulation
Step 1: Prepare Your File and Folder Structure
To run correctly, your files must be placed in specific locations within your package.
colcon_ws/
└── src/
└── <your_package_name>/
├── launch/
│ └── <your_launch_file_name>.launch.py <-- Save the code here
├── mujoco/
│ └── <your_robot_model>.xml <-- Your robot model
└── ...
Step 2: Build Your Workspace
After adding the new launch file, you need to build your workspace so ROS 2 can find it. Run this command from the root of your workspace (e.g., colcon_ws/
).
colcon build --packages-select <your_package_name>
Step 3: Source Your Environment
Once the build is complete, source the setup file to make your package available in the current terminal.
source install/setup.bash
Step 4: Launch the Simulation
Now you are ready to go. Run the following command to start the simulation:
ros2 launch <your_package_name> <your_launch_file_name>.launch.py
If successful, the MuJoCo viewer window will open, displaying the robot defined in your <your_robot_model>.xml
file.
(Advanced) Dynamically Specifying a Model from the Command Line
Thanks to DeclareLaunchArgument
, you can switch models at runtime without editing any files.
ros2 launch <your_package_name> <your_launch_file_name>.launch.py \
robot_model:='<path/to/your/other_robot.xml>'