Difference between revisions of "The Linux on the pc104"

From Wiki for iCub and Friends
Jump to: navigation, search
(Common Problems and how to solve them)
(22 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<big>'''These instructions only apply to YARP > 2.3.23 and iCub > 1.1.13 software versions'''</big>
<big>'''Please note that this page has been discontinued, please refer to [https://icub-tech-iit.github.io/documentation/icub_operating_systems/pc104/icub-live/ the latest documentation on GitHub]'''</big>
''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 [[The Linux on the pc104#Burn the Debian image | following section]].<br> 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 [[The Linux on the pc104#iCub LIVE passwords|below]].
== Versioning ==
*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 ([https://rt.wiki.kernel.org/index.php/Main_Page rt.wiki.kernel.org]).
*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.x This is a Debian Stretch 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. <br>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)
<br>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.<br>
The Debian image to use depends on the iCub version: <br>
* 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.<br>
* 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) <br>
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 [http://wiki.icub.org/iCub/downloads/pc104-images/ here]
=== How to create the bootable USB drive with the live image ===
# Download the latest image from the above link
# 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'')
# Format the drive with fat32 filesystem
# Unzip the content of the image archive into the root of the USB drive
# Execute the "Make bootable" script as follows:
==== Windows ====
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
==== linux ====
Open a shell, then go to the folder ''utils/linux'' and execute the script ''makeboot.sh'' '''with root privileges''' (eg. ''sudo bash makeboot.sh''); 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 [http://wiki.icub.org/iCub/downloads/pc104-images/ 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 icub_iso2usb.sh script : this script will create a working bootable USB from the ISO file and ensure compatibility on some old PC104.<br>
This scripts will also enable file persistence (see below).<br>
'''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 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
*'''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
  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.
== Burn the Debian image  version  < 5.x (oldest) ==
Instructions for burning images version < 5.0 are now grouped [[How to burn Linux pc104 image (version prev. 5.0) | 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/id_rsa.pub icub@pc104
See page [[ICub laptop installation instructions#Configuration of the icub user | 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 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
that refers to pc104 or and login again.<br>This must be done from each machine you wan to connect to the PC104.<br>''See also [http://askubuntu.com/questions/9800/remote-host-identification-has-changed-warning-when-connecting-over-ssh 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 [https://svn.robotology.eu/repos/iCubHardware-pub/trunk/mechanics/public/doc/howTo/Connect_VGA_to_PC104.pd 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 [[ICub PC104 Linux Image - Detailed info|this page]]

Latest revision as of 11:19, 23 December 2020

Please note that this page has been discontinued, please refer to the latest documentation on GitHub