The Iliad hacker's toolbox

Data transfer

Whenever you tinker with your Iliad, you will have to get your changes to the device somehow. There are several ways to transfer data from or to the Iliad. They differ in ease of use, availability and possible target locations.

Card jockeying

The most obvious method is copying something onto a removable storage medium from your computer and plug it into the device. This is the method of choice for documents to be viewed, but is also suitable for adequately packaged third-party applications.

USB

Using the small breakout box, you can connect the Iliad to your computer as an external USB drive. Which storage area is exported can be selected in the settings. Choosing anything other than the internal flash memory is rather pointless since you can put the removable cards directly into your PC. If you choose the internal flash, you have access to its data partition, though not the system installation.

scp

If you seriously consider tinkering with your Iliad, you should install the SSH (Secure SHell) server package. Once you have it installed and have connected the Iliad to your network, you can use the scp program to copy files to and from it. Unlike the above methods, this allows you to access any storage area, including the system partition.

NFS

Among the Linux kernel developer downloads, iRex provides a kernel zImage_nfs which includes NFS (Network File System) functionality. Reputedly, this can be used to mount the file system of the Iliad from a PC via NFS, but I have not tried it.

Creating an Ext2 file system for use with the Iliad

The Iliad's Linux kernel can only mount Ext2 file systems with a block size of 1024 bytes and an inode size of 128 bytes. If you want to use Ext2 formatted memory cards to transfer data to the Iliad, you have to pass the following options to mke2fs when creating the file system (assuming /dev/sdb1 is the first partition on the memory card):

mke2fs -b 1024 -I 128 /dev/sdb1

To abbreviate these parameters, you can put the following definition in /etc/mke2fs.conf in the [fs_types] section:

iliad = {
        blocksize = 1024
        inode_size = 128
}

Then you can create an appropriate file system by:

mke2fs -T iliad /dev/whatever

In order have such cards automatically mounted on the Iliad, you have to change the file system type in /etc/fstab from vfat to ext2. (Of course you can also mount such cards manually while you are logged in via SSH.)

The command line to create a file system exactly like the root file system on the Iliad is:

mke2fs -r 0 -b 1024 -I 128 -i 8192 -g 7432 -O none /dev/sdb1 74256

This may be necessary to create a file system the Iliad can boot from; but at the time of writing I have not yet successfully managed to boot from a CF card.

Recovery

If you have accidentally messed up your Iliad, there is still a smallish chance that you can fix it yourself, if you were so provident as to prepare for one of the following methods of recovery:

ssh

As said before, the first order of the day before starting to mess with your Iliad is to install the SSH (Secure SHell) server package. You can then log in via your local network (or a crossover network cable) and fix things from the shell. This still requires that the device's system starts up normally, as the SSH server is started by an init script (/etc/init.d/dropbear). But it helps when you broke one of the programs for running the display or touchscreen or the script /home/root/start.sh which starts all of them.

Serial console

If you have been so reckless to tinker without installing the SSH server first, or if it does not start up for some reason, but the device still boots, there is a way to log in, though I recommend it only for hardware folks. An entry in /etc/inittab, independent of other services, opens a console on one of the builtin serial interfaces of the processor. This serial interface is accessible on the debug connector, if you open up the device and either obtain a matching connector or solder some leads directly onto the board. The interface speed is 115200 baud (see third line in /proc/tty/driver/serial).

Wiping the system

If the device does not boot, one thing that can be done is to restore the whole system partition as described below. This functionality is contained in a secondary kernel and initrd which cannot be replaced, so it should be impossible to break. If you want to restore a previous state (rather than formatting the device to its original state), you should make a backup of the system partition beforehand, for instance with the command:

dd if=/dev/tffsa1 of=/mnt/cf/app.image

(I have used the cp command for the same purpose on other Linux systems, but it does not seem to work on the Iliad.) Then you have to gzip it, add an MD5 checksum and proceed as described below.

Alternative boot

As described here, you can boot an alternative system from a CompactFlash card if it is e2fs formatted and has a file config.txt in its root directory which contains only the line "boot". If you have put an SSH server on that system installation, you can log in, mount the built-in system partition and try to fix things. Of course, you should set up the duplicate system before you start messing with the original. In fact, you might want to turn this recovery method around and experiment with a duplicate system installation on a CF card and leave the built-in installation alone until you are sure your changes work.

System upgrade or restore

Via CompactFlash card

The upgrade method of choice for version 2 Iliads uses a CompactFlash card and is described in this howto by iRex. The CF card has to be formatted with a FAT file system (as most of them are out of the box). It has to contain a folder images and a plain text file config.txt in the root directory. The config.txt details what should be upgraded; the images directory contains the data.

To upgrade the kernel, config.txt has to contain a line "kernel", and the images directory has to contain the gzipped kernel image zImage.gz and a file with its MD5 hash zImage.gz.md5. For the initrd, it is the line "initrd" and the files initrd.gz and initrd.gz.md5. The system partition can be upgraded by the line "applications" and the gzipped image of an adequately sized Ext2 image app.image.gz (with hash app.image.gz.md5). According to iRex, the gzipped size of the kernel image and initrd must not exceed 1 MB and 2.5 MB, respectively (they don't say if these are binary or "marketing" MB). The initrd is an Ext2 image containing 4096 blocks with block size 1 kiB; the system partition image must contain 74256 blocks, also with block size 1 kiB.

If config.txt contains only the line "format", the flash storage space is repartitioned, and the provided kernel, initrd and system partition images are written to the flash memory. zImage.gz, initrd.gz, app.image.gz and their MD5 hash files all have to be present. Pristine copies can be downloaded from iRex; a link is provided from the download page for the reflash howto. They have the version 2.10, however, which is not the most recent.

Via /mnt/protected partition

This is not recommended any more, but used to be the only way on version 1 Iliads. The gzipped image of either the kernel or the system partition has to be copied to the partition /mnt/protected, named os.gz or fs.gz, respectively. The actual upgrade is probably triggered by writing a "1" to /proc/sysset/updos or /proc/sysset/updfs, respectively, and rebooting the device. (But note that some have run into trouble doing that.)

Disabling automatic upgrades

The Iliad automatically downloads and installs system upgrades whenever the device connects to the internet. Normally this is triggered manually by using the connection manager and/or the connect button. But if your main way of working on the Iliad is via SSH, it will connect whenever possible. An appropriate DHCP network configuration file is installed by the SSH server package in order to allow you to connect.

So, in this situation, the Iliad may download and install upgrade packages immediately after startup without giving you a choice. This is bad, because you have no way of knowing what will be installed and when and how it will get along with your possibly modified system. It is a recipe for chaos to have two administrators for one system, particularly when they know as little of each other as you and iRex.

But there is a way to block the automatic installation of the downloaded upgrade packages. As I have described here, upgrade packages are downloaded to /tmp (data) and /etc/post_download/todo (installation scripts) and are installed by the script /usr/bin/post_download.sh. I have written a replacement script which does not run the install scripts, but rather copies them and the data to a predefined directory and notifies the root user by appending a line to a file in /home/root. When next logging in as root, one can look at what the upgrade packages contain, check that they do not clash with one's system and run the installation scripts manually.

The directory for storing the upgrade package data is located on the data partition; if you use it regularly for reading, you might want to change that. Besides, I have to admit that there is a small chance that the script may malfunction and you may lose upgrades. I have reverse engineered the location of downloaded package data and scripts from the original script and the installation scripts of the few upgrades I have seen; if additional data are put in a different volatile location, they may be lost without my script returning an error.

TOS / Impressum