System Prerequisite#

Working with a real robot system is not an easy thing. You first need to setup the computer systems that support robot control. Deoxys assumes one desktop and one Intel NUC (or non-GPU PC that can be installed with a real-time kernel). In the following section, we describe installation on Desktop and NUC.

Desktop#

Currently the codebase has been tested on Ubuntu 18.04 and 20.04. If you want to run neural network inference efficiently, make sure the GPU(s) of your desktop support(s) CUDA. Other than that, Deoxys does not have other specific requirements for the system.

NUC - RTOS Installation#

libfranka is the low-level API interface we need to control the robot. To run the robot in real-time mode, we need to guarantee that the control command is pre-emptive. Therefore, we need a system that enables pre-emptive scheduling.

We use Intel NUC as the control PC for robot control. This is a small, light-weight computer system. The reason we are not doing this on the desktop is that Real-Time Operating System (RTOS) doesn’t support NVIDIA GPUs. Franka documentation has the overview workflow for compiling RTOS patches. Here we will recap most of the stuff, and include some of the compilation errors we encountered during testing.

Make sure Performance mode is enabled!

For all the programs, make sure the NUC is in the Performance mode. This is to enable pre-emptive scheduling of the system, and a prerequisite to run the franka control programs. It will crash the workflow if this mode is not turned on. To check this, run the following command:

cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor

Assitive Note - RTOS Installation

We've provided a list of checkboxes for you to keep track of all the necessary steps to install RTOS.




Step 1: Compile RTOS patch / Get a pre-compile RTOS patch.

To make the kernel of linux systems to be real-time, we need to compile a RTOS patch and then update the linux kernel with the patch. You can follow the instruction on the official franka documentation. For different systems, you need to compile the ROTS patch on your own.

Potential compilation error

You might encounter the following error:

make[4]: *** No rule to make target 'debian/canonical-certs.pem', needed by 'certs/x509_certificate_list'.  Stop.

When you encounter the error, modify the kernel config files as explained here

Alternatively, you can use the pre-compiled RTOS patch we provide for Ubuntu 20.04.

Step 2: Update your system kernel with RTOS patch.

Once you download the RTOS patches, do:

sudo dpkg -i YOUR_PATH/linux-headers-*.deb YOUR_PATH/linux-image-*.deb

Then restart the system and choose to load the real-time kernel. The system might directly under ubuntu without going through the grub menu. In this case, you need to change GRUB_TIMEOUT to some positive values in the file /etc/default/grub.

Step 3: Configure RTOS.

After restart, you can confirm if the RT kernel has been successfully installed by running the command:

uname -r

And it should show the new kernel such as : 5.4.3-rt1. Run the command cat /sys/kernel/realtime and the termianl should output “1” if everything is correct.

Set real-time settings. This step is crucial as libfranka’s realtime scheduling can only be enabled when the user is added to realtime group. Also make sure that you load the real-time kernel when you have multple coexisting kernels on your system.

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

Add the following to: /etc/security/limits.conf (with sudo gedit or sudo )

@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 one final time.

Step 4: Set up CPU monitoring utilities.

This part is based on the instruction from FrankaPy from Professor Oliver Kroemer’s group at CMU.

Now, we want to install some utilities and files that will maintain the correct CPU governor mode automatically. (For reference, there are usually two CPU governor modes available: powersave and performance. We always want to run the arms in performance mode, which maintains the maximum CPU frequency. Powersave is great for laptops, not laboratory experiments. The following is adapted from link and link

Run the following terminal command:

sudo apt install indicator-cpufreq cpufrequtils

Restart 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. To make our lives easier, we will automate the performance mode selection.

Run the following terminal commands to define the default CPU governor:

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

Then restart cpufrequtils so that performance mode can selected

sudo /etc/init.d/cpufrequtils restart

Edit the following file to change the cpu default behavior (Or create one if there is none):

sudo vim /etc/init.d/cpu.sh

In the cpu.sh file, add the following lines to the file:

sleep 60 # Give CPU startup routines time to settle
sudo /etc/init.d/cpufrequtils restart

Make cpu.sh executable:

sudo chmod +x /etc/init.d/cpu.sh

Allows cpu.sh to be executed at startup:

sudo update-rc.d cpu.sh defaults

Opens /etc/rc.local for editing (see next step for what to add):

sudo vim /etc/rc.local

Add the following line above the line of exit 0:

/etc/init.d/cpu.sh &

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

The purpose of testing CPU Governor Mode

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 the machines are logged in and prevent us from forgetting.

To test if Step 4 is configured correctly: After previous restart, log in to the system with the real-time kernel. 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 (30-60 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.