Install on Linux

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

C++ RDK

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 C++ dependencies

  1. Clone or download flexiv_rdk repo following page Download Flexiv RDK.

  2. Choose a directory for installing C++ RDK 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

Install C++ RDK

  1. After all dependencies are installed, open a new Terminal and use CMake to configure the flexiv_rdk 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.

  • The configuration process can also be done using CMake GUI.

  1. Install C++ RDK:

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

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

  • include/flexiv/rdk/

  • lib/cmake/flexiv_rdk/

Python RDK

Prepare build tools

Besides tools in Prepare build tools, 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 Python dependencies

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

python3.x -m pip install numpy spdlog

Install Python RDK

  1. Similar to step 1 in Install C++ RDK, but set an additional CMake variable INSTALL_PYTHON_RDK to ON when configuring flexiv_rdk to install Python RDK to the user site packages path, which is globally discoverable by Python interpreter:

    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.

  1. Install Python RDK:

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

  2. If the installation was successful, you should be able to import flexivrdk from any Python script. Test the following commands in a new Terminal, which should give no error:

    python3
import flexivrdk

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.

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