Text size:

JPilot and the Palm Z22

Syncing your Linux-based machine with the Palm Handheld

Sticking to the philosophy of the Unix world, where an application is designed to do one thing, and do it as well as possible, this howto is also designed to do one thing, and only one: explain how to connect a Palm Z22 handheld computer to your desktop or laptop computer running GNU/Linux. If you want explanations on how to use your Palm Z22 then you've come to the wrong page. The user documentation that's available on the palm.com site is very well written. Similarly, this document makes no attempt to explain how to use pilot-link or jpilot − that's the job of their respective sites. Finally, instructions on how to recompile a new Linux kernel are given on numerous howto pages out there on the 'Net, such as this one. GIYF (Google Is Your Friend).

What you will find here are the pitfalls that I fell into and that I'm publishing so that others can avoid falling into them.

The content of this page should also apply to other PalmOS-based handhelds with little or no modification.

Copyright © 2006-2024 Howard Pritchett.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is available from the Free Software Foundation.

I recently purchased one of these gadgets in order to lend a hand managing my customer base, which seems to be growing quite rapidly of late. Better late than never − I set up shop 4 years ago, so it's about time :o)

The big idea was to replace the big, heavy, clumsy, slow Apple Newton I already had with something smaller, lighter, easier to use and faster. Okay, so just about any Fisher-Price toy would fit that bill, so let's say that I wanted something with which I could do something serious. Among other criteria was the ability to sync the PDA with my computer that runs Slackware Linux. All the usual precautions were taken before buying the thing and then finding out that I wouldn't be able to use it with the PC: I downloaded the user manual from the palm.com site and made sure I'd be able to do what I wanted to do with it, and I sat googling for an hour or two and came to the conclusion that pilot-link as the back-end and jpilot as the gooey front-end would do the trick.

So, I ordered one. Soon after it arrived, it emerged that getting it to work with Linux wasn't going to be as easy as the howtos made it look.

In order to be able to use the pilot-link/jpilot combo, support for the hardware will need to be added to the kernel. This device connects to your machine via a USB port, so it's logical that the two kernel elements you'll need should be in there. This is valid both for 2.4.x and 2.6.x kernels. However, before going and compiling a kernel for nothing, you might want to check that the required modules aren't already provided. Assuming your system supports hotplug (which is a pretty safe assumption these days), run:
# tail -f /var/log/messages
and keep your eye on the console while plugging the cable into the Z22. If you see something like this then you're already set:
Mar 30 19:00:30 dragonfly kernel: usb 3-2: new full speed USB device using uhci_hcd and address 11
Mar 30 19:00:30 dragonfly kernel: usb 3-2: configuration #1 chosen from 1 choice
Mar 30 19:00:30 dragonfly kernel: visor 3-2:1.0: Handspring Visor / Palm OS converter detected
Mar 30 19:00:30 dragonfly kernel: usb 3-2: Handspring Visor / Palm OS converter now attached to ttyUSB0
Mar 30 19:00:30 dragonfly kernel: usb 3-2: Handspring Visor / Palm OS converter now attached to ttyUSB1
If you don't get that, or at least if you don't get the last two lines, then you're going to have to add a few things to your kernel. I suggest you build them as modules because you won't have to reboot in order to start using them.

I think that in this day and age it's safe to assume that USB support and hotplug are set up for your machine. The two modules you will need to make sure are present are the USB to serial converter and the visor/PalmOS driver. Assuming you use the "make menuconfig" approach to configuring your Linux kernel, for a 2.4.x kernel you'll need to go into the "USB Support" page, and for a 2.6.x kernel you'll need to go into "Device Drivers" / "USB Support". From there you'll have to enter the "USB Serial Converter support" page and select "USB Serial Converter support" as a module. This will have the effect of displaying the list of compatible device drivers, in which you'll find "USB Handspring Visor / Palm m50x / Sony Clie Driver", also to be selected as a module.

