PC104 Linux Image - Support for version prev 5.0

From Wiki for iCub and Friends
Jump to: navigation, search

NOTE : this page is valid ONLY for the PC104 image with version older that 5.0 for newer versions read this page

This page contains detailed information about the Linux distribution running inside the iCub's pc104 and keep track of important files and configurations, therefore it's meant to be read by iCub "nanny" (a.k.a. production and support).

This page will explain last version of iCub usb key, namely versions 1.7 and 3.0

Let's start from the beginning: which Linux am I facing? At any time to determine the version of the image is running on your iCub, the following commands can be used:

cat /VERSION     The version of the image will be prompted
cat /ChangeLog   The list of changes applied to the image will be prompted

Archives with all configuration files and kernel install packages have been uploaded at https://robotcub.svn.sourceforge.net/svnroot/robotcub/trunk/iCub/pc104/Debian-OS-customizations/

Info point.jpg Compile the Kernel

  • image 1.7

this version uses default 2.6.24-etchnhalf.1-686 kernel.

  • image3.0

Kernel has been recompiled with RealTime patch (rt30) from http://rt.wiki.kernel.org/ adding fully preemptible feature.

Install following packages required for the procedure.

Super user icon.jpeg sudo apt-get install kernel-package build-essential ncurses-dev zlib1g-dev sed fakeroot

N.B. first 2 packages are REQUIRED also when the resulting .debs are installed on the new system in order to correctly create the initrd.

Apply the rt-patch:

cd /usr/src/linux-folder
#if you have a bz2 patch file
bzip2 -dc /usr/src/patch-file.bz2 | patch -p1 --dry-run	(just test if patch is correct but do nothing on files)
bzip2 -dc /usr/src/patch-file.bz2 | patch -p1			(if previous command gave no errors)

#if patch file is already uncompressed
patch -p1 --dry-run < ../patch-file				(as above)
patch -p1 < ../patch-file	

#copy the existing .config file if any
cp /boot/config-'uname -r' ./.config

make menuconfig

Set the RT kernel options:
kernel type and features

-> preemtion model
-> rt-mode (4th)

kernel hacking

-> kernel debugging OFF!
-> tracing : optional, activate to see kernel latency

Disable power saving options like explained in the hereafter, (extracted from rt.wiki.kernel.org). See the official website for updated info:

Activated the High-Resolution-Timer Option (Attention, the amount of supported platforms by the HR timer is still very limited. Right now the option is only supported on x86 systems, PowerPC and ARM Support are however in queue.)
disabled all Power Management Options like ACPI or APM. NOTE: Since rt patch 2.6.18-rt6 you will probably have to activate ACPI option to activate high resolution timer. Since the TSC timer on PC platforms, as used in the previous versions, are now marked as unsuitable for hrt mode due to many lacks of functionalities and reliabilties, you will need i.E. pm_timer as provided by ACPI to use as clock source. To activate the pm_timer, you can just activate the ACPI_SUPPORT in menuconfig and deactivate all other sub modules like "fan", "processor" or "button". If you have an old pc, which lacks ACPI support, you migh have problems using the high resolution timer. Further interesting options can be found under the "Kernel Hacking" menu entry This menu lists options for system debugging and performance measurement. Keep in mind that the debug options may either increase the kernel size or cause higher latencies. If you do not want to debug the kernel or get some automatically produced histograms, make sure that you don't activate any unnecessary options here. If you have activated any latency critical options the kernel will warn at boot time. experimental features can be remove if not needed, reducing possible unstable problems.

Firewire support: enable legacy support for icubmoddev module of dragonfly2 cameras
Device drivers --> IEEE1394 --> enable legacy driver stack
sbp2 (storage)

save and quit

get the number of CPUs with

getconf _NPROCESSORS_ONLN	-> will get an 'N' number

compile using:

make-kpkg clean
CONCURRENCY_LEVEL=N CONFIG_DEBUG_SECTION_MISMATCH=Y fakeroot make-kpkg --initrd --append-to-version=-MY_STRING kernel-image kernel-headers modules_image

where N is the CPUs number get before
MY_STRING is an optional string you can add to identify the resulting kernel
CONFIG_DEBUG_SECTION_MISMATCH should not be necessary starting from kernel version

