Move setup instructions to ur_client_library

.github/workflows/ci.yml

@@ -103,5 +103,5 @@ jobs:
         run: |
           .github/helpers/check_urls.sh \
             -d ".git build CMakeModules debian" \
-            -f "package.xml urcl_architecture.svg trajectory_interface.svg dataflow.graphml start_ursim.sh" \
+            -f "package.xml urcl_architecture.svg trajectory_interface.svg dataflow.graphml start_ursim.sh ursim_docker.rst" \
             -p "vnc\.html opensource\.org\/licenses\/BSD-3-Clause kernel\.org\/pub\/linux\/kernel"

doc/architecture/trajectory_point_interface.rst

@@ -8,7 +8,7 @@ be used in conjunction with the :ref:`reverse_interface` during trajectory forwa
 
 Communication regarding trajectory point execution would usually look like this:
 
-.. figure:: /images/trajectory_interface.svg
+.. figure:: ../images/trajectory_interface.svg
    :width: 100%
    :alt: Trajectory interface
 

doc/conf.py

@@ -46,9 +46,10 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "sphinx_tabs.tabs",
+    "sphinx.ext.todo",
     "sphinx_copybutton",
     "sphinx_rtd_theme",
-    "sphinx.ext.todo",
 ]
 
 copybutton_exclude = ".linenos, .gp, .go"

doc/index.rst

@@ -10,6 +10,7 @@ can be found on `GitHub <https://github.com/UniversalRobots/Universal_Robots_Cli
    :caption: Contents:
 
    installation
+   setup
    polyscope_compatibility
    architecture
    example

doc/setup.rst

@@ -0,0 +1,11 @@
+Setup a robot
+=============
+
+.. toctree::
+   :maxdepth: 1
+
+   setup/robot_setup
+   setup/network_setup
+   setup/install_urcap_cb3
+   setup/install_urcap_e_series
+   setup/ursim_docker.rst

doc/setup/install_urcap_cb3.rst

@@ -0,0 +1,68 @@
+.. _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.
+
+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 select *Setup Robot* and then *URCaps* to enter the URCaps installation
+screen.
+
+
+.. image:: ../images/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
+the **externalcontrol-1.0.5.urcap** file and click *open*. Your URCaps view should now show the
+**External Control** in the list of active URCaps and a notification to restart the robot. Do that
+now.
+
+
+.. image:: ../images/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.
+
+
+.. image:: ../images/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 remote
+application.
+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.
+
+
+.. image:: ../images/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
+
+
+.. image:: ../images/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
+this driver

doc/setup/install_urcap_e_series.rst

@@ -0,0 +1,66 @@
+.. _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.
+
+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.
+
+
+.. image:: ../images/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
+the **externalcontrol-1.0.5.urcap** file and click *open*. Your URCaps view should now show the
+**External Control** in the list of active URCaps and a notification to restart the robot. Do that
+now.
+
+
+.. image:: ../images/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.
+
+
+.. image:: ../images/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 remote
+application. 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.
+
+
+.. image:: ../images/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
+
+
+.. image:: ../images/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
+this driver.

doc/setup/network_setup.rst

@@ -0,0 +1,50 @@
+.. _network_setup:
+
+Network setup
+=============
+
+Robot 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.56.101
+   Subnet mask: 255.255.255.0
+   Default gateway: 192.168.56.1
+   Preferred DNS server: 192.168.56.1
+   Alternative DNS server: 0.0.0.0
+
+Remote PC setup
+---------------
+
+#. On the remote PC, turn off all network devices except the "wired connection", e.g. turn off
+   wifi. You can skip this step if you are certain that no other active connection is using the
+   same IP range.
+
+#. 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.56.1
+      Netmask: 255.255.255.0
+
+#. Verify the connection from the PC with e.g. ping. You should see something like this:
+
+   .. code-block:: console
+
+      $ ping 192.168.56.101
+      PING 192.168.56.101 (192.168.56.101) 56(84) bytes of data.
+      64 bytes from 192.168.56.101: icmp_seq=1 ttl=64 time=0.037 ms
+      64 bytes from 192.168.56.101: icmp_seq=2 ttl=64 time=0.043 ms
+      64 bytes from 192.168.56.101: icmp_seq=3 ttl=64 time=0.047 ms

doc/setup/robot_setup.rst

@@ -0,0 +1,92 @@
+.. _robot_setup:
+
+Robot setup
+===========
+
+In order to use the client library with a robot, that robot has to be setup.
+
+.. tabs::
+
+   .. tab:: PolyScope 5
+
+      **Enable remote control:**
+
+      #. Go to the hamburger menu -> settings.
+      #. Go to System -> Remote control.
+      #. Unlock the menu using the admin password, and enable Remote Control.
+      #. Press exit.
+      #. The robot can now be toggled between local and remote control in the upper right hand corner.
+
+      .. image:: ../images/initial_setup_images/remote_control.png
+         :width: 600
+         :alt: Screenshot showing remote control toggle.
+
+
+      **If using PolyScope 5.10 or greater: Enable services**
+
+      #. Go to the hamburger menu -> settings.
+      #. Go to Security -> Services.
+      #. Unlock the menu using the admin password.
+      #. Enable the Dashboard Server, Primary Client Interface, Secondary Client Interface and Real-Time Data Exchange (RTDE) interfaces.
+      #. Lock the menu and press exit.
+
+      .. image:: ../images/initial_setup_images/services_polyscope5.png
+            :width: 600
+            :alt: Screenshot from PolyScope 5.xx services menu.
+
+
+   .. tab:: PolyScope X
+
+      **Enable services:**
+
+      #. Go to the hamburger menu -> settings.
+      #. Go to Security -> Services.
+      #. Unlock the menu using the admin password.
+      #. Enable the Primary Client Interface, Secondary Client Interface and Real-Time Data Exchange (RTDE) interfaces.
+      #. Lock the menu and press exit.
+
+      .. image:: ../images/initial_setup_images/services_polyscopex.jpg
+         :width: 600
+         :alt: Screenshot from PolyScope X screen.
+
+
+URCap installation
+------------------
+
+To use the client library with a robot, you'll have to have the **External Control URCap**
+installed. It allows a remote PC to control the robot externally. Generally, you will launch the
+driver on the remote PC and then start a program from the tech pendant to connect to the remote
+application.
+
+.. tabs::
+
+   .. tab:: CB3
+
+      .. note::
+
+         A minimal PolyScope version of 3.14.3 is required to use this URCap
+
+      The latest release can be downloaded from `its own repository <https://github.com/UniversalRobots/Universal_Robots_ExternalControl_URCap/releases>`_.
+
+      For installing the necessary URCap and creating a program, please see the individual tutorials on
+      how to :ref:`setup a CB3 robot <install-urcap-cb3>`.
+
+   .. tab:: e-Series
+
+      .. note::
+
+         A minimal PolyScope version of 5.9.4 is required to use this URCap
+
+      The latest release can be downloaded from `its own repository <https://github.com/UniversalRobots/Universal_Robots_ExternalControl_URCap/releases>`_.
+
+      For installing the necessary URCap and creating a program, please see the individual tutorials on
+      how to :ref:`setup an e-Series robot <install-urcap-e-series>`.
+
+   .. tab:: PolyScope X
+
+      .. warning::
+
+         Support for PolyScope X isn't fully developed, yet. Please consider using External Control
+         with PolyScope X an open beta.
+
+      For details on installing the External Control URCapX, please see https://github.com/UniversalRobots/Universal_Robots_ExternalControl_URCapX