The Linux iPAQ HOWTO

Table of Contents

Preface

Today, Personal Digital Assistants (PDAs) are getting more and more popular, allowing the power of a 5-year old PC to fit in your hand, for the high-end models. Most of these PDAs come with an operating system and a set of softwares such as a contact management, a diary, a mail reader, a task manager, a calculator, a terminal emulator, a file explorer, a multimedia reader, a spreadsheet, a word processor, and of course, games.

Unfortunately, all these softwares are proprietary, and only licensed to the final user, who have no way to modify or improve them. Even worse, software development is difficult too, since proprietary development tools are required, which mean in turn that a programmer has to learn this tool and the provided Application Programming interface (API).

Hopefully, an alternative to this sad situation exists. Free Software, best represented by the GNU/Linux operating system, has proven its capability to provide quality tools through knowledge sharing, community support and good will. Moreover, the power of creativity is given back to the developers, allowing them to write programs using whatever API they prefer best, or even write their own if they want to.

This document proposes you to free your iPAQ from commercial software licenses by replacing the proprietary softwares by a GNU/Linux operating system and a set of application softwares that will provide the same (or even better...) tools than the original ones. Not only will it give you a taste of freedom, but it will also bring you back the joy of creativity, knowledge, and fun.

I hope you'll enjoy reading this document as much as I have enjoyed writing it.

1. Introduction

As an electronic engineer, I always enjoyed minimalistic systems. They always provide a kind of challenge to your accepted rules, as your dogmas tend to collapse when facing the crude reality. On minimal systems, this phenomenon tends to happen even quicker than on complex ones. One other interesting feature of this minimalistic approach is that it tends to keep things humanly manageable, which is comfortable, as today's computer science requires you to master a broad set of concepts, tools and computer languages...

Back in 1980, my first computer was a Goupil 2, quickly followed by an Apple II+, where I started programming. Having undergone dozens of computers, computer languages, and proprietary operating systems, I discovered Linux in 1994, when my company at that time (Lectra Systèmes), decided to take a Unix-like operating system on a PC platform as its base for application development. After careful evaluation and pushed by Pierre Ficheux and Daniel Roche, Linux was preferred to other commercial products, first because of its good performance but also because of its price. At that time, emails were not on everybody's computer, and the computer community was just emerging from the universities. We thus followed the growth of Free Software, and as an engineer, I found working like that was fun.

Since then, I tried to keep on working with GNU/Linux as much as possible, although I should not be considered as a Free Software activist. I am just pragmatic, and I still use commercial software whenever I don't find the corresponding free tools. I know, I should write my own, but sometimes, I am just too lazy, or focused on the more important goal that required this tool. I don't feel too guilty for that, as I try to participate to the Free Software movement whenever I can.

I got a first Uniden® PDA, but I should say that it belongs now to one of my brothers, since I was very disappointed by the fact that there was no (at least documented) way to change the software on it, or even to write programs for it without having to learn tons of things about DLL's major enhancement (I already played with shared libraries on my Amiga 500 in 1987...), and the virtues of Hungarian notation (I still find this is one of the silliest things ever invented, especially since polymorphisms in Object Oriented Programming).

I was a kind of shocked when I first saw my actual boss, Jean-Marc Lange, play with its iPAQ PDA. But what really stunt me is when I discovered by browsing on the Web that some crazy persons did it. Yes, thanks to what was formerly named Compaq® (now Hewlett Packard®), and a lot of good-willed persons, it was possible to put Free Software on this machine.

I took this as a challenge, and I think that writing this document on converting an iPAQ to GNU/Linux is my best effort to help the Free Software Community.

This document was also a good exercise to practice DocBook. If you read these lines, it means that I was able to master it!

2. Audience of this document

This text should be considered as a step-by-step approach of converting an iPAQ to a GNU/Linux operating system, onto which the Opie application suite will be installed. Of course, you can choose to install some different softwares (like the X11 system), but I chose this alternative to provide a strict replacement to the original softwares, and I considered Opie as one of the most advanced projects.

3. Organization of the material

The document introduces its topics in a logical order, corresponding to the steps required to put GNU/Linux on an iPAQ.

