Install on Linux
====================

The RDK C++ and Python libraries are packed into a unified modern CMake project named ``flexiv_rdk``, which can be configured and installed using CMake on all supported OS.

C++
-------

.. _prepare_cpp_build_tools_on_linux:

Prepare build tools
~~~~~~~~~~~~~~~~~~~~

Compiler kit and CMake (with GUI) are needed and can be installed via::

	sudo apt install build-essential cmake cmake-qt-gui -y


.. _install_cpp_deps_on_linux:

Install dependencies
~~~~~~~~~~~~~~~~~~~~~

1. Clone or download ``flexiv_rdk`` repo following page :doc:`download_rdk`.
2. Choose a directory for installing RDK C++ library and all its dependencies. This directory can be under system path or not, depending on whether you want RDK to be globally discoverable by CMake. For example, a new folder named ``rdk_install`` under the home directory.
3. In a new Terminal, run the provided script to compile and install all C++ dependencies to the installation directory chosen in step 2::

		cd flexiv_rdk/thirdparty
		bash build_and_install_dependencies.sh ~/rdk_install

  .. note::
    Internet connection is required for this step.

.. _install_cpp_rdk_on_linux:

Install RDK library
~~~~~~~~~~~~~~~~~~~

1. After all dependencies are installed, open a new Terminal and configure ``flexiv_rdk`` library as a CMake project::

		cd flexiv_rdk
		mkdir build && cd build
		cmake .. -DCMAKE_INSTALL_PREFIX=~/rdk_install

  .. note::
    * ``-D`` followed by ``CMAKE_INSTALL_PREFIX`` sets the CMake variable that specifies the path of the installation directory.
    * Alternatively, this configuration step can be done using CMake GUI.

2. Install ``flexiv_rdk`` C++ library, which may or may not be globally discoverable by CMake::

		cd flexiv_rdk/build
		cmake --build . --target install --config Release

3. If the installation was successful, the following directories should appear in ``rdk_install`` folder:

  * include/flexiv/rdk/
  * lib/cmake/flexiv_rdk/


.. _link_cpp_rdk_on_linux:

Link to installed library from a user program
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

After the RDK C++ library ``flexiv_rdk`` is installed, it can be found as a CMake target and linked to from other CMake projects. Using the provided examples project for instance::

	cd flexiv_rdk/example
	mkdir build && cd build
	cmake .. -DCMAKE_INSTALL_PREFIX=~/rdk_install
	cmake --build . --config Release -j 4

.. note::
  ``-D`` followed by ``CMAKE_INSTALL_PREFIX`` tells the user project's CMake where to find the installed RDK C++ library.


Python
-------

Prepare build tools
~~~~~~~~~~~~~~~~~~~~

Besides tools in :ref:`prepare_cpp_build_tools_on_linux`, Python interpreter and Python package manager are also needed and can be installed via::

	sudo apt install python3 python3-pip -y

To install a different version of Python alongside the system's native Python, add and use a personal package archive (PPA)::

      sudo apt install software-properties-common
      sudo add-apt-repository ppa:deadsnakes/ppa
      sudo apt update
      sudo apt install python3.x

When done, this specific version of Python can be invoked from Terminal using ``python3.x``::

      python3.x --version

However, the commands above do not install the ``pip`` package manager for this Python 3.x and it needs to be manually installed::

      wget https://bootstrap.pypa.io/get-pip.py
      python3.x get-pip.py

Once it's finished, you can install a Python package discoverable by the PPA-installed Python 3.x via::

      python3.x -m pip install <package_name>

.. warning::
   The ``sudo apt install python3-pip`` command only installs ``pip`` for the system's native Python, and Python packages installed using this ``pip`` is not discoverable by other versions of Python.

.. _install_py_deps_on_linux:

Install dependencies
~~~~~~~~~~~~~~~~~~~~~

Install dependencies of RDK Python library for a specific version of Python::

	python3.x -m pip install numpy spdlog


.. _install_py_rdk_on_linux:

Install RDK library
~~~~~~~~~~~~~~~~~~~

