:github_url: https://github.com/UniversalRobots/Universal_Robots_Client_Library/blob/master/doc/setup/ursim_docker.rst

.. _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.

The following example will start up a simulator on a UR5e. See the Docker image `documentation <https://hub.docker.com/r/universalrobots/ursim_e-series>`_ for more details and configuration options.

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 Docker image `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>`.

Network setup
-------------

As described above, you can always start the URSim container using the default network setup. It will most probably
always get the same IP address assigned every time, as long as you don't have any other docker containers running.
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.

We can skip the port exposure, as we use a fixed IP address for the simulated robot. Therefore, 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_client_library`` package.

.. tabs::


   .. tab:: ROS 1

      .. code-block:: bash

         rosrun ur_client_library 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

         roslaunch ur_robot_driver ur5e_bringup.launch robot_ip:=192.168.56.101

   .. tab:: ROS 2

      .. code-block:: bash

         ros2 run ur_client_library 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_robot_driver ur_control.launch.py ur_type:=ur5e robot_ip:=192.168.56.101

   .. tab:: Other

      If you have installed the client library from another source than ROS / ROS 2 or have
      compiled it yourself, run the ``start_ursim.sh`` script directly from the package's
      ``scripts`` folder.