4. Prerequisite

There is no prerequisite background to use this document, beside being able to launch a shell command under GNU/Linux either in a text display or in an Xterm, to be able to edit a text file using whatever text editor you are familiar with, and know how to use the iPAQ user interface.

For this guide, I used a Compaq (now HP) iPAQ 3850 iPAQ HP iPAQ H5500 running PocketPC 2002 Microsoft® Pocket PC (Windows CE 4.2) , but all the given examples should work without problem on other iPAQs too, as long as they have a serial connection capability. I will be glad to add new targets if you succeeded in doing it on other platforms.

Of course, you will need a computer running the Linux operating system. For this guide, I used the Red Hat 7.2 Gentoo GNU/Linux 1.4 distribution, but it should work on others, with minor changes due to distribution-specific glitches.

This computer will need to be connected to the Internet, as the transformation requires downloading some files for the iPAQ. It is also possible to pre-download them and work locally.

In order to download files to the iPAQ, the computer will also have to run either an FTP and/or an HTTP (like apache) server.

5. Versions

This document describes the installation of the following versions:

• Backup and flashing utility - BootBlaster_1.19
• Bootloader - bootldr-2.18.01
• Linux distribution - familiar-0.5.3 familiar-0.7.2
• Graphical interface - opie_1.5.0-20020515 opie_1.1.6-20040917

6. Sources of further information

There is much useful information available on the Internet; the following is a sampling. Internet sites, of course, tend to be highly volatile while printed books are hard to update. Thus, this list should be regarded as being somewhat out of date.

7. Legal information

7.1. Copyright

This document is copyright © 2002 by Michel Stempin.

7.2. NO WARRANTY

There is no warranty for the programs or examples given in this document, to the extent permitted by applicable law. Except when otherwise stated in writing the copyright holders and/or other parties provide the programs or examples "as is" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the programs or examples is with you. Should the programs or examples prove defective, you assume the cost of all necessary servicing, repair or correction.

In no event unless required by applicable law or agreed to in writing will any copyright holder, or any other party who may modify and/or redistribute the programs or examples as permitted above, be liable to you for damages, including any general, special, incidental or consequential damages arising out of the use or inability to use the programs or examples (including but not limited to loss of data or data being rendered inaccurate or losses sustained by you or third parties or a failure of the programs or examples to operate with any other programs), even if such holder or other party has been advised of the possibility of such damages.

7.3. Trademarks

iPAQ™ was a trademark of Compaq, Inc., now Hewlett Packard, Inc.

Linux™ is a trademark of Linus Torvalds.

Windows™, PocketPC™ 2002 and ActiveSync™ are trademarks of Microsoft Corporation.

8. Online version

9. Conventions used in this document

The following is a list of the typographical conventions used in this document:

New Term

Used for new terms

Filename

Used for file and directory names

Command

Used for program and command names

Constant Width

Used in the text to indicate words that appear in code or other literal strings

Replaceable

Used to indicate variable options, keywords, or text that the user is to replace with an actual value

User Input

Used in examples to show commands or other text that should be typed literally by the user

Listing

Used in examples to show the contents of files

Output

Used in examples to show the output from commands

bash#

Used in examples to show a "root" shell prompt

bash$

Used in examples to show a normal user shell prompt

This is a tip. It contains useful supplementary information about the topic at hand.

Pay special attention to notes set apart from the text with the following formatting:

Warning

This is a warning. It helps you solve and avoid annoying problems.

10. Feedback

11. Acknowledgments

I would like to thank Sophie Calot for understanding the long hours I spent on writing this document, having confidence in me that I was doing something important, even if she is not the kind of girl that will use it...

Chapter 1. Connecting a PocketPC iPAQ to a GNU/Linux host

1.1. Creating a connection on the GNU/Linux host

Although the iPAQ's cradle has an USB cable, we will not be able to use it while the iPAQ is running PocketPC, as its use is limited to the proprietary ActiveSync program.

1.1.1. pppd configuration

