# 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:
```shell
cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
```
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:
``` shell
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](https://askubuntu.com/questions/1329538/compiling-the-kernel-5-11-11)
Alternatively, you can use the pre-compiled RTOS patch we provide for [Ubuntu 20.04](https://utexas.box.com/s/wrc76zrc8oh4nlk5kq3hqmyy5rire7y0).
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:
```shell
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](https://github.com/iamlab-cmu/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](https://askubuntu.com/questions/929884/how-to-set-performance-instead-of-powersave-as-default)
and [link](https://askubuntu.com/questions/621184/how-to-make-cpupower-not-reset-after-each-restart)
Run the following terminal command:
``` shell
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:
``` shell
echo "GOVERNOR="performance"" | sudo tee /etc/default/cpufrequtils
```
Then restart `cpufrequtils` so that `performance mode` can selected
``` shell
sudo /etc/init.d/cpufrequtils restart
```
Edit the following file to change the cpu default behavior (Or create
one if there is none):
``` shell
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.