1. Similar to step 1 in :ref:`install_cpp_rdk_on_linux`, but set an additional CMake variable ``INSTALL_PYTHON_RDK`` to ON when configuring ``flexiv_rdk`` to also install the Python library to the user site packages path::

		cd flexiv_rdk
		mkdir build && cd build
		cmake .. -DCMAKE_INSTALL_PREFIX=~/rdk_install -DINSTALL_PYTHON_RDK=ON

  .. note::
    This will install RDK for Python 3.10 by default. To choose another Python version to install RDK for, open CMake GUI for ``flexiv_rdk``::

			cd flexiv_rdk/build
			cmake-gui ..

    Select another version from the drop-down menu of CMake variable ``RDK_PYTHON_VERSION``, then click *Generate* and close the GUI window.

2. Install ``flexivrdk`` Python library, which is globally discoverable by the Python interpreter with the specified version::

		cd flexiv_rdk/build
		cmake --build . --target install --config Release

.. _link_py_rdk_on_linux:

Link to installed library from a user program
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

After the RDK Python library ``flexivrdk`` is installed, it can be imported from any Python script. Test with the following commands in a new Terminal, which should start Flexiv RDK::

		python3
		import flexivrdk
      robot = flexivrdk.Robot("Rizon4-123456")

If a robot is not connected, the program will just exit after a couple of seconds.

.. _rt_kernel:

Set up real-time kernel (optional, Linux only)
-------------------------------------------------

.. important::
   Not all use cases require patching the Linux real-time kernel, please read below to determine if you need it.


Should I patch the real-time kernel?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Yes
^^^

Linux real-time kernel is recommended if you require **hard real-time** performance, which means:

* No missed cycle.
* Minimal and stable whole-loop latency (from sending out command to receiving feedback: ~2ms).
* Deterministic program execution with stable cycle time.

But do note that:

* The patching process is tedious and may take hours.
* Successful patching is not guaranteed since some computers may be incompatible with the real-time kernel.

.. note::
   Ubuntu 22.04 users can take advantage of its native real-time kernel support and skip the following manual patching process. To activate the native real-time kernel, follow `this tutorial <https://ubuntu.com/blog/real-time-ubuntu-released>`_.


No
^^^

You can skip the patching and use the generic kernel shipped natively with Linux installation if you only require **soft real-time** performance, which means:

* A small number of missed cycles can be tolerated.
* Relatively greater and less stable whole-loop latency (from sending out command to receiving feedback: 4~10ms).
* Less deterministic program execution with less stable cycle time.

Or, you only need **non-real-time** access to the robot.


Prepare files
~~~~~~~~~~~~~~

In order to control the robot using RDK, the controller program on the workstation PC must run as a *real-time process* under a 
real-time kernel. We suggest the *PREEMPT_RT* kernel for this purpose due to its balance between ease of use and real-time performance.

.. note::
   There has been reports on issues with NVIDIA graphics card drivers when used with *PREEMPT_RT* kernel. Please refer to 
   NVIDIA's support forums for installing a driver patch.

Install dependencies::

   sudo apt install -y git build-essential cmake ncurses-dev xz-utils libssl-dev bc flex libelf-dev bison curl gnupg2


A standard Ubuntu installation comes with a generic kernel, you can check the version of your kernel using ``uname -r``. 
It should appear as ``x.y.z`` where x, y and z are the major, minor and patch digits. In the following, we use Ubuntu 20.04 
machine with a ``5.11.4`` kernel as example.

Real-time kernel patches are only available for selected versions. Please visit `<https://mirrors.edge.kernel.org/pub/linux/kernel/v5.x/>`_ 
to make sure the kernel source named ``linux-5.11.4.tar.xz`` is available. Then visit `<https://mirrors.edge.kernel.org/pub/linux/kernel/projects/rt/>`_ 
to make sure the real-time patch corresponding to the kernel source you are going to use is also available. The version of 
the kernel source should be the same as the version indicated on the patch. For example, we need to make sure ``patch-5.11.4-rt11.patch.xz`` is 
available.

