Linux on Zipit

Update: Please see my newer Debian on Zipit article for a better installation process.

This is an article about running Linux on the Zipit Z2 instant messaging device. Or rather, it is about running a general-purpose Linux distro, since the device out-of-the-box runs a Linux kernel with proprietary userland software.

Why is this interesting? With a list price of US$50 (and sale prices approaching half that), this device can be an SSH client, DOSbox, NES emulator, video streamer, music player and/or IRC client.

Since the state of documentation seems to be lagging behind the state of development on this device, I’m using this post as an information dump about all the things I found a hassle to figure out (and hope to save others that same hassle).

I expect frequent changes to this post as I learn more about the device in question. Because of this, I’m suspending my usual practice of clearly marking all edits and updates.

Initial Install

Hunter Davis has some excellent installation instructions, as well as a demonstration video. I did not have any trouble to speak of following the directions, but some possible gotchas:

• On my machine (an Acer Aspire One with built-in card reader), the SD card whole-disk block device is /dev/mmc0blk. The gparted partition editor tool mentioned in the installation instructions does not locate this device when run without arguments. Workaround: Specify the block device file on the gparted command line.
• Make sure you run “gparted /dev/mmc0blk” not “gparted /dev/mmc0blkp1“. The second one is a partition within the device. gparted will happily run and try to create partitions within a partition; this is not what you want. (A silly mistake, but one I made.)
• After you run the autoloader, it is really very important that you make a copy of the original kernel and wireless chipset firmware somewhere safe, before you re-partition your SD card. I came within a hair of screwing this up, and on a scale from good to bad that would have been bad.

Tips and Tricks

• On the left-hand edge of the device, near the front, is a tiny hole. This is not a microphone; a reset toggle lives inside there. If you get the device wedged, gently poke an unfolded paper clip inside to do a hard reset. No more having to take the battery out.
• The default volume setting is quite low, and this can’t be fixed through the aumix application or the built-in volume controls in mplayer. Run alsamixer and use the right-arrow keys to page right until you find the speaker settings. (The speaker is lousy and distorts horribly if you drive it more than a moderate amount. However, this’ll at least make it audible.)

WiFi Setup

The wireless network chipset in the Zipit Z2 is a Marvell 88W8686 802.11b/g, apparently the same as found in the Apple iPhone. There isn’t any open (or even redistributable) firmware for it, and it lacks a promiscuous mode (so applications like kismet won’t work). However, there are working drivers and wpa_supplicant integration. I have personally gotten it working on two different WPA2 networks (one with a Linksys WRT54GL AP running Tomato, and one with a Motorola WS5100 wireless switch).

The first hurdle is getting the firmware files. As part of the install process, the autoloader should have copied the original firmware files to your SD card. Copy these originals (named gspi8686.bin and helper_gspi.bin) over the stub files found in your root filesystem image, in the /lib/firmware/libertas/ directory. Note that you’ll have to rename helper_gspi.bin to gspi8686_hlp.bin; gspi8686.bin has the same name in both places.

Next is getting the /etc/wpa_supplicant.conf file set up correctly. For a WPA or WPA2 network using PSK, you’ll need to put something in there like:

network={
    ssid="YourSSIDGoesHere"
    scan_ssid=1
    key_mgmt=WPA-PSK
    psk="Your very secret passphrase goes here."
}

If you crave a more complete example, you may download my complete config file (944 bytes text).

Also note that the original wpa_supplicant.conf has an “eapol_version=” line near the top. I had to comment this out to get it to work.

Once that’s done, run the supplicant:
wpa_supplicant -Dwext -ieth0 -c/etc/wpa_supplicant.conf

You should see a series of diagnostic messages, including some saying it has associated and that key negotiation has been completed. If so, suspend the supplicant using ^Z, then background it with bg. (Once you get it working reliably, you can avoid the suspend/background hassle with the -B option to launch it as a dæmon.)

If you aren’t sure if the output you’re seeing is normal, download example output from a working session (717 bytes text).

Finally (assuming you are on a network with DHCP support) run the DHCP client: udhcpc

If you’re not using DHCP (or if your lease does not include a default route and/or working DNS settings), then you have to manually configure the missing bits.

Keyboard

The keyboard map is a little funky. Here is how to type some of the “missing” symbols:

• escape is the smiley-face key just below and to the right of the power switch
• control is the key just below A, marked with a white ellipsis and a red [X]
• page-up and page-down are “prev” and “next”, respectively
• tab is the big rectangular Zipit logo key, at the top center of the keyboard
• ( ) (left and right parens) are alt-J and alt-K (even though the red silk-screened legend on the keycaps looks more like left and right square brackets)
• ^ (caret) is shift-alt-Y; you must hold down both shift and alt, then press and release the Y/6 key
• ~ (tilde) is shift-alt-Q
• { } (left and right curly-brace) are shift-alt-J and shift-alt-K respectively (mnemonic: the shifted versions of the corresponding parens)
• [ ] (left and right square bracket) are shift-alt-comma and shift-alt-period (mnemonic: shifted versions of the corresponding angle brackets)
• | (pipe) is alt-escape (or alt-smileyface, if you prefer)
• ` (backtick) is shift-escape
• \ (backslash) is alt-shift-escape

Note that modifier keys (alt, shift and control) are not “sticky”; you have to hold them down while you press some other key. This can be troublesome if you are used to a device like the Nokia n810 where you can press a modifier, release it, then press another key.

Under fluxbox (the window manager you get by default when you run “startx”), there are some useful additional keymappings:

• start new terminal is alt-T
• maximize window is alt-M
• minimize window is alt-I
• fullscreen is alt-F
• close window is alt-C

Also note that if you start X, then exit back to the text console, the mouse emulator will remain running. If you wish to use the directional pad as arrow keys again, you must kill it.

Video Playback

Once again, thanks to Hunter Davis (and specifically his post about using an external transcoder to stream Hulu to the Zipit).

To transcode a random video file to a format suitable for playback on the Zipit:

mencoder -oac mp3lame -ovc lavc -lavcopts vcodec=mpeg2video:vhq:autoaspect -vf scale=-11:240 original.avi -o output.avi

The original file can be any container/codec combination that mencoder understands (i.e., most of them). You want the pixel-size of the output to be as large as possible that’ll still fit in 320×240 and maintain the original aspect ratio. My example is right if the video is too tall. If it is too wide, then use “-vf scale=320:-11”. (The -11 is the magic value meaning “pick the multiple of 16 that comes closest to keeping the correct aspect.) In case it isn’t obvious: You almost certainly want to do the transcoding step on a real computer, then just move the output file to the Zipit.

To play back such a file on the Zipit:

mplayer -vo fbdev -vf rotate=2 -fs output.avi

Links

• Hunter Davis: Zipit Hacking — a mother lode of useful information, links and potential applications
• Aliosa27 — root filesystem image and mouse emulation for X11
• ZipitForce — vendor-owned “collaboration area” with some useful links, but also some content behind a registration wall (where said registration requires acceptance of an onerous non-negotiated agreement the other party can change at will)
• OpenZipit — specs, development toolchain and lots of interesting links
• Zipit2 System — Sourceforge site for Zipit v2 development
• eLinux.org Zipit category — some outdated and/or Z1-specific stuff, but quite useful anyway

[Edited 2010-02-10 by dhenke to remove Amazon links. See explanatory post.]

---

Full disclosure: My employer sells Motorola products, including the WS5100. This post, like all contents of this site, is my own personal, unsolicited, uncompensated opinion. It is not work for hire and may not reflect the views of my employer.