The OS on icub-head - Installation from scratch

Since iCubOS is based on the Ubuntu server, we will install the latter from the default installer and then manually customize it.

Latest versions

The latest version is based on Ubuntu Server 20.04.1

Create the USB installer

The first step is to download the official Ubuntu 20.04 LTS Server install media from the release page. Search for ubuntu-20.04.x-live-server-amd64.iso.

Then, please create the USB installer using a USB memory and a tool like Balena Etcher.

Find further information about creating a bootable USB stick on Windows, Ubuntu or macOS.

Install Ubuntu

Follow the below steps to install the Ubuntu server on icub-head.

Please, note that the installation procedure can be slightly different in each release, you can see the Ubuntu server official install guide

Warning

The installation procedure will overwrite the disk of your icub-head, so all data will be deleted.

Ubuntu Installer configuration

Install the system by choosing the default options, except for the following steps:

Keyboard and language

Layout : US
Variant : US

Storage configuration

Disable the following option : Setup this disk as an LVM group

Identity

Your name : icub
Your Server's name : icub-head
Pick a username : icub
Choose a password : icub

SSH

Enable the following option : Install SSH server

Required Packages

Install the following packages

nfs-common python-tk libopencv-dev ntpdate vim ssh cmake-curses-gui iperf libportaudio2 portaudio19-dev linux-sound-base alsa-base alsa-utils gdb meld bmon libi2c-dev expect libgfortran10-dev qml-module-qt-labs-folderlistmodel qml-module-qt-labs-settings

Low Latency kernel

Install the following packages

linux-image-lowlatency linux-headers-lowlatency

Disable X server at startup

The x server is started automatically at startup by GDM, so please disable GDM

sudo systemctl disable gdm

Configuration steps

SSH configuration

Configure passwordless ssh: see this link
Disable reverse DNS lookup in SSH server: add the following line to the file /etc/ssh/sshd_config
```
UseDNS no
```

Network performances tweaks

Install the following packages

sudo apt install linux-image-lowlatency linux-headers-lowlatency

Modify the real-time priority of the process, add the file /etc/security/limits.d/icub.conf as follows
```
icub    soft    rtprio    99
icub    hard    rtprio    99
```
Set the max OS receive-buffer size for all types of connections, by adding the file /etc/sysctl.d/20-net-rbuffer.conf as follows
```
# This sets the max OS receive-buffer size for all types of connections
net.core.rmem_max=8388608
```

NTP

Edit the file /etc/default/ntpdate by changing the following lines

NTPDATE_USE_NTP_CONF="no"
...
NTPSERVERS="10.0.0.1 ntp.ubuntu.com"

IMU Bosch

Installation

To use the IMU Bosch BNO055 through the i2c bus these additional steps are required:

Install libraries for i2c: sudo apt install libi2c-dev i2c-tools
Unzip kempld-drivers.30.tar.gz
Compile the custom kernel modules:
```
cd kempld-drivers.30/kempld-modules-{ver}
make
sudo make install
```
{ver} is the Linux version (see uname -r). Ignore ssl errors during installation.
Load the required kernel module(the best should be add them at the startup):
```
sudo insmod kempld-core.ko
sudo insmod i2c-kempld.ko
```
Finally add icub user to i2c group:
```
usermod -a -G i2c icub
```

Test the configuration of i2c and BNO055

To test the installation with the python script BNO055:

python BNO055.py

Note that to make it work you might change the script at line 195:

# Open I2C bus
self._bus = smbus.SMBus(1)

specifying the right number: instead of 1, specify the correct number that can be found through:

i2cdetect -l

Another possible troubleshooting could be to change in the script BNO055.py (line 187) the default address from 0x28 to 0x29

Fixed USB resource names

In order to get a fixed device name for some USB resources such as IMU and USB2SERIAL, you have to create the following UDEV rules

IMU BOSCH: add the file /etc/udev/rules.d/88-bosch-i2c-imu.rules as follows

# iCub Bosch i2c IMU
SUBSYSTEM=="i2c-dev", ATTRS{name}=="i2c-kempld", SYMLINK+="bosch-i2c-imu", MODE="0660", GROUP="i2c"

USB to Serial interface: add the file /etc/udev/rules.d/99-usb-serial.rules as follows

# tty Xsens
SUBSYSTEM=="tty", ATTRS{idVendor}=="2639", SYMLINK+="ttyXsens", MODE="0660", GROUP="tty"

Further installation steps and configuration

Mount via SSH

On the icub-head, graphics-based tools have not been installed (except the ones required for firmware interfaces) and it is better not to install them. Anyway, using graphic tools (like editors, file managers, etc..) is very useful and sometimes essential. Instead of running remotely a tool and displaying it locally (like we did in old PC104), we can mount locally the icub-head filesystem via SSH and run locally all the tools we need. In order to mount locally the icub-head filesystem on your client:

install the sshfs package
```
sudo apt-get install sshfs
```
create a mount point for the remote filesystem (eg.) mkdir /home/icub/icub-head_fs

mount the remote /usr/local/src/robot via SSH

sudo sshfs -o allow_other icub@10.0.0.2:/usr/local/src/robot/ /home/icub/icub-head_fs

If you already set the passwordless SSH login, you can skip the password:

sudo sshfs -o allow_other,IdentityFile=/home/icub/.ssh/id_rsa icub@10.0.0.2:/usr/local/src/robot/ /home/icub/icub-head_fs

Customize the system

What now you need to do is to customize the installation with your hardware and environment (see the "Required configuration" paragraph in Networking, Bluetooth, User Environment chapters as well as Further Tasks chapter )