Using your Pilot with Unix

This page is hopelessly outdated. Please do not use it!

All the documentation included with the Pilot for connecting it to a desktop computer refers to PCs and Macs. Unix users are dutifully ignored. So a wonderful bunch of people has set to develop all the software necessary to use their Pilots without having to connect or use inferior computing platforms.

However, as the software is still under development, the documentation is sparse, and the procedure to make things work is sometimes not very clear. Since I have been asked a lot of times how to do it, I put together this page, which contains instructions based on my experience.

Please note that I use Solaris 2.5.1 on a Sparc machine, so my instructions are specific to this platform. The instructions should be general enough to work on almost any Unix platform, but you may have to discover some details by yourself. Of course, if you do, please send them to me! Then we can make this page better by adding system-specific details.

Note: All the information in this page is based on my direct experience. If you discover any inaccuracies, omissions or blatant mistakes, please let me know. If you are the author of one of the tools described and think I don't have described it correctly, please let me know, sending me what you would like me to put here.

On the hardware side

  1. Find which one is the serial port in your machine.

    In Sparc[5,10,20] and Ultra machines: you have two serial ports, which are labeled "A" and "B" in the back of your machine, and they are 25-pin female connectors.

    In a Sun IPC (maybe IPX and Classic also, if someone has access to one of those please confirm) the serial ports are labeled "1" and "2" (if memory serves me correctly, that is my home machine) and they are 8-pin female mini-DIN connectors, such as those found in Macs.

  2. Get an appropriate converter for connecting the Pilot cradle to your machine.

    For a Sparc/Ultra, you can get a 9-pin-male to 25-pin male converter, or use the 9-pin-male to 25-pin-female one included with your Pilot, and get a 25-pin-male to 25-pin-male gender changer.

  3. Find out which device file your operating system uses to communicate with the physical port you have selected.

    For Solaris, they will usually be /dev/ttya or /dev/ttyb.

    For Linux, they may be /dev/cua0 or /dev/cua1.

  4. Plug the cradle to the appropriate port in your machine. Remember to turn off the machine before plugging or unplugging anything. Nasty things can happen to serial ports (or to any port, for that matter) if the wrong pins accidentally touch or short-circuit.

On the software side

  1. Go to ftp://ryeham.ee.ryerson.ca/pub/PalmOS/ and get the latest version of pilot-link, which will be named something like pilot-link.x.y.z.tar.gz, where x.y.z is the version number. Pilot-link is the package developed by Kenneth Albanowski (kjahds@kjahds.com) that contains the libraries for communicating with your Pilot from a Unix workstation. It also includes several programs that make use of the libraries (and that are useful in various degrees), and bindings for being able to use the libraries from Java, Perl, Tcl, and Python programs.

    To compile and install pilot-link:

    1. Uncompress and untar the package: 
      gunzip -c pilot-link.x.y.z.tar.gz | tar xvf -
    2. Cd to the resulting directory.
    3. If you have a C compiler (better if it is gcc) installed, normally the following will work: 
      ./configure
make

      You can give options to configure to change parameters such as the base directory where things will be installed (/usr/local by default) and others. Do a ./configure --help for all the options.

    4. Test that it works by doing: 
      ./pilot-xfer port -l

      where port is the device to which your Pilot cradle is connected. Put the Pilot in the cradle, press the HotSync button, and if things are ok, you will see a listing in the screen of all the databases installed in your Pilot.

    5. Install everything by doing 
      make install
    6. Optionally, you can install the Perl, Tcl, Java, and/or Python bindings by doing: 
      make Perl
make Java
make Tcl
make Python

      You can also cd to each directory, make and make test. Usually the test program will ask you to put your Pilot in the cradle and press the HotSync button, and will read some databases or something like that.

      I have only been successful with the Perl and Java bindings. The Tcl keeps crashing when I run the test, and I haven't tried Python.

  2. Play around with the programs. Some of them have man pages, but most don't. The main programs you will likely use are:
    pilot-xfer
    This is the most evolved program of them all. It allows you to read, write, and delete databases from the Pilot, list its contents, backup and restore the Pilot, etc. Run it without arguments to get a help screen. For example, for installing a .prc file you get from the net, you would do: 
    pilot-xfer port -i file.prc

    Where port is the device file for the port where your cradle is connected.

    Most programs in the pilot-link package understand the following environment variables, so if you set them, you can usually leave the arguments out when invoking the commands:

    PILOTPORT for specifying the port where the cradle is connected.

    PILOTRATE for specifying the rate at which to transfer data. The default is 9600 baud, which can be slow. I normally use 38400, which is the higher with which most people report success.

    pilot-mail
    Allows you to send and receive email from the Mail application if you have a PalmPilot Professional. Run it with option -h to get a help screen. By default, it tries to access a POP server to get your new email, downloads it to the Pilot, and sends any email you have composed in the Pilot. By using the -m option, you can get email from an MH folder instead. What I do is that I have an MH folder called "topilot" and as I go through my email, I link to that folder messages that I want to take off-line. At the end of the day, I do: 
    pilot-mail /dev/ttya -m ~/Mail/topilot -d delete -k delete

    Actually, I specify all the information in the appropriate environment variables, which are given in the help screen.

    I know of no easy way of downloading email from a standard Unix mailbox to the Pilot. A temporary workaround could be, if you have the MH software installed, to use the inc command to convert the mailbox to an MH mailbox and use pilot-mail as described above.

    pilot-addresses
    Can be used to download and upload the AddressBook database, storing it in a text format in the Unix side. The format is: 
    "last","first","title","company","work","home","fax","other",
