Installation¶

Requirements¶

A computer with Ubuntu 18.04 / 20.04 Realtime Kernel and at least 1 ethernet port.
ROS Melodic / Noetic or ROS2 Foxy / Humble
Google Protocol Buffer

Recommended Computer Configuration¶

2 Ethernet ports
Wifi
Intel i5-9600K or better
16 GB of RAM
256 GB SSD or more

Computer Setup Instructions¶

These instructions are assuming that you just freshly installed Ubuntu 18.04 / 20.04 on the computer, which we will call the Control PC.

First make sure your computer is completely up to date with all packages:
```
sudo apt update
sudo apt upgrade
```

Install basic packages:

sudo apt install curl openssh-server git vim terminator

Install ROS Melodic or ROS Noetic. Make sure that source /opt/ros/melodic/setup.bash or source /opt/ros/noetic/setup.bash is in your ~/.bashrc file.

Protobuf¶

First determine the number of cores on your computer using the command:
```
nproc
```

Execute the following commands:

sudo apt-get install autoconf automake libtool curl make g++ unzip
wget https://github.com/protocolbuffers/protobuf/releases/download/v21.8/protobuf-all-21.8.zip
unzip protobuf-all-21.8.zip
cd protobuf-21.8
./configure

Use the number that was previously printed out using the nproc command above and substitute it as N below:
```
make -jN
sudo make install
sudo ldconfig
```

Virtual Environment¶

Install Python3:
```
sudo apt install -y python3-distutils
```

Install Pip:

curl https://bootstrap.pypa.io/get-pip.py | sudo -H python3

Install Virtual Environment and Other Useful Python Packages:
```
sudo -H pip3 install numpy matplotlib virtualenv
```
Create a Virtual Environment for Franka-interface:
```
virtualenv -p python3 franka_virtual_env
```
Enter into the Virtual Environment:
```
source franka_virtual_env/bin/activate
```
How to exit the Virtual Environment:
```
deactivate
```

Realtime Kernel¶

If you don’t want to go through the hassle of compiling the realtime kernel yourself, feel free to download a precompiled version for Ubuntu 18.04 here or Ubuntu 20.04 here. Otherwise skip down to the next section first and then come back to this section and start from step 5.

Simply unzip the packages into your Downloads folder.
Enter the directory where you unzipped the files:
```
cd Downloads/Realtime\ Kernel\ Files/
```

Install the realtime kernel by typing the following command. If you are using Ubuntu 18.04, switch all of the 5.15.55-rt48 to 5.4.3-rt1:

sudo dpkg -i linux-headers-5.15.55-rt48_5.15.55-rt48-1_amd64.deb linux-image-5.15.55-rt48_5.15.55-rt48-1_amd64.deb linux-libc-dev_5.15.55-rt48-1_amd64.deb

Restart your computer after it has finished installing the realtime kernel:
```
sudo reboot
```
Once your computer has finished rebooting, uname -r should show the new kernel: 5.15.55-rt48 or 5.4.3-rt1 and cat /sys/kernel/realtime should show an output of 1.

Next you need to set realtime settings:

sudo addgroup realtime
sudo usermod -a -G realtime $(whoami)

Add the following to the end of /etc/security/limits.conf (with sudo gedit or sudo <your favorite editor>):

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

Restart your computer again:
```
sudo reboot
```

Compiling your own Realtime Kernel¶

In order to communicate with the Franka Panda Research Arm at 1 kHz, we need Ubuntu to be patched with the PREEMPT_RT patch. This is also known as the “realtime kernel” patch.

First, install required dependencies:

sudo apt install build-essential bc curl ca-certificates fakeroot gnupg2 libssl-dev lsb-release libelf-dev bison flex

