From 082dd2a90e0b2ac8b69d69bacf662806a7a572b9 Mon Sep 17 00:00:00 2001 From: Felix Exner Date: Mon, 25 Apr 2022 07:32:54 +0200 Subject: [PATCH] Add sphinx documentation (#340) * First version of sphinx doc * Add generated docs to index * Add missing file * URSim-Docker section * Added package overview entry page * Update MoveIt! instructions as in the main README * update ur_robot_driver README links --- .gitignore | 4 + ur_bringup/CMakeLists.txt | 4 + ur_bringup/scripts/start_ursim.sh | 124 +++++++++ ur_robot_driver/README.md | 10 +- ur_robot_driver/doc/ROS_INTERFACE.md | 2 +- ur_robot_driver/doc/conf.py | 175 +++++++++++++ ur_robot_driver/doc/features.md | 27 -- ur_robot_driver/doc/features.rst | 57 +++++ ur_robot_driver/doc/index.rst | 25 ++ .../initial_setup_images/cb3_01_welcome.png | Bin .../cb3_05_urcaps_installed.png | Bin .../cb3_07_installation_excontrol.png | Bin .../cb3_10_prog_structure_urcaps.png | Bin .../cb3_11_program_view_excontrol.png | Bin .../initial_setup_images/e-Series.jpg | Bin .../initial_setup_images/es_01_welcome.png | Bin .../es_05_urcaps_installed.png | Bin .../es_07_installation_excontrol.png | Bin .../es_10_prog_structure_urcaps.png | Bin .../es_11_program_view_excontrol.png | Bin .../install_urcap_cb3.rst} | 37 ++- .../install_urcap_e_series.rst} | 37 ++- .../doc/{ => installation}/real_time.md | 0 .../doc/installation/robot_setup.rst | 88 +++++++ ur_robot_driver/doc/installation/toc.rst | 16 ++ .../doc/installation/ursim_docker.rst | 99 +++++++ ur_robot_driver/doc/make.bat | 35 +++ ur_robot_driver/doc/overview.rst | 22 ++ ur_robot_driver/doc/rosdoc.yaml | 4 - .../doc/setup_tool_communication.md | 58 ----- .../doc/setup_tool_communication.rst | 67 +++++ ur_robot_driver/doc/usage.rst | 242 ++++++++++++++++++ 32 files changed, 1023 insertions(+), 110 deletions(-) create mode 100755 ur_bringup/scripts/start_ursim.sh create mode 100644 ur_robot_driver/doc/conf.py delete mode 100644 ur_robot_driver/doc/features.md create mode 100644 ur_robot_driver/doc/features.rst create mode 100644 ur_robot_driver/doc/index.rst rename ur_robot_driver/doc/{ => installation}/initial_setup_images/cb3_01_welcome.png (100%) rename ur_robot_driver/doc/{ => installation}/initial_setup_images/cb3_05_urcaps_installed.png (100%) rename ur_robot_driver/doc/{ => installation}/initial_setup_images/cb3_07_installation_excontrol.png (100%) rename ur_robot_driver/doc/{ => installation}/initial_setup_images/cb3_10_prog_structure_urcaps.png (100%) rename ur_robot_driver/doc/{ => installation}/initial_setup_images/cb3_11_program_view_excontrol.png (100%) rename ur_robot_driver/doc/{ => installation}/initial_setup_images/e-Series.jpg (100%) rename ur_robot_driver/doc/{ => installation}/initial_setup_images/es_01_welcome.png (100%) rename ur_robot_driver/doc/{ => installation}/initial_setup_images/es_05_urcaps_installed.png (100%) rename ur_robot_driver/doc/{ => installation}/initial_setup_images/es_07_installation_excontrol.png (100%) rename ur_robot_driver/doc/{ => installation}/initial_setup_images/es_10_prog_structure_urcaps.png (100%) rename ur_robot_driver/doc/{ => installation}/initial_setup_images/es_11_program_view_excontrol.png (100%) rename ur_robot_driver/doc/{install_urcap_cb3.md => installation/install_urcap_cb3.rst} (62%) rename ur_robot_driver/doc/{install_urcap_e_series.md => installation/install_urcap_e_series.rst} (63%) rename ur_robot_driver/doc/{ => installation}/real_time.md (100%) create mode 100644 ur_robot_driver/doc/installation/robot_setup.rst create mode 100644 ur_robot_driver/doc/installation/toc.rst create mode 100644 ur_robot_driver/doc/installation/ursim_docker.rst create mode 100644 ur_robot_driver/doc/make.bat create mode 100644 ur_robot_driver/doc/overview.rst delete mode 100644 ur_robot_driver/doc/rosdoc.yaml delete mode 100644 ur_robot_driver/doc/setup_tool_communication.md create mode 100644 ur_robot_driver/doc/setup_tool_communication.rst create mode 100644 ur_robot_driver/doc/usage.rst diff --git a/.gitignore b/.gitignore index c10fba21d..141947570 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,7 @@ install_manifest.txt .directory .vscode .moveit_ci/ +docs_output +docs_build +cross_reference +ur_robot_driver/doc/generated diff --git a/ur_bringup/CMakeLists.txt b/ur_bringup/CMakeLists.txt index b4eedf832..457158a5a 100644 --- a/ur_bringup/CMakeLists.txt +++ b/ur_bringup/CMakeLists.txt @@ -7,4 +7,8 @@ install(DIRECTORY config launch DESTINATION share/${PROJECT_NAME} ) +install(PROGRAMS scripts/start_ursim.sh + DESTINATION lib/${PROJECT_NAME} +) + ament_package() diff --git a/ur_bringup/scripts/start_ursim.sh b/ur_bringup/scripts/start_ursim.sh new file mode 100755 index 000000000..a8f717898 --- /dev/null +++ b/ur_bringup/scripts/start_ursim.sh @@ -0,0 +1,124 @@ +#!/bin/bash + +# copyright 2022 Universal Robots A/S +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright +# notice, this list of conditions and the following disclaimer. +# +# * Redistributions in binary form must reproduce the above copyright +# notice, this list of conditions and the following disclaimer in the +# documentation and/or other materials provided with the distribution. +# +# * Neither the name of the {copyright_holder} nor the names of its +# contributors may be used to endorse or promote products derived from +# this software without specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. + +PERSISTENT_BASE="${HOME}/.ursim" +URCAP_VERSION="1.0.5" + +help() +{ + # Display Help + echo "Starts URSim inside a docker container" + echo + echo "Syntax: `basename "$0"` [-m|s|h]" + echo "options:" + echo " -m Robot model. One of [ur3, ur3e, ur5, ur5e, ur10, ur10e, ur16e]. Defaults to ur5e." + echo " -h Print this Help." + echo +} + +ROBOT_MODEL=UR5 +ROBOT_SERIES=e-series + +validate_model() +{ + case $ROBOT_MODEL in + ur3|ur5|ur10) + ROBOT_MODEL=${ROBOT_MODEL^^} + ROBOT_SERIES=cb3 + ;; + ur3e|ur5e|ur10e|ur16e) + ROBOT_MODEL=${ROBOT_MODEL^^} + ROBOT_MODEL=$(echo ${ROBOT_MODEL:0:$((${#ROBOT_MODEL}-1))}) + ROBOT_SERIES=e-series + ;; + *) + echo "Not a valid robot model: $ROBOT_MODEL" + exit + ;; + esac +} + + +while getopts ":hm:s:" option; do + case $option in + h) # display Help + help + exit;; + m) # robot model + ROBOT_MODEL=${OPTARG} + validate_model + ;; + \?) # invalid option + echo "Error: Invalid option" + help + exit;; + esac +done + +URCAP_STORAGE="${PERSISTENT_BASE}/${ROBOT_SERIES}/urcaps" +PROGRAM_STORAGE="${PERSISTENT_BASE}/${ROBOT_SERIES}/programs" + +# Create local storage for programs and URCaps +mkdir -p "${URCAP_STORAGE}" +mkdir -p "${PROGRAM_STORAGE}" + +# Download external_control URCap +if [[ ! -f "${URCAP_STORAGE}/externalcontrol-${URCAP_VERSION}.jar" ]]; then + curl -L -o "${URCAP_STORAGE}/externalcontrol-${URCAP_VERSION}.jar" \ + "https://github.com/UniversalRobots/Universal_Robots_ExternalControl_URCap/releases/download/v${URCAP_VERSION}/externalcontrol-${URCAP_VERSION}.jar" +fi + +# Check whether network already exists +docker network inspect ursim_net > /dev/null +if [ $? -eq 0 ]; then + echo "ursim_net already exists" +else + echo "Creating ursim_net" + docker network create --subnet=192.168.56.0/24 ursim_net +fi + +# run docker container +docker run --rm -d --net ursim_net --ip 192.168.56.101\ + -v "${URCAP_STORAGE}":/urcaps \ + -v "${PROGRAM_STORAGE}":/ursim/programs \ + -e ROBOT_MODEL="${ROBOT_MODEL}" \ + --name ursim \ + universalrobots/ursim_${ROBOT_SERIES} || exit + +trap "echo killing; docker container kill ursim; exit" SIGINT SIGTERM + +echo "Docker URSim is running" +printf "\nTo access Polyscope, open the following URL in a web browser.\n\thttp://192.168.56.101:6080/vnc.html\n\n" +echo "To exit, press CTRL+C" + +while : +do + sleep 1 +done diff --git a/ur_robot_driver/README.md b/ur_robot_driver/README.md index 3e504b477..4f520eb63 100644 --- a/ur_robot_driver/README.md +++ b/ur_robot_driver/README.md @@ -5,8 +5,7 @@ repository and requires other packages from that repository. Also, see the [main README](../README.md) for information on how to install and startup this driver. ## ROS-API -The ROS API is documented in a [standalone document](doc/ROS_INTERFACE.md). It is auto-generated -using [catkin_doc](https://github.com/fzi-forschungszentrum-informatik/catkin_doc). +The ROS API is documented in a [standalone document](doc/ROS_INTERFACE.md). ## Technical details The following image shows a very coarse overview of the driver's architecture. @@ -23,9 +22,8 @@ available. To actually control the robot, a program node from the **External Control** URCap must be running on the robot interpreting commands sent from an external source. When this program is not running, no -controllers moving the robot around will be available, which is handled by the -[controller_stopper](../controller_stopper/README.md). Please see the [initial setup -guide](../README.md) on how to install and start this on the robot. +controllers moving the robot around will be available. Please see the [initial setup +guide](doc/installation/robot_setup.rst) on how to install and start this on the robot. The URScript that will be running on the robot is requested by the **External Control** program node from the remote ROS PC. The robot *ur_control.launch* file has a parameter called `urscript_file` to @@ -48,7 +46,7 @@ dashboard services. For using the **tool communication interface** on e-Series robots, a `socat` script is prepared to forward the robot's tool communication interface to a local device on the ROS PC. See [the tool -communication setup guide](doc/setup_tool_communication.md) for details. +communication setup guide](doc/setup_tool_communication.rst) for details. This driver is using [ROS-Control](https://wiki.ros.org/ros_control) for any control statements. Therefore, it can be used with all position-based controllers available in ROS-Control. However, we diff --git a/ur_robot_driver/doc/ROS_INTERFACE.md b/ur_robot_driver/doc/ROS_INTERFACE.md index 38b08c26f..829302e0a 100644 --- a/ur_robot_driver/doc/ROS_INTERFACE.md +++ b/ur_robot_driver/doc/ROS_INTERFACE.md @@ -1,6 +1,6 @@ **NOTE**: This documentation is obsolete and does not cover in full the current state of driver. -# ur_robot_driver +# ROS interface The new driver for Universal Robots UR3, UR5 and UR10 robots with CB3 controllers and the e-series. diff --git a/ur_robot_driver/doc/conf.py b/ur_robot_driver/doc/conf.py new file mode 100644 index 000000000..1c42fdb8c --- /dev/null +++ b/ur_robot_driver/doc/conf.py @@ -0,0 +1,175 @@ +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = "ur_robot_driver" +copyright = "2022, Universal Robots A/S" +author = "Felix Exner" + +# 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", ".md"] + +# The master toctree document. +master_doc = "index" + +# 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 = None + +# 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"] + +# 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_robot_driverdoc" + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ( + master_doc, + "ur_robot_driver.tex", + "ur\\_robot\\_driver Documentation", + "Felix Exner", + "manual", + ), +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [(master_doc, "ur_robot_driver", "ur_robot_driver Documentation", [author], 1)] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ( + master_doc, + "ur_robot_driver", + "ur_robot_driver Documentation", + author, + "ur_robot_driver", + "One line description of project.", + "Miscellaneous", + ), +] + + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ["search.html"] diff --git a/ur_robot_driver/doc/features.md b/ur_robot_driver/doc/features.md deleted file mode 100644 index d8a72d260..000000000 --- a/ur_robot_driver/doc/features.md +++ /dev/null @@ -1,27 +0,0 @@ -# Feature list and roadmap - -| Feature | ROS2 Driver -| --- | --- | -| joint-position-based control | yes | -| scaled joint-position-based control | yes | -| joint-velocity-based control | yes1 | -| Cartesian position-based control | no | -| Cartesian twist-based control | no | -| Trajectory forwarding for execution on robot | no | -| reporting of tcp wrench | yes | -| pausing of programs | yes | -| continue trajectories after EM-Stop resume | yes | -| continue trajectories after protective stop | yes | -| panel interaction in between possible | yes | -| get and set IO states | yes | -| use [tool communication forwarder](https://github.com/UniversalRobots/Universal_Robots_ToolComm_Forwarder_URCap) on e-series | yes | -| use the driver without a teach pendant necessary | yes | -| support of CB1 and CB2 robots | no | -| trajectory extrapolation on robot on missing packages | yes | -| use ROS as drop-in for TP-programs | yes | -| headless mode | yes | -| extract calibration from robot | yes | -| send custom script commands to robot | no | -| Reconnect on a disconnected robot | yes | - -1 Velocity-based joint control is implemented in the driver, but the current version of ros2_control do not yet support Velocity-based joint trajectory control diff --git a/ur_robot_driver/doc/features.rst b/ur_robot_driver/doc/features.rst new file mode 100644 index 000000000..535f3be37 --- /dev/null +++ b/ur_robot_driver/doc/features.rst @@ -0,0 +1,57 @@ +.. role:: raw-html-m2r(raw) + :format: html + + +Feature list and roadmap +------------------------ + +.. list-table:: + :header-rows: 1 + + * - Feature + - ROS2 Driver + * - joint-position-based control + - yes + * - scaled joint-position-based control + - yes + * - joint-velocity-based control + - yes\ :raw-html-m2r:`1` + * - Cartesian position-based control + - no + * - Cartesian twist-based control + - no + * - Trajectory forwarding for execution on robot + - no + * - reporting of tcp wrench + - yes + * - pausing of programs + - yes + * - continue trajectories after EM-Stop resume + - yes + * - continue trajectories after protective stop + - yes + * - panel interaction in between possible + - yes + * - get and set IO states + - yes + * - use `tool communication forwarder `_ on e-series + - yes + * - use the driver without a teach pendant necessary + - yes + * - support of CB1 and CB2 robots + - no + * - trajectory extrapolation on robot on missing packages + - yes + * - use ROS as drop-in for TP-programs + - yes + * - headless mode + - yes + * - extract calibration from robot + - yes + * - send custom script commands to robot + - no + * - Reconnect on a disconnected robot + - yes + + +:raw-html-m2r:`1` Velocity-based joint control is implemented in the driver, but the current version of ros2_control do not yet support Velocity-based joint trajectory control diff --git a/ur_robot_driver/doc/index.rst b/ur_robot_driver/doc/index.rst new file mode 100644 index 000000000..bf536ad81 --- /dev/null +++ b/ur_robot_driver/doc/index.rst @@ -0,0 +1,25 @@ +.. ur_robot_driver documentation master file, created by + sphinx-quickstart on Fri Apr 8 13:58:02 2022. + You can adapt this file completely to your liking, but it should at least + contain the root ``toctree`` directive. + +Welcome to ur_robot_driver's documentation! +=========================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + overview + installation/toc + usage + setup_tool_communication + ROS_INTERFACE + generated/index + + + +Indices and tables +================== + +* :ref:`genindex` diff --git a/ur_robot_driver/doc/initial_setup_images/cb3_01_welcome.png b/ur_robot_driver/doc/installation/initial_setup_images/cb3_01_welcome.png similarity index 100% rename from ur_robot_driver/doc/initial_setup_images/cb3_01_welcome.png rename to ur_robot_driver/doc/installation/initial_setup_images/cb3_01_welcome.png diff --git a/ur_robot_driver/doc/initial_setup_images/cb3_05_urcaps_installed.png b/ur_robot_driver/doc/installation/initial_setup_images/cb3_05_urcaps_installed.png similarity index 100% rename from ur_robot_driver/doc/initial_setup_images/cb3_05_urcaps_installed.png rename to ur_robot_driver/doc/installation/initial_setup_images/cb3_05_urcaps_installed.png diff --git a/ur_robot_driver/doc/initial_setup_images/cb3_07_installation_excontrol.png b/ur_robot_driver/doc/installation/initial_setup_images/cb3_07_installation_excontrol.png similarity index 100% rename from ur_robot_driver/doc/initial_setup_images/cb3_07_installation_excontrol.png rename to ur_robot_driver/doc/installation/initial_setup_images/cb3_07_installation_excontrol.png diff --git a/ur_robot_driver/doc/initial_setup_images/cb3_10_prog_structure_urcaps.png b/ur_robot_driver/doc/installation/initial_setup_images/cb3_10_prog_structure_urcaps.png similarity index 100% rename from ur_robot_driver/doc/initial_setup_images/cb3_10_prog_structure_urcaps.png rename to ur_robot_driver/doc/installation/initial_setup_images/cb3_10_prog_structure_urcaps.png diff --git a/ur_robot_driver/doc/initial_setup_images/cb3_11_program_view_excontrol.png b/ur_robot_driver/doc/installation/initial_setup_images/cb3_11_program_view_excontrol.png similarity index 100% rename from ur_robot_driver/doc/initial_setup_images/cb3_11_program_view_excontrol.png rename to ur_robot_driver/doc/installation/initial_setup_images/cb3_11_program_view_excontrol.png diff --git a/ur_robot_driver/doc/initial_setup_images/e-Series.jpg b/ur_robot_driver/doc/installation/initial_setup_images/e-Series.jpg similarity index 100% rename from ur_robot_driver/doc/initial_setup_images/e-Series.jpg rename to ur_robot_driver/doc/installation/initial_setup_images/e-Series.jpg diff --git a/ur_robot_driver/doc/initial_setup_images/es_01_welcome.png b/ur_robot_driver/doc/installation/initial_setup_images/es_01_welcome.png similarity index 100% rename from ur_robot_driver/doc/initial_setup_images/es_01_welcome.png rename to ur_robot_driver/doc/installation/initial_setup_images/es_01_welcome.png diff --git a/ur_robot_driver/doc/initial_setup_images/es_05_urcaps_installed.png b/ur_robot_driver/doc/installation/initial_setup_images/es_05_urcaps_installed.png similarity index 100% rename from ur_robot_driver/doc/initial_setup_images/es_05_urcaps_installed.png rename to ur_robot_driver/doc/installation/initial_setup_images/es_05_urcaps_installed.png diff --git a/ur_robot_driver/doc/initial_setup_images/es_07_installation_excontrol.png b/ur_robot_driver/doc/installation/initial_setup_images/es_07_installation_excontrol.png similarity index 100% rename from ur_robot_driver/doc/initial_setup_images/es_07_installation_excontrol.png rename to ur_robot_driver/doc/installation/initial_setup_images/es_07_installation_excontrol.png diff --git a/ur_robot_driver/doc/initial_setup_images/es_10_prog_structure_urcaps.png b/ur_robot_driver/doc/installation/initial_setup_images/es_10_prog_structure_urcaps.png similarity index 100% rename from ur_robot_driver/doc/initial_setup_images/es_10_prog_structure_urcaps.png rename to ur_robot_driver/doc/installation/initial_setup_images/es_10_prog_structure_urcaps.png diff --git a/ur_robot_driver/doc/initial_setup_images/es_11_program_view_excontrol.png b/ur_robot_driver/doc/installation/initial_setup_images/es_11_program_view_excontrol.png similarity index 100% rename from ur_robot_driver/doc/initial_setup_images/es_11_program_view_excontrol.png rename to ur_robot_driver/doc/installation/initial_setup_images/es_11_program_view_excontrol.png diff --git a/ur_robot_driver/doc/install_urcap_cb3.md b/ur_robot_driver/doc/installation/install_urcap_cb3.rst similarity index 62% rename from ur_robot_driver/doc/install_urcap_cb3.md rename to ur_robot_driver/doc/installation/install_urcap_cb3.rst index 600b7c848..bd0afdba4 100644 --- a/ur_robot_driver/doc/install_urcap_cb3.md +++ b/ur_robot_driver/doc/installation/install_urcap_cb3.rst @@ -1,9 +1,12 @@ -# Installing a URCap on a CB3 robot +.. _install-urcap-cb3: + +Installing a URCap on a CB3 robot +================================= For using the *ur_robot_driver* with a real robot you need to install the **externalcontrol-1.0.5.urcap** which can be found inside the **resources** folder of this driver. -**Note**: For installing this URCap a minimal PolyScope version of 3.7 is necessary. +**Note**\ : For installing this URCap a minimal PolyScope version of 3.7 is necessary. To install it you first have to copy it to the robot's **programs** folder which can be done either via scp or using a USB stick. @@ -11,7 +14,11 @@ via scp or using a USB stick. On the welcome screen select *Setup Robot* and then *URCaps* to enter the URCaps installation screen. - ![Welcome screen of a CB3 robot](initial_setup_images/cb3_01_welcome.png) + +.. image:: initial_setup_images/cb3_01_welcome.png + :target: initial_setup_images/cb3_01_welcome.png + :alt: Welcome screen of a CB3 robot + There, click the little plus sign at the bottom to open the file selector. There you should see all urcap files stored inside the robot's programs folder or a plugged USB drive. Select and open @@ -19,25 +26,41 @@ the **externalcontrol-1.0.5.urcap** file and click *open*. Your URCaps view shou **External Control** in the list of active URCaps and a notification to restart the robot. Do that now. - ![URCaps screen with installed urcaps](initial_setup_images/cb3_05_urcaps_installed.png) + +.. image:: initial_setup_images/cb3_05_urcaps_installed.png + :target: initial_setup_images/cb3_05_urcaps_installed.png + :alt: URCaps screen with installed urcaps + After the reboot you should find the **External Control** URCaps inside the *Installation* section. For this select *Program Robot* on the welcome screen, select the *Installation* tab and select **External Control** from the list. - ![Installation screen of URCaps](initial_setup_images/cb3_07_installation_excontrol.png) + +.. image:: initial_setup_images/cb3_07_installation_excontrol.png + :target: initial_setup_images/cb3_07_installation_excontrol.png + :alt: Installation screen of URCaps + Here you'll have to setup the IP address of the external PC which will be running the ROS driver. Note that the robot and the external PC have to be in the same network, ideally in a direct connection with each other to minimize network disturbances. The custom port should be left untouched for now. - ![Insert the external control node](initial_setup_images/cb3_10_prog_structure_urcaps.png) + +.. image:: initial_setup_images/cb3_10_prog_structure_urcaps.png + :target: initial_setup_images/cb3_10_prog_structure_urcaps.png + :alt: Insert the external control node + To use the new URCaps, create a new program and insert the **External Control** program node into the program tree - ![Program view of external control](initial_setup_images/cb3_11_program_view_excontrol.png) + +.. image:: initial_setup_images/cb3_11_program_view_excontrol.png + :target: initial_setup_images/cb3_11_program_view_excontrol.png + :alt: Program view of external control + If you click on the *command* tab again, you'll see the settings entered inside the *Installation*. Check that they are correct, then save the program. Your robot is now ready to be used together with diff --git a/ur_robot_driver/doc/install_urcap_e_series.md b/ur_robot_driver/doc/installation/install_urcap_e_series.rst similarity index 63% rename from ur_robot_driver/doc/install_urcap_e_series.md rename to ur_robot_driver/doc/installation/install_urcap_e_series.rst index db26cc2c4..7ff99bc44 100644 --- a/ur_robot_driver/doc/install_urcap_e_series.md +++ b/ur_robot_driver/doc/installation/install_urcap_e_series.rst @@ -1,16 +1,23 @@ -# Installing a URCap on a e-Series robot +.. _install-urcap-e-series: + +Installing a URCap on a e-Series robot +====================================== For using the *ur_robot_driver* with a real robot you need to install the **externalcontrol-1.0.5.urcap** which can be found inside the **resources** folder of this driver. -**Note**: For installing this URCap a minimal PolyScope version of 5.1 is necessary. +**Note**\ : For installing this URCap a minimal PolyScope version of 5.1 is necessary. To install it you first have to copy it to the robot's **programs** folder which can be done either via scp or using a USB stick. On the welcome screen click on the hamburger menu in the top-right corner and select *Settings* to enter the robot's setup. There select *System* and then *URCaps* to enter the URCaps installation screen. - ![Welcome screen of an e-Series robot](initial_setup_images/es_01_welcome.png) + +.. image:: initial_setup_images/es_01_welcome.png + :target: initial_setup_images/es_01_welcome.png + :alt: Welcome screen of an e-Series robot + There, click the little plus sign at the bottom to open the file selector. There you should see all urcap files stored inside the robot's programs folder or a plugged USB drive. Select and open @@ -18,25 +25,41 @@ the **externalcontrol-1.0.5.urcap** file and click *open*. Your URCaps view shou **External Control** in the list of active URCaps and a notification to restart the robot. Do that now. - ![URCaps screen with installed urcaps](initial_setup_images/es_05_urcaps_installed.png) + +.. image:: initial_setup_images/es_05_urcaps_installed.png + :target: initial_setup_images/es_05_urcaps_installed.png + :alt: URCaps screen with installed urcaps + After the reboot you should find the **External Control** URCaps inside the *Installation* section. For this select *Program Robot* on the welcome screen, select the *Installation* tab and select **External Control** from the list. - ![Installation screen of URCaps](initial_setup_images/es_07_installation_excontrol.png) + +.. image:: initial_setup_images/es_07_installation_excontrol.png + :target: initial_setup_images/es_07_installation_excontrol.png + :alt: Installation screen of URCaps + Here you'll have to setup the IP address of the external PC which will be running the ROS driver. Note that the robot and the external PC have to be in the same network, ideally in a direct connection with each other to minimize network disturbances. The custom port should be left untouched for now. - ![Insert the external control node](initial_setup_images/es_10_prog_structure_urcaps.png) + +.. image:: initial_setup_images/es_10_prog_structure_urcaps.png + :target: initial_setup_images/es_10_prog_structure_urcaps.png + :alt: Insert the external control node + To use the new URCaps, create a new program and insert the **External Control** program node into the program tree - ![Program view of external control](initial_setup_images/es_11_program_view_excontrol.png) + +.. image:: initial_setup_images/es_11_program_view_excontrol.png + :target: initial_setup_images/es_11_program_view_excontrol.png + :alt: Program view of external control + If you click on the *command* tab again, you'll see the settings entered inside the *Installation*. Check that they are correct, then save the program. Your robot is now ready to be used together with diff --git a/ur_robot_driver/doc/real_time.md b/ur_robot_driver/doc/installation/real_time.md similarity index 100% rename from ur_robot_driver/doc/real_time.md rename to ur_robot_driver/doc/installation/real_time.md diff --git a/ur_robot_driver/doc/installation/robot_setup.rst b/ur_robot_driver/doc/installation/robot_setup.rst new file mode 100644 index 000000000..2ed92781b --- /dev/null +++ b/ur_robot_driver/doc/installation/robot_setup.rst @@ -0,0 +1,88 @@ + +Setting up a UR robot for ur_robot_driver +========================================= + +Network setup +------------- + +There are many possible ways to connect a UR robot. This section describes a good example using static IP addresses and a direct connection from the PC to the Robot to minimize latency introduced by network hardware. Though a good network switch usually works fine, as well. + + +#. + Connect the UR control box directly to the remote PC with an ethernet cable. + +#. + Open the network settings from the UR teach pendant (Setup Robot -> Network) and enter these settings: + +.. code-block:: + + IP address: 192.168.1.102 + Subnet mask: 255.255.255.0 + Default gateway: 192.168.1.1 + Preferred DNS server: 192.168.1.1 + Alternative DNS server: 0.0.0.0 + + +#. + On the remote PC, turn off all network devices except the "wired connection", e.g. turn off wifi. + +#. + Open Network Settings and create a new Wired connection with these settings. You may want to name this new connection ``UR`` or something similar: + +.. code-block:: + + IPv4 + Manual + Address: 192.168.1.101 + Netmask: 255.255.255.0 + Gateway: 192.168.1.1 + + +#. Verify the connection from the PC with e.g. ping. + +.. code-block:: + + ping 192.168.1.102 + +Prepare the robot +----------------- + +This section describes installation and launching of the URCap program from the pendant. It allows ROS to control the robot externally. Generally, you will launch the driver via ROS then start URCap from the pendant. + +For using the *ur_robot_driver* with a real robot you need to install the +**externalcontrol urcap**. The latest release can be downloaded from `its own repository `_. + +**Note**: For installing this URCap a minimal PolyScope version of 3.7 or 5.1 (in case of e-Series) is +necessary. + +For installing the necessary URCap and creating a program, please see the individual tutorials on +how to :ref:`setup a cb3 robot ` or how to +:ref:`setup an e-Series robot `. + +To setup the tool communication on an e-Series robot, please consider the :ref:`tool communication setup +guide `. + +Prepare the ROS PC +------------------ + +For using the driver make sure it is installed (either by the debian package or built from source +inside a colcon workspace). + +Extract calibration information +------------------------------- + +Each UR robot is calibrated inside the factory giving exact forward and inverse kinematics. To also +make use of this in ROS, you first have to extract the calibration information from the robot. + +Though this step is not necessary to control the robot using this driver, it is highly recommended +to do so, as otherwise endeffector positions might be off in the magnitude of centimeters. + +For this, there exists a helper script: + +.. code:: bash + + $ ros2 launch ur_calibration calibration_correction.py.launch \ + robot_ip:= target_filename:="${HOME}/my_robot_calibration.yaml" + +For the parameter ``robot_ip`` insert the IP address on which the ROS pc can reach the robot. As +``target_filename`` provide an absolute path where the result will be saved to. diff --git a/ur_robot_driver/doc/installation/toc.rst b/ur_robot_driver/doc/installation/toc.rst new file mode 100644 index 000000000..926be1acd --- /dev/null +++ b/ur_robot_driver/doc/installation/toc.rst @@ -0,0 +1,16 @@ +############ +Installation +############ + +This chapter explains how to install the ``ur_robot_driver`` + + +.. toctree:: + :maxdepth: 4 + :caption: Contents: + + real_time + robot_setup + install_urcap_cb3 + install_urcap_e_series + ursim_docker diff --git a/ur_robot_driver/doc/installation/ursim_docker.rst b/ur_robot_driver/doc/installation/ursim_docker.rst new file mode 100644 index 000000000..da7d66961 --- /dev/null +++ b/ur_robot_driver/doc/installation/ursim_docker.rst @@ -0,0 +1,99 @@ +.. _ursim_docker: + +Setup URSim with Docker +======================= +URSim is the offline simulator by Universal Robots. Packed into a remote or virtual machine it acts almost +identically to a real robot connected over the network. While it is possible to get URSim running +locally on a Linux system or inside a VirtualBox virtual machine, we will focus on getting things +setup using Docker. Using Docker for your simulated robot allows you to very quickly spin up a robot +testing instance with very little computational overload. + +This guide will assume that you have Docker already installed and setup such that you can startup +Docker containers using your current user. + +Start a URSim docker container +------------------------------ + +To startup a simulated robot run the following command. This will start a Docker container named +``ursim`` and startup a simulated UR5e robot. It exposes ports 5900 and 6080 for the browser-based +polyscope access. Note that this will expose the simulated robot to your local area network if you +don't have any further level of security such as a firewall active. To prevent this, you can either +skip the port forwarding instructions (skip the two ``-p port:port`` statements) in which case +you'll have to use the container's IP address to access the polyscope gui rather than ``localhost`` or +you can restrict the port forwarding to a certain network interface (such as the looppack interface) +see Docker's upstream documentation on port exposure for further information. + +.. code-block:: bash + + docker run --rm -it -p 5900:5900 -p 6080:6080 --name ursim universalrobots/ursim_e-series + +External Control +---------------- + +To use the external control functionality, we will need the ``external_control`` URCap installed on +the robot and a program containing its *ExternalControl* program node. Both can be prepared on the +host machine either by creating an own Dockerfile containing those or by mounting two folders +containing installed URCaps and programs. See the Dockerfile's upstream `documentation `_. + +In this example, we will bind-mount a folder for the programs and URCaps. First, let's create a +local folder where we can store things inside: + +.. code-block:: bash + + mkdir -p ${HOME}/.ursim/programs + mkdir -p ${HOME}/.ursim/urcaps + +Then, we can "install" the URCap by placing its ``.jar`` file inside the urcaps folder + +.. code-block:: bash + + URCAP_VERSION=1.0.5 # latest version as if writing this + curl -L -o ${HOME}/.ursim/urcaps/externalcontrol-${URCAP_VERSION}.jar \ + https://github.com/UniversalRobots/Universal_Robots_ExternalControl_URCap/releases/download/v${URCAP_VERSION}/externalcontrol-${URCAP_VERSION}.jar + +With this, start your URSim containers with the following command: + +.. code-block:: bash + + docker run --rm -it -p 5900:5900 -p 6080:6080 -v ${HOME}/.ursim/urcaps:/urcaps -v ${HOME}/.ursim/programs:/ursim/programs --name ursim universalrobots/ursim_e-series + +With this, you should be able to setup the ``external_control`` URCap and create a program as +described in :ref:`URCap setup guide `. + +Network setup +------------- + +As described above, you can always start the URSim container using the default network setup. As long +as you don't have any other docker containers running, it will most probably always get the same IP +address assigned every time. However, to make things a bit more explicit, we can setup our own +docker network where we can assign a static IP address to our URSim container. + +.. code-block:: bash + + docker network create --subnet=192.168.56.0/24 ursim_net + docker run --rm -it -p 5900:5900 -p 6080:6080 --net ursim_net --ip 192.168.56.101 universalrobots/ursim_e-series + +The above commands first create a network for docker and then create a container with the URSim +image attaching to this network. + +As we now have a fixed IP address we can also skip the port exposure as we know the robot's IP +address. The VNC web server will be available at ``_ + +Script startup +-------------- + +All of the above is put together in a script in the ``ur_bringup`` package. + +.. code-block:: bash + + ros2 run ur_bringup start_ursim.sh + +This will start a URSim docker container running on ``192.168.56.101`` with the ``external_control`` +URCap preinstalled. Created programs and installation changes will be stored persistently inside +``${HOME}/.ursim/programs``. + +With this, you can run + +.. code-block:: bash + + ros2 launch ur_bringup ur_control.launch.py ur_type:=ur5e robot_ip:=192.168.56.101 diff --git a/ur_robot_driver/doc/make.bat b/ur_robot_driver/doc/make.bat new file mode 100644 index 000000000..27f573b87 --- /dev/null +++ b/ur_robot_driver/doc/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/ur_robot_driver/doc/overview.rst b/ur_robot_driver/doc/overview.rst new file mode 100644 index 000000000..07721cc24 --- /dev/null +++ b/ur_robot_driver/doc/overview.rst @@ -0,0 +1,22 @@ +Overview +======== + +This driver collaborates closely with other ROS packages: + +``ur_bringup`` + Package to launch the driver, simulated robot and test scripts. +``ur_calibration`` + Package containing the calibration extraction program that will extract parameters for correctly + parametrizing the URDF with calibration data from the specific robot. +``ur_controllers`` + Controllers specifically made for UR manipulators. +``ur_dashboard_msgs`` + Message packages used for the `dashboard `_ communication. +``ur_moveit_config`` + MoveIt! configuration for a plain robot. This is good as a starting point, but for a real + application you would rather create your own MoveIt! configuration package containing your actual + robot environment. +``ur_description`` (`separate repository `_) + URDF description for UR manipulators + +.. include:: features.rst diff --git a/ur_robot_driver/doc/rosdoc.yaml b/ur_robot_driver/doc/rosdoc.yaml deleted file mode 100644 index d27dced12..000000000 --- a/ur_robot_driver/doc/rosdoc.yaml +++ /dev/null @@ -1,4 +0,0 @@ -- builder: doxygen - name: C++ API - output_dir: c++ - file_patterns: '*.c *.cpp *.h *.cc *.hh *.dox' diff --git a/ur_robot_driver/doc/setup_tool_communication.md b/ur_robot_driver/doc/setup_tool_communication.md deleted file mode 100644 index b2ccd6431..000000000 --- a/ur_robot_driver/doc/setup_tool_communication.md +++ /dev/null @@ -1,58 +0,0 @@ -# Setting up the tool communication on an e-Series robot -The Universal Robots e-Series provides an rs485 based interface at the tool flange that can be used -to attach an rs485-based device to the robot's tcp without the need to wire a separate cable along -the robot. - -This driver enables forwarding this tool communication interface to an external machine for example -to start a device's ROS driver on a remote PC. - -This document will guide you through installing the URCap needed for this and setting up your ROS -launch files to utilize the robot's tool communication. - -## Robot setup -For setting up the robot, please install the **rs485-1.0.urcap** found in the **resources** folder. -Installing a URCap is explained in the [setup guide](install_urcap_e_series.md) for the **external-control** URCap. - -After installing the URCap the robot will expose its tool communication device to the network. - -## Setup the ROS side -In order to use the tool communication in ROS, simply pass the correct parameters to the bringup -launch files: - -```bash -$ ros2 launch ur_bringup ur_control.launch.py ur_type:=ur5e robot_ip:=yyy.yyy.yyy.yyy use_tool_communication:=true use_fake_hardware:=false launch_rviz:=false - # remember that your user needs to have the rights to write that file handle to /tmp/ttyUR -``` - -Following parameters can be set [ur.ros2_control.xacro](../../ur_description/urdf/ur.ros2_control.xacro): -- `tool_voltage` -- `tool_parity` -- `tool_baud_rate` -- `tool_stop_bits` -- `tool_rx_idle_chars` -- `tool_tx_idle_chars` -- `tool_device_name` -- `tool_tcp_port` - -The `tool_device_name` is an arbitrary name for the device file at which the device will be -accessible in the local file system. Most ROS drivers for rs485 devices accept an argument to -specify the device file path. With the example above you could run the `rs485_node` from the package -`imaginary_drivers` using the following command: - -```bash -$ ros2 run imaginary_drivers rs485_node --ros-args -p device:=/tmp/ttyUR - -``` - -You can basically choose any device name, but your user has to have the correct rights to actually -create a new file handle inside this directory. Therefore, we didn't use the `/dev` folder in the -example, as users usually don't have the access rights to create new files there. - -For all the other tool parameters seen above, please refer to the Universal Robots user manual. - -More information can be found at [Universal_Robots_ToolComm_Forwarder_URCap](https://github.com/UniversalRobots/Universal_Robots_ToolComm_Forwarder_URCap). -The convenience script for `socat` call is [here](../scripts/tool_communication.py) for ROS2 driver and can be run by: -```asm -$ ros2 run ur_robot_driver tool_communication.py --ros-args -p robot_ip:=192.168.56.101 -p device_name:=/tmp/ttyUR - -``` diff --git a/ur_robot_driver/doc/setup_tool_communication.rst b/ur_robot_driver/doc/setup_tool_communication.rst new file mode 100644 index 000000000..7893f36e6 --- /dev/null +++ b/ur_robot_driver/doc/setup_tool_communication.rst @@ -0,0 +1,67 @@ +.. _setup-tool-communication: + +Setting up the tool communication on an e-Series robot +====================================================== + +The Universal Robots e-Series provides an rs485 based interface at the tool flange that can be used +to attach an rs485-based device to the robot's tcp without the need to wire a separate cable along +the robot. + +This driver enables forwarding this tool communication interface to an external machine for example +to start a device's ROS driver on a remote PC. + +This document will guide you through installing the URCap needed for this and setting up your ROS +launch files to utilize the robot's tool communication. + +Robot setup +----------- + +For setting up the robot, please install the **rs485-1.0.urcap** found in the **resources** folder. +Installing a URCap is explained in the :ref:`setup guide ` for the **external-control** URCap. + +After installing the URCap the robot will expose its tool communication device to the network. + +Setup the ROS side +------------------ + +In order to use the tool communication in ROS, simply pass the correct parameters to the bringup +launch files: + +.. code-block:: bash + + $ ros2 launch ur_bringup ur_control.launch.py ur_type:=ur5e robot_ip:=yyy.yyy.yyy.yyy use_tool_communication:=true use_fake_hardware:=false launch_rviz:=false + # remember that your user needs to have the rights to write that file handle to /tmp/ttyUR + +Following parameters can be set `ur.ros2_control.xacro `_\ : + + +* ``tool_voltage`` +* ``tool_parity`` +* ``tool_baud_rate`` +* ``tool_stop_bits`` +* ``tool_rx_idle_chars`` +* ``tool_tx_idle_chars`` +* ``tool_device_name`` +* ``tool_tcp_port`` + +The ``tool_device_name`` is an arbitrary name for the device file at which the device will be +accessible in the local file system. Most ROS drivers for rs485 devices accept an argument to +specify the device file path. With the example above you could run the ``rs485_node`` from the package +``imaginary_drivers`` using the following command: + +.. code-block:: bash + + $ ros2 run imaginary_drivers rs485_node --ros-args -p device:=/tmp/ttyUR + +You can basically choose any device name, but your user has to have the correct rights to actually +create a new file handle inside this directory. Therefore, we didn't use the ``/dev`` folder in the +example, as users usually don't have the access rights to create new files there. + +For all the other tool parameters seen above, please refer to the Universal Robots user manual. + +More information can be found at `Universal_Robots_ToolComm_Forwarder_URCap `_. +The convenience script for ``socat`` call is `here `_ for ROS2 driver and can be run by: + +.. code-block:: bash + + $ ros2 run ur_robot_driver tool_communication.py --ros-args -p robot_ip:=192.168.56.101 -p device_name:=/tmp/ttyUR diff --git a/ur_robot_driver/doc/usage.rst b/ur_robot_driver/doc/usage.rst new file mode 100644 index 000000000..39ad3eb0e --- /dev/null +++ b/ur_robot_driver/doc/usage.rst @@ -0,0 +1,242 @@ +.. role:: raw-html-m2r(raw) + :format: html + + +Usage +===== + +Launch files +------------ + +For starting the driver there are two main launch files in the ``ur_bringup`` package. + + +* ``ur_control.launch.py`` - starts ros2_control node including hardware interface, joint state broadcaster and a controller. This launch file also starts ``dashboard_client`` if real robot is used. +* ``ur_dashboard_client.launch.py`` - start the dashboard client for UR robots. + +Also, there are predefined launch files for all supported types of UR robots. + +The arguments for launch files can be listed using ``ros2 launch ur_bringup .launch.py --show-args``. +The most relevant arguments are the following: + + +* ``ur_type`` (\ *mandatory* ) - a type of used UR robot (\ *ur3*\ , *ur3e*\ , *ur5*\ , *ur5e*\ , *ur10*\ , *ur10e*\ , or *ur16e*\ ). +* ``robot_ip`` (\ *mandatory* ) - IP address by which the root can be reached. +* ``use_fake_hardware`` (default: *false* ) - use simple hardware emulator from ros2_control. + Useful for testing launch files, descriptions, etc. See explanation below. +* ``initial_positions`` (default: dictionary with all joint values set to 0) - Allows passing a dictionary to set the initial joint values for the fake hardware from `ros2_control `_. It can also be set from a yaml file with the ``load_yaml`` commands as follows: + + .. code-block:: + + + + In this example, the **initial_positions_file** is a xacro argument that contains the absolute path to a yaml file. An example of the initial positions yaml file is as follows: + + .. code-block:: + + elbow_joint: 1.158 + shoulder_lift_joint: -0.953 + shoulder_pan_joint: 1.906 + wrist_1_joint: -1.912 + wrist_2_joint: -1.765 + wrist_3_joint: 0.0 + +* ``fake_sensor_commands`` (default: *false* ) - enables setting sensor values for the hardware emulators. + Useful for offline testing of controllers. + +* ``robot_controller`` (default: *joint_trajectory_controller* ) - controller for robot joints to be started. + Available controllers: + + + * joint_trajectory_controller + * scaled_joint_trajectory_controller + + Note: *joint_state_broadcaster*\ , *speed_scaling_state_broadcaster*\ , *force_torque_sensor_broadcaster*\ , and *io_and_status_controller* will always start. + + *HINT* : list all loaded controllers using ``ros2 control list_controllers`` command. + +**NOTE**\ : The package can simulate hardware with the ros2_control ``FakeSystem``. This emulator enables an environment for testing of "piping" of hardware and controllers, as well as testing robot's descriptions. For more details see `ros2_control documentation `_ for more details. + +Modes of operation +------------------ + +As mentioned in the last section the driver has two basic modes of operation: Using fake hardware or +using real hardware(Or the URSim simulator, which is equivalent from the driver's perspective). +Additionally, the robot can be simulated using +`Gazebo `_ or +`ignition `_ but that's +outside of this driver's scope. + +.. list-table:: + :header-rows: 1 + + * - mode + - available controllers + * - fake_hardware + - :raw-html-m2r:`
  • joint_trajectory_controller
  • forward_velocity_controller
  • forward_position_controller
` + * - real hardware / URSim + - :raw-html-m2r:`
  • joint_trajectory_controller
  • scaled_joint_trajectory_controller
  • forward_velocity_controller
  • forward_position_controller
` + + +Usage with official UR simulator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The easiest way to use URSim is the `Docker +image `_ provided by Universal Robots (See +`this link `_ for a CB3-series image). + +To start it, we've prepared a script: + +.. code-block:: bash + + ros2 run ur_bringup start_ursim.sh -m + +With this, we can spin up a driver using + +.. code-block:: bash + + ros2 launch ur_bringup ur_control.launch.py ur_type:= robot_ip:=172.17.0.2 launch_rviz:=true + +You can view the polyscope GUI by opening ``_. + +When we now move the robot in Polyscope, the robot's RViz visualization should move accordingly. + +For details on the Docker image, please see the more detailed guide :ref:`here `. + +Example Commands for Testing the Driver +--------------------------------------- + +Allowed UR - Type strings: ``ur3``\ , ``ur3e``\ , ``ur5``\ , ``ur5e``\ , ``ur10``\ , ``ur10e``\ , ``ur16e``. + +1. Start hardware, simulator or mockup +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + +* To do test with hardware, use: + + .. code-block:: + + ros2 launch ur_bringup ur_control.launch.py ur_type:= robot_ip:= launch_rviz:=true + + For more details check the argument documentation with ``ros2 launch ur_bringup ur_control.launch.py --show-arguments`` + + After starting the launch file start the external_control URCap program from the pendant, as described above. + +* To do an offline test with URSim check details about it in `this section <#usage-with-official-ur-simulator>`_ + +* To use mocked hardware(capability of ros2_control), use ``use_fake_hardware`` argument, like: + + .. code-block:: + + ros2 launch ur_bringup ur_control.launch.py ur_type:=ur5e robot_ip:=yyy.yyy.yyy.yyy use_fake_hardware:=true launch_rviz:=true + + **NOTE**\ : Instead of using the global launch file for control stack, there are also prepeared launch files for each type of UR robots named. They accept the same arguments are the global one and are used by: + + .. code-block:: + + ros2 launch ur_bringup .launch.py + +2. Sending commands to controllers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Before running any commands, first check the controllers' state using ``ros2 control list_controllers``. + + +* Send some goal to the Joint Trajectory Controller by using a demo node from `ros2_control_demos `_ package by starting the following command in another terminal: + + .. code-block:: + + ros2 launch ur_bringup test_scaled_joint_trajectory_controller.launch.py + + After a few seconds the robot should move. + +* To test another controller, simply define it using ``initial_joint_controller`` argument, for example when using fake hardware: + + .. code-block:: + + ros2 launch ur_bringup ur_control.launch.py ur_type:=ur5e robot_ip:=yyy.yyy.yyy.yyy initial_joint_controller:=joint_trajectory_controller use_fake_hardware:=true launch_rviz:=true + + And send the command using demo node: + + .. code-block:: + + ros2 launch ur_bringup test_joint_trajectory_controller.launch.py + + After a few seconds the robot should move(or jump when using emulation). + +3. Using only robot description +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you just want to test description of the UR robots, e.g., after changes you can use the following command: + +.. code-block:: + + ros2 launch ur_description view_ur.launch.py ur_type:=ur5e + +Using MoveIt +------------ + +`MoveIt! `_ support is built-in into this driver already. + +Real robot / URSim +^^^^^^^^^^^^^^^^^^ + +To test the driver with the example MoveIt-setup, first start the driver as described +`above <#start-hardware-simulator-or-mockup>`_. + +.. code-block:: + + ros2 launch ur_moveit_config ur_moveit.launch.py ur_type:=ur5e launch_rviz:=true + +Now you should be able to use the MoveIt Plugin in rviz2 to plan and execute trajectories with the +robot as explained `here `_. + +Fake hardware on ROS2 Galactic +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Currently, the ``scaled_joint_trajectory_controller`` does not work on ROS2 Galactic. There is an +`upstream Merge-Request `_ pending to fix that. Until this is merged and released, please change the +default controller in the `controllers.yaml `_ file. Make +sure that the ``default`` field is assigned ``true`` for the ``joint_trajectory_controller`` and ``false`` +for the +``scaled_joint_trajectory_controller``. + +.. code-block:: + + controller_names: + - scaled_joint_trajectory_controller + - joint_trajectory_controller + + + scaled_joint_trajectory_controller: + action_ns: follow_joint_trajectory + type: FollowJointTrajectory + default: false + joints: + - shoulder_pan_joint + - shoulder_lift_joint + - elbow_joint + - wrist_1_joint + - wrist_2_joint + - wrist_3_joint + + + joint_trajectory_controller: + action_ns: follow_joint_trajectory + type: FollowJointTrajectory + default: true + joints: + - shoulder_pan_joint + - shoulder_lift_joint + - elbow_joint + - wrist_1_joint + - wrist_2_joint + - wrist_3_joint + +Then start + +.. code-block:: + + ros2 launch ur_bringup ur_control.launch.py ur_type:=ur5e robot_ip:=yyy.yyy.yyy.yyy use_fake_hardware:=true launch_rviz:=false initial_joint_controller:=joint_trajectory_controller + # and in another shell + ros2 launch ur_moveit_config ur_moveit.launch.py ur_type:=ur5e launch_rviz:=true