N.B. adding the patch some compile time error can arise, but can easily fixed.

Two .deb files will be created, one for the kernel image and the other with the headers. Install those files using dpkg to install the new kernel. A new entry in the grub will be automatically added.

== Using RT patch == (to be translated)

Qualunque applicazione può essere lanciata con priorità RT, ma per poterlo fare l'utente deve avere particolari autorizzazioni, che NON c'entrano con l'essere root o meno.

Il file che tiene memoria di queste speciali autorizzazioni è: /etc/security/limits.conf

Ci sono diverse configurazioni possibili che possono essere utilizzate, ma come minimo servono:

nome_utente - rtprio maxpriority nome_utente - memlock maxmem(KB)

nome_utente indica che l'utente è abilitato a lanciare programmi con livello di priorità RT fino a maxpriority, le priorità vanno da 0 a 99, il kernel di default usa priorità 50. memlock indica che una determinata porzione di memoria viene bloccata in RAM e non viene swappata via, per il processo RT. Questa impostazioni danno solamente al processo la FACOLTA' di utilizzare tali features del kernel RT, cioè danno l'abilitazione al processo ad utilizzare delle specifiche chiamate a funzioni che il kernel mette a disposizione, ma se il programma non effettua queste chiamate, non cambia nulla. Questo significa che:

  • Un software compilato per kernel NON-RT, può essere lanciato su un kernel RT da qualunque utente, senza abilitazioni particolari. Continuerà a funzionare pressochè nello stesso modo e con le stesse tempistiche di prima, godendo della maggior preemptibilità del kernel RT può essere un po' più responsivo, ma non è detto.
  • Un software compilato con le chiamate alle funzioni apposta per RT, può essere lanciato da un utente non abilitato al RT, queste chiamate falliranno e il processo verrà schedulato come un qualunque altro processo NON-RT, senza godere dei benefici della patch.
  • Un software compilato con le chiamate alle funzioni apposta per RT, deve essere lanciato da un utente abilitato a farlo per poter godere dei benefici del kernel RT, nella misura della sua abilitazione
  • Un utente con abilitazione al RT che lancia un'applicazione NON-RT, questa non avrà alcun beneficio.

Info point.jpg Boot & startup scripts

All the startup scripts and device drivers are stored inside the usb key therefore when the pc104 boots up, all configuration can be correctly loaded. This makes the configuration of the external server or laptop easier and all set-up more reliable with respect to live version.

The flow of execution is the following:

/etc/inittab -> /etc/rcS.d/S*.sh -> /etc/rc3.d/S*.sh -> /etc/rc.local -> /etc/rciCub.d/S*.sh
  • /etc/inittab : Set the runlevel number (by default 3) and starts basic system services like tty console.
  • rcS.d/S*.sh: runs all system Start-up scripts
    • S20iCub-tmpfs-mount.sh: this script assure folders listed below are mounted in RAM on a tmpfs, meaning they are volatile and changes in those folder won't survive across reboots. This has been done to avoid too much write operation on the usb key, that may shorten it's life. No swap partition on the disk has been made on disk for the same reason.
      • /tmp, (by script)
      • /var/log, (by script)
      • /var/run, (by system option)
      • /var/lock, (by system option)
      • /dev/shm, (by default)
      • /dev (by default)
  • rc3.d/S*.sh: system configurations
  • /etc/rc.local: this file will jump to the iCub custom folder and execute all the S*.sh scripts inside.
  • /etr/rciCub.d/S*.sh: following iCub customization scripts.
    • S00_remount.sh
    • S01_esd.sh (image 1.7 only)
    • S01_plx.sh (image 1.7 only)
    • S02_cfw002.sh (image 3.0 only)
    • S03_emotions.sh
    • S04_sound.sh
    • S05_network_buffers.sh
    • S06_update-ssh-keys.sh
    • S09_cfw2_sound.sh
    • S10_ntpdate.sh
    • nfs-remount
    • synchtime.sh

Info point.jpg Udev

The /etc/udev/rules.d/70-persistent-net.rules has been modified in the following way, in order to have the 1Gb/s Ethernet port named eth0 and the 100Mb/s interface as eth1.

