This repository contains various examples for how to template description files in ROS 2. Each example demonstrates the use of a templating engine, with a description format, at compile time or launch time. All examples have the same final result, which makes it easy to compare them side-by-side.
Templating engines:
Description formats:
Is your engine or format of choice not represented? Consider opening a pull request to add it!
-
Install ROS Humble or higher
-
Clone this repository:
mkdir -p ~/ws/src cd ~/ws/src git clone https://github.com/chapulina/desplate
-
Install dependencies:
cd ~/ws rosdep install --from-paths src --ignore-src -r -y
-
Build and install:
cd ~/ws colcon build
-
Run one of the examples, i.e.:
ros2 launch desplate_empy vehicle_sdf_generate.launch.py
-
You should see a differential drive robot (like dolly) on RViz:
-
Also try checking the inertia visualization:
Templating engine | Format | Stage | Command |
---|---|---|---|
EmPy | SDF | launch | ros2 launch desplate_empy vehicle_sdf_generate.launch.py |
EmPy | URDF | launch | ros2 launch desplate_empy vehicle_urdf_generate.launch.py |
EmPy | SDF | compilation | ros2 launch desplate_empy vehicle_sdf_installed.launch.py |
EmPy | URDF | compilation | ros2 launch desplate_empy vehicle_urdf_installed.launch.py |
ERB | SDF | launch | ros2 launch desplate_erb vehicle_sdf_generate.launch.py |
ERB | URDF | launch | ros2 launch desplate_erb vehicle_urdf_generate.launch.py |
ERB | SDF | compilation | ros2 launch desplate_erb vehicle_sdf_installed.launch.py |
ERB | URDF | compilation | ros2 launch desplate_erb vehicle_urdf_installed.launch.py |
Xacro | SDF | launch | ros2 launch desplate_xacro vehicle_sdf_generate.launch.py |
Xacro | URDF | launch | ros2 launch desplate_xacro vehicle_urdf_generate.launch.py |
Xacro | SDF | compilation | ros2 launch desplate_xacro vehicle_sdf_installed.launch.py |
Xacro | URDF | compilation | ros2 launch desplate_xacro vehicle_urdf_installed.launch.py |
Generating description files at launch time is convenient if you're often iterating on parameters for those files. On the other hand, if your files aren't changing much, consider generating them at compile time to save some time every time you launch.
Generate templates at launch file following these steps:
-
Install all template files, i.e.:
desplate/desplate_empy/CMakeLists.txt
Lines 39 to 46 in 86b7960
-
In a launch file, get the path to the installed template file, for example:
desplate/desplate_empy/launch/vehicle_sdf_generate.launch.py
Lines 30 to 31 in 86b7960
-
Use the templating engine to generate a file and store it in a string variable. See each engine below.
-
Pass that description string to another node. For robots, that's usually
robot_state_publisher
, i.e.:desplate/desplate_common/launch/visualize.launch.py
Lines 40 to 45 in 86b7960
Add these lines to a launch file to generate a description from an EmPy template:
desplate/desplate_empy/launch/vehicle_sdf_generate.launch.py
Lines 33 to 36 in 86b7960
Add this line to a launch file to generate a description from an ERB template:
desplate/desplate_erb/launch/vehicle_sdf_generate.launch.py
Lines 32 to 33 in 86b7960
Add this line to a launch file to generate a description from a Xacro template:
desplate/desplate_xacro/launch/vehicle_sdf_generate.launch.py
Lines 33 to 34 in 86b7960
Generating description files at compile time is efficient if you're not iterating on parameters for those files, because you're not generating them over and over every time the application is launched. On the other hand, if your files often take different arguments for each run, consider generating them at launch time.
Generate templates at compile file following these steps:
-
Invoke the templating engine with CMake to generate the description into the
build
directory. One way to do it is creating a custom command and making a target that depends on it. The difference for each engine will be what command is invoked, see below for each engine.desplate/desplate_empy/CMakeLists.txt
Lines 11 to 20 in 86b7960
-
Install the generated description, i.e.:
desplate/desplate_empy/CMakeLists.txt
Lines 47 to 54 in 86b7960
-
In a launch file, find the installed description and store it in a string, i.e.:
desplate/desplate_empy/launch/vehicle_sdf_installed.launch.py
Lines 28 to 33 in 86b7960
-
Pass that description string to another node. For robots, that's usually
robot_state_publisher
, i.e.:desplate/desplate_common/launch/visualize.launch.py
Lines 40 to 45 in 86b7960
Invoke empy
on .em
files from the custom CMake command:
desplate/desplate_empy/CMakeLists.txt
Lines 14 to 16 in 86b7960
Invoke erb
on .erb
files from the custom CMake command:
desplate/desplate_erb/CMakeLists.txt
Lines 14 to 16 in 86b7960
Invoke xacro
on .xacro
files from the custom CMake command:
desplate/desplate_xacro/CMakeLists.txt
Lines 14 to 16 in 86b7960
This package makes it possible to compare how the same result can be achieved using different templating engines and description formats. You can use a tool like Meld to see these files side-by-side.
For example, to compare Xacro and EmPy:
Or to compare URDF and SDF: