diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 23f034f6..e4f4ba56 100644 --- a/.github/workflows/ci.yml +++ b/.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" diff --git a/README.md b/README.md index 27d46f93..24e6f169 100644 --- a/README.md +++ b/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. +
Universal Robot family diff --git a/doc/architecture/trajectory_point_interface.rst b/doc/architecture/trajectory_point_interface.rst index b9fdbc90..689d8391 100644 --- a/doc/architecture/trajectory_point_interface.rst +++ b/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 diff --git a/doc/conf.py b/doc/conf.py index 68cf4852..9c3e37b3 100644 --- a/doc/conf.py +++ b/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" diff --git a/doc/images/initial_setup_images/cb3_01_welcome.png b/doc/images/initial_setup_images/cb3_01_welcome.png new file mode 100644 index 00000000..1e0af1e9 Binary files /dev/null and b/doc/images/initial_setup_images/cb3_01_welcome.png differ diff --git a/doc/images/initial_setup_images/cb3_05_urcaps_installed.png b/doc/images/initial_setup_images/cb3_05_urcaps_installed.png new file mode 100644 index 00000000..0f111cb0 Binary files /dev/null and b/doc/images/initial_setup_images/cb3_05_urcaps_installed.png differ diff --git a/doc/images/initial_setup_images/cb3_07_installation_excontrol.png b/doc/images/initial_setup_images/cb3_07_installation_excontrol.png new file mode 100644 index 00000000..133e9b6c Binary files /dev/null and b/doc/images/initial_setup_images/cb3_07_installation_excontrol.png differ diff --git a/doc/images/initial_setup_images/cb3_10_prog_structure_urcaps.png b/doc/images/initial_setup_images/cb3_10_prog_structure_urcaps.png new file mode 100644 index 00000000..9a001031 Binary files /dev/null and b/doc/images/initial_setup_images/cb3_10_prog_structure_urcaps.png differ diff --git a/doc/images/initial_setup_images/cb3_11_program_view_excontrol.png b/doc/images/initial_setup_images/cb3_11_program_view_excontrol.png new file mode 100644 index 00000000..dd1ba4a9 Binary files /dev/null and b/doc/images/initial_setup_images/cb3_11_program_view_excontrol.png differ diff --git a/doc/images/initial_setup_images/es_01_welcome.png b/doc/images/initial_setup_images/es_01_welcome.png new file mode 100644 index 00000000..fba14a58 Binary files /dev/null and b/doc/images/initial_setup_images/es_01_welcome.png differ diff --git a/doc/images/initial_setup_images/es_05_urcaps_installed.png b/doc/images/initial_setup_images/es_05_urcaps_installed.png new file mode 100644 index 00000000..8a02bc54 Binary files /dev/null and b/doc/images/initial_setup_images/es_05_urcaps_installed.png differ diff --git a/doc/images/initial_setup_images/es_07_installation_excontrol.png b/doc/images/initial_setup_images/es_07_installation_excontrol.png new file mode 100644 index 00000000..3b1a9361 Binary files /dev/null and b/doc/images/initial_setup_images/es_07_installation_excontrol.png differ diff --git a/doc/images/initial_setup_images/es_10_prog_structure_urcaps.png b/doc/images/initial_setup_images/es_10_prog_structure_urcaps.png new file mode 100644 index 00000000..6d1e2fff Binary files /dev/null and b/doc/images/initial_setup_images/es_10_prog_structure_urcaps.png differ diff --git a/doc/images/initial_setup_images/es_11_program_view_excontrol.png b/doc/images/initial_setup_images/es_11_program_view_excontrol.png new file mode 100644 index 00000000..9b2c50d4 Binary files /dev/null and b/doc/images/initial_setup_images/es_11_program_view_excontrol.png differ diff --git a/doc/images/initial_setup_images/family_photo.png b/doc/images/initial_setup_images/family_photo.png new file mode 100644 index 00000000..678d312d Binary files /dev/null and b/doc/images/initial_setup_images/family_photo.png differ diff --git a/doc/images/initial_setup_images/remote_control.png b/doc/images/initial_setup_images/remote_control.png new file mode 100644 index 00000000..0f104b6f Binary files /dev/null and b/doc/images/initial_setup_images/remote_control.png differ diff --git a/doc/images/initial_setup_images/services_polyscope5.png b/doc/images/initial_setup_images/services_polyscope5.png new file mode 100644 index 00000000..a32720ff Binary files /dev/null and b/doc/images/initial_setup_images/services_polyscope5.png differ diff --git a/doc/images/initial_setup_images/services_polyscopex.png b/doc/images/initial_setup_images/services_polyscopex.png new file mode 100644 index 00000000..d70140ba Binary files /dev/null and b/doc/images/initial_setup_images/services_polyscopex.png differ diff --git a/doc/index.rst b/doc/index.rst index be3ca1f6..7a2d6e12 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -10,6 +10,7 @@ can be found on `GitHub 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 diff --git a/doc/setup/robot_setup.rst b/doc/setup/robot_setup.rst new file mode 100644 index 00000000..95462e29 --- /dev/null +++ b/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 `_. + + 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 `_. + + 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 diff --git a/doc/setup/ursim_docker.rst b/doc/setup/ursim_docker.rst new file mode 100644 index 00000000..45d1bfc5 --- /dev/null +++ b/doc/setup/ursim_docker.rst @@ -0,0 +1,127 @@ +.. _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 `_ 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 `_. + +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. 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 ``_. + +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. diff --git a/doc_requirements.txt b/doc_requirements.txt index 0033332f..325ab111 100644 --- a/doc_requirements.txt +++ b/doc_requirements.txt @@ -1,4 +1,5 @@ sphinx -sphinx_rtd_theme sphinx-copybutton +sphinx-tabs +sphinx_rtd_theme catkin-pkg