URSim-Docker section

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()

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 <model>     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

ur_robot_driver/doc/installation/toc.rst

@@ -13,3 +13,4 @@ This chapter explains how to install the ``ur_robot_driver``
    robot_setup
    install_urcap_cb3
    install_urcap_e_series
+   ursim_docker

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 <https://hub.docker.com/r/universalrobots/ursim_e-series>`_.
+
+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 <install-urcap-e-series>`.
+
+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 `<http://192.168.56.101:6080/vnc.html>`_
+
+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