Installation on Linux
=====================
This chapter describes how to install ``libfranka`` and ``franka_ros``, either
as binary packages or by building from source, and how to install a real-time
Linux kernel. ``franka_ros`` is only required if you want to control your robot
using `ROS `_.
.. note::
While ``libfranka`` and the ``franka_ros`` packages should work on different Linux distributions,
official support is currently only provided for:
* Ubuntu 18.04 LTS `Bionic Beaver` and ROS `Melodic Morenia` (requires at least ``libfranka`` 0.6.0)
* Ubuntu 20.04 LTS `Focal Fossa` and ROS `Noetic Ninjemys` (requires at least ``libfranka`` 0.8.0)
The following instructions are exemplary for Ubuntu 20.04 LTS system and ROS `Noetic Ninjemys`.
They only work in the supported environments.
.. warning::
We do not offer support for Ubuntu 16.04 LTS `Xenial Xerus` and ROS `Kinetic Kame` anymore, as they have reached their
end-of-life.
Installing from the ROS repositories
------------------------------------
.. hint::
These packages might not always be up-to-date, as they are only synced at certain intervals.
Read the changelog at https://frankaemika.github.io to find out which ``libfranka`` version is required for
a particular robot software version. If this doesn't match the ``ros-noetic-libfranka`` version from the
repositories, you need to :ref:`build from source `.
Binary packages for ``libfranka`` and ``franka_ros`` are available from the ROS repositories.
After `setting up ROS Noetic `__, execute::
sudo apt install ros-noetic-libfranka ros-noetic-franka-ros
.. _installation-build-from-source:
Building from source
--------------------
Before building from source, please uninstall existing installations of ``libfranka`` and
``franka_ros`` to avoid conflicts::
sudo apt remove "*libfranka*"
.. _build-libfranka:
Building libfranka
^^^^^^^^^^^^^^^^^^
To build ``libfranka``, install the following dependencies from Ubuntu's package manager::
sudo apt install build-essential cmake git libpoco-dev libeigen3-dev
Then, download the source code by cloning ``libfranka`` from `GitHub `__.
For Panda you need to clone:
.. code-block:: shell
git clone --recursive https://github.com/frankaemika/libfranka # only for panda
cd libfranka
By default, this will check out the newest release of ``libfranka``. If you want to build a particular version of
``libfranka`` instead, check out the corresponding Git tag::
git checkout
git submodule update
The above instructions for cloning libfranka only work for Panda. For Franka Research 3 you have to clone:
.. code-block::
git clone --recursive https://github.com/frankaemika/libfranka --branch 0.10.0 # only for FR3
cd libfranka
In the source directory, create a build directory and run CMake:
.. code-block:: shell
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=OFF ..
cmake --build .
Optionally (but recommended), a ``libfranka`` Debian package can be built using the following command in the same directory:
.. code-block:: shell
cpack -G DEB
This creates `libfranka--.deb`. This package can then be installed with:
.. code-block:: shell
sudo dpkg -i libfranka*.deb
Building the ROS packages
^^^^^^^^^^^^^^^^^^^^^^^^^
After `setting up ROS Noetic `__, create a Catkin
workspace in a directory of your choice:
.. code-block:: shell
cd /path/to/desired/folder
mkdir -p catkin_ws/src
cd catkin_ws
source /opt/ros/noetic/setup.sh
catkin_init_workspace src
Then clone the ``franka_ros`` repository from `GitHub `__::
git clone --recursive https://github.com/frankaemika/franka_ros src/franka_ros
By default, this will check out the newest release of ``franka_ros``. If you want to build a particular version of
``franka_ros`` instead, check out the corresponding Git tag::
git checkout
Install any missing dependencies and build the packages:
.. code-block:: shell
rosdep install --from-paths src --ignore-src --rosdistro noetic -y --skip-keys libfranka
catkin_make -DCMAKE_BUILD_TYPE=Release -DFranka_DIR:PATH=/path/to/libfranka/build
source devel/setup.sh
.. warning::
If you also installed ``ros-noetic-libfranka``, ``libfranka`` might be picked up from ``/opt/ros/noetic``
instead of from your custom ``libfranka`` build!
.. _preempt:
Setting up the real-time kernel
-------------------------------
In order to control your robot using ``libfranka``, the controller program on
the workstation PC must run with `real-time priority` under a ``PREEMPT_RT``
kernel. This section describes the procedure of patching a kernel to support
``PREEMPT_RT`` and creating an installation package.
.. note::
NVIDIA binary drivers are not supported on ``PREEMPT_RT`` kernels.
First, install the necessary dependencies::
sudo apt-get install build-essential bc curl ca-certificates gnupg2 libssl-dev lsb-release libelf-dev bison flex dwarves zstd libncurses-dev
Then, you have to decide which kernel version to use. To find the one you are
using currently, use ``uname -r``. Real-time patches are only available for
select kernel versions, see
https://www.kernel.org/pub/linux/kernel/projects/rt/. We recommend choosing the
version closest to the one you currently use. If you choose a
different version, simply substitute the numbers. Having decided on a version,
use ``curl`` to download the source files:
.. note::
For Ubuntu 16.04 tested with the kernel version 4.14.12:
.. code::
curl -SLO https://www.kernel.org/pub/linux/kernel/v4.x/linux-4.14.12.tar.xz
curl -SLO https://www.kernel.org/pub/linux/kernel/v4.x/linux-4.14.12.tar.sign
curl -SLO https://www.kernel.org/pub/linux/kernel/projects/rt/4.14/older/patch-4.14.12-rt10.patch.xz
curl -SLO https://www.kernel.org/pub/linux/kernel/projects/rt/4.14/older/patch-4.14.12-rt10.patch.sign
.. note::
For Ubuntu 18.04 tested with the kernel version 5.4.19:
.. code::
curl -SLO https://www.kernel.org/pub/linux/kernel/v5.x/linux-5.4.19.tar.xz
curl -SLO https://www.kernel.org/pub/linux/kernel/v5.x/linux-5.4.19.tar.sign
curl -SLO https://www.kernel.org/pub/linux/kernel/projects/rt/5.4/older/patch-5.4.19-rt10.patch.xz
curl -SLO https://www.kernel.org/pub/linux/kernel/projects/rt/5.4/older/patch-5.4.19-rt10.patch.sign
.. note::
For Ubuntu 20.04 tested with the kernel version 5.9.1:
.. code::
curl -SLO https://www.kernel.org/pub/linux/kernel/v5.x/linux-5.9.1.tar.xz
curl -SLO https://www.kernel.org/pub/linux/kernel/v5.x/linux-5.9.1.tar.sign
curl -SLO https://www.kernel.org/pub/linux/kernel/projects/rt/5.9/patch-5.9.1-rt20.patch.xz
curl -SLO https://www.kernel.org/pub/linux/kernel/projects/rt/5.9/patch-5.9.1-rt20.patch.sign
And decompress them with::
xz -d *.xz
Verifying file integrity
^^^^^^^^^^^^^^^^^^^^^^^^
.. note::
This step is optional but recommended!
The ``.sign`` files can be used to verify that the downloaded files were not
corrupted or tampered with. The steps shown here are adapted from the
`Linux Kernel Archive `_ , see the
linked page for more details about the process.
You can use ``gpg2`` to verify the ``.tar`` archives::
gpg2 --verify linux-*.tar.sign
gpg2 --verify patch-*.patch.sign
If your output is similar to the following::
$ gpg2 --verify linux-*.tar.sign
gpg: assuming signed data in 'linux-4.14.12.tar'
gpg: Signature made Fr 05 Jan 2018 06:49:11 PST using RSA key ID 6092693E
gpg: Can't check signature: No public key
You have to first download the public key of the person who signed the above
file. As you can see from the above output, it has the ID ``6092693E``. You can
obtain it from the key server::
gpg2 --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 6092693E
Similarly for the patch::
gpg2 --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 2872E4CC
Note that keys for other kernel version might have different IDs, you will have to
adapt accordingly.
Having downloaded the keys, you can now verify the sources. Here is an example of
a correct output::
$ gpg2 --verify linux-*.tar.sign
gpg: assuming signed data in 'linux-4.14.12.tar'
gpg: Signature made Fr 05 Jan 2018 06:49:11 PST using RSA key ID 6092693E
gpg: Good signature from "Greg Kroah-Hartman " [unknown]
gpg: aka "Greg Kroah-Hartman " [unknown]
gpg: aka "Greg Kroah-Hartman (Linux kernel stable release signing key) " [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
See `Linux Kernel Archive `_
for more information about the warning.
Compiling the kernel
^^^^^^^^^^^^^^^^^^^^
Once you are sure the files were downloaded properly, you can extract the source
code and apply the patch::
tar xf linux-*.tar
cd linux-*/
patch -p1 < ../patch-*.patch
Next copy your currently booted kernel configuration as the default config for the new real time kernel::
cp -v /boot/config-$(uname -r) .config
Now you can use this config as the default to configure the build::
make olddefconfig
make menuconfig
The second command brings up a terminal interface in which you can configure the preemption model. Navigate with the
arrow keys to *General Setup* > *Preemption Model* and select *Fully Preemptible Kernel (Real-Time)*.
After that navigate to *Cryptographic API* > *Certificates for signature checking*
(at the very bottom of the list) > *Provide system-wide ring of trusted keys* >
*Additional X.509 keys for default system keyring*
Remove the "debian/canonical-certs.pem" from the prompt and press Ok. Save this
configuration to ``.config`` and exit the TUI.
.. note::
If you prefer GUIs over TUIs use ``make xconfig`` instead of ``make menuconfig``
Afterwards, you are ready to compile the kernel. As this is a lengthy process, set the
multithreading option ``-j`` to the number of your CPU cores::
make -j$(nproc) deb-pkg
Finally, you are ready to install the newly created package. The exact names
depend on your environment, but you are looking for ``headers`` and ``images``
packages without the ``dbg`` suffix. To install::
sudo dpkg -i ../linux-headers-*.deb ../linux-image-*.deb
Verifying the new kernel
^^^^^^^^^^^^^^^^^^^^^^^^
Restart your system. The Grub boot menu should now allow you to choose your
newly installed kernel. To see which one is currently being used, see the output
of the ``uname -a`` command. It should contain the string ``PREEMPT RT`` and the
version number you chose. Additionally, ``/sys/kernel/realtime`` should exist and
contain the the number ``1``.
.. note::
If you encounter errors that you fail to boot the new kernel see :ref:`troubleshooting_realtime_kernel`
.. _installation-real-time:
Allow a user to set real-time permissions for its processes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
After the ``PREEMPT_RT`` kernel is installed and running, add a group named
`realtime` and add the user controlling your robot to this group::
sudo addgroup realtime
sudo usermod -a -G realtime $(whoami)
Afterwards, add the following limits to the `realtime` group in
``/etc/security/limits.conf``::
@realtime soft rtprio 99
@realtime soft priority 99
@realtime soft memlock 102400
@realtime hard rtprio 99
@realtime hard priority 99
@realtime hard memlock 102400
The limits will be applied after you log out and in again.