# PCI device 0x8086:0x27dc (e100)
SUBSYSTEM=="net", ACTION=="add", DRIVERS=="e100", ATTR{dev_id}=="0x0", ATTR{type}=="1", KERNEL=="eth*", NAME="eth1"
# PCI device 0x8086:0x109a (e1000e)
SUBSYSTEM=="net", ACTION=="add", DRIVERS=="e1000e", ATTR{dev_id}=="0x0", ATTR{type}=="1", KERNEL=="eth*", NAME="eth0"

Info point.jpg Device Drivers

Device drivers have also been moved inside the usb key for the same reason as the start-up scripts: self-consistency of the usk key.

  • PLX (image 1.7 only)

This driver is needed by iCub version 1.0 and 1.1 for the PLX board, it is loaded by the /etc/rciCub.d/S01_plx.sh script and it is located in the folder


which contains the .ko module, include files, library and scripts to load and unload the module.

  • ESD (image 1.7 only)

This driver handle the usb to can converter used in iCub version 1.0 and 1.1. The module esdcan-usb331.ko is loaded by the /etc/rciCub.d/S01_esd.sh script and it is located inside the usb key in the folder:

  • CFW002 (image 3.0 only)

All iCub mounting a cfw002 board are capable of (and kindly suggested to) update their Linux distribution to squeeze (image3.X).
Following information are referred to this situation.

The driver cfw002 is locate inside the folder:


In order to work correctly, the cfw002 board needs to load a firmware inside it's memory during the 'open' call of the driver. This binary is placed inside the /lib/firmware folder and then a script is running at the start-up to update it, if necessary, into /lib/firmware/$(uname -r)/ because the kernel module handling this operation looks inside this folder to get the file. The advantage of using the script is that if a new kernel is installed (hope not, but who knows) the firmware will automatically copied inside the correct place, and the same happen if a new version of the firmware is released.

The library /lib/modules/ is present through a symbolic link in /usr/local/lib because it's needed by the test program /lib/modules/ that is testing the audio functionality of the board and set a software audio gain.

Source and compiled files can be downloaded from SVN repository at https://robotcub.svn.sourceforge.net/svnroot/robotcub/trunk/iCub/pc104/device-drivers/

  • Microphones

First initialization of the sound card is achieved with the command:

Super user icon.jpeg #root permissions required 
alsactl init

This is required just once and it has been already done while configuring the images, so it's not required when burning an image; while each bootstrap the script S04_sound does tuning of volume and loads necessary modules.

== Retina camera drivers == (this is for iKart actually)

To compile the kernel module retina.ko with linux versions 3.2 it is necessary to have the makefile written following this manual: http://www.kernel.org/doc/Documentation/kbuild/modules.txt the Kbuild file (with capital K) is needed. A final release of this build system will be committed on sourceforge when stable.

Settings 3.jpg SSH & Environment Variables

  • SSH passwordless login

User authentication credentials are stored inside the /home/icub/.ssh/authorized_key file; each line in this file is related to a different entry user@host. Steps to follow in order to add a new entry are explained in the following link iCub laptop installation instructions.
At boot-time, the '/etc/rciCub.d/update-ssh-keys.sh' script will look in the nfs folder searching for the .ssh/id_rsa.pub file and add user credentials to the authorized_key file, if new. To force this update, the former script can be run manually; once the key has been added, the id_rsa.pub file can be deleted or overwritten to add another user.

User credentials can be added also by using this command for each user@machine you want to log from:

User.jpg ssh-copy-id -i /home/user/.ssh/id_rsa.pub icub@pc104
  • Opening a new ssh shell

/etc/profile (quando si apre una login-shell, che sia root o user, nel caso di non-login questo viene skippato)

  -> /etc/bash.bashrc			(SEMPRE quando si apre una shell, sia root che user, sia login che non)

-> /home/icub/.bash_iCubrc (variabili di configurazione di iCub, aggiunto da me) -> /home/$USERNAME/.profile (login shell utente) -> /home/$USERNAME/.bashrc (shell utente, login o meno)

  • Environment variables

iCub specific settings are stored inside the /home/icub/.bash_iCubrc file, to leave the standard ~/.bashrc as clean as possible. This file is loaded every time a new shell is opened or an ssh command is sent to the pc104 so it's better to avoid doing too many stuff in those files. By default the robotname is set to an invalid value, so each time a new key is burned from the image, this values needs to be properly set to your iCub name.