When decided which version to use, download both the source and patch files using::

   curl -LO https://mirrors.edge.kernel.org/pub/linux/kernel/v5.x/linux-5.11.4.tar.xz
   curl -LO https://mirrors.edge.kernel.org/pub/linux/kernel/v5.x/linux-5.11.4.tar.sign
   curl -LO https://mirrors.edge.kernel.org/pub/linux/kernel/projects/rt/5.11/patch-5.11.4-rt11.patch.xz
   curl -LO https://mirrors.edge.kernel.org/pub/linux/kernel/projects/rt/5.11/patch-5.11.4-rt11.patch.sign  

Unzip the xz packages::

   xz -dk linux-5.11.4.tar.xz
   xz -dk patch-5.11.4-rt11.patch.xz


Verify downloaded files (optional)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To verify the signature of kernel sources, run the following::

   gpg2 --locate-keys torvalds@kernel.org gregkh@kernel.org
   gpg2 --verify linux-5.11.4.tar.sign

To verify the patches, please visit `the Linux Foundation Wiki <https://wiki.linuxfoundation.org/realtime/preempt_rt_versions>`_  
to search for a key of the author, then run the following::

   gpg2 --verify patch-5.11.4-rt11.patch.sign


Compile and install real-time kernel
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Before compiling the sources, we have to apply the patches::

   tar xf linux-5.11.4.tar
   cd linux-5.11.4
   patch -p1 < ../patch-5.11.4-rt11.patch

Next, we configure our kernel::

   make oldconfig

A series of questions will pop up, you can select the default option. When asked for the Preemption Model, choose the ``Fully Preemptible Kernel``::

   Preemption Model
   1. No Forced Preemption (Server) (PREEMPT_NONE)
   > 2. Voluntary Kernel Preemption (Desktop) (PREEMPT_VOLUNTARY)
   3. Preemptible Kernel (Low-Latency Desktop) (PREEMPT)
   4. Fully Preemptible Kernel (Real-Time) (PREEMPT_RT) (NEW)
   choice[1-4?]: 4

For all the other questions, press enter to select the default option. Note you can long-press enter to fast-forward all questions with the default option. 
When done, a file called ".config" will be generated. Before we can compile the kernel, open the ".config" file, find and set the following configuration parameters::

   CONFIG_SYSTEM_TRUSTED_KEYS = ""
   CONFIG_SYSTEM_REVOCATION_KEYS = ""
   
Now, we are ready to compile our new kernel::

   make -j `getconf _NPROCESSORS_ONLN` deb-pkg

After the build is finished check the debian packages::

   ls ../*deb
   
Then we install all compiled kernel debian packages::

   sudo dpkg -i ../*.deb


Set user privileges to use real-time scheduling
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To be able to schedule threads with user privileges, we will need to change the user's limits by modifying ``/etc/security/limits.conf``. 
To do so, we create a group named *realtime* and add the user operating the robot to this group::

   sudo groupadd realtime
   sudo usermod -aG realtime $(whoami)

Next, make sure ``/etc/security/limits.conf`` contains the following::

   @realtime soft rtprio 99
   @realtime soft priority 99
   @realtime soft memlock 102400
   @realtime hard rtprio 99
   @realtime hard priority 99
   @realtime hard memlock 102400


Set GRUB to boot with real-time kernel
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

We will use grub-customizer to configure grub. To install for Ubuntu 20.04::

   sudo apt install grub-customizer -y

To install for Ubuntu 18.04::

   sudo add-apt-repository ppa:danielrichter2007/grub-customizer -y
   sudo apt update -y
   sudo apt install grub-customizer -y

Simply follow the instructions in this `It's FOSS tutorial <https://itsfoss.com/grub-customizer-ubuntu/>`_ to update your grub settings.

Now reboot the system and select the ``PREEMPT_RT`` kernel. Once booted, run ``uname -a`` command in Terminal. If everything is done correctly, 
the command will return a string with ``PREEMPT_RT`` keyword.


Disable CPU speed scaling (optional) 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Modern CPUs are able to dynamically scale their frequency depending on operating conditions. In some cases, this can lead to uneven processing speed 
that in turn interrupts execution. These fluctuations in processing speed can affect the overall performance of the real-time processes.

To disable speed scaling, we will use ``cpufrequtils`` to disable power saving mode::

   sudo apt install cpufrequtils

Running ``cpufreq-info`` shows you the available cpufreq governors. The standard setting is ``performance, powersave``. 
We will switch all governers to ``performance``::

   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