These are notes and utilities and files I’ve gathered together to make my IPaq hx4700 useful to me, and setting it up decently easy. I know it took forever to type them up and finally publish them, but better late than never.

Mission

To turn basic Familiar 0.8.4 on the IPaq hx4700 into something useful. More specifically, to make IR and Bluetooth work, to make my Belkin IR Keyboard (F8U1500-E) work, and then to install a Debian chroot on an SD card (via the cross install technique) where we can then install, for example, every programming language and text editor we could want for portable programming purposes.

Getting Started

So, first things first, you need an IPaq hx4700. Or at least an IPaq, and hopefully one supported by Familiar Linux. As you can see from the list the hx4700 is supposed to have A+ support. It turns out that’s kind of a lie. But we can do surprisingly well with some work. First off, throw away the Familiar Installation guide, it doesn’t apply to the hx4700. They put together a different one on the wiki at handhelds.org/moin/moin.cgi/HpIpaqHx4700HowtoInstallLinux. Read it.

Files and Filesystems

So now’s as good a time as any to mention that I’ve collected all the files you’ll need and put them on my FTP at /resources/ipaq-hx4700.

First off you need a SD card and you need to write the bootloader all over it so whip out DD and does as the instructions say. Then when that’s done toss an ext2 file system on your SD card, we’ll need it later.

Now for some work with the CF card. Since we’re flashing from it I’d suggest using the FAT filesystem. We’ll stash all our system stuff on it here’s a quick list of what you should grab from the FTP and put on it.

  • zImage-2.6.15-hh2-ipaq-pxa270: kernel
  • zImage-2.6.17-hh3: exciting new and more useful kernel, but we can’t install it until the system is up and we copy it’s modules over to the ipaq.
  • bootgpe-v0.8.4-ipaq-pxa270.jffs2: Root filesystem with GPE installed. I’d recommend GPE over OPIE.
  • reflash.ctl: Control file for the bootloader to know what it can flash. This one is updated with an option for the new kernel.
  • RADIO0d.BIN: Firmware driver
  • radio11.bin: Firmware driver
  • wlangen.bin: Firmware driver
  • 2.6.17-hh3.tar.gz: Kernel modules for a newer kernel. Untar it in place.
  • install-firmware.sh: Shell script to install the firmware. The names are case sensitive so depending on how your FAT filesystem performs this might not work :/.
  • install-modules.sh: Install the kernel modules for the 2.6.17 kernel. Assumes it’s running with the untarred file 2.6.17-hh3.tar.gz. Copies the modules to /lib/modules on the ipaq.

And now is a good time to mention that I got an IR keyboard with my IPaq, specifically a Belkin F8U1500-E, which didn’t work with the IPaq for a number of reasons at first. I solved them all. If you have this key board you’ll also want the following files. If you have any IR keyboard you still might want at least the init.d file from the list.

  • install-kbdd.sh: Shell script to install the files
  • init.d.kbdd: Adds lines to the start function to remove extra IR kernel modules that prevent simply IR keyboards from working. Also kill irattach.
  • kbdd.conf: Config file that just says use a belkinir keyboard on /dev/tts/2.
  • kbdd: My patched kbdd program with proper support for my keyboard.

I also put up kbd.c which is the file I modified from the kbdd source for anyone who wanted to see what I’d done (also, I suppose, to comply with the GPL ;)). I know it’s a hideous mess and hack, but using a case statement was easier initially in order for me to figure out how to get the keyboard working. I fully intended to turn it into an array latter, but once it worked I got lazy and left it. Meh.

Getting Familiar up and Running

Ok, you now have the CF card with all the files you need. Toss it in the IPaq and follow the flashing instructions on the wiki. Flash the 2.6.15 kernel, and then the GPE root filesystem. Then you can let GPE boot. It might take a bit.

