dual arm tutorial documentation

Author: URJala

my_dual_robot_cell/doc/assemble_urdf.rst

@@ -0,0 +1,113 @@
+:github_url: https://github.com/UniversalRobots/Universal_Robots_ROS2_Tutorials/blob/main/my_dual_robot_cell/doc/assemble_urdf.rst
+
+Assembling the URDF
+===================
+
+The `ur_description <https://github.com/UniversalRobots/Universal_Robots_ROS2_Description>`_ package provides `macro files <https://github.com/UniversalRobots/Universal_Robots_ROS2_Description/blob/rolling/urdf/ur_macro.xacro>`_ to generate an instance of a Universal Robots arm.
+We'll use this to create a custom workcell with two robots in it, both a UR3e (called Alice) and a UR5e (called Bob). In this section we will only go into
+detail about the URDF / xacro files, not the complete package structure. Please see the
+`description package source code
+<https://github.com/UniversalRobots/Universal_Robots_ROS2_Tutorials/blob/main/my_robot_cell/my_robot_cell_description>`_ for all other files assembling the description package.
+
+Workcell description
+--------------------
+
+.. literalinclude:: ../my_dual_robot_cell_description/urdf/my_dual_robot_cell.urdf.xacro
+    :language: xml
+    :linenos:
+    :caption: my_robot_cell_description/urdf/my_robot_cell.urdf.xacro
+
+Let's break it down:
+
+First, we'll have to **include** the macro to generate our custom workcell:
+
+.. literalinclude:: ../my_dual_robot_cell_description/urdf/my_dual_robot_cell.urdf.xacro
+    :language: xml
+    :start-at:   <xacro:include filename="$(find my_dual_robot_cell_description)/urdf/my_dual_robot_cell_macro.xacro"/>
+    :end-at:   <xacro:include filename="$(find my_dual_robot_cell_description)/urdf/my_dual_robot_cell_macro.xacro"/>
+    :caption: my_dual_robot_cell_description/urdf/my_dual_robot_cell.urdf.xacro
+
+This line only loads the macro for generating the robot workcell.
+
+We will need to provide some parameters to our workcell in order to parametrize the arms. Therefore,
+we need to declare certain arguments that must be passed to the macro.
+
+.. literalinclude:: ../my_dual_robot_cell_description/urdf/my_dual_robot_cell.urdf.xacro
+    :language: xml
+    :start-at:   <xacro:arg name="alice_ur_type" default="ur3e"/>
+    :end-at:      <xacro:arg name="bob_visual_parameters_file" default="$(find ur_description)/config/$(arg bob_ur_type)/visual_parameters.yaml"/>
+    :caption: my_dual_robot_cell_description/urdf/my_dual_robot_cell.urdf.xacro
+
+The workspace macro contains all items within the workcell including the robot arm. If you are not
+experienced in writing URDFs, you may want to refer to this  `tutorial
+<https://docs.ros.org/en/rolling/Tutorials/Intermediate/URDF/URDF-Main.html>`_. The macro's content
+is generated using
+
+.. literalinclude:: ../my_dual_robot_cell_description/urdf/my_dual_robot_cell.urdf.xacro
+    :language: xml
+    :start-at:     <link name="world"/>
+    :end-at:       </xacro:my_dual_robot_cell>
+    :caption: my_dual_robot_cell_description/urdf/my_dual_robot_cell.urdf.xacro
+
+Here, a ``world`` link is created, and the robot workcell is created relative to the ``world`` link.
+
+Workcell macro
+--------------
+
+The workcell macro is defined in the following manner:
+
+.. literalinclude:: ../my_dual_robot_cell_description/urdf/my_dual_robot_cell_macro.xacro
+    :language: xml
+    :linenos:
+    :caption: my_dual_robot_cell_description/urdf/my_dual_robot_cell_macro.xacro
+
+This macro provides an example of what a custom workcell could resemble. Your workspace will likely
+vary from this one. Please feel free to modify this portion of the URDF to match your own setup. In
+this instance, our workspace comprises a table in front of a wall, featuring a monitor, and the
+two robot arms mounted on top.
+
+Ensure that your custom workcell includes the parent link, which must be passed to the **ur_robot**
+macro. In this example, we chose to create two links, one named **alice_robot_mount** and one named **bob_robot_mount**.
+
+.. literalinclude:: ../my_dual_robot_cell_description/urdf/my_dual_robot_cell_macro.xacro
+    :language: xml
+    :start-at: <link name="alice_robot_mount"/>
+    :end-before: <!--Creates the 1st Robot-->
+    :linenos:
+    :caption: my_dual_robot_cell_description/urdf/my_dual_robot_cell_macro.xacro
+
+After that we are finally able to actually **create the robot arms** by calling the macro.
+
+.. literalinclude:: ../my_dual_robot_cell_description/urdf/my_dual_robot_cell_macro.xacro
+    :language: xml
+    :start-at:   <!--Creates the 1st Robot-->
+    :end-before:   </xacro:macro>
+    :linenos:
+    :caption: my_dual_robot_cell_description/urdf/my_dual_robot_cell_macro.xacro
+
+Note that the **origin** argument is transmitted in a different manner than the other arguments.
+
+Before we can test our code, it's essential to build and source our Colcon workspace:
+
+.. code-block:: bash
+
+    #cd to your colcon workspace root
+    cd ~/colcon_ws
+
+    #source and build your workspace
+    colcon build
+    source install/setup.bash
+
+
+We can view our custom workspace by running:
+
+.. code-block:: bash
+
+    #launch rviz
+    ros2 launch my_dual_robot_cell_description view_robot.launch.py
+
+Use the sliders of the ``joint_state_puplisher_gui`` to move the virtual robots around.
+It should look something like this:
+
+.. image:: rviz.png
+    :alt: RViz window showing the custom workspace

