Previous Next Contents

3. Sharing Pilot Data with your Linux System

3.1 The pilot-link software

The pilot-link suite of software tools allows you to download programs onto your Pilot, and transfer data for the Pilot's various built-in programs between the linux system and the Pilot. While these programs are not quite as seamless as the desktop software that comes with the Pilot, they do allow you to copy your data in both directions. In general, each separate program in the pilot-link suite manages one type of data. The PilotManager software is built on top of pilot-link and provides a more integrated solution, which typically includes full synchronization of the various types of data.

Installing the pilot-link software

The prepackaged versions will inevitably lag slightly behind the master distribution, but will be easier to install and not require configuration. The master distribution might be a better choice in those rare occasions when you have been waiting for a particular feature or bug fix.

You can get the Debian Linux port of pilot-link version 0.7.2 from ftp://ftp.debian.org/pub/debian/hamm/hamm/binary-i386/otherosfs/pilot-link_0.7.2-1.deb. Install this file in the normal manner and skip to Using the pilot-link software.

You can get the RedHat Linux port of pilot-link version 0.7.6 from ftp://ftp.redhat.com/pub/contrib/i386/pilot-link-0.7.6-2.i386.rpm. Install this file in the normal manner and skip to Using the pilot-link software.

For other versions of linux or unix, download the version 0.8.2 of pilot-link from ftp://ryeham.ee.ryerson.ca/pub/PalmOS/pilot-link.0.8.2.tar.gz. The version number is likely to change, but new versions should end up in the same location with a similar name.

Once you have the software distribution, unpack it with:

tar -xvzf pilot-link.0.8.2.tar.gz
This will create a directory (pilot-link.0.8.2) containing the source.

Run ./configure. This will search through your system for information needed to compile the software. configure will set things up to be installed in /usr/local by default. If you want to change it, run ./configure --prefix=DIR, where DIR is replaced with the name of the directory to which the software will be installed.

Run make. This will compile the software. The software will not be installed until later, so that you have a chance to try it out first. (If you are replacing an older version with a newer release, you may wish to check and make sure that no functionality that you need has been broken. Generally, this is not a problem.)

As the root user, run make install. This will copy the software into directories under /usr/local (or wherever you specified with the --prefix option). If you can not log in as root, you can install the software to some directory where you have write access.

Don't forget to add any new directories of executables to your search path.

Using the pilot-link software

Most of the programs in the pilot-link suite are conduits, that is they transfer data into or out of your Pilot.

Each time you use of one of these programs, press the HotSync button on your Pilot's cradle. This will initiate the Pilot side of the data transfer. Note that not all of these programs prompt you to press the `HotSync' button, so you may have to remember to do it yourself.

For more details, and other options to these programs, view the corresponding manual page. For the pilot-xfer program, for example, type man pilot-xfer at your unix shell prompt.

If you are going to use PilotManager, you may not need to bother learning to use these (more primitive) tools.

pilot-xfer

Possibly the most useful program in the pilot-link suite, pilot-xfer allows you to install programs on your Pilot, make a backup, and restore that backup.

To install a program:

pilot-xfer /dev/pilot -i program.prc

To backup your Pilot:

pilot-xfer /dev/pilot -b backup-directory
This will copy all of the databases on your Pilot, (including programs?) to a directory called ``backup-directory'', creating it if it does not already exist.

To restore data to Pilot:

pilot-xfer /dev/pilot -r backup-directory
Generally, you will only need to do this if your Pilot loses power or if you have to do a hard reset.

To list the programs on your Pilot:

pilot-xfer /dev/pilot -l

install-memo

Install a linux file onto the Pilot as a memo.

To install a memo into your (already existing) project category:

install-memo /dev/pilot -c project project.memo

The name of the file will be inserted into the memo as its first line and will appear in the directory of memos on your Pilot.

memos

This program grabs each memo from the Pilot and prints it out in standard mailbox format.

To view your memos:

memos /dev/pilot 

pilot-addresses

pilot-addresses Transfer the address database to or from the Pilot.

To write your address data to a linux file from your Pilot:

pilot-addresses /dev/pilot -w storage.file

To read your address data from a linux file onto your Pilot:

pilot-addresses /dev/pilot -r storage.file

3.2 MakeDoc

One short-coming of the Pilot's built-in memo program is that it does not deal well with large documents. To compensate for this, Rick Bram wrote Doc, a document reader for the Pilot. (See http://www.concentric.net/~rbram/doc.shtml). Documents can be converted to the Doc format with MakeDoc, by Pat Beirne.

Installing MakeDoc

MakeDoc can be downloaded from http://www.concentric.net/~rbram/makedoc7.cpp. Compile it with your C++ compiler and install the resulting executable as ``makedoc'' in a directory in your search path. There seems to be a small bug in makedoc (version 0.7a) in that it does not output a newline as the last character displayed to the user. This does not seem to affect the resulting document file, but it is annoying.

There is a new version out, but it requires Java. Take a look at Pat Beirne's MakeDoc web page at http://cpu563.adsl.sympatico.ca/MakeDocJ.htm.

Using MakeDoc

Use MakeDoc as follows:

makedoc data.txt data.prc "Data to display with Doc"
This will create a file data.prc, which can be installed on your Pilot with pilot-xfer. The text "Data to display with Doc" will be displayed in the directory of documents that Doc manages.

The syntax for MakeDoc is as follows:

makedoc [-n] [-b] <text-file> <prc-file> <story-name>
or
makedoc -d [-b] <prc-file> <text-file>
<text-file>

The file that you wish to convert.

<prc-file>

The name of the resulting file. (End the name with ``.prc''.)

<story-name>

The name you want displayed in the Doc or Jdoc directory of documents.

There are also options to decode the resulting .prc file and manage various compression options.

3.3 PilotManager

PilotManager is a generalized tool which allows multiple databases to be synchronized in a single HotSync session.

I have not been able to build and install PilotManager in time to write about it for this version of the Pilot-HOWTO.

A few links that might be helpful:

This patch for PilotManager is only intended for use with PilotManager version 1.009 Beta 3 when used with pilot-link version 0.8.0. Install the PilotManager source and apply the patch with the commands:
tar -xvzf pilotmgr,v1.009-BETA-3.dev.tar.gz
cd pilotmgr,v1.009-BETA-3
patch -p1 < ../pilotmgr,v1.009-BETA-3.patch
I hope to be able to install this software soon and report about it in a future version of this document.


Previous Next Contents