PocketWorkstation runs in a chroot environment on a storage card, using the vendor's preinstalled native Linux system for most hardware access. GUI is based on Xf4vnc and the fbvnc framebuffer viewer. (Check out the PocketWorkstationXQT variant for a native X11 GUI.)

See also DebianOnHandhelds for other related projects.

Runs on Sharp Zaurus handhelds: SL-5x00, SL-6000, and the clamshell models SL-C7x0, SL-C8x0.

http://pocketworkstation.org/ http://pocketworkstation.org/fbvnc.html (Having DNS issues... Try http://pocketworkstation.infinology.net until these are resolved. New stable/sarge -v1.0 images being uploaded now.)

For general Debian issues on handheld computers, please use the debian-handheld mailing list. But please make sure to check out the "known bugs" section below first.

For discussions, please use the (low volume) http://lists.debian.org/debian-handheld/ mailing list.

This page is intended to be a community-editable forum to collect documentation, install instructions, tips and tricks.


NOTE: I haven't had time recently to update the installation software or instructions. Please take a look at these user-contributed instructions:

Get the most current zaurus-debian-*.tgz archive from the download section. The '-base-' package contains a minimal environment and needs 95 MB when unpacked, the '-big-' package contains additional software and needs 195 MB. You only need one of them, the contents of the 'base' package are completely contained in the 'big' one. See below for a full content listing. Alternatively, you can use chroot-debian-bootstrap to create a customized package yourself from the Debian FTP servers, but this is a lot more complicated and time-consuming.

If you can plug the target SD/MMC/CF card into a Linux computer (i.e. using a SD-to-PCMCIA adapter on a notebook, or a USB card writer), it's fastest to unpack it there. Otherwise transfer the archive to the Zaurus.

Make sure that the card is mounted using ext2 on the Zaurus (automatic mounting sometimes gets this wrong - edit /etc/fstab and use 'ext2' instead of 'auto' for the filesystem type).

Important: ensure that the filesystem is mounted with device files enabled - current ?OpenZaurus versions mount with the 'nodev' option which completely breaks the chroot environment. See 'known bugs' below.

Unpack the archive:

  cd /mnt/card    # SD/MMC card, Sharp or OpenZaurus ROM
  cd /home        # SD/MMC card, Crow ROM
  cd /mnt/cf      # CompactFlash or Microdrive
  # download and decompress GNU tar, busybox tar is broken in some
  # versions and messes up the archive contents
  wget http://pocketworkstation.org/files/gnu-tar.gz
  gunzip gnu-tar.gz
  # create the destination directory
  mkdir debroot
  # Unpack if you haven't done so already.
  # Don't forget the 'p' switch, or you'll get wrong permissions.
  ./gnu-tar -C debroot -xvzpf zaurus-debian-*.tgz
  # Configure and integrate into native system

Please read the fbvnc documentation for more information about the VNC-based GUI.

You can edit the file /etc/debroot.conf to control the integration into the native system and startup options. If you don't select automatic startup, just run the following commands on the text console to launch it manually:

  Vncserver   # it backgrounds, hit ENTER to get the prompt back

To get out of the Debian environment, use

  <Fn>-<Shift>-<Q> on the virtual keyboard, 


  ["Action"]-<Shift>-<Q> on the real keyboard. 

This quits fbvnc, which will return you to the command line, but Xvnc will keep running in the background. Kill the 'Xvnc' process to shut down all X11 applications.

FAQ / How-To

Here is the PockeWorkstationFaqHowTo page where you might find answers to your question and post your own how-did-I-do-it solutions.

Tips and Tricks

Platform specific notes and gotchas

Sharp SL-5000D, SL-5500

These should work without special tweaking.

Sharp SL-5600, SL-6000

See the SL-C7x0 section, most of this applies for these as well.

Sharp SL-C7x0, SL-C8x0

The SL-C7x0/8x0 support is still somewhat rough, and needs some manual tweaking:

Compaq/HP iPAQ

Some brief notes on getting things working on an ?iPAQ from Alessandro Miele, more details needed...

Run the following commands to help it find the touch screen:

     ln -s /dev/touchscreen/0 /dev/h3600_ts
     ln -s /dev/touchscreen/0raw /dev/h3600_tsraw

Edit the Fbvnc script:

      change   fbvnc  to  fbvnc -hw ipaq  near the end of the script
      change   fbvnc "$@"       to  fbvnc -hw ipaq "$@"       near the end of the script