my_dual_robot_cell/doc/build_moveit_config.rst

@@ -0,0 +1,154 @@
+:github_url: https://github.com/UniversalRobots/Universal_Robots_ROS2_Tutorials/blob/main/my_dual_robot_cell/doc/build_moveit_config.rst
+
+
+========================
+Build the MoveIt! config
+========================
+
+At this point, you should be able to run the ``ur_robot_driver`` for your custom UR setup.
+Now, we are only one last step away from actually planning and executing trajectories.
+
+To utilize MoveIt! 2 for this purpose, which will handle trajectory planning for us, we need to set up a MoveIt! configuration package.
+To create such a MoveIt! `configuration package <https://github.com/UniversalRobots/Universal_Robots_ROS2_Tutorials/tree/main/my_dual_robot_cell/my_dual_robot_cell_moveit_config>`_, MoveIt! provides a very useful Setup Assistant.
+
+Setup Assistant
+---------------
+
+We can start the MoveIt! Setup Assistant by running:
+
+.. code-block:: bash
+
+   ros2 launch moveit_setup_assistant setup_assistant.launch.py
+
+Please note that MoveIt! itself provides a detailed `tutorial <https://moveit.picknik.ai/main/doc/examples/setup_assistant/setup_assistant_tutorial.html?highlight=setup%20assistant>`_ on how to use the Setup Assistant, so you may want to go through that.
+Although the Setup Assistant is very straightforward, there are some tips and tricks we want to discuss in the following sections.
+
+The first task the MoveIt! Setup Assistant asks us to do is to load the URDF with the optional xacro arguments. If you would like to change the ``ur_type`` for example, you could also specify that here. For this demonstration we'll go with our description's default values.
+
+.. image:: load_urdf.png
+   :alt: Load a URDF
+
+Next, make sure that the generated **self-collisions** are detected correctly. In our example the robot
+is positioned on the table in such a way, that it collides with the monitor on the table when all
+joints are in the 0 position. Hence, the collision is allowed as "Collision by default". We remove
+that tick, since we don't want that collision to be ignored.
+
+.. image:: self_collisions.png
+   :alt: Adjust self-collisions - Remove the tick for the collision between monitor and ur20_upper_arm_link.
+
+
+We skip adding virtual joints for now and continue with our **planning group(s)**.
+We add a planning group called **ur_arm**. A reasonable and error-resistant approach is to define
+it as a kinematic chain in the following manner:
+
+.. image:: planning_group_kinematics.png
+   :alt: Kinematic setup for our planning group
+
+.. image:: planning_group_chain.png
+   :alt: Kinematic Chain
+
+Your planning groups should look something like this:
+
+.. image:: planning_groups.png
+   :alt: Planning Groups
+
+We'll skip setting up ros2_control related points, since we've already configured that in our
+control package.
+
+In the **MoveIt Controllers** step we setup our desired controller to match the name
+"scaled_joint_trajectory_controller":
+
+.. image:: moveit_controllers.png
+   :alt: MoveIt! coontrollers configuration
+
+We skip **perception** as we don't have any cameras setup in our scenario.
+
+In the next step we modify the **launch files** being generated by the assistant. We only generate
+"RViz Launch and Config", "MoveGroup Launch" and "Setup Assistant Launch". The other launch files
+are for starting a demo using mock hardware, which would basically be a duplication of what we
+already did in our control package. Since we also do not use the Warehouse feature for now, we also
+skip that file.
+
+.. image:: launch_files.png
+   :alt: Select the launch files to be generated
+
+After the **Author information** we select which configuration files to generate. Again, we strip
+down all the files needed for mock hardware startup.
+
+.. image:: config_files.png
+   :alt: Select the config files to be generated
+
+With all the information entered, you can **generate** the package and close the setup assistant.
+
+Manual adaptions
+----------------
+
+Before we can actually use our package we have to adapt the joint limits. Since MoveIt! requires
+joint acceleration limits to be specified but the description doesn't contain those, we need to
+specify these inside the generated ``config/joint_limits.yaml`` file.
+
+They are not part of the arm's description since there are no physical acceleration limits, as
+those are highly dependent on the robot's current pose and TCP force (e.g. induced by the weight
+carried at the TCP). Setting the acceleration limits to ``5.0`` for all joints should be a
+conservative value. Higher values might lead to unwanted slowdowns during execution or even
+protective stops, while lower values will result in slower motions due to slow ramp-up and
+ramp-down parts of the trajectory.
+
+.. literalinclude:: ../my_dual_robot_cell_moveit_config/config/joint_limits.yaml
+   :language: yaml
+   :linenos:
+   :caption: my_dual_robot_cell_moveit_config/config/joint_limits.yaml
+
+Please note that you could also change the default velocity and acceleration scaling in this file.
+Also, if you want to specify any limits (position or velocity) that differ from your description, you
+can set them here. Remember that these will only be used for planning trajectories, not necessarily
+for execution. If you send trajectories from another source than MoveIt!, those limits will not
+apply!
+
+
+Usage
+-----
+
+Before we can test our code, it's essential to build and source our Colcon workspace:
+
+.. code-block:: bash
+
+   #cd to your colcon workspace root
+   cd ~/colcon_ws
+
+   #source and build your workspace
+   colcon build
+   source install/setup.bash
+
+
+Now you are ready to use MoveIt! with two actual robot arms, MoveIt! itself also provides you with the opportunity to start a robot with mock hardware.
+
+To startup the complete system, you'll have to start three launch files in three individual
+terminals.
+
+First, we need to start a robot, simulated or real. If you start a real robot, make sure that the
+*external_control* program is active on the robot.
+
+.. code-block:: bash
+
+   # You can switch to real hardware if you prefer
+   ros2 launch my_dual_robot_cell_control start_robots.launch.py bob_use_mock_hardware:=true alice_use_mock_hardware:=true
+
+
+
+Second, we can start the move_group node by running the launch file the setup assistant created for us:
+
+.. code-block:: bash
+
+    ros2 launch my_dual_robot_cell_moveit_config move_group.launch.py
+
+If everything went well you should see the output: **"You can start planning now!"**.
+
+To interact with the MoveIt! setup, you can start RViz with the correct setup file:
+
+.. code-block:: bash
+
+    ros2 launch my_dual_robot_cell_moveit_config moveit_rviz.launch.py
+
+From that setup you can start developing your application involving a custom move_group interface
+or similar. Please refer to the MoveIt! documentation for further reading.