On the GNU/Linux host, PPP is implemented by the pppd command, which uses either options specified after the name pppd on the command line, separated by space characters, or a configuration file. This method will be preferred, as it is tedious to type the same things over and over.

1.1.2. Naming the iPAQ

As a convenience, we will add the following line to the /etc/hosts file:

This will allow us to connect to the iPAQ using its name, instead of its IP address. This can be achieved using you favorite text editor, or with the following simple command:

1.2. Creating a connection on the iPAQ

1.2.1. Disabling ActiveSync

The ActiveSync program is a nice tool if you want to synchronize your PocketPC to a Windows host. Alas, as it uses a proprietary protocol, it is of no use to us. Worse, it will prevent us from achieving a connection to a GNU/Linux host by capturing some characters on the serial line.

We thus have to disable it, following these simple instructions:

1. In the "Start" menu, tap on the "ActiveSync" entry. The ActiveSync main window will show up
2. Tap on the "Tools" menu, then on the "Options..." entry
3. Uncheck the "Synchronize automatically..." box and tap "ok". We are back to the ActiveSync main screen Uncheck the "Use mobile schedule to sync with this PC
4. Tap on the "Options..." button
5. Uncheck Enable PC sync using this connection
6. Tap on "X" to close the program.

In order for this modification to take effect, I recommend you switch the iPAQ off, then back on (I spent hours figuring out why it was not working ;-)).

1.2.2. Creating a new "modem" connection

For PocketPC, a serial connection has to be a modem... This is how to do it, using the standard PocketPC parameters the PocketPC 2003 settings:

1. In the "Start" menu, tap on the "Settings" entry
2. Tap on the "Connections" tab
3. Tap on the "Connections" icon
4. Tap on "Add a new modem connection" below "My ISP"
5. Enter a name for the connection ("Linux" for example) and select "Hayes Compatible on COM1" as the modem. Tap on "Next"
6. Enter "0" as the phone number. Tap on "Next"
7. Tap on "Advanced...". Select "115200" in the "Baud rate" pulldown menu, uncheck "Wait for dial tone before dialing" and uncheck "Cancel if not connected...". Tap on "Port settings"
8. Select 8 data bits, parity "none", 1 stop bit, "None" flow control, and uncheck all the boxes. Tap on the "TCP/IP" tab
9. Check "Use server-assigned IP address", uncheck "Use Slip", and check both "compression" boxes. Tap on the "Servers" tab
10. Check "Use server-assigned address", then tap "ok". We are back to the new connection setup screen
11. Tap on "Finish"
12. Our new connection is created. Tap on "ok". We are back to the main screen
13. Tap on "X" to exit "Settings"

1.3. Connecting the iPAQ to the PC

1.3.1. On the GNU/Linux host

1.3.1.1. Manual connection

On the GNU/Linux host, you can launch the connection manually by typing:

1.3.1.2. Automatic connection

Alternatively, you can launch it automatically, by adding the following lines to your /etc/inittab file:

This last line tells the init process (father of all) to launch the same command whenever it enters into run levels 2,3,4 or 5, and to respawn (relaunch) it when it dies.

You can enter these two lines either using your favorite text editor, or by issuing the following commands:

For this automatic feature to take effect, you have to tell the running init process to re-read its configuration by typing:

You can observe if pppd is running by checking the /var/log/messages file.

1.3.2. On the iPAQ

You just have to open your "modem" connection:

1. From the "Start" menu, tap on the "Settings" entry
2. Tap on the "Connections" tab
3. Tap on the "Connections" icon
4. Tap on "Manage existing connections" below "My ISP"
5. Tap long on the connection and select "Connect" from the popup menu
6. If a "User name/Password/Domain" dialog appears, just check "Save password" and tap on "OK"
7. A "Connecting..." window will pop up, soon replaced by a "Connected" window, that will close automatically after some seconds, unless you tap on "Hide" before...
8. Tap on "ok" to close the "My ISP" screen
9. Tap on "ok" to close the "connections" screen
10. Tap on "X" to close the "Settings" screen
11. The connection status is visible in the top bar as two small arrows. By tapping on these, a popup window will appear, that gives you the ability to close the connection by tapping on "Disconnect".