Also, the boot loader and possibly the IPaq itself are kind of finicky. If it just won’t turn on, don’t worry, you probably haven’t bricked it, its just in a funk. Let it sit for like 5 minutes. Also try pulling its battery for a bit, putting it back in and then putting it on AC power. Eventually it’ll decide that the time is right to try booting again.

So, once GPE is up, there are a few change that we need to make to make life easier and better. First, go to “Setup->Login Setup” and set “Automatic Login” to yes. This will automatically log you on as root, instead of asking you for user name and password of some non root user. Really much beter in the long run for this device. Then log out and you should automatically be logged back in as root.

Now we can proceed.

We’ll need to do some typing to get the necessary files installed, so you’ll need to bring up the on screen keyboard. It kind of sucks, but I’ve seen worse. It is usable. Also, I’ve tried to write scripts to automate a bunch of stuff to keep the typing to a minimum until a real key board can be used.

So, bring up a root console from “Others->Root Console”. “cd” onto the CF card, “/media/cf”.

First we’ll install the firmware, so run sh install-firmware. Ideally this will work but you should double check and fix if it doesn’t. What should happen is the 3 “.bin” files are copied into “/lib/firmware” and their names are all uppercase except the “d” in RADIO0d.BIN.

Next run sh install-modules which should copy the 2.6.17 kernel module directory (you untared the .tar.gz right :)) into /lib/modules. Now when we flash our new kernel it’ll find it’s kernel modules installed and actually work, as opposed to choking in boot, or booting but being generally useless.

If you have a Belkin IR Keyboard (F8U1500-E) then you’ll also want my kbdd, and if you have any IR keyboard you might want my init.d.kbdd file.

So run sh install-kbdd. It should copy kbdd to /usr/sbin/kbdd (saving the old one as /usr/sbin/kbdd.old), copy kbdd.conf to /etc and copy init.d.kbdd to /etc/init.d/kbdd.

Now you should have your base system much closer to ready. Now that the firmware is installed if you were to reboot your Bluetooth should work. However the kernel that shipped with Familiar 0.8.4 had broken IR support, so we need to upgrade to the 2.6.17 kernel I compiled for the IPaq. If you have a different piece of hardware there are instructions in the handhelds.org wiki for getting and compiling kernel source. Ignore the part about them making their own configs, it didn’t work for me, instead just copy /proc/config.gz to your sd/cf card and use that.

So to flash the new kernel after the modules are installed, reboot the IPaq holding the two upper keys (as the instructions said) as well to bring up the boot flasher and this time pick the 2.6.17 kernel.

Now it should boot up and Bluetooth and IR should work and your Belkin IR keyboard should work. Like magic. I still haven’t gotten wireless to work but I’ll update this if/when I do.

Wired USB internet

Next? We need connectivity. I still haven’t gotten the wireless to work, but you can easily do ethernet-over-usb and use a desktop as a router. My instructions are Linux specific but I’m sure other OS specific instructions can easily be found by Google.

I already wrote instruction on how to get a mobile Linux device online with Linux so check out the instructions at 2006-12-11-installing-chrootable-gentoo-on-a-gp2x.md#gp2x_networking.

The net.sh script for the IPaq has an extra line and looks like

#!/bin/sh

ifconfig usb0 up 10.1.0.2
route add default gw 10.1.0.1

and you can get it at /resources/ipaq-hx4700/net.sh.

Native Video

So the IPaq can play video. It’s a smidgen of a hack for GPE because the version with familiar doesn’t actually have a mplayer compiled for it so I nicked the one for OPIE and flubbed one of the dependancies: instead of using the SDL 1.2.7 compiled for OPIE and depending on OPIE on used the 1.2.4 version compiled for GPE. This might be why the video is currently choppy until I can find a better solution because there might be a much faster rendering path on OPIE for SDL than there is under GPE. Still, this will work if you don’t mind choppy video (but at least the audio is 100% solid). What I think I really need to do is find a way to make XV work on GPE and get mplayer to use it.

