Linux and the PalmPilot

Building the pilot-link software is quite simple. After you've unpacked the package (tar xvzf pilot-link.tar.gz), decide where you want to install it. I installed it under /usr/local/pilot/. You must tell the configure script where the installation directory is; it assumes /usr/local. Should you also decide to install the man pages somewhere unusual, you should tell the configure script that as well.

To build the package, run the configure script, followed by make and make install. Here is the configure command I used:

 configure --prefix=/usr/local/pilot\
     --mandir=/usr/local/man\
     --with-java=/usr/lib/java

The Java option was necessary to get a clean run in the configure step. It doesn't actually cause the Java extensions to be built—that has to be done manually, although these extensions are not required. You can use pilot-xfer and the other tools without the Java extensions.

After the make install was complete, I added /usr/local/pilot/bin to my path as:

PATH=$PATH:/usr/lib/pilot/bin
export PATH

At this point the pilot-link tools are ready for use with your Pilot. There are man pages for only a few of the programs in pilot-link, but most provide help if invoked without options or command-line arguments.

The Makedoc utility is a single C++ file. You can compile it using the following command line:

g++ -DUNIX makedoc7.cpp -o makedoc

The HOWTO doesn't spell this out, but it was rather easy to figure out after a short inspection of the code. Once you've built MakeDoc you should copy it into the same directory where you installed the pilot-link tools.

Once built, you need to test that the tools are working properly. The first thing to do is connect your PalmPilot HotSync cradle to your Linux box. To do this, connect the serial cable on the cradle to one of the serial ports on your computer. The cable on the cradle has a female connector, so you may need a gender changer to make the connection. I use an A/B switch box to connect both my external modem and Pilot to the same serial port (/dev/cua1) while using the other serial port for my mouse. This seems to work just fine, but be careful. If you switch between the two devices while one is running it can cause you to either have to manually reset the modem (turn it off and then on again) or reload your Pilot. So, be careful not to change the switch box setting while using either the modem or the Pilot.

Another thing you might want to do before trying the software is to make a symbolic link from the serial port to which the Pilot is connected to /dev/pilot. Most, if not all, of the tools in the pilot-link software use /dev/pilot as the default device, although they all take the port device as a command-line argument. Having the /dev/pilot symbolic link makes life a little easier.

You should also make sure that the serial device has the correct read/write permissions for whatever user ID you use while reading and writing to the Pilot. On my system /dev/cua1 has 666 permissions so that an ordinary user can access it. I don't know if this is a security violation or not, but it's my box—I'm the only user and I'm not too worried about security on it.

Now that the hardware is connected, you should test that the software can communicate with your Pilot. Place the Pilot in the cradle, making certain that it is properly seated. (See the instructions that come with the Pilot.) The first test you should run is:

% pilot-xfer /dev/cua1 -l

where /dev/cua1 is the port the Pilot is connected to. If you aren't familiar with the serial port devices, /dev/cua0 is generally the first serial port and /dev/cua1 is the second. There may be others configured for your system. Once you've typed this command you will be prompted to press the HotSync button on the Pilot's cradle to begin the data transfer process.

The -l option for pilot-xfer will simply list the applications currently installed on the Pilot. If this works, you're in business. If not, check that the cable connectors are properly fastened together. Don't forget to press the HotSync button on the cradle once you've started the pilot-xfer command.

If the communication between pilot-xfer and the Pilot is working, you will get a list of the applications and databases installed on the Pilot. The results of this command vary depending on what else you have installed on the Pilot, but my stock configuration looks like this:

% pilot-xfer /dev/cua1 -l
 Waiting for connection on /dev/pilot (press
     the HotSync button now)...
 Connected
 Reading list of databases...
 'System Preferences'
 'Graffiti ShortCuts'
 'AddressDB'
 'MemoDB'
 'ToDoDB'
 'DatebookDB'
 List done.

Once you get this command working, do a backup of your Pilot data by typing:

pilot-xfer /dev/pilot -b `date +%Y%m%d`

I do this in my ~/lib/pilot directory. The “date” is actually the name of the directory where I want my backups placed. I use the format YYYYMMDD so that the directories sort correctly when listed using the ls command.

Now verify the programs and databases you just backed up:

pilot-xfer /dev/pilot -u `date +%Y%m%d`

The pilot-xfer program should recognize that the data has not changed and indicate that no changes are being made. That's what you want.