Rebuild the kernel and your modules, and then reinstall the modules with:
# make bzImage modules modules_install
This will have the crucial effect of updating your module dependencies, thus now enabling hotplug to load the correct modules and set up the hardware as soon as you plug the Z22 into the computer. Oh, and don't forget to install the new kernel and System.map (not forgetting to run lilo if that's the bootloader you use) so that everything is fully in sync next time you boot the machine.

So, plug in the Z22 while following your logs as above and you should see things happening as normal. If not, this should sort things out:
# modprobe usbserial
# modprobe visor
From the point of view of the kernel, everything should be set up now. Time to install the userland software.

The work of transferring data to and from the Z22 is done by pilot-link, so that's what we're going to install first. As of writing this page, the latest version available is 0.12.0-pre4. Grab it, build it and install it as follows. Note that the steps described here assume that you have libiconv and libpng installed in /usr (you can adjust the paths as necessary) and that you also have libusb installed (if you're using a USB scanner with a 2.6.x kernel then don't worry, you do have libusb installed). Also, libiconv is very useful for charset conversion. I recommend installing it now if you haven't already:
$ wget http://katerina.frederic.k12.wi.us/mirror/pilot-link/pilot-link-0.12.0-pre4.tar.bz2
$ tar -xjf pilot-link-0.12.0-pre4.tar.bz2
$ cd pilot-link-0.12.0-pre4
$ LDFLAGS="-lz -lm" ./configure --prefix=/usr/local --enable-conduits --enable-threads \
--enable-libusb --with-libpng=/usr --with-libiconv=/usr --with-perl=`which perl`
$ make
$ su -c "make install"
(supply your root password at the prompt)
$ su -c "/sbin/ldconfig"
(supply your root password again)
NB:

The URL above was leeched from the pilot-link.org website. Check there to see if there's a more recent version before simply downloading that one.

The LDFLAGS="-lz -lm" was necessary on my system running Slackware 10.2. Without it, PNG support would fail because of the autoconf script failing to link a test program with libz, and the compile cycle would fail due to the use of some functions in the libm math libraries.

Those are backticks around which perl at the end of the same command line. If you're not sure of yourself, bash allows an alternative way of achieving the same thing: instead of `which perl`, you can use $(which perl).

Optionally, if you like living dangerously, you can go through the whole cycle above as root, in which case the last two lines will be simply make install and ldconfig.

With pilot-link installed, the next step is to install the GUI software that will use it as a back-end, JPilot. The site doesn't allow users to fetch the tarball directly with a tool such as wget so you'll have to download it using your usual browser and copy it to the directory in which you build your software from source.
$ tar -xzf jpilot-0.99.8.tar.gz
$ cd jpilot-0.99.8
There are a couple of patches to apply to version 0.99.8 before building the software:
$ wget -O - http://www.jpilot.org/patch.jpilot-sync | patch
$ wget -O - http://www.jpilot.org/patch.0.99.8-memory | patch
Now we build JPilot proper, still assuming that you have libiconv in /usr:
$ ./configure --prefix=/usr/local --enable-gtk2 --enable-stock-buttons \
--with-libiconv-prefix=/usr --with-pilot-prefix=/usr/local
$ make
$ sudo -c "make install"
$ sudo -c "/sbin/ldconfig"
That's it! jpilot is installed, so fire it up:

The first thing to do is to tell jpilot where your Z22 is. Remember the logs above telling me that the Z22 was connected to ttyUSB0 and ttyUSB1? You want to use the second tty given, /dev/ttyUSB1. Obviously, if you already have hardware using usbserial then you might well end up with the Z22 being connected to other ttys, like ttyUSB2 and ttyUSB3 for example. Whichever ttys are used, jpilot needs to use the second one. So, go to the File menu, Preferences, hit the "Settings" tab and enter the device node of the tty to which your Z22 is attached (highlighted here):