Secondly, you need to pick a mainline kernel version that has a preempt_rt [“RT”] patch. What worked best was selecting the next closest RT kernel available to what was installed on the system. (List of RT versions: https://mirrors.edge.kernel.org/pub/linux/kernel/projects/rt/)

3. Out of the box, Ubuntu 18.04.6 LTS comes with kernel “5.4.0”. So we picked 5.4.3 here. For Ubuntu 20.04.4 LTS, it comes with kernel “5.15.0” so we picked 5.15.55 here. You can identify what kernel version you are currently using with the command uname -r.

We will download both the mainline version of the kernel we want along with the RT patch, extract the mainline kernel and apply the RT patch, then compile the kernel and install it.

Create the directory and download the kernel files (if you are using Ubuntu 18.04, we used 5.4.3):

mkdir -p ~/Downloads/preempt_rt_5.15.55
cd ~/Downloads/preempt_rt_5.15.55
curl -SLO https://mirrors.edge.kernel.org/pub/linux/kernel/v5.x/linux-5.15.55.tar.xz
curl -SLO https://mirrors.edge.kernel.org/pub/linux/kernel/projects/rt/5.15/patch-5.15.55-rt48.patch.xz

6. (In the patch directory (https://mirrors.edge.kernel.org/pub/linux/kernel/projects/rt/5.15/ in this case) you may see both patch and patches file. Use patch – it’s one file that contains everything that’s needed.) The .sign files are used to verify the files (if you’d like – it’s optional).

Decompress tar files:

xz -d linux-5.15.55.tar.xz
xz -d patch-5.15.55-rt48.patch.xz

Apply the kernel patch:

tar xf linux-5.15.55.tar
cd linux-5.15.55/
patch -p1 < ../patch-5.15.55-rt48.patch

Follow additional kernel configuration options here.
If you run into errors with certificates, I followed instructions here. and here.

Now, we want to install the new .deb packages, but not ones with dbg in the file name:

cd ..
sudo dpkg -i linux-headers-5.15.55-rt48_5.15.55-rt48-1_amd64.deb linux-image-5.15.55-rt48_5.15.55-rt48-1_amd64.deb linux-libc-dev_5.15.55-rt48-1_amd64.deb

Restart your computer after it has finished installing:
```
sudo reboot
```

CPU Monitoring Utilities¶

Now, we want to install some utilities and files that will maintain the correct CPU governor mode. (For reference, there are usually two CPU governor modes available: powersave and performance. We always want to run the Control PC in performance mode, which maintains the maximum CPU frequency. Powersave is great for laptops, not laboratory experiments. The following is adapted from https://askubuntu.com/questions/929884/how-to-set-performance-instead-of-powersave-as-default and https://askubuntu.com/questions/621184/how-to-make-cpupower-not-reset-after-each-restart)

Run the following command:

sudo apt install indicator-cpufreq cpufrequtils

Restart the computer and then confirm that indicator-cpufreq starts when logged in. You should see what looks like a CPU icon in the system toolbar, with a drop-down menu that shows the current CPU governor. You can select the performance mode here, but we will now add files to do this automatically. Run the following terminal commands in order.

Defining the default CPU governor:

echo "GOVERNOR="performance"" | sudo tee /etc/default/cpufrequtils

Restarting cpufrequtils so that performance mode is selected:
```
sudo /etc/init.d/cpufrequtils restart
```
Creating the cpu.sh script that restarts cpufrequtils:
```
sudo gedit /etc/init.d/cpu.sh
```

Add the following lines to cpu.sh:

sleep 60
sudo /etc/init.d/cpufrequtils restart

Enabling cpu.sh to be executable:
```
sudo chmod +x /etc/init.d/cpu.sh
```
Allowing cpu.sh to be executed at startup:
```
sudo update-rc.d cpu.sh defaults
```
Creating the /etc/rc.local file:
```
sudo gedit /etc/rc.local
```

Add the following lines to /etc/rc.local:

#!/bin/sh -e
#
# rc.local
#
# This script is executed at the end of each multiuser runlevel.
# Make sure that the script will "exit 0" on success or any other
# value on error.
#
# In order to enable or disable this script just change the execution
# bits.
#
# By default this script does nothing.

/etc/init.d/cpu.sh &

exit 0

Make rc.local executable:
```
sudo chmod +x /etc/rc.local
```
Reboot the computer:
```
sudo reboot
```

In short, we have defined the default CPU governor, then created several processes for Ubuntu to automatically select this governor when you log in.

It is important to test that the correct CPU governor mode is automatically selected on startup, because using the wrong mode may adversely affect communications with the robot arms and thus experiments. We want this to be automatically set correctly when logging in to the computer and not have to deal with it.

From a computer reboot, log in to the computer. Select the indicator-cpufreq icon to display the drop-down menu, but do not select anything. We will keep the menu open during this test. Observe that the governor is currently set to performance. After some time after login (20-40 seconds), a system process will change this to powersave. You will see this change automatically in the menu.

However, after about 60 seconds, you should observe that the governor automatically changes back to performance. This happens because of the commands we added to the /etc/rc.local file!

If you observe that the governor properly gets changed to performance mode, then everything has been set up correctly.

Franka-Interface Installation Steps¶

Clone the Franka-interface Repository and its Submodules:

git clone --recurse-submodules https://github.com/iamlab-cmu/franka-interface.git
cd franka-interface

Clone LibFranka corresponding to your robot version. For example if your firmware is 3.x use the following command:
```
bash ./bash_scripts/clone_libfranka.sh 3
```
If you are using a Franka Research 3, you should use the following command:
```
bash ./bash_scripts/clone_libfranka.sh 6
```

In addition, if you are using a Franka Research 3, you should go to the following file (franka-interface/include/franka-interface/termination_handler/termination_handler.h) and comment lines 97 and 98 and uncomment lines 102 and 103:

// Franka Panda Joint Limits from https://frankaemika.github.io/docs/control_parameters.html
const std::array<double, 7> max_joint_limits_ = std::array<double, 7>{2.88, 1.75, 2.88, -0.06, 2.88, 3.74, 2.88};
const std::array<double, 7> min_joint_limits_ = std::array<double, 7>{-2.88, -1.75, -2.88, -3.06, -2.88, -0.0025, -2.88};

// Comment the 2 lines above and uncomment the 2 lines below if you are using a Franka Research 3
// Franka Research 3 Joint Limits from https://frankaemika.github.io/docs/control_parameters.html
// const std::array<double, 7> max_joint_limits_ = std::array<double, 7>{2.73, 1.77, 2.88, -0.14, 2.79, 4.5, 3.0};
// const std::array<double, 7> min_joint_limits_ = std::array<double, 7>{-2.73, -1.77, -2.88, -3.03, -2.79, 0.53, -3.0};

Build LibFranka:
```
bash ./bash_scripts/make_libfranka.sh
```

If you ran the command clone_libfranka.sh with the number 5, you should follow the additional commands:

cd libfranka/build
sudo make install
cd ../../catkin_ws/src/
git clone https://github.com/frankaemika/franka_ros.git
cd franka_ros
git checkout 0.9.1
cd ../../../

If you have the franka research 3 and ran the command clone_libfranka.sh with the number 6, you should follow the additional commands:

cd libfranka/build
sudo make install
cd ../../catkin_ws/src/
git clone https://github.com/frankaemika/franka_ros.git
cd franka_ros
git checkout 0.10.0
cd ../../../

Otherwise, if you used clone_libfranka.sh with the numbers 2, 3, or 4, follow the below command to install the franka_ros package. Switch noetic to melodic if you are on Ubuntu 18.04:
```
sudo apt install ros-noetic-libfranka ros-noetic-franka-ros
```

Build franka-interface:

bash ./bash_scripts/make_franka_interface.sh

Enter the franka virtual environment (Virtual Environment) and then run the following commands:
```
pip install catkin-tools empy
bash ./bash_scripts/make_catkin.sh
```
Afterwards source the catkin_ws using the following command:

source catkin_ws/devel/setup.bash
Add the following lines to the end of your ~/.bashrc file:

source /path/to/franka_virtual_env/franka/bin/activate source /path/to/franka-interface/catkin_ws/devel/setup.bash –extend