1.4. Transferring files between the iPAQ and the GNU/Linux host

As is, PocketPC has only one tool that uses the standard TCP/IP protocols able to transfer files: it is the Internet Explorer Web browser. Although its usage is straightforward, it has two drawbacks:

1. it requires a running Web server on the GNU/Linux host
2. it is only able to transfer file in one direction (from the GNU/Linux host to the iPAQ)

That is, it does not fulfill our requirements: to be able to exchange files in both directions.

The workaround I have found is to use it initially to download a minimum FTP server on the PocketPC iPAQ, which will be used for all subsequent transfers.

1.4.1. Downloading and running the mini FTP server

As we will use a Web browser on the iPAQ, we need first to set up a Web server on the GNU/Linux host, place the mini FTP server so it can be accessed from the iPAQ, then download it and install it.

1.4.1.1. Setting up a Web server on the GNU/Linux host

Giving all the details required to set up a Web server on a GNU/Linux host is beyond the scope of this guide. Maybe you already have done it for another task, or your GNU/Linux distribution has already done it for you.

So, I will only describe what is required to set up the Apache Web server. I will assume that you already have installed the required package for it, using your distribution's packaging tool.

We first have to locate the Apache configuration file, by running the following command:

This tells us that the file is located in the directory /etc/httpd/conf. In this directory, we will find where the root of the Web server is; that is, in which directory we will have to place files so they can be seen from the iPAQ. I search on the whole directory, as the information is not necessarily in the httpd.conf file in old Apache versions:

Some other lines that may list errors can be safely ignored. The only interesting thing here is the second line, saying that the DocumentRoot is located in the /var/www/html directory. This may be different for your system.

Using this information, we will create a directory where we will store the files for the iPAQ: let's call it iPAQ:

We then have to launch the Apache Web server. On my Red Hat 7.2 distribution, I can issue either:

or

Depending on your GNU/Linux distribution, you may have to find the right way to do it...

1.4.1.2. Getting the PocketPC mini FTP server

Copy in this directory the FTPS006AP.ZIP file (aka, the ftpserv zipped file), downloaded from the following location:

1.4.1.3. Downloading the mini FTP server on the PocketPC iPAQ

If everything is OK, you should be able to download the ftpsvr.exe file by fetching the following URL in the Internet Explorer Web browser on the PocketPC iPAQ:

1.4.2. Transferring files using FTP

On the GNU/Linux host, you can either use the command line ftp, or your favorite graphical FTP client. I will show here the basic, command line option:

You can now transfer files back and forth:

Chapter 2. Backing up the PocketPC iPAQ

There are several reasons why you should consider backing up the PocketPC iPAQ before proceeding to the GNU/Linux replacement:

• the operating system replacement is a destructive operation, that will erase everything on the machine
• the software that comes pre-installed on the machine is licensed to you (remember you paid for it!), so even if you don't want it, you should keep it as valuable
• if you are not satisfied with GNU/Linux, this will be the only way to go back to the original operating system
• concerning your own data, remember that you are the only one able to re-create it...
• if you experiment on someone else's iPAQ (you probably shouldn't, anyway), you will have to restore everything to its original state

This is why I urge you to backup your iPAQ. When it comes to safety procedure, it is better to have suspenders, a belt, and a parachute than nothing...

2.1. Downloading the necessary softwares

You can download all the software we will need in just one file, which contains the right versions for our iPAQ. To download it go to the following homepage:

2.2. Backing up the Bootloader

Once BootBlaster is copied onto the iPAQ:

2.3. Backing up PocketPC

This operation is very similar to the previous one:

Chapter 3. Setting up a serial terminal connection to the iPAQ

In this chapter, we will set up a serial terminal connection to the iPAQ that will be used later for:

• taking control of the bootloader to send the GNU/Linux bootstrap image to the iPAQ and flash it
• taking control of the GNU/Linux on the iPAQ while there is no graphical interface

On the GNU/Linux host, we will use minicom as a terminal emulator.

3.1. Shutting down ppp

3.2. Setting up minicom

Launch minicom in setup mode by typing:

The "configuration" window will popup. Using the arrow down key, move to the "Serial port setup" entry and press Enter.

A new popup window will appear, giving you the ability to change the serial port settings. Press the A key and enter the serial line to suit your hardware configuration (/dev/ttyS0 for BIOS port "COM1", /dev/ttyS1 for BIOS port "COM2"). Press Enter.

Press E to change the serial parameters. A new window "comm parameters" will show up.

In this new window, press I to set the speed to 115200bps, and Q to use 8 data bits, no parity, and 1 stop bit. Press Enter to go back to the previous window.

Press F and G to set both the hardware and software flow control to "none". Press Enter to go back to the main "configuration" window.

Using the arrow down key, move down to either "Save setup as dfl" or "Save setup as...", depending if you want to save this setup as the default setup, or save it into an alternate configuration file.

Using the arrow down key, move down to "Exit" to leave the configuration mode and go into terminal emulation mode.

Chapter 4. Installing the bootloader

This chapter covers the only dangerous step in the whole conversion process. By dangerous, I mean that this can really turn your iPAQ into a useless high-tech paperweight! Fortunately, this only happen very seldom, and the risk is close to zero if you follow the instructions carefully.

As a service, Compaq (now HP) Research ensures that it will fix your unit in case it was rendered nonbooting by a failed installation. Of course, this may take a while before you get it back, and this should only be seen as the last resort.

4.1. Downloading the bootloader

