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"

README.md

@@ -4,6 +4,10 @@ A C++ library for accessing Universal Robots interfaces. With this library C++-b
 implemented in order to create external applications leveraging the versatility of Universal Robots
 robotic manipulators.
 
+The library has no external dependencies besides the standard C++ libraries such as ROS, or boost
+to make it easy to integrate and maintain. It also serves as the foundation for the ROS and ROS 2
+drivers.
+
 <!-- markdownlint-disable MD033 -->
 <div align="center">
   <img src="doc/resources/family_photo.png" alt="Universal Robot family" style="width: 90%;"/>

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,12 @@
+Setup a robot
+=============
+
+The robot has to be prepared, to enable communication between the robot and the client library.
+This documentation will guide you through the necessary steps.
+
+.. toctree::
+   :maxdepth: 1
+
+   setup/robot_setup
+   setup/network_setup
+   setup/ursim_docker.rst

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,213 @@
+.. _robot_setup:
+
+Robot setup
+===========
+
+The robot needs to be prepared before it can be used with the client library.
+
+.. tabs::
+
+   .. group-tab:: CB3
+
+      CB3 robots can directly be used with the ur_client_library. No special preparation is needed.
+
+
+   .. group-tab:: PolyScope 5
+
+      There are two ways the client library can be enabled to send command to the robot.
+
+      - **Remote control**: There the full control is given to the client library and enables it to e.g. power on and off, brake release, load PolyScope programs and send URScript programs directly to the controller.
+      - **External Control URCap**: There the control to power on, off and start programs etc. still remains on the teach pendant. The External Control URCap injects the needed URScript code from the client library. This also makes it possible to combine the use of the client library and other PolyScope program nodes, like standard moves or other third-party URCaps.
+
+      **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.
+
+
+   .. group-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.png
+         :width: 600
+         :alt: Screenshot from PolyScope X screen.
+
+.. _install_urcap:
+
+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::
+
+   .. group-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>`_.
+
+      To install the URCap 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-X.Y.Z.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
+
+   .. group-tab:: PolyScope 5
+
+      .. 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>`_.
+
+      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-X.Y.Z.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.
+
+   .. group-tab:: PolyScope X
+
+      .. warning::
+
+         Support for PolyScope X isn't fully developed, yet. Please consider using External Control
+         with PolyScope X as an open beta.
+
+      For details on installing the External Control URCapX, please see https://github.com/UniversalRobots/Universal_Robots_ExternalControl_URCapX