The Linux on the pc104

From Wiki for iCub and Friends
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 in the iCub LIVE version 5, see below.

Versioning

  • 1.x This is an Etch'n'half based distribution, built on a Debian LIVE system.
  • 2.x This is a Lenny based distribution, built on a Debian LIVE system.
  • 3.x This is a Squeeze based distribution, contains a kernel with Real-Time patch (rt.wiki.kernel.org).
  • 4.x This is a Wheezy based distribution, this version contains an updated version of libportaudio.
  • 5.x This is a 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)

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

icub-live_5.0-14.11.12-rt-amd64.iso 

is

*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 10.0.0.2, it mounts software from 10.0.0.1).
* iit: custom IIT standard installation (static ip 10.0.0.20, it mounts software from 10.0.0.11), 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
/exports/code/iCub/main/build
/exports/code/iCub/main/build-pc104

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 5.0 @ November 2014)

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

NOTE : Instructions for burning images version < 5.0 are now grouped here.
From version 5.0 on, the image is based on a Debian LIVE system, which comes into a standard ISO Hybrid image file.

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 pu the iso on a USB memory

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

What is file persitence and how to use it

File persistence is used to write the changes you made to the live filesystem (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 icub_iso2usb.sh 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

icub_iso2usb.sh -f LIVE_ISO_FILE -t USB_TARGET_DEVICE [-p PERSISTENCE_SIZE]

where:

  • 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:

 icub_iso2usb.sh -f icub-live_4.0-14.11.12-rt-amd64.iso -t sdc

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

icub_icub2usb.sh -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.

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@10.0.0.2) 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.

  • Set RobotName variable

edit the file:

/home/icub/.bashrc_iCub

replace the line:

 export YARP_ROBOT_NAME=myiCubRobotName00

with the name of your robot e.g. iCubGenova01

  • Setup password-less login (PC104 & laptop):

See page ICub laptop installation for details.

Important: 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/id_rsa.pub icub@pc104

Common Problems and how to solve them

The icub_iso2usb.sh 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

~/.ssh/known_hosts

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

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