To suspend, run "cru apm --suspend", to toggle the light run "cru bl 1 1 0" or "cru bl 1 0 0" - these need to go into the "zsuspend" and "bl" shell scripts. The bl command is not included in the familiar 0.8 distro, but is present in the package http://familiar.handhelds.org/releases/v0.7/base/armv4l/h3600-utils_1.2.1_arm.ipk

Known Bugs

Current OZ versions mount the SD/MMC and CF cards in a secure mode with device files disabled, which unfortunately completely breaks the chroot environment. A symptom is that you get weird messages about devices such as /dev/null not working, and you may just get a blank X11 screen without any user interface, or terminal windows which open and close again immediately.

As a workaround, run the following from the command line:

        mount /mnt/card -o remount,dev,suid,exec

NOTE: This doesn't seem to valid for oz 3.5.2 pocket workstation worked out of the box for it.

On some machines, Opie and/or Qtopia crash when you launch it after previously running the Debian environment. This appears to be a power management conflict - try running /etc/rc.d/init.d/zdebian stop on the text console before launching Opie/Qtopia, and let me know if that makes a difference. An alternative on newer ?ROMs seems to be using the standard apm tool and not using zapmd at all.

On my Zaurus SL-5000D, operations that write lots of data to the MMC card often crash the Zaurus - it's still pingable, but the filesystem is dead. A typical symptom is "apt-get install" getting stuck at the "Getting package information..." stage. I think this is bug in the MMC/SD driver, everything works fine on a microdrive.

Mounting the SD/MMC card in synchronous write mode makes things very slow, but helps prevent these crashes:

        mount /dev/mmcda1 -o remount,sync,noatime

Don Leuenberger reported that running a background sync loop during the installation also helps prevent crashes:

        while true; do sync; sleep 1; done &

Since writes to flash memory are very slow, you'll need to be patient for many operations that would finish quickly on regular disk drives. apt and dpkg should be fixed so that they don't constantly write multiple identical copies of the package information files in various locations.

?OpenZaurus has a fairly weird startup sequence - Opie starts in the foreground, and the other startup scripts don't run until after Opie is shut down.

On the Compaq ?iPAQ, Power and light management don't work out of the box, I haven't had the time to make the installer handle it yet. Send me mail if you care about this, and I'll fix it.

Oz 3.5.2 and pocket workstation seem to work well. To play mp3's install xmms and xmms-mad.

Upgrading to Etch

Klaus Weidner, the person responsible for beginning this project has recommended Not upgrading to Debian Etch (the new stable branch for 2007). On my system, a SL-C860, I have successfully upgraded to Etch and written to Klaus about my experience. I only seemed to have 2 serious problems with my upgrade and Klaus said he will try to correct these issues in versions after the v1.0 release.

The first problem was Xvnc(xf4vnc) not being able to find fonts, and the second was Xvnc not being able to find the rgb database.

> Fatal server error:
> could not open default font 'fixed'

> Couldn't open RGB_DB

Although figuring out the solution took me about two weeks, these are both easily solved by editing the file /usr/local/bin/zvncserver (or /INSTALL.d/debroot/usr/local/bin/zvncserver). In that file, you should see it where it runs the program Xvnc. It will have some options after the program that look something like this:

# Run the VNC server in the background
Xvnc -geometry $GEOMETRY \
        -depth 16 -pixelformat RGB565 \
        $DISPLAY &

To run Etch, these program options need to be added to the Xvnc program:

-fp /usr/share/fonts/X11/misc
-co /usr/share/X11/rgb          # (*NOT* /usr/share/X11/rgb.txt)

I edited this file from a terminal in the Qtopia environment AFTER I had already upgraded. If you know of a better way, please post it here. Anyway, here is an Example of how the options should be inserted:

# Run the VNC server in the background
Xvnc -geometry $GEOMETRY \
        -fp /usr/share/fonts/X11/misc \
        -co /usr/share/X11/rgb \ # Leave off .txt
        -depth 16 -pixelformat RGB565 \
        $DISPLAY &

I now run a full Etch system (except I use the default Sharp Linux kernel) from my SD card. Be sure to realize that many programs are larger in Etch, so you may have to be careful about which programs you upgrade. I'm currently still using firefox 1.X, because 2.0 is really big.

Also, if you are tight on space, upgrade a few packages, use "apt-get clean; debshrink -r", then upgrade a few more packages, and repeat. If you try to use "apt-get upgrade", you will probably run out of space. Use "cru df -h /mnt/card" to check your diskspace.

I have successfully upgraded to Etch a PocketWorkstation/XQt installation on SL-C1000. You can find the instruction in XQt PocketWorkstationXQT section.