Making Familiar 0.8.4 Linux useful on the IPaq hx4700
Debian, GP2X, Guide, IPaq, Linux, Tech
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.
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.
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 ftp.mindstab.net/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 instal-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 www.mindstab.net/wordpress/archives/174#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 ftp.mindstab.net/ipaq-hx4700/net.sh.
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 ftp.mindstab.net/ipaq-hx4700/ipkg:
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 ftp.mindstab.net/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
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!
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.