As for getting this working, all you need are some packages I’ve collected. Just grab the following from my iipkg collection at /resources/ipaq-hx4700/ipkg:

  • libmad.ipk
  • libpostproc.ipk
  • libsdl.ipk
  • mplayer.ipk

I think that’s all you need. Either way, if it asks for other dependancies they are in the folder, so just grab everything. I think you have to force one of them to install ignoring it’s dependancies with the ‘-nodeps’ flag. Anyway, once you get mplayer installed, it uses the SDL video output plugin. In order to make video and audio sync and not play laggy or slow I recomend the following flags:

mplayer -framedrop -nocache $MOVIE

As I said, it’s currently laggy, but it works, and I’m looking for a better solution.

Making an ARM Debian Chroot##

Note: For anyone who has been waiting for almost a year for my promised guide on how to make a Debian chroot for the GP2X, this is it. The instructions are the same. I originally did this on my GP2X until I got netwokring working on the IPaq, and shared the chroot SD card between them.

Now the IPaq only has limited space and only a limited number of programs compiled for it. If you want access to absolutely all software, then we need another source. The answer is a Debian chroot. Debian has great arm support so about 99% (Not Java) of stuff in the Debian repository will be accessible to you. All you need is space. So grab a decently sized SD card and put a reasonable filesystem on it, like ext2. Now, in order to install Debian we need Debootstrap, their utility for installing Debian from anywhere. You could try and install it on the IPaq but it’d be a hassle. I found the best solution was to download the ARM install disks (or minimal CD) and just copy off the entire filesystem. It’s only a few MB. You can get my copy at /resources/ipaq-hx4700/deboot.tar.gz Untar it on the SD card.

For this to work you’ll need a network connection on the IPaq so make sure that’s setup and working.

(For GP2X users, for each chroot (the debootstrap one, and the final one) you’ll also want to run cp /lib/libiconv_plug.so lib where lib is what will be the root lib directory in the chroot.)

Then on the IPaq execute the following to set up the environment to chroot into the Debian install environment.

cd deboot
cp /etc/resolve.conf etc
mount -t proc none proc
mount -o bind /dev dev
chroot .

Now you’re in the actual minimal Debian install environment that is really only capable of doing one thing: running Debootstrap. So go for it. Install it in the chroot for now, you can always move it out once done.

debootstrap --verbose --arch arm etch /mnt/etch http://gulus.usherbrooke.ca/debian

Keeping in mind to change the Debian release name to what you want and to change the mirror to something appropriate to you. For a full list of Debian mirrors look at www.debian.org/mirror/list.

When it’s done, you’ll have your very own Debian chroot in /mnt/etch under the chroot or /media/card/deboot/mnt/etch in the IPaq filesystem.

You’ll probably want to move the chroot to either the root of the SD card or just a subdirectory, so exit the chroot and then

mv /media/card/deboot/mnt/etch /media/card/etch

Now you have your very own Debian chroot. A few last things need to be set up before using it. Again, it will need internet too if you want to be able to install software, so run

cp /etc/resolve.conf /media/card/etch/etc

Next you need to add a few things so the environment will be have as Debian expects, and not inherit the slightly different IPaq environment, so grab profile and profile.ipaq and put them in the /etc directory of your chroot. Mostly it just sets your home directory to /root instead of /home/root and a few other minor things but important things.

Finally, get the chrootme.sh script and put it in the root of your chroot.

Now all you should need to do to use your chroot is

cd /media/card/etch
./chrootme.sh
source /etc/profile

Now you are in your live Debian chroot! Congrats! So why did we go to all this effort to just get another Linux environment when IPaq already has one? Well, this one can now install any software that Debian supports, which is pretty much all software :). But first, at least in my case, we have to do a few things for apt so it will be happy. Run

touch /root/.gnupg/trustedkeys.gpg

