The Linux on the pc104

From Wiki for iCub and Friends
Revision as of 09:22, 12 November 2019 by (talk | contribs) (Versioning)
Jump to: navigation, search

These instructions only apply to YARP > 2.3.23 and iCub > 1.1.13 software versions

See The Linux on the pc104 oldrepo for older instructions

The pc104 located inside the iCub head runs a full Debian distribution. This version of Linux has been customized for the specific application and to boot from an USB key. As the iCub (project) grows up, many updates have been performed to this Linux usb-key image to follow the hardware as well as the Debian distribution changes. Stable versions are frozen into image files and uploaded to the iCub webserver, for detailed instruction on where to get the image and how to flash it, see following section.
At any time to determine the version of the image is running on your iCub, the following files in the root of the filesystem can be inspected:

  • VERSION_PC104: contains the version of the image
  • ChangeLog_PC104: list changes to the image

Important: the iCub User password is changed from the iCub LIVE version 5, see below.


  • 1.x This is an Etch'n'half based distribution, built on a Debian LIVE system.
  • 2.x This is a Debian Lenny based distribution, built on a Debian LIVE system.
  • 3.x This is a Debian Squeeze based distribution, contains a kernel with Real-Time patch (
  • 4.x This is a Debian Wheezy based distribution, this version contains an updated version of libportaudio.
  • 5.x This is a Debian Wheezy based distribution, built on a Debian LIVE system with overlay persistence, compiled for kernel rt-amd64 (x86 64 bit with real time PREEMPT_RT patches)
  • 6.x This is a Debian Jessie based distribution, built on a Debian LIVE system with overlay persistence, compiled for kernel rt-amd64 (x86 64 bit with real time PREEMPT_RT patches)
  • 7.9.x This is a Debian Stretch (v9) based distribution, built on a Debian LIVE system with overlay persistence, compiled for kernel rt-amd64 (x86 64 bit with real time PREEMPT_RT patches)
  • 7.10.x This is a Debian Buster (v10) based distribution, built on a Debian LIVE system with overlay persistence, compiled for kernel rt-amd64 (x86 64 bit with real time PREEMPT_RT patches)

Starting from version 5.0, the image file name is composed by four parts: a a major release, a a minor release, a build release which is a string that contains the build date and a kernel flavor string, which describes the kernel architecture the image is built for. For example



*5 is the major release
*0 is the minor release
*14.11.12 is the build release (Year.Month.Day)
*rt-amd64 is the kernel flavour

Up to version 4.0, the image file name is composed by three parts: a major number related to the Debian distribution, a minor number which tells the internal update version and the build release is a short string related to the network configuration, for example the file image1.6-oc.img, the major number is 1, minor is 6 and build is oc. Here, the build release refers to the network configuration the final distribution will boot-up with. We release the following three types of configuration:

* oc: "open call" standard installation (static ip, it mounts software from
* iit: custom IIT standard installation (static ip, it mounts software from, to be used inside IIT labs.
* dhcp: dhcp-enabled network configuration. If you want to connect the robot on your own network you should be able to use this image. The pc104 will use dhcp. (click here to see how configure a dhcp server: live-with-dhcp).

NEW We wish to make the user experience with the iCub easier so with this release of the pc104 image two main changes has been done in this direction:

  • In version 4.0 The image comes in only 2 versions, static and dhcp, while from version 5.0 ht image is only with static IP address.
  • Starting from the 4.0 version, the pc104 will mount the very same folder as the server/laptop does, but use a different build folder to have separeted binary code.
    The folder is the one called /exports/code in the server, so you'll see

This way by updating the repository, both the server and the pc104 will benefit of the new code. (They still need to be compiled one by one)
The /exports/code-pc104 is no longer used.

Which version do I need?

This question is quite common whenever the number of versions and revisions start to become... more than one.
The Debian image to use depends on the iCub version:

  • iCub up to version 1.1 must use a Etch and a Half distribution (image version 1.x). Persistent filesystem allows deep system configuration; if you are happy with current configuration you can skip this update, while if you really need to change system configuration now you can by appling this update.
  • iCub from version 1.2 on can use the latest version: we kindly recommend you to keep Debian system updated to the last version (at the time of writing it means the 7.9 @ December 2017)

For persistent filesystem this configuration can be changed without re-burning a new image, you can just edit the configuration files of the network as you would normally do with Linux system.

Burn the Debian image version 7.x (latest)

Starting from version 6.0 images come in a zip archive file containing the image live image itself, the persistency file and the tools to make an USB bootable.

Where to download the ZIP archive

ZIP archives can be downloaded here

How to create the bootable USB drive with the live image

  1. Download the latest image from the above link
  2. Take an USB 2 drive at least of 8 GB size (please note that using an USB3 disk or a huge disk, eg. 32 GB, may not work depending on the version of your PC104)
  3. Format the drive with fat32 filesystem
  4. Unzip the content of the image archive into the root of the USB drive
  5. Execute the "Make bootable" script as follows:


Open a command prompt with administrative rights and then go to the folder utils/win64 (or utils/win32 if yo have a 32 bit Windows) and execute the script makeboot64.bat (or makeboot.bat if you have a 32 bit indows); then follow on-screen instructions


Open a shell, then go to the folder utils/linux and execute the script with root privileges (eg. sudo bash; then follow on-screen instructions

Burn the Debian image version 5.x (old)

From version 5.0 on, the image is based on a Debian LIVE system. Version 5.x images come into a standard ISO Hybrid image file and there is a script to write the image to a USB memory

Where to download the ISO image and burn script

ISO images and the script can be downloaded here
Some images are compressed, if so uncompress it before proceeding.
To verify the file has been successfully downloaded, the md5 code can be verified by placing the .md5 file in the same folder as the uncompressed image and typing the following command:

md5sum --check MD5FILE.md5

How to put the iso on a USB memory

Please use the script : this script will create a working bootable USB from the ISO file and ensure compatibility on some old PC104.
This scripts will also enable file persistence (see below).
NOTE : this script is compatible ONLY with Debian GNU/LInux 7 [wheezy] and Ubuntu 14.04.3 LTS [Trusty]

What is file persitence and how to use it

File persistence is used to write the changes you made to the live filesystem (i.e. if you modify a file or write a new one) to a separate partition on the USB memory, allowing those changes to survive a reboot. The bigger is the USB memory, the more space you have for the new files, so we suggest at least a 4 Gb USB memory. If you mount an USB memory which persistence enable on a normal PC, you will see two partitions:

  • LIVE partition, which contains the live image files
  • PERSITENCE partition, which contains all the modified or new files

How to use the script

This script takes a iCub PC104 live image and write it to an USB memory, optionally enbling file persistence. The script run on a Linux system and requires the following commands to be installed

  • parted
  • mkdiskimage
  • mkdosfs
  • mkfs.ext4
  • install-mbr
  • syslinux
  • p7zip

On a Debian 7 system, this means that you must install the following packages

parted syslinux syslinux-common syslinux-utils dosfstools e2fsprogs p7zip mbr

The script usage is the following -f LIVE_ISO_FILE -t USB_TARGET_DEVICE [-p PERSISTENCE_SIZE]


  • LIVE_ISO_FILE is the live filename (mandatory parameter)
  • USB_TARGET_DEVICE is the device to write to the iso image - important: USE a device not a partition (mandatory parameter)
  • PERSISTENCE_SIZE is the size of overlay partition (in MB) - set to 0 to disable overlay, the default persistence size is 1024 MB

Example: -f icub-live_4.0-14.11.12-rt-amd64.iso -t sdc

There is also an inline help for the script, available with -h

The image requires an amount of space which is bigger than the the ISO size of a 10%, so setup the persistence partition size accordingly. The script checks if the target USB memory has enough space for live system and persistence (if not disabled), so don't worry.

Burn the Debian image version < 5.x (oldest)

Instructions for burning images version < 5.0 are now grouped here.

Users and Passwords

Starting from version 5.0, the default user is

username : icub
password : live

If you want to change the default password simply execute (this works only if you are using persistence)

 passwd icub

NOTE: the root user has no password, this means that the direct login (i.e. ssh root@ is disabled, but you can always do

sudo su - 

once connected as icub, to switch to the root user.

Startup scripts

Important: these instructions apply to the recent persistent images of the Linux (starting from 1.7 and 3.0).

There are some scripts that customize the Linux when the pc104 boots up; those scripts are inside /etc/rciCub.d folder. Normally, you don't need to modify them, but be aware of them.

Set RobotName variable

edit the file:


replace the line:

 export YARP_ROBOT_NAME=myiCubRobotName00

with the name of your robot e.g. iCubGenova01

Important: clean the CMakeCache before compiling

When upgrading the usb key to a different version, remember to clean the CMakeCache before compiling!! This is because some path are likely to be changed in the meanwhile

Further Customization

The persistent version of the Debian distribution is now writable so any customization can be done. Please be aware of what you do, because any changes in configuration file can lead to malfunction.

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. User credentials can be added also by using this command for each user@machine you want to log from :

ssh-copy-id -i /home/user/.ssh/ icub@pc104

See page ICub laptop installation for further details.

Common Problems and how to solve them

I used an USB3 and/or 32 GB disk and the system does not boot

Try with a USB2 smaller ( 16GB or better 8 GB) drive. Some PC104 have problems in reading those recent USB drives.

The script asks me "The closest location we can manage is.. Is this still acceptable to you?"

Simply press "Y" and forget about the warning "Information: You may need to update /etc/fstab." :)

Once I created a new USB memory with the PC104 image, ssh complains that "Remote host identification has changed" and does not connect to the PC104

This is normal: for security reasons when a new iCub live is executed for the first time, a new SSH Key is created for the PC104 host. Please remove all the entries in the file


that refers to pc104 or and login again.
This must be done from each machine you wan to connect to the PC104.
See also this external page

I used the live USB first on a computer, then when I plugged it into the PC104 it does not work anymore

Probably the PC104 booted correctly, but the network is not reachable (you can check it by connecting a vga cable to the PC104 inside iCub's head)

Live systems write some info about the network card the first time they boot on a machine. This implies that if you boot the live on a desktop and then you plug it to a different machine the network may not work (since the network card is different).

To fix this you have two options:

1. quick and dirty - on the live USB, open the file /etc/udev/rules.d/70-presisten-net.rules and remove any pair of lines like the following:

# PCI device 0x8086:0x10f5 (e1000e)`
SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", ATTR{address}=="00:1f:16:0b:47:4d", ATTR{dev_id}=="0x0", ATTR{type}=="1", KERNEL=="eth*", NAME="eth0"

(of course attributes like address, name or device are not exactly the same in your file)

2. clean and easy - burn another USB and FIRST install it on the PC104

Detailed information

If you want to get detailed information about the iCub LIVE image (i.e. the differences from a standard Debian LIVE) please read this page