User.jpg # icub user can edit this file
if [ "$PS1" ]; then 
	echo "Setting up yarp and iCub env vars"

## name of your robot e.g. iCubGenova01
export ICUB_ROBOTNAME=myiCubRobotName00

export REMOTE_MP=/exports/code-pc104
export LOCAL_MP=/usr/local/src/robot

export YARP_ROOT=$ROBOT_CODE/yarp2
export YARP_DIR=$YARP_ROOT/build-pc104
export YARP_CONF=$YARP_ROOT/conf
export YARP_NAMESPACE=/root

export ICUB_DIR=$ICUB_ROOT/main/build-pc104

# For compiling
DRIVER_ROOT=/lib/modules/$(uname -r)/iCubDrivers/
# not used anymore in iCub version >= 1.2

# Set-up optimizations
export CMAKE_BUILD_TYPE=Release

export PATH=$PATH:$ICUB_DIR/bin:$YARP_DIR/bin

Death-Danger.jpgImportant -> Since the robotname is stored inside the usbkey, it means that once it's configured, the key is NOT EXCHANGEABLE BETWEEN DIFFERENT ICUBs!! Death-Danger.jpg

Settings 3.jpg Network configuration

Each image version is released in three different builds (oc, iit, dhcp) characterized by different network configuration. Files involved in this configuration are:

/etc/network/interfaces  : store ip address of the interfaces, gateway and dns nameserver if any
/etc/hosts    : matches the string 'icubsrv' with the corresponding ip address
/etc/ntp.conf : configuration of the network time protocol

Depending on the build release, the default configuration is:

oc: "open call" standard installation

  • /etc/network/interfaces
    • pc104 has static ip,
    • external mount server,
    • gateway
  • /etc/hosts
    • added " icubsrv" for name resolution
  • /etc/ntp.conf
    • server
    • restrict
    • ntpdate
    • restrict mask nomodify notrap

NFS and mounting

The pc104 mounts through NFS a folder from an external server. To assure the mount process complete successfully, beside inserting the following entry in the /etc/fstab file

Super user icon.jpeg icubsrv:/exports/code-pc104	/usr/local/src/robot	nfs	rw,intr,hard,nolock	0	0

also the /etc/rciCub.d/nfs-remount script takes care of retrying the nfs-mount operation at given intervals until success.


  • Tab completion

In Debian by default tab completion doesn't work if you start a command with sudo, which is very annoing 'cause sudo is used a lot; a smart bash completion can be enabled so that it works also with sudo!! This feature needs to be enabled in the /etc/bash.bashrc file uncommenting the following lines (i.e. removing the '#' at the beginning of the line):

#if [ -f /etc/bash_completion ]; then
# . /etc/bash_completion

and defining appropriate rules in the /etc/bash_completion file, or just coping a default one.

  • Give iCub user the superuser power

Add "icub ALL=NOPASSWD:ALL" to /etc/sudoers file

  • Miscellaneous

This usb key contains a standard version of the Debian distribution and it's writable so any customization can be done just like on your pc. Please be aware of what you do, because any changes in configuration file can lead to malfunction.

Talking Head

For the talking head you should do the following change at the scripts in rciCub.d:

  • S04_sound.sh
amixer -c 0 sset PCM,0 90%,90% unmute cap
amixer -c 0 sset Line,0 50%,50% unmute cap
amixer -c 0 sset Capture,0 70%,70% unmute cap
amixer -c 0 sset Master,0 90%,90% unmute cap
  • S09_cfw2_sound.sh
lib/modules/ 2 

(2 instead of 6)

Install the following package:

sudo apt-get install espeak

Add in /etc/rciCub.d/ the following script (S11_speak.sh):

  • S11_speak.sh
# iCub say something at the startup
espeak -s 130 -v en+f3 "Hello, the Talking Head is on"

note: Remember to change the chown and chmod to this file:

sudo chown icub:icub S11_speak.sh
sudo chmod 775 S11_speak.sh

Feedback and reports Fumetto.jpg

If you experience any problems, likes to have extra functionality or just wish to give any feedback, please send me an email at alberto.cardellino@iit.it