Wenzhi Bai

Wenzhi Bai

Ph.D. Student in Robotics

Franka Research 3 Environment

5 minute read

Published:

This blog details the steps to configure and install my usual development environment for Franka Research 3.

1. Basic Info

  • Franka Research 3 (version 7)
  • Ubuntu 20.04 Focal Fossa
  • ROS Noetic Ninjemys

2. Installation Instructions

More info see official installation instructions.

2.1. Installing from the ROS repositories

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

2.2. Setting up the real-time kernel

Note: NVIDIA binary drivers are not supported on PREEMPT_RT kernels.

2.2.1. 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

2.2.2. Download real-time patches

For Ubuntu 20.04 tested with the franka recommended kernel version 5.9.1:

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

For Ubuntu 20.04 tested with a newer kernel version 5.15.173:

curl -SLO https://www.kernel.org/pub/linux/kernel/v5.x/linux-5.15.173.tar.xz
curl -SLO https://www.kernel.org/pub/linux/kernel/v5.x/linux-5.15.173.tar.sign
curl -SLO https://www.kernel.org/pub/linux/kernel/projects/rt/5.15/patch-5.15.173-rt82.patch.xz
curl -SLO https://www.kernel.org/pub/linux/kernel/projects/rt/5.15/patch-5.15.173-rt82.patch.sign

2.2.3. Decompress patches

xz -d *.xz

2.2.4. Verifying file integrity

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 xxxxxx
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 xxxxxx. You can obtain it from the key server:

gpg2  --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys xxxxxx

Similarly for the patch:

gpg2 --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys xxxxxx

Note: 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 <gregkh@linuxfoundation.org>" [unknown]
gpg:                 aka "Greg Kroah-Hartman <gregkh@kernel.org>" [unknown]
gpg:                 aka "Greg Kroah-Hartman (Linux kernel stable release signing key) <greg@kroah.com>" [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

2.2.5. 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 user interface (TUI) in which you can configure the preemption model. Use the arrow keys to navigate through the options and make selections.

Navigate with the arrow keys to General Setup > Preemption Model > 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.

After that navigate to Cryptographic API > Certificates for signature checking (at the very bottom of the list) > Provide system-wide ring of revocation certificates > X.509 certificates to be preloaded into the system blacklist keyring

Remove the “debian/canonical-revoked-certs.pem” from the prompt and press Ok.

Save this configuration to .config and exit the TUI.

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

Note: If any errors occur during the process, use make -j1 deb-pkg to rebuild it. This will provide more detailed output for debugging.

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

2.2.6. Verifying the new kernel

  • Restart your system.
  • The Grub boot menu should now allow you to choose your newly installed kernel. It could be found at Advanced options for Ubuntu on the Grub.
  • 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, cat /sys/kernel/realtime should exist and contain the the number 1.

2.2.7. 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(first add write permission by sudo chmod a+w /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.