Article: Hacking the iPAQ with Linux, for fun and profit
Dec 23, 2000 — by Rick Lehrbaum — from the LinuxDevices Archive — 85 viewsForeword: This article is the second in a LinuxDevices.com series by Jerry Epplin that explores the history, status, alternative architectures, and future developments of Linux on PDAs and handheld devices. In this installment Epplin explores the possibilities of installing Linux on the Compaq iPAQ PDA.
Linux on the iPAQ
In the first article of this series, we reviewed the architectures of several approaches to running Linux on the Compaq iPAQ PDA. Compaq ships the iPAQ with Windows CE, but they also sponsor an admirably open effort to port Linux to the PDA, at www.handhelds.org. In addition to the handhelds.org effort, at least three companies have released GUI development environments and application suites designed to work with the handhelds.org kernel . . .
- Century Software's Microwindows PDA Operating Environment
- Trolltech's Qt Palmtop Environment (later renamed “Qtopia”)
- Transvirtual Technology's PocketLinux
For the rest, this series of articles will cover the basics of iPAQ Linux software development. As always, in the open source world, there are many different approaches — each having strong adherents!
Before you attempt to use any of the add-on development toolkits, I recommend that you first install the handhelds.org environment, and become familiar with its resources. That's because the add-ons rely heavily on the handhelds.org environment as a base for many of their services.
In this article, then, I'll take you through the process of locating the required support at handhelds.org, downloading the iPAQ Linux environment, setting up your iPAQ for reprogramming, reprogramming it with Linux, and testing the result.
Ready? Let's get started!
Where to begin?
First, explore the handhelds.org web site. The web site uses a “Wiki” tool for organizing user-contributed material. There are HOWTOs and other documents describing various details of installing and using Linux on the iPAQ. Anyone can add to this information — no special privileges are necessary. While I hate to criticize such a democratic model of documentation, I frankly found it difficult to find much useful material on the handhelds.org Wiki at this time. The quality of the documentation varies, but almost all of it assumes more knowledge than a beginner is likely to possess. In addition, the Wiki seems to be in a constant state of flux — so even if you find a helpful document, there is no assurance it will be in the same place the next time you look for it.
As with many open source projects, especially early-stage ones, the definitive repository of iPAQ Linux information is the mailing lists. In the case of handhelds.org, they are found here. See especially the 'linux' and 'ipaq' lists. All of the major iPAQ Linux developers are active on these lists, so any questions you can't answer by other means can probably be answered there.
The mailing list archives are also quite helpful, though a searchable archive is missing. You might want to download the gzipped text archive for each month, uncompress it, and search the text — a somewhat cumbersome process, at best.
Finally, for those so inclined, a very active IRC channel named 'ipaq' is available at irc.gimp.org. As with the mailing lists, many of the major players are active on the IRC, so most questions can be answered at this forum as well.
The iPAQ's flash memory map
Next, familiarize yourself with the layout of the flash memory areas of the iPAQ, and how they are typically viewed from Linux. Its flash memory is divided into seven areas, referred to as /dev/flash0 through /dev/flash6. These areas are used as follows (thanks to Jan Koop and Jamey Hicks) . . .
Each of these is flashed separately into the iPAQ.
Hey! How do I turn it off?
Something else you might want to know before you start your exploration of Linux on the iPAQ, is that its power button (on the front) is not currently implemented under Linux. Sure, the kernel sees the button pressed. But power management for the StrongARM processor is not finished under Linux, so as a result, pushing the power button currently does nothing — a situation that is likely to be a source of confusion (and frustration) to iPAQ Linux beginners!
OK, so how do you turn it off? See the small switch on the bottom left of the unit? Use the stylus to slide the door open, to the right. Then, flip the switch to the right, to turn the unit off.
Fasten your seat belt!
Once you're familiar with the resources available, it's time to install the handhelds.org Linux port on the iPAQ — which is as easy as 1-2-3 . . .
- Step 1: Obtain an iPAQ
This is perhaps the most difficult step, because as of this writing they are quite difficult to find.
- Step 2: Set up the serial connection
Another prerequisite is to have a serial connection between the iPAQ and your desktop computer. If your iPAQ came with a serial cradle then you are ready for the next step. But many iPAQs in the US are shipped with USB cradles.
You can either obtain a serial cradle or follow these online directions to convert a USB cradle to use a serial connection.
- Step 3: Replace Windows CE with Linux
Now, get ready to replace Windows CE with Linux. There are two approaches you can use: you can do it from a Windows computer, or you can perform a Linux-only installation. It turns out that the installation is somewhat risky, and the Windows-based process is the most mature. Take your choice . . .
- Windows-host procedure — follow these instructions, which explain how to load your iPAQ over a serial connection from a Windows computer.
- Linux-host procedure — here is one of the more clearly written procedures.
* * * NOTE * * *
If something goes wrong while loading the bootloader,
your iPAQ can become unusable!
In actuality, this is quite rare, so don't panic if something seems wrong when you perform the installation. In most cases, the system is recoverable even when it seems dead; and Compaq has reportedly been quite helpful in repairing units in those few cases when there was no way for the customers to recover them.
After performing the initial installation, reboot. You should now have a complete X-based Linux handheld. The handhelds.org kernel uses a serial console, so you will need to connect to it using minicom or any other terminal emulator. minicom is a good choice, since it is normally installed by default in most Linux distributions.
To configure the serial port, press ctrl-a, 'o', select 'Serial port setup'. Specify the serial port (typically /dev/ttyS0 or /dev/ttyS1), set 'Bps/Par/Bits' to '115200 8N1', and select No for 'Hardware Flow Control'.
Once connected, you can log in as root (no password) and look around.
Next you'll want to establish a PPP connection between your Linux box and the iPAQ. Carl Worth has written very clear directions on doing so, which are located on the Wiki in the PPPHowto. Once connected, I suggest logging on to the iPAQ using 'rlogin ipaq -l guest', then 'su' to work as root (I add an entry '192.168.1.100 ipaq' to the /etc/hosts file on my desktop). Also, Carl Worth suggests, at the end of the PPPHowto, running X programs (such as xterm) with their display set to your host. Just be aware that you may need to set your LD_LIBRARY_PATH to use /usr/X11R6/lib/X11, or the iPAQ's X programs won't be able to find their libraries.
Loading it up
Finally, you need a way to transfer files to and from the iPAQ. Numerous options are available — FTP, SSH, NFS, and probably many others I'm not thinking of. I use NFS with my iPAQ as the client, because it needs no special modifications to the standard handhelds.org installation to use, and because, like many desktops, my computer is already set up as an NFS server.
I designate a directory (/home/jerry/ipaq/devel) on my desktop for transferring files with an entry in my /etc/exports file as follows: “/home/jerry/ipaq/devel ipaq(rw)”. This allows machine 'ipaq' to mount my devel directory for reading and writing.
Restart the NFS server (“/etc/rc.d/init.d/nfs stop ; /etc/rc.d/init.d/nfs start” on many distributions), and then mount the directory from the iPAQ onto a mount point (e.g., /mnt/ramfs/home/guest/devel) with “mount -t nfs 192.168.1.100:/home/jerry/ipaq/devel /mnt/ramfs/home/guest/devel”.
For my development, I build executables using the 'skiff' cross-development tools (described later) into my 'devel' directory, and then execute my code directly from the NFS-mounted directory on my iPAQ.
Fun with flash
If you've made it this far, you have probably realized that the standard installation process is somewhat tedious and time consuming, involving downloading multiple files into the iPAQ's flash memory. It can easily take thirty minutes or longer to load the files, and loading them individually requires near-constant attention. You will also find that while configuring your system (or developing applications for it) you're going to need to reprogram the flash numerous times.
Fortunately, there are several ways to simplify and optimize this process. My favorite is a little Perl program called ipaqflasher, written by Greg Harfst and available here. This admirably flexible script lets you program multiple files into your iPAQ unattended. You can set up a configuration file specifying which files (kernel, init, usr, etc.) you wish to load, and then simply invoke ipaqflasher by name to perform the operation. Some other options are possible, including specifying parameters on the command line — see the comment block at the beginning of ipaqflasher for details.
About the only thing missing is the ability to flash the /usr/local block. You can easily add support for that by changing line 63 to . . . oh, never mind, I'll do it myself. You can get my modified version, here.
After flashing the /usr/local block, execute a 'mount /dev/flash6 /usr/local'.
Of course, the process of programming the flash is no faster than with the manual minicom-based method. It's just that ipaqflasher lets you perform the operation unattended. You may wish to invoke the program from your Makefile when developing software.
Now what?
Having installed the handhelds.org distribution, you now have a full standard Linux machine based on X. Most of your favorite X-based applications will compile for and run on the iPAQ with little trouble. Some libraries that you take for granted on your desktop may be absent — don't expect to find the Gnome or KDE libraries, for example. But generally, you'll find the environment quite similar to that of your desktop.
In fact, the handhelds.org environment makes little attempt at minimization (thanks to the relatively generous resources provided by the iPAQ). You won't, for example, find BusyBox — although someone at Lineo has recently ported it to the iPAQ. The X implementation, on the other hand, is a small footprint version called Tiny-X, which is now fully supported by XFree86.
Getting down to development
For software development you need the 'skiff' cross-development GNU toolchain. You can build it from source for any architecture supporting Linux, but I recommend using the prebuilt x86 binaries, found here.
When untarred, this file places the toolchain at /skiff/local. See the README in the above directory on how to finish configuring the skiff toolchain. The only other step is to set up a couple of symbolic links. Building an application, then, is much like native development under Linux — except that you need to define CC, LD, and the rest as follows (this works for bash; other shells are similar):
- export AR=/skiff/local/bin/arm-linux-ar
export AS=/skiff/local/bin/arm-linux-as
export CC=/skiff/local/bin/arm-linux-gcc
export CXX=/skiff/local/bin/arm-linux-c++
export GXX=/skiff/local/bin/arm-linux-g++
export LD=/skiff/local/bin/arm-linux-ld
export NM=/skiff/local/bin/arm-linux-nm
export RANLIB=/skiff/local/bin/arm-linux-ranlib
export STRIP=/skiff/local/bin/arm-linux-strip
Testing your creations
To test software, you can simply build on your x86 host and copy the executable into the iPAQ using your favorite file copy utility, as described earlier. This works well for development, but your changes won't be preserved over power cycles.
For permanent changes, you'll need to work with 'cramfs' filesystems — which write your software into the iPAQ's nonvolatile flash memory. The files that are loaded into flash (init, root, usr, and local) are created using the 'mkcramfs' utility, available from the same FTP location that holds the handhelds.org distribution.
Linux 2.4 can read and write cram filesystems natively, so if you are already using a 2.4 series kernel on your desktop you can manipulate them very simply. If, on the other hand, you're still using a 2.2 kernel, use mkcramfs to compress a directory structure into a cramfs file; the result is the file that is programmed into flash using ipaqflasher. Note that the process is one-way if you use mkcramfs. For example: start with the /usr tree, make your modifications, create the usr.cramfs file using mkcramfs, and program it into your iPAQ. When you want to make further changes to /usr, start over again with the /usr tree, and discard the previous usr.cramfs.
The hacker's iPAQ
Many Linux users and developers will load the iPAQ distribution from handhelds.org and use it — seeing no need to use the third-party GUI development tools we will describe in the future articles of this series. Others will manually apply certain tools, such as FLTK or Qt/Embedded, on top of the base distribution and begin to port their favorite programs to the iPAQ. This is feasible because the iPAQ has sufficient RAM, flash, and processing power to handle Linux, X, a windowing toolkit, and applications.
On the other hand, the development toolkits offered by Century Software, Trolltech, and Tranvirtual Technologies, will appeal to those looking for a more complete, preconfigured environment in which to develop applications. These environments also strive to provide a common user experience among applications. They can be expected to appeal to developers of vertical applications targeting the iPAQ, because they make it practical to focus on the applications rather than on the Linux environment itself.
About the author: Jerry Epplin has written embedded software for the past fifteen years, primarily for medical devices. He can be reached at [email protected]
The following article may also be of interest . . .
This article was originally published on LinuxDevices.com and has been donated to the open source community by QuinStreet Inc. Please visit LinuxToday.com for up-to-date news and articles about Linux and open source.