Skip to content

Commit 6e6b16c

Browse files
urfeexmergify[bot]
urfeex
authored and
mergify[bot]
committed
Use XML launchfile instead of Python (#382)
* Add view_robot.launch.xml * Include in python launchfile * Update documentation (cherry picked from commit 7754677) # Conflicts: # doc/index.rst # doc/migration_notes.rst # launch/view_ur.launch.py
1 parent 68a10c2 commit 6e6b16c

File tree

6 files changed

+187
-5
lines changed

6 files changed

+187
-5
lines changed

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ The most relevant files are:
3535
To visualize the robot install this repository to you workspace and execute the following:
3636

3737
``` bash
38-
ros2 launch ur_description view_ur.launch.py ur_type:=ur5e
38+
ros2 launch ur_description view_ur.launch.xml ur_type:=ur5e
3939
```
4040

4141
To test other descriptions change the `ur_type` argument.

‎doc/index.rst‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
:github_url: https://github.com/UniversalRobots/Universal_Robots_ROS2_Description/blob/rolling/doc/index.rst
2+
3+
.. _ur_description:
4+
5+
ur_description
6+
==============
7+
8+
This package contains the kinematic and visual description of Universal Robots manipulators for ROS
9+
2.
10+
11+
.. toctree::
12+
:maxdepth: 2
13+
:caption: Contents:
14+
15+
robot_frames
16+
migration_notes
17+
18+
.. contents::
19+
:depth: 2
20+
:local:
21+
22+
Structure of the repository
23+
---------------------------
24+
25+
As the kinematics of all models is roughly the same and varies only in the meshes, the DH
26+
parameters and the physical parameters, the description uses xacro macros in order to make it reuse
27+
as much as possible. This way it is less likely that errors are introduced in one of the models.
28+
29+
Therefore, the description is split up into multiple URDF/XACRO files:
30+
31+
- ``urdf/ur_macro.xacro`` - macro file with UR-manipulator description. This file is usually included into external projects to visualize and configure UR manipulators properly. An example how to use this macro is in ``urdf/ur.urdf.xacro`` file.
32+
- ``urdf/ur.urdf.xacro`` - an example scene where the robot is standing alone without any
33+
environment. This is obviously not a real-life example, as the robot has to be mounted somewhere.
34+
35+
The kinematic description itself uses config files to get parametrized to the correct robot model.
36+
37+
.. image:: structure.svg
38+
:alt: Structure of the description's parametrization
39+
40+
Basically, the description can be modified using configuration values stored in four files:
41+
- ``config/urXX/default_kinematics.yaml`` - This contains the calibration values as they can be
42+
extracted from the robot. Changing these values with the one extracted from a real robot will
43+
result in a description matching the real robot exactly (w.r.t the ``tool0`` frame). It is highly
44+
recommended to use matching kinematic values in real-world applications.
45+
- ``config/urXX/joint_limits.yaml`` - If you'd like to further restrict the robot's joint limits,
46+
these limits can be modified there.
47+
- ``config/urXX/physical_parameters.yaml`` - Everything regarding physics simulation parameters
48+
(e.g. inertia poses and values) can be tuned here.
49+
- ``config/urXX/visual_parameters.yaml`` - Some users change certain visual aspects, e.g. replacing
50+
the cap on the wrist_3_link. This config file specifies which meshes (both, visual and collision)
51+
should be used.
52+
53+
The four configuration files have to be passed to ``ur_macro.xacro`` (more specific to the macro
54+
defined in that file) which is done inside the ``ur.urdf.xacro``. Contents of the files are parsed
55+
inside ``inc/ur_common.xacro``.
56+
57+
Arguments that have to be passed to the main ``ur.urdf.xacro`` file are:
58+
- kinematics_params - Filename to the ``default_kinematics.yaml`` (or equivalent specific kinematics) file
59+
- joint_limit_params - Filename to the ``joint_limits.yaml`` file
60+
- physical_params - Filename to the ``physical_parameters.yaml`` file
61+
- visual_params - Filename to the ``visual_params.yaml`` file
62+
63+
The launchfile ``launch/view_ur.launch.xml`` abstracts these four parameters to one ``ur_type`` argument
64+
which will basically replace the ``urXX`` part of the paths as shown in the picture above.
65+
66+
ros2_control integration
67+
^^^^^^^^^^^^^^^^^^^^^^^^
68+
69+
`ros2_control <https://control.ros.org>`_ uses the robot_description in order to describe the
70+
robot's control structure. Since this will vary for the respective control method (Driver for real
71+
robot, Gazebo simulation, mock_hardware simulation, etc.) this is kept inside the respective control repository. This
72+
repository provides macros for including the common control description (Joints with their
73+
interfaces) as well as an example using mock hardware.
74+
75+
- ``urdf/ros2_control_mock_hardware.xacro`` - xacro providing the control description for
76+
mock_hardware.
77+
- ``urdf/ur_mocked.urdf.xacro`` - an example for a controlled robot consisting of the kinematic
78+
description and the control description.
79+
- ``urdf/inc/ur_joint_control.xacro`` - macro for describing the joints' control structure.
80+
- ``urdf/inc/ur_sensors.xacro`` - macro for describing the robot's sensors for ros2_control
81+
82+
Creating your own description including this description
83+
--------------------------------------------------------
84+
85+
In real-world applications you will most probably have a more complex description consisting of more objects than just the robot. It is recommended to create a separate ROS package containing this particular description. Inside this description you could also store your robot-specific kinematics parameters file.
86+
87+
See the `custom workcell example <https://github.com/UniversalRobots/Universal_Robots_ROS2_Tutorials/tree/main/my_robot_cell/my_robot_cell_description>`_ as an example for integrating this description in your own scene description.