"email","address","city","state","zip","country","custom1",
"custom2","custom3","custom4","note","0"

    this is, the order in which the fields appear in the PhoneBook application, each value in double quotes, separated by commas. The "note" is the optional note you can add to each record. The "0" at the end, I suppose, is for marking it as non-private. Every record has to be in a single line, but you can have as many records per file as you want.

    You can use this, for example, if you already have an address book in some other format, to put it all in your Pilot.

    There is one slightly non-intuitive thing with this program, and it is that the -r option is used to "read from the file, and write to the Pilot", while the -w option means to "read from the Pilot, and write to the file". I found it confusing, you may not, but be careful not to wipe out things inadvertently.

    install-datebook, install-memo, install-todos
    Allow you to install items in the corresponding databases.
    read-expenses, read-todos, read-ical, addresses, memos
    Allow you to read different items to files in your Unix machine. read-ical reads the DateBook database and writes it in ical format.
    pilot-file
    Dumps a .prc or .pdb file (which must be already in your Unix machine) in a hex-and-ASCII format.
    install-user
    Allows you to set the user name that the Pilot keeps in its memory, and that appears when you start the HotSync application.
  3. Now, pilot-link provides you with the basic command-line tools for accessing your Pilot, and the libraries for writing your own programs for doing so. However, The existing applications do not do much in terms of actually "HotSync'ing" the data, this is, incorporating changes from the Pilot to the desktop and vice versa, so that you have updated copies on both sides of the world.

    This is where PilotManager comes in. It is a graphical application (written in Perl/Tk) developed by Bharat Mediratta, that provides a framework for running conduits that synchronize different types of data. Currently, conduits exist for backing up the contents of your Pilot, for installing new files, and for synchronizing the Date Book (transferring data in format of Sun's calendar manager) and Memo Pad (storing the files as ASCII files in a specified directory).

    One problem with PilotManager is that currently it runs only under Solaris. Sources are provided, but you are mostly on your own if you want to port it to other system. In the latest version (1.100-BETA-6), the SyncCM conduit requires the CSA library and rpc.csmd server included Solaris 2.6, and which is optional in Solaris 2.5.1. So you may have to install it first if you haven't.

    However, if you have a Solaris machine, good news! PilotManager is very easy to install and run:

    1. Go to http://www.moshpit.org/pilotmgr/binaries/ and download the latest appropriate version for your machine (it comes in versions for both Sparc and x86 architectures).
    2. Make sure you have Perl 5.003 or later installed. Really. I tried with Perl 5.002 and it doesn't run.
    3. As I said before, make sure you have the libcsa library installed, if you want to successfully use SyncCM.
    4. Unpack the PilotManager tar file.
    5. Edit the PilotManager file, and change the first line to reflect the location of your Perl interpreter.
    6. If you have version 1.100-B-5 or later and you are not using precisely Perl 5.003 (this is, you are using something latter, such as 5.004), do the following:
      1. cd to the directory where you unpacked PilotManager.
      2. cd lib/perl5/[arch], where [arch] will be sun4-solaris or something similar, depending on your architecture.
      3. mv 5.003 `perl -e 'print $]'`
      This will make PilotManager find the directories it needs adequately.
    7. Run PilotManager. If everything is ok, you should see the main window. Select the "Properties" menu item, select the appropriate port and speed you want to use, select and configure the conduits you want to run.
    8. Finally, put your Pilot in the cradle, press the HotSync icon in PilotManager, press the HotSync button in the cradle, and your Pilot should start synchronizing.
    9. If you need help, go to the PilotManager home page. There is not much documentation, but you may find what you need. Also, there is a mailing list. Help is also included in the program.
    A few tips regarding PilotManager may be useful:
Go back to my Pilot Page

Diego Zamboni

Last modified: Mon Aug 2 14:51:44 EST 1999