diff --git a/ur_robot_driver/doc/installation/installation.rst b/ur_robot_driver/doc/installation/installation.rst index b6820262..9055669a 100644 --- a/ur_robot_driver/doc/installation/installation.rst +++ b/ur_robot_driver/doc/installation/installation.rst @@ -4,6 +4,15 @@ Installation of the ur_robot_driver You can either install this driver from binary packages as shown above or build it from source. We recommend a binary package installation unless you want to join development and submit changes. +.. note:: + + Controlling the robot using ROS raises the requirement for strict cycle times. To achieve this, + we strongly recommend to use a lowlatency or even ``PREEMPT_RT``-patched kernel. See + :ref:`real time setup` for details on setting this up. + + For the same reason we encourage users to use a direct network connection between the ROS pc and + the robot controller without a switch. + Install from binary packages ---------------------------- diff --git a/ur_robot_driver/doc/installation/real_time.rst b/ur_robot_driver/doc/installation/real_time.rst deleted file mode 100644 index 2bb5b786..00000000 --- a/ur_robot_driver/doc/installation/real_time.rst +++ /dev/null @@ -1,311 +0,0 @@ - -Setting up Ubuntu with a PREEMPT_RT kernel -========================================== - -In order to run the ``universal_robot_driver``\ , we highly recommend to setup a ubuntu system with -real-time capabilities. Especially with a robot from the e-Series the higher control frequency -might lead to non-smooth trajectory execution if not run using a real-time-enabled system. - -You might still be able to control the robot using a non-real-time system. This is, however, not recommended. - -To get real-time support into a ubuntu system, the following steps have to be performed: - - -#. Get the sources of a real-time kernel -#. Compile the real-time kernel -#. Setup user privileges to execute real-time tasks - -This guide will help you setup your system with a real-time kernel. - -Preparing ---------- - -To build the kernel, you will need a couple of tools available on your system. You can install them -using - -.. code-block:: bash - - $ sudo apt-get install build-essential bc ca-certificates gnupg2 libssl-dev wget gawk flex bison - -Before you download the sources of a real-time-enabled kernel, check the kernel version that is currently installed: - -.. code-block:: bash - - $ uname -r - 4.15.0-62-generic - -To continue with this tutorial, please create a temporary folder and navigate into it. You should -have sufficient space (around 25GB) there, as the extracted kernel sources take much space. After -the new kernel is installed, you can delete this folder again. - -In this example we will use a temporary folder inside our home folder: - -.. code-block:: bash - - $ mkdir -p ${HOME}/rt_kernel_build - $ cd ${HOME}/rt_kernel_build - -All future commands are expected to be run inside this folder. If the folder is different, the ``$`` -sign will be prefixed with a path relative to the above folder. - -Getting the sources for a real-time kernel ------------------------------------------- - -To build a real-time kernel, we first need to get the kernel sources and the real-time patch. - -First, we must decide on the kernel version that we want to use. Above, we -determined that our system has a 4.15 kernel installed. However, real-time -patches exist only for selected kernel versions. Those can be found on the -`linuxfoundation wiki `_. - -In this example, we will select a 4.14 kernel. Select a kernel version close to the -one installed on your system. - -Go ahead and download the kernel sources, patch sources and their signature files: - -.. code-block:: bash - - $ wget https://cdn.kernel.org/pub/linux/kernel/projects/rt/4.14/patch-4.14.139-rt66.patch.xz - $ wget https://cdn.kernel.org/pub/linux/kernel/projects/rt/4.14/patch-4.14.139-rt66.patch.sign - $ wget https://www.kernel.org/pub/linux/kernel/v4.x/linux-4.14.139.tar.xz - $ wget https://www.kernel.org/pub/linux/kernel/v4.x/linux-4.14.139.tar.sign - -To unzip the downloaded files do - -.. code-block:: bash - - $ xz -dk patch-4.14.139-rt66.patch.xz - $ xz -d linux-4.14.139.tar.xz - -Verification -^^^^^^^^^^^^ - -Technically, you can skip this section, it is however highly recommended to verify the file -integrity of such a core component of your system! - -To verify file integrity, you must first import public keys by the kernel developers and the patch -author. For the kernel sources use (as suggested on -`kernel.org `_\ ) - -.. code-block:: bash - - $ gpg2 --locate-keys torvalds@kernel.org gregkh@kernel.org - -and for the patch search for a key of the author listed on -`linuxfoundation wiki `_. - -.. code-block:: bash - - $ gpg2 --keyserver hkp://keys.gnupg.net --search-keys zanussi - gpg: data source: http://51.38.91.189:11371 - (1) German Daniel Zanussi - 4096 bit RSA key 0x537F98A9D92CEAC8, created: 2019-07-24, expires: 2023-07-24 - (2) Michael Zanussi - 4096 bit RSA key 0x7C7F76A2C1E3D9EB, created: 2019-05-08 - (3) Tom Zanussi - Tom Zanussi - Tom Zanussi - 4096 bit RSA key 0xDE09826778A38521, created: 2017-12-15 - (4) Riccardo Zanussi - 2048 bit RSA key 0xD299A06261D919C3, created: 2014-08-27, expires: 2018-08-27 (expired) - (5) Zanussi Gianni - 1024 bit DSA key 0x78B89CB020D1836C, created: 2004-04-06 - (6) Michael Zanussi - Michael Zanussi - Michael Zanussi - Michael Zanussi - 1024 bit DSA key 0xB3E952DCAC653064, created: 2000-09-05 - (7) Michael Zanussi - 1024 bit DSA key 0xEB10BBD9BA749318, created: 1999-05-31 - (8) Michael B. Zanussi - 1024 bit DSA key 0x39EE4EAD7BBB1E43, created: 1998-07-16 - Keys 1-8 of 8 for "zanussi". Enter number(s), N)ext, or Q)uit > 3 - -Now we can verify the downloaded sources: - -.. code-block:: bash - - $ gpg2 --verify linux-4.14.139.tar.sign - gpg: assuming signed data in 'linux-4.14.139.tar' - gpg: Signature made Fr 16 Aug 2019 10:15:17 CEST - gpg: using RSA key 647F28654894E3BD457199BE38DBBDC86092693E - gpg: Good signature from "Greg Kroah-Hartman " [unknown] - gpg: WARNING: This key is not certified with a trusted signature! - gpg: There is no indication that the signature belongs to the owner. - Primary key fingerprint: 647F 2865 4894 E3BD 4571 99BE 38DB BDC8 6092 693E - - $ gpg2 --verify patch-4.14.139-rt66.patch.sign - gpg: assuming signed data in 'patch-4.14.139-rt66.patch' - gpg: Signature made Fr 23 Aug 2019 21:09:20 CEST - gpg: using RSA key 0x0129F38552C38DF1 - gpg: Good signature from "Tom Zanussi " [unknown] - gpg: aka "Tom Zanussi " [unknown] - gpg: aka "Tom Zanussi " [unknown] - gpg: WARNING: This key is not certified with a trusted signature! - gpg: There is no indication that the signature belongs to the owner. - Primary key fingerprint: 5BDF C45C 2ECC 5387 D50C E5EF DE09 8267 78A3 8521 - Subkey fingerprint: ACF8 5F98 16A8 D5F0 96AE 1FD2 0129 F385 52C3 8DF1 - -Compilation ------------ - -Before we can compile the sources, we have to extract the tar archive and apply the patch - -.. code-block:: bash - - $ tar xf linux-4.14.139.tar - $ cd linux-4.14.139 - linux-4.14.139$ xzcat ../patch-4.14.139-rt66.patch.xz | patch -p1 - -Now to configure your kernel, just type - -.. code-block:: bash - - linux-4.14.139$ make oldconfig - -This will ask for kernel options. For everything else then the ``Preemption Model`` use the default -value (just press Enter) or adapt to your preferences. For the preemption model select ``Fully Preemptible Kernel``\ : - -.. code-block:: bash - - Preemption Model - 1. No Forced Preemption (Server) (PREEMPT_NONE) - > 2. Voluntary Kernel Preemption (Desktop) (PREEMPT_VOLUNTARY) - 3. Preemptible Kernel (Low-Latency Desktop) (PREEMPT__LL) (NEW) - 4. Preemptible Kernel (Basic RT) (PREEMPT_RTB) (NEW) - 5. Fully Preemptible Kernel (RT) (PREEMPT_RT_FULL) (NEW) - choice[1-5]: 5 - -Now you can build the kernel. This will take some time... - -.. code-block:: bash - - linux-4.14.139$ make -j $(getconf _NPROCESSORS_ONLN) deb-pkg - -After building, install the ``linux-headers`` and ``linux-image`` packages in the parent folder (only -the ones without the ``-dbg`` in the name) - -.. code-block:: bash - - linux-4.14.139$ sudo apt install ../linux-headers-4.14.139-rt66_*.deb ../linux-image-4.14.139-rt66_*.deb - -Setup user privileges to use real-time scheduling -------------------------------------------------- - -To be able to schedule threads with user privileges (what the driver will do) you'll have to change -the user's limits by changing ``/etc/security/limits.conf`` (See `the manpage `_ for details) - -We recommend to setup a group for real-time users instead of writing a fixed username into the config -file: - -.. code-block:: bash - - $ sudo groupadd realtime - $ sudo usermod -aG realtime $(whoami) - -Then, make sure ``/etc/security/limits.conf`` contains - -.. code-block:: - - @realtime soft rtprio 99 - @realtime soft priority 99 - @realtime soft memlock 102400 - @realtime hard rtprio 99 - @realtime hard priority 99 - @realtime hard memlock 102400 - -Note: You will have to log out and log back in (Not only close your terminal window) for these -changes to take effect. No need to do this now, as we will reboot later on, anyway. - -Setup GRUB to always boot the real-time kernel ----------------------------------------------- - -To make the new kernel the default kernel that the system will boot into every time, you'll have to -change the grub config file inside ``/etc/default/grub``. - -Note: This works for ubuntu, but might not be working for other linux systems. It might be necessary -to use another menuentry name there. - -But first, let's find out the name of the entry that we will want to make the default. You can list -all available kernels using - -.. code-block:: bash - - $ awk -F\' '/menuentry |submenu / {print $1 $2}' /boot/grub/grub.cfg - - menuentry Ubuntu - submenu Advanced options for Ubuntu - menuentry Ubuntu, with Linux 4.15.0-62-generic - menuentry Ubuntu, with Linux 4.15.0-62-generic (recovery mode) - menuentry Ubuntu, with Linux 4.15.0-60-generic - menuentry Ubuntu, with Linux 4.15.0-60-generic (recovery mode) - menuentry Ubuntu, with Linux 4.15.0-58-generic - menuentry Ubuntu, with Linux 4.15.0-58-generic (recovery mode) - menuentry Ubuntu, with Linux 4.14.139-rt66 - menuentry Ubuntu, with Linux 4.14.139-rt66 (recovery mode) - menuentry Memory test (memtest86+) - menuentry Memory test (memtest86+, serial console 115200) - menuentry Windows 7 (on /dev/sdc2) - menuentry Windows 7 (on /dev/sdc3) - -From the output above, we'll need to generate a string with the pattern ``"submenu_name>entry_name"``. In our case this would be - -.. code-block:: - - "Advanced options for Ubuntu>Ubuntu, with Linux 4.14.139-rt66" - -**The double quotes and no spaces around the ``>`` are important!** - -With this, we can setup the default grub entry and then update the grub menu entries. Don't forget this last step! - -.. code-block:: bash - - $ sudo sed -i 's/^GRUB_DEFAULT=.*/GRUB_DEFAULT="Advanced options for Ubuntu>Ubuntu, with Linux 4.14.139-rt66"/' /etc/default/grub - $ sudo update-grub - -Reboot the PC -------------- - -After having performed the above mentioned steps, reboot the PC. It should boot into the correct -kernel automatically. - -Check for preemption capabilities ---------------------------------- - -Make sure that the kernel does indeed support real-time scheduling: - -.. code-block:: bash - - $ uname -v | cut -d" " -f1-4 - #1 SMP PREEMPT RT - -Optional: Disable CPU speed scaling ------------------------------------ - -Many modern CPUs support changing their clock frequency dynamically depending on the currently -requested computation resources. In some cases this can lead to small interruptions in execution. -While the real-time scheduled controller thread should be unaffected by this, any external -components such as a visual servoing system might be interrupted for a short period on scaling -changes. - -To check and modify the power saving mode, install cpufrequtils: - -.. code-block:: bash - - $ sudo apt install cpufrequtils - -Run ``cpufreq-info`` to check available "governors" and the current CPU Frequency (\ ``current CPU -frequency is XXX MHZ``\ ). In the following we will set the governor to "performance". - -.. code-block:: bash - - $ sudo systemctl disable ondemand - $ sudo systemctl enable cpufrequtils - $ sudo sh -c 'echo "GOVERNOR=performance" > /etc/default/cpufrequtils' - $ sudo systemctl daemon-reload && sudo systemctl restart cpufrequtils - -This disables the ``ondemand`` CPU scaling daemon, creates a ``cpufrequtils`` config file and restarts -the ``cpufrequtils`` service. Check with ``cpufreq-info``. - -For further information about governors, please see the `kernel -documentation `_. diff --git a/ur_robot_driver/doc/installation/toc.rst b/ur_robot_driver/doc/installation/toc.rst index 2ee60aae..a99fa533 100644 --- a/ur_robot_driver/doc/installation/toc.rst +++ b/ur_robot_driver/doc/installation/toc.rst @@ -10,7 +10,6 @@ This chapter explains how to install the ``ur_robot_driver`` :caption: Contents: installation - real_time robot_setup install_urcap_cb3 install_urcap_e_series