gpg  --keyserver subkeys.pgp.net --no-default-keyring --primary-keyring /etc/apt/trusted.gpg --recv 359AAB34 

wget http://ftp-master.debian.org/ziyi_key_2006.asc
gpg --no-default-keyring --primary-keyring /etc/apt/trusted.gpg --import ziyi_key_2006.asc

This install the required gpg trust info so that you can securely talk to the Debian package server. You can also select a mirror by editing etc/apt/sources.list. Now just

apt-get update

and then you can apt-get install any piece of software you want. I’d recommend starting off with a text editor like vim and/or emacs, and the some programming languages like Python, Ruby, Lisp, or C. Now you have a mobile coding environment that fits in your pocket!

Conclusion

Well, now you have an ultra portable computer that can run any piece of Linux software. I turned mine into a portable development machine. I’ve been using it at University in my CS classes, but you can do what ever you want with yours.

As for the future, the only real things this tutorial still need are ways to get the WiFi working and usable, and a way to squeeze better framerate out of MPlayer. If anyone has any ideas, please get in touch and let me know :)

I hope this set of notes/tutorial/howto is useful to anyone.

Comments

ajehuk Says:

December 14th, 2007

The wifi works (for me at least) with any of the 2.6.21 kernels. You need the acx / hx4700_Acx kernel module and firmware for the card (available within the Angstrom/Gentoo/Qt images for the HX4700).

Its as simple as dropping the firmware into /lib/firmware (maintaining the correct file names), modifying the /etc/network/interfaces file to reflect your network (the card is wifi0 under most things, wifi2 under gentoo) and then inserting the relevant modules (modprobe hx4700, modprobe acx). It works a charm.

As for mplayer.. I have been playing with Gentoo on the hx4700 and mplayer works neatly without tweaking so the hardware is definitely capable, but I haven’t manages to get it working nicely using Familiar/GPE (or opie).

digitaller Says:

December 30th, 2007

debootstrap –verbose –arch arm etch /mnt/etch http://gulus.usherbrooke.ca/debian

When i do the above step, after downloading and extracting all the packages, I get an error saying can’t find /usr/lib/debootstrap/devices.tar.gz. Then the process stopped. Any idea? Thanks in advance.

hakujin Says:

January 14th, 2008

Just so I understand it when you chroot over to the debian you don’t have X right? Or can the deb chroot use GPE’s X server? Sorry for the lame questions but I am really still hopelessly mired in the intricacies of desktop debian.

Dan Ballard Says:

January 14th, 2008

No X installed in the chroot, however you can install X apps that pull in X libs. You can access X from with in the chroot by running

mount -o /tmp /mnt/card/etch/tmp

outside of the chroot. The X socket is in tmp and so apps from within the chroot can then talk to the IPaq’s X. The chrootme.sh script already handles this,

hakujin Says:

January 15th, 2008 at 6:58 am [edit]

So that’s like running X client apps on one machine using a server on a different machine? So when you chroot you need to build a whole new system within the chroot’s filesystem? Your kernel never changes though right, you still need to have the same kernel modules (version wise I mean) on the chroot filesystem as on the base root? Not to get off topic but wouldn’t it be possible to install a bootstrap image and then chroot to a debian root filesystem? Thanks for the info.

Dan Ballard Says:

January 15th, 2008

Yep, I think what you describe is fine. But the chroot doesn’t need a kernel at all, since it’s being run under the system kernel. The kernel is just a program apps talk to, generally through /dev or libc, to get things done. One needs to be in memory. You certainly couldn’t have two kernels in memory at the same time (well, monolithic ones at least…), so yeah, the chroot uses the system kernel and thats the only way that can work.

As for digitaller’s problem, I’m not sure what’s happened but I’d try to find a copy of devices.tar.gz either on your system or the net and place it where requested I guess.

hakujin Says:

January 15th, 2008