The default bootloader (code name Parrot) is quite sophisticated. It can be accessed by pushing the central "arrow pad" on the iPAQ and resetting by putting the stylus into the narrow hole at the bottom of the case (don't do it!). Then, using a terminal emulator as set up in the previous chapter, you can obtain a command line that allow you to do various things.

Unfortunately, this bootloader is only able to boot the pre-installed operating system, so we have to replace it in order to boot another OS, like GNU/Linux.

4.2. Flashing the bootloader

If you followed the steps sequentially, you should have a BootBlaster*.exe file and a bootldr-*.bin file on your PocketPC iPAQ. We will flash the new bootloader by doing the following:

4.3. Verifying the bootloader

Before reseting your iPAQ, you must check that you have a valid bootloader. This is how to verify it:

1. In BootBlaster, tap on the "Flash" menu.
2. Tap on the "Verify" entry. A popup window will open, stating that you have a valid OHH (Open HandHeld) Boot loader * in flash, and how to access the serial console. Tap on "ok" to close this dialog.

4.4. Rebooting the iPAQ

If you reset your iPAQ by pushing the recessed reset button at the lower right of the unit, the bootloader will boot PocketPC if present, just as usual.

What is different, is that you can get a serial console onto the iPAQ and that you get the following splash screen:

Chapter 5. Bootstrapping Familiar GNU/Linux

In this chapter, we will install the Familiar GNU/Linux bootstrap onto the iPAQ. It will be used in next chapter to install the full-blown Familiar GNU/Linux onto the iPAQ.

5.1. Getting the root image

5.2. Performing bootloader configuration

In order to boot GNU/Linux with the correct kernel arguments, the flash partitions need to be setup correctly, by typing:

This command defines three two partitions:

• the bootloader partition
• the GNU/Linux partition
• the asset partition, containing unit specific information

5.3. Flashing the root filesystem

Issue the following commands:

This command tells the iPAQ to be ready to receive the root image using the ymodem protocol. You just have to feed it from the running minicom window, by pressing Ctrl-A and S. A small popup window will appear, allowing you to choose the transfer protocol. Using the arrow down key, move down to the "ymodem" entry and press Enter.

5.4. Booting GNU/Linux for the first time

Simply issue the following command:

The familiar penguin should appear on the iPAQ's screen, as well as the following output in the terminal emulator:

By default Familiar prints it's messages to ttySAO so you will not see all of it while booting. I you want to see everything run the following commands before boot:

You can login as the "root" user by providing the default "rootme" password.

Chapter 6. Setting up an USB network

Setting up an USB network will allow us to speed up the installation by providing a faster, as well as an easier way to transfer files than the serial method used up to now.

There are two steps involved in setting up the network:

1. Establish the iPAQ connection to the LAN (Local Area Network), if it exists. Anyway, if it does not exist, this connection will be used to access the Internet. We will use the mechanism known as proxy_arp, that will assign two IP addresses to the host, one for itself and one for the iPAQ.
2. Establish the iPAQ connection to the Internet. If the GNU/Linux host is part of a LAN and already has access to it, then no further work is required, and the iPAQ should be able to access it too. However, if the host is directly connected to the Internet through a modem, then we will have to set a mechanism called NAT (Network Address Translation), in order to map iPAQ's address to the same IP address the GNU/Linux host uses to access the Internet. This is required, as your ISP (Internet Service Provider) probably supplied only a single address to you. Another consideration will be to declare the iPAQ to the firewall, so it gets proper authorizations to access the Internet.

6.1. Connecting to the LAN

For this step, work is needed both on the GNU/Linux host and on the iPAQ.

6.1.1. USB networking on the GNU/Linux host

You need to have a supported USB hub in your PC, and have the kernel module installed for it. You should also obtain the kernel module named usbnet, which is bundled in Linux kernel since version 2.4.10, but working version is only bundled since 2.4.13. However, I found the experimental module in my stock Red Hat 7.2 distribution (kernel 2.4.7), and it seems not to behave too badly...

It is normally found as /lib/modules/kernel_version/kernel/drivers/usb.

If you cannot find the module, but have a supported kernel, you need to enable the CONFIG_USB_USBNET option in the kernel config (from the main config menu, go into "USB Support", you may need the "Code maturity level option" set to "EXPERIMENTAL"), and compile it with a command line like: and recompile your kernel.

If you do not want to compile a whole kernel, you can try to compile only the usbnet module with the following command:

Once the module is compiled, copy usbnet.o into the module directories and update the module dependencies with:

Otherwise, consider upgrading your kernel. As an alternative, you can continue to download all the required files using the serial method, it will only be slower.

You can then insert the module with:

6.1.2. USB networking on the iPAQ

On the iPAQ side, the USB driver is included in the bootstrap image with an usbnet package. This is responsible for configuring our network. We will only need to set the correct IP addresses in the /etc/network/interfaces file.

We use sed as the editor to change the IP addresses in the file. First we go to the /etc/network directory and list the content of the interfaces file. This way we know which IP addresses to change. Next we change it using sed. We have to use a temporary file for this. Here is how we do all of this:

We are looking for the "iface usbf inet static" part. The IP address after the address keyword is the IP of the iPAQ and the address after the gateway keyword is the IP of our GNU/Linux host. We also need to change the network to 192.168.1.0 in our example. We will change these three addresses:

We have to see something like above in the newinterfaces file. If it is correct then we can replace the interfaces file with this one:

This is all the editing we need. The /etc/init.d/initd-usbnet file is responsible for starting usbnet using the parameters given in /etc/network/interfaces. If you want it to start right after booting the iPAQ you have to create a symbolic link to this script into the /etc/rc2.d directory, which is the directory containing the scripts to launch when you go into runlevel 2 (the normal runlevel):

For this first time, we can just launch it manually by typing:

6.1.3. Bringing up the USB network

If you have not already done it, insert the usbnet module on the GNU/Linux host:

This means that our host's USB subsystem has correctly detected and configured the iPAQ. On the iPAQ, you can check that everything is working by issuing the following command:

This last paragraph provides the necessary information about the USB network interface.

On the GNU/Linux host, a new network interface usbN (where N is a number starting from 0) will appear when the iPAQ is connected to the USB bus. You can then configure it like any other ethernet interface.

To save a lot of typing if you are going to use it on a regular basis, I suggest you to create the following ipaqnet script on your GNU/Linux host (please replace the addresses and UPLINK_IF with your appropriate values):

Make this script executable by typing:

We should now be able to launch the connection by typing:

If some sort of error message appears at this point, it means that the iPAQ insertions was not correctly handled, try re-inserting it.

This script uses the proxy_arp mechanism introduced above to forward data to the iPAQ.

On the GNU/Linux host, you can check that everything is working by issuing the following command:

Again, this last paragraph provides the necessary information about the USB network interface.

6.2. Connecting to the Internet

If your GNU/Linux host is part of a local network, then no further work is required. If it is connected to the Internet directly through a modem, then we will have to configure the firewall to do both address translation and to accept the iPAQ connection.

Configuring a firewall is very configuration-dependent. As a guideline, I provide the following /etc/sysconfig/iptables script, which work for the RedHat distribution (it can be adapted to other distributions too):

6.3. Shutting down USB networking

Whenever you want to stop the USB network, on the iPAQ issue:

On the GNU/Linux host, issue:

6.4. Automating the USB connection

Unfortunately, automating the USB connection on the GNU/Linux host heavily depends on the GNU/Linux distribution you are using. As a guideline, here is what happens when an USB device is plugged or unplugged. The kernel first checks for a /proc/sys/kernel/hotplug pseudo-file that should contain the name of a user program to launch with the event type (usb, pci, isapnp, net, ieee1394, printer, disk, parport, ...) and a device descriptor as arguments. This program is usually a shell script, that will delegate processing to some other scripts, using text configuration files. Not two different GNU/Linux distributions are using the same schema, which makes it very difficult to write a general way of automating. So, the only general way to handle this will be to edit the hotplug script.

On my RedHat 7.2, I need to add the following lines at the beginning of the /sbin/hotplug file to use the /etc/rc.d/init.d/ipaq script introduced above:

This way, the USB network will be correctly brought up/shut down when you plug/unplug the iPAQ.

Chapter 7. Installing Familiar GNU/Linux

In this chapter, we will install the Familiar GNU/Linux distribution onto the iPAQ.

7.1. Upgrading packages definition

7.2. Running SSH

You can now forget minicom and the serial line, as you can take control of the iPAQ using the SSHD daemon running on it. The only remaining usage for minicom would be to get a serial bootloader console. To access the iPAQ from your GNU/Linux host, issue:

or

7.3. Installing additional Familiar packages

At your convenience, you can install more Familiar packages. You can get the list of packages available by issuing the following command:

I recommend you to install at least a decent shell (bash), a tool to list the running processes (psmisc), and a text display utility (less).

If you want to be at the leading (bleeding?) edge of technology, you can uncomment the familiar-unstable line in the /etc/ipkg.conf file and perform an ipkg update followed by an ipkg upgrade to get the state of the art packages. Just remember what unstable means...

From this point, you have the choice to install a full blown GNU/Linux system, with or without X11, or to continue with the Opie installation. As said before, this last option was chosen in this document to demonstrate that an Open Source system can compare to a commercial system, and even do better.

Chapter 8. Installing Opie

8.1. Bootstrapping Upgrading Opie

You may want to upgrade Opie to the current testing version. It is quite stable and has many good features that the stable version doesn't have. To do this you have to change the feed information in /etc/ipkg/opie.conf followed by ipkg update and ipkg upgrade:

8.2. Finishing Opie installation

At this point, you have the choice either to continue to install the Opie applications from the command line, as we did before, or to use the graphical package manager. For this last one, you can launch it by tapping on the Settings tab, then tapping on the Software icon.

However, from my experience, it still suffers from minor problems, so my recommendation would be to continue to use the ipkg command line tool.

Use the task-opie-xxx meta-package to install a group of application at once.

You may choose to install the Konqueror/Embedded Web browser, which is definitively one of the best browser with such a small footprint. To install it, add a new feed to the ipkg installer by typing run the following command :

At this point, you now have a fully functional iPAQ running GNU/Linux, as a perfect replacement for PocketPC, having almost the same capabilities ([[??]]except maybe for the synchronization facility) but with all the advantages of an open source solution.

Enjoy and have fun! I just hope you will not follow the last chapter of this document, dealing with PocketPC re-installation!

Chapter 9. Reinstalling PocketPC

This chapter is provided in case you are not satisfied with GNU/Linux on your iPAQ, or are forced to switch back to the original operating system. The steps of restoring the original PocketPC and bootloader images saved in Chapter 2 are covered here.

9.1. Restoring PocketPC

First, make sure you have set up a terminal connection, as described in Chapter 3.

You need to reboot the iPAQ. If you have GNU/Linux running on it, this can be achieved by typing:

# shutdown -r now Another alternative is to push the recessed button at the lower right of the unit with a sharp object. Warning Make sure you have bootldr 2.18.01 or higher installed on the iPAQ before proceeding with the following instructions. Compaq/HP Cambridge Research Labs will fix any units that fail to restore properly, but this should be seen as a last resort solution. When the bootldr screen appears, press on the "Calendar" button at the lower left corner of the unit to get a serial bootloader console. At the boot prompt, type: boot> set ymodem 1 boot> load root loading flash region root using ymodem ready for YMODEM transfer... This command tells the iPAQ to be ready to receive the root image using the xmodem protocol. You just have to feed it from the running minicom window, by pressing Ctrl-A and S. A small popup window will appear, allowing you to choose the transfer protocol. Using the arrow down key, move down to the "ymodem" entry and press Enter. A file selector window will open, where you need to specify the file to download. Using the arrow right key and pressing Enter, you can go to the directory containing the wince_image.gz you created in Chapter 2. Using the arrow down key, move down to the correct file, and hit space to select the file, then press Enter. A window will open, displaying the current transfer status. The transfer should take about 20 minutes (yes, it is much larger than GNU/Linux), so be patient. When completed, a beep will awake you, so press Esc to close the window. The following lines should appear: Looks like a gzipped image, let's verify it... Verifying gzipped image ......................................; programming flash...erasing ... Erasing sector 00040000 Erasing sector 00080000 Erasing sector 000C0000 ... Erasing sector 01F80000 writing flash.. addr: 00040000 data: EA0003FE addr: 00050000 data: 0F6A0F6A addr: 00060000 data: 11A0F003 ... addr: 01FA0000 data: FFFFFFFF addr: 01FB0000 data: FFFFFFFF verifying ... calculated crc32 = 0x282F31FE desired crc32 = 0x282F31FE formatting ... done. boot> You can now boot PocketPC by typing: boot> boot wince booting wince... Disabling LCD controller The iPAQ will boot PocketPC automatically, unless you hold the center of the joypad while pushing the recessed reset button.

9.2. Checking PocketPC restoration

To be safe, you can check that PocketPC restoration worked successfully. You must launch the iTask manager by pushing the iTask button at the front lower right corner of the unit. Tap on the "iTask" icon at the lower left corner of the window that will appear. In the menu that will open, tap on the "Self Test" menu entry. Check at least the "ROM checksum" box and tap on the "Next" button.

In the new screen that will open, check the "Perform automatic Reset" checkbox and tap on the "Start" button.

Answer all the questions and verify that the "ROM checksum test Passed" line appears. If not, try reflashing PocketPC using the procedure above.

Tap on the "Finish" button and save a log of the test if you wish so, then tap on the "Ok" at the top right of the screen.

9.3. Restoring the original bootloader

Appendix A. GNU Free Documentation License

Version 1.1, March 2000 Copyright (C) 200 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

A.1. PREAMBLE

The purpose of this License is to make a manual, textbook, or other written document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

A.2. APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you".

A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License.

The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License.

A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque".

Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only.

The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

A.3. VERBATIM COPYING

You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and you may publicly display copies.

A.4. COPYING IN QUANTITY

If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

A.5. MODIFICATIONS

You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five). C. State on the Title page the name of the publisher of the Modified Version, as the publisher. D. Preserve all the copyright notices of the Document. E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice. H. Include an unaltered copy of this License. I. Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. K. In any section entitled "Acknowledgements" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. M. Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version. N. Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section. If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

A.6. COMBINING DOCUMENTS

You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice.

The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgements", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements."

A.7. COLLECTIONS OF DOCUMENTS

You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

A.8. AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.

A.9. TRANSLATION

Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.

A.10. TERMINATION

You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

A.11. FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

A.12. How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page: Copyright (c) YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled "GNU Free Documentation License". If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being LIST"; likewise for Back-Cover Texts. If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.