my_dual_robot_cell/doc/conf.py

@@ -0,0 +1,82 @@
+project = "ur_dual_arm_tutorial"
+copyright = "2025, Universal Robots A/S"
+author = "Jacob Larsen"
+
+# The short X.Y version
+version = ""
+# The full version, including alpha/beta/rc tags
+release = ""
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+source_suffix = [".rst"]
+
+# The master toctree document.
+master_doc = "index"
+
+numfig = True
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = "en"
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "migration/*.rst"]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = None
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "alabaster"
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = ["_static"]
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = "ur_dual_arm_tutorial_doc"

my_dual_robot_cell/doc/figures/rviz.png

@@ -0,0 +1,22 @@
+:github_url: https://github.com/UniversalRobots/Universal_Robots_ROS2_Tutorials/blob/main/my_dual_robot_cell/doc/index.rst
+
+.. _dual_arm_tutorial:
+
+================
+Dual robot arm cell
+================
+
+Example about integrating two UR arms into a custom workspace. We will build a custom workcell
+description containing two robot arms, start the driver and create a MoveIt config to enable trajectory planning with MoveIt.
+
+Please see the `package source code
+<https://github.com/UniversalRobots/Universal_Robots_ROS2_Tutorials/tree/main/my_robot_cell>`_ for
+all files relevant for this example.
+
+.. toctree::
+   :maxdepth: 4
+   :caption: Contents:
+
+   assemble_urdf
+   start_ur_driver
+   build_moveit_config