Pilot HOWTO by David H. Silber pilot@orbits.com v0.5, 17 August 1997 This HOWTO document explains how to use your Pilot with a linux sys­ tem. Although HOWTO documents are targeted towards use with the linux operating system, this one is not dependent on the version of unix used. 1. Introduction The Pilot comes with software to synchronize its memory with data on a Microsoft Windows system. There is optional software you can buy to synchronize with an Apple Macintosh. The linux/unix community has been ignored by the manufacturers of the Pilot. Fortunately, a suite of free software has been developed to fill this need. This document describes this software, where to get it, and how to install and use it. 1.1. This Document The latest version of this document can be read at http://www.orbits.com/Pilot/Pilot-HOWTO.html, and is part of the Linux Documentation Project (LDP). See http://sunsite.unc.edu/LDP/ for further information about the LDP and other HOWTO documents. Future versions will cover more unix tools for writing application programs to run on the Pilot and conduits to transfer data between the unix system and the Pilot. If you find anything in this document which needs to be corrected or better explained, please send me e-mail at the address above and specify which version of this document you are referring to. This document is Copyright © 1997 by David H. Silber. It is released under the copyright terms in the LDP HOWTO-INDEX document. 1.2. Mailing List The pilot-unix mailing list is maintained by Matthew Cravit . Its mandate is: The pilot-unix mailing list is for discussion and idea-sharing for those interested in using the US Robotics Pilot PDAs with UNIX systems. This includes people who are interested in helping to develop tools to allow the Pilot to operate with UNIX, and possibly to develop an SDK for the Pilot for Unix. For more information, including how to subscribe to the list, send mail containing the word ``INFO'' to pilot-unix- request@lists.best.com. The subject line does not matter. 1.3. Mailing List Archives An archive of the pilot-unix mailing list can be found at http:///www.acm.rpi.edu/~albert/pilot/. It is maintained by Chris Stevens . 1.4. FTP Site An FTP site containing an archive of Pilot tools for use on unix systems is located at ftp://ryeham.ee.ryerson.ca/pub/PalmOS/. It is maintained by Jeff Dionne . 2. General Information 2.1. What is a Pilot? The Pilot is a small pen-based Personal Digital Assistant (PDA). It is made by U. S. Robotics, now part of 3Com. For those of you unfamiliar with the term, a Personal Digital Assistant is one of those small electronic devices which typically contain various types of personal information, such as addresses and telephone numbers, a calendar, checkbook registry, lists of reminders and/or memos and is designed to be conveniently carried so as to be handy when the information is needed. The more adaptable PDAs, such as the Pilot, allow for the data stored on the PDA to be backed up to another computer and for data and new programs to be loaded onto the PDA from another computer. 2.2. Different types of Pilots There are four versions of the Pilot. The earlier two, the 1000 and the 5000 have 128k and 512k of RAM, respectively. The more recent two, the PalmPilot Personal and the PalmPilot Professional have 512k and 1 Meg of RAM, respectively. They also have a backlighting feature for the LCD panel and version 2.0 of the operating system. The Professional also comes with a TCP/IP stack and a few extra programs built-in. It is possible to upgrade any Pilot by swapping out the memory card, which includes both RAM & ROM. Of course, this doesn't get you backlighting for the older pilots. 2.3. Hardware Installation Pilots come with a ``cradle'' for exchanging data with the desktop computer. This device is actually a serial cable with a custom holder for the Pilot end and a `HotSync' button. Plug your cradle into a spare serial port on your computer. When you run each of the stand- alone programs, you will need to place your Pilot in the cradle and push the `HotSync' button so the Pilot knows that it has to communicate. If the Pilot happens to be off when the button is pushed, it will turn itself on. For convenience, create a device, /dev/pilot which will be an alternate name for the serial port to which your Pilot cradle is connected. As the root user, enter the following at the shell prompt: ln /dev/cua0 /dev/pilot Replace cua0 with the name of the port to which you connected your Pilot's cradle. 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. 3.1.1. 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. 3.1.2. 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. 3.1.2.1. 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 pro­ grams?) 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 3.1.2.2. 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. 3.1.2.3. memos This program grabs each memo from the Pilot and prints it out in standard mailbox format. To view your memos: memos /dev/pilot 3.1.2.4. 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 . 3.2.1. 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. 3.2.2. 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 dis­ played in the directory of documents that Doc manages. The syntax for MakeDoc is as follows: makedoc [-n] [-b] or makedoc -d [-b] The file that you wish to convert. The name of the resulting file. (End the name with ``.prc''.) 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: · The PilotManager package: http://playground.sun.com/~bharat/pilotmgr.html · A patch: ftp://ftp.orbits.com/pub/Pilot/pilotmgr,v1.009-BETA-3.patch 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. 4. Tools for Developing Pilot Software 4.1. prc-tools The prc-tools package is a complete development environment built from the FSF GNU utilities, compiler and debugger with the addition of a few special tools. There is not much in the way of documentation, but you might want to look at the Pilot Software Development web page at http://www.massena.com/darrin/pilot/. 4.1.1. Installing prc-tools Download the most recent version of prc-tools from ftp://ryeham.ee.ryerson.ca/pub/PalmOS. The GNU tools can be retrieved from ftp://prep.ai.mit.edu/pub/gnu. Get binutils-2.7.tar.gz, gcc-2.7.2.2.tar.gz and gdb-4.16.tar.gz. The version numbers specified for the GNU tools are correct as of prc-tools release 0.5.0. Later releases of prc-tools may require newer versions of the GNU tools. Put all of the distribution packages in one directory. Unpack only the prc-tools distribution. The prc-tools Makefile will take care of the other packages. By default, prc-tools will be installed in /usr/local/gnu. If you want them installed somewhere else, you need to change the value of INSTALLDIR in Makefile. The steps are: tar -xvzf prc-tools.0.5.0.tar.gz cd prc-tools-0.5.0 (Edit Makefile, if necessary.) make doeverything 4.1.2. Using prc-tools One good reference for general use of prc-tools is the example directory, particularly the Makefile. Documentation for PilRC is provided in the file pilrc1.5/doc/pilrc.htm included as part of prc- tool version 0.5.0. E. People Kenneth Albanowski Maintains the pilot-link suite of tools. Donnie Barnes Packaged pilot-link suite as Red Hat RPM files. Rick Bram Author of Doc. Matthew Cravit List owner for the pilot-unix mailing list. Jeff Dionne Original author of the pilot-link suite of tools. Manages the FTP area for the UNIX PalmOS/Pilot development project. Mark W. Eichin Ported pilot-link suite to Debian Linux. David H. Silber Author of this document. Chris Stevens Maintains the pilot-unix mailing list archives.