Obviously, the ttys need to exist… If you're using udev then the correct ttys should appear in /dev when you plug the Z22 in. If you're not using udev then you'll need to make sure the device nodes are there and create them as necessary:
# for i in 0 1 2 3 4 5 6 7; do \
mknod /dev/ttyUSB$i c 188 $i; chown root:uucp /dev/ttyUSB$i; chmod 660 /dev/ttyUSB$i; \
done
You must also have write access to the device node of your Z22 which means that you must be a member of the uucp group of users. Don't forget to log out and back in again if you just made the change to your group membership.

If if you've already synced your Z22 with a computer then you can skip this part. If not, or if you just performed a hard reset on it, (or if you're just plain curious…) then read on. You must install a user name to the Z22 before being able to sync it to your computer with jpilot. Go to the File menu and select "Install User":

Either accept the defaults or fill in your own information, but before clicking on the "Install User" button, let me introduce you to the first pitfall I came across. All the available documentation says that for versions of pilot-link greater than or equal to 0.11.8 (I think, but something prior to what we're using here anyway), you should launch the command on the computer and then, once the computer is waiting for the Z22 to react, hit the Hot Sync button on the handheld.

It certainly isn't the case here. I have to tap the "Hot Sync" icon first and then do whatever needs doing on the PC.

So, tap on your handheld's "Hot Sync" icon first, and then a couple of seconds later, click on the "Install User" button. The handheld will chirp a couple of times as data is being exchanged between it and jpilot.

If this is your first Hot Sync then I recommend you do a full backup of the handheld at the same time. Start by tapping the Hot Sync icon on the handheld, wait a second or two, then click on the "Sync then do a backup" icon in jpilot. The operation may take a little time since jpilot will, in fact, be sucking the entire contents of your handheld's memory and backing it up to the computer.

Subsequent backups of all the data you've input into the Z22 can be achieved by using the Hot Sync function. Simply tap on the handheld's Hot Sync icon, then click on the same icon in jpilot, and any changes made to data either in the handheld or in jpilot will be synchronised across the two.

It is, however, wise to do a full backup periodically. Although it hasn't happened to me yet, I assume that the reset button on the back of the Z22 is to reset it after a crash. A soft reset will retain all the information held within the Z22, but a hard reset will remove everything. If you do have to do a hard reset at some point, at least you have the ability to restore the handheld to a known state with all of your information intact if you've been making regular backups.

There are a few differences between how jpilot handles data and how the Z22 handles the same data. I assume that these are extensions to PalmOS that came about since either pilot-link or jpilot was designed. Note that this is in no way trashing the efforts of the software's respective authors, I'm merely pointing out differences you'll come across between jpilot's PalmOS-like interface and the original Z22 interface. Note also that when I place the "blame" on JPilot below, it's a shorthand way of saying "JPilot doesn't show this. I do not know whether it's because pilot-link doesn't support it and therefore JPilot has nothing to show, or because pilot-link is fetching the information and JPilot doesn't know how to deal with it."

An appointment in the calendar can be assigned to one in a (configurable and color-coded) list of categories on the Z22, not in jpilot.

The Z22 allows you to input the birthday of a contact in the contact list and (optionally) have a reminder displayed either on the contact's birthday or 'n' days before. Jpilot doesn't.

When entering a contact's postal address, you can specify whether it's a work address, home address or 'O' (other?) address by tapping on the field name and selecting an option in the drop-down list. Jpilot would only appear to allow a work address − Addr(W).

Elements in the ToDo list that have a due date can cause a reminder alarm to ring at a configurable time 'n' days before the due date and can also be repeated automatically the same way as appointments in the calendar. Jpilot doesn't support either.

When deleting certain items from the Z22's memory you are asked if you want those items to be archived on the computer. Regardless of whether or not you wanted the items to be archived, they are deleted from jpilot next time you hot sync.

NAVIGATION:
>> /

Last update: 24-OCT-2006
This page has been served 43660 times since 30-MAR-2006