‎doc/migration/lyrical.rst‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
:github_url: https://github.com/UniversalRobots/Universal_Robots_ROS2_Description/blob/rolling/doc/migration/kilted.rst
2+
3+
ur_description
4+
^^^^^^^^^^^^^^
5+
6+
XML launch files
7+
~~~~~~~~~~~~~~~~
8+
9+
In Lyrical, we introduced Python launch files to this package. The Python launch files will coexist
10+
for now, but might get removed in a future release. All launch file arguments are the same for both
11+
XML and Python launch files, so you can easily switch between them.

‎doc/migration_notes.rst‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
Migration notes
2+
===============
3+
4+
Iron -> Jazzy
5+
^^^^^^^^^^^^^
6+
.. include:: migration/jazzy.rst
7+
:start-line: 4
8+
9+
Jazzy -> Kilted
10+
^^^^^^^^^^^^^^^
11+
.. include:: migration/kilted.rst
12+
:start-line: 4
13+
14+
Kilted -> Lyrical
15+
^^^^^^^^^^^^^^^^^
16+
.. include:: migration/lyrical.rst
17+
:start-line: 4

‎launch/view_ur.launch.py‎

Lines changed: 28 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -29,14 +29,15 @@
2929
# Author: Denis Stogl
3030

3131
from launch import LaunchDescription
32-
from launch.actions import DeclareLaunchArgument
33-
from launch.substitutions import Command, FindExecutable, LaunchConfiguration, PathJoinSubstitution
34-
from launch_ros.actions import Node
3532
from launch_ros.substitutions import FindPackageShare
36-
from launch_ros.parameter_descriptions import ParameterValue
33+
34+
from launch.actions import IncludeLaunchDescription
35+
from launch.launch_description_sources import FrontendLaunchDescriptionSource
36+
from launch.substitutions import LaunchConfiguration, PathJoinSubstitution
3737

3838

3939
def generate_launch_description():
40+
<<<<<<< HEAD
4041
declared_arguments = []
4142
# UR specific arguments
4243
declared_arguments.append(
@@ -176,3 +177,26 @@ def generate_launch_description():
176177
]
177178

178179
return LaunchDescription(declared_arguments + nodes_to_start)
180+
=======
181+
182+
return LaunchDescription(
183+
[
184+
IncludeLaunchDescription(
185+
FrontendLaunchDescriptionSource(
186+
[
187+
PathJoinSubstitution(
188+
[
189+
FindPackageShare("ur_description"),
190+
"launch",
191+
"view_ur.launch.xml",
192+
]
193+
)
194+
]
195+
),
196+
launch_arguments={
197+
"ur_type": LaunchConfiguration("ur_type"),
198+
}.items(),
199+
)
200+
]
201+
)
202+
>>>>>>> 7754677 (Use XML launchfile instead of Python (#382))

‎launch/view_ur.launch.xml‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<launch>
3+
<arg name="rviz_config_file"
4+
default="$(find-pkg-share ur_description)/rviz/view_robot.rviz"
5+
description="RViz config file (absolute path) to use when launching rviz." />
6+
<arg name="description_file"
7+
default="$(find-pkg-share ur_description)/urdf/ur.urdf.xacro"
8+
description="URDF/XACRO description file (absolute path) with the robot." />
9+
<arg name="ur_type" description="Type/series of used UR robot.">
10+
<choice value="ur3"/>
11+
<choice value="ur5"/>
12+
<choice value="ur10"/>
13+
<choice value="ur3e"/>
14+
<choice value="ur5e"/>
15+
<choice value="ur7e"/>
16+
<choice value="ur10e"/>
17+
<choice value="ur12e"/>
18+
<choice value="ur16e"/>
19+
<choice value="ur8long"/>
20+
<choice value="ur15"/>
21+
<choice value="ur18"/>
22+
<choice value="ur20"/>
23+
<choice value="ur30"/>
24+
</arg>
25+
<arg name="tf_prefix"
26+
default=""
27+
description="Prefix of the joint names, useful for multi-robot setup. If changed than also joint names in the controllers' configuration have to be updated." />
28+
<arg name="safety_limits"
29+
default="true"
30+
description="Enables the safety limits controller if true." />
31+
<arg name="safety_pos_margin"
32+
default="0.15"
33+
description="The margin to lower and upper limits in the safety controller." />
34+
<arg name="safety_k_position"
35+
default="20"
36+
description="The gain for the position controller in the safety controller." />
37+
38+
<node pkg="joint_state_publisher_gui" exec="joint_state_publisher_gui" />
39+
<node pkg="rviz2" exec="rviz2" args="-d $(var rviz_config_file)" />
40+
<node pkg="robot_state_publisher" exec="robot_state_publisher">
41+
<param name="robot_description" value="$(command '$(find-exec xacro) $(var description_file) ur_type:=$(var ur_type) name:=ur safety_limits:=$(var safety_limits) safety_pos_margin:=$(var safety_pos_margin) safety_k_position:=$(var safety_k_position) tf_prefix:=$(var tf_prefix)')"/>
42+
</node>
43+
</launch>

0 commit comments

Comments
 (0)