How about when you need to do dynamically load a kernel module? Like say you are in your chroot environment and you want to start you wifi whose kernel is not built in. Do you have to chroot back to the boot environment and then chroot back in to the alternate environment? Cuz when you modprobe it looks for modules in a certain directory and chrooting effectively puts your / to an entirely different effective filesystem right?

Dan Ballard Says:

January 15th, 2008

you can’t load a kernel module from with in a chroot. If you really need the module copy it to the real kernel’s module directory and load it from there. But it has to be a module for that kernel which you’re unlikely to find else where.

patrick deschastres Says:

May 18th, 2008

All is working fine, even WiFi (but I had to give an ESSID, “any” does not allow you to see all WiFi hostspots around. Seems normal). But I could not chroot. When I do:

…
mount -o bind /dev dev
chroot .

I get: chroot: cannot execute /bin/sh: no such file or directory Do you have any idea on what was wrong ? Thanks. patrick

Dan Ballard Says:

May 18th, 2008

Could be a number of things I guess. I mean the obvious is you are in the wrong directory or you didn’t get everything installed properly. Check that there is a bin/sh releative to you. Might try

chroot . /bin/bash

to specify another shell. Also possible, are you using a FAT filesystem on the SD card. It shouldn’t make a difference but maybe that lack of attribute bits means that bin/sh can’t be set as exectureable?

patrick deschastres Says:

May 21st, 2008

Thank you Dan. I formated the SD card yesterday with an ext2 filesystem and now it works. You were right about attribute bits. 4 packages were not installed from debian repository because of an error. I’ll retry tonight.

Mike Says:

July 17th, 2008

Dan,

Thanks so much for this tutorial. I have familiar working find (minus wireless) and am enjoying seeing linux on my 4700 instead of the memory-leaking OS that came on it. (I know you said shut this program down, but I’ll just minimize it instead ;v)

I did have a problem with when I fired up debootstrap. I get the following (excluding a bunch of download/extraction messages):

…
I: Extracting sysvinit-utils…
I: Extracting tar…
I: Extracting tzdata…
I: Extracting util-linux…
I: Extracting zlib1g…
E: no /usr/lib/debootstrap/devices.tar.gz. cannot create devices

I searched the device, card, and files I downloaded from your FTP site, but I don’t see the missing devices.tar.gz. Any ideas how to find/create this file?

Thanks, Mike

P.S. I’m also trying to get the wireless going in the few spare cycles I have. I’ll post how I got it to work if/when I do.

Dan Ballard Says:

July 17th, 2008

@Mike: Yeah, if you download a copy of debootstrap from debian it should be in the tar ball. If you installed it somewhere, it should probably be kicking around. Run a locate for it. Good luck.

patrick deschastres Says:

July 21st, 2008

For those who encounter the “/usr/lib/debootstrap/devices.tar.gz. cannot create devices” problem: look at this page http://mail.opensolaris.org/pipermail/brandz-discuss/2006-January/001606.html in § “Issue with device archive”. I tried it and it works well. patrick

Dan Ballard Says:

July 21st, 2008

Ha nice. Thanks for passing it along!

David Says:

November 5th, 2008

Hi Dan. What a wonderful guide. I have no linux experience but I know its power and potential. While browsing the web to learn a bit about the os, I stumbled on linux for handhelds. When I read here that I could turn a cheap obsolete PDA (bad, old wince to blame) into a powerful linux micropc, I decided to grab one and start learning the os. Now I´m beginning the challenge to actually get linux on the thing with the debian chroot, so I have access to almost all desktop software. I will be trying to follow your steps tomorrow. But one question before I start please. Is there any new version or better distro since you wrote this guide or is the familiar/debian chroot still the way to go?

Best regards,

David

Dan Ballard Says:

November 7th, 2008

Ha, sorry, haven’t played around with it too much lately. But you might want to look into Angstrom, I think I played around with it a bit, and it’s where all the dev is going on these days. http://www.angstrom-distribution.org/