Pilot-link documentation

How to use the Unix<-->PalmOS utilities in the pilot-link misc collection. These will help you slurp stuff to or dump stuff from your PalmOS-running handheld, herein referred to as a Palm.

The current release is 0.9.3. This page still documents the 0.8.13 version (I'll check eventually to see if there have been any user-visible changes. I do not think so).

The most useful tool is pilot-xfer, so if you're new to this, you might want to skip down and read that first.

Contents

There are also man pages for pilot-xfer, pilot-read-ical, pilot-install-memo, and pilot-install-datebook.

pilot-addresses

This utility lets you mess around with addresses in text format.

Usage

pilot-addresses [-aeq] [-p port] [-c cat] [-d cat] -r|-w file

-q -- run "quietly", i.e. do not prompt for HotSync button press.

-a -- augment records with additional information. (when -w is used)

-e -- encode special chars (pilot '\n' <==> file "\\n", etc)

-p <port> -- the serial port you're using for the Palm cradle. For example, /dev/ttya.

-c <category name> -- install to this category, instead of to 'Unfiled'. (when -w is used)

-d <category name> -- deletes from your Palm all existing addresses in this category in addition to (I think "after", if it matters to you) reading or writing the file.

-r -- read file ==> install in Palm

-w -- write file <== get from Palm

Notes

Remember that "read" and "write" are with respect to the file, not the PalmOS database. Also, backing up your address database (pilot-xfer -f AddressDB) beforehand is always recommended, so that you can easily undo anything that turned out to be a bad idea.

The file format is one entry per line, each field in quotes and separated by commas, e.g.

"Spitznagel","Bridget","","","268-8101","","","","sprite@cs","WeH 1305","","","","","URL: http://www.cs.cmu.edu/~sprite/","","","","","0"

I'm not convinced that -a does anything helpful, at least in combination with -r.


pilot-file

This utility is for examining .pdb files (and .prc?) It does not use the serial port.

Usage

pilot-file [options] file

-h -- dump header to stdout

-a -- dump app_info

-s -- dump sort_info

-l -- list records

-r <index> -- dump a specified record

-v -- dump all data and all records

-R, -V -- as -r, -v, but also dump resources to files

Notes

Harmless, obviously.


pilot-getram

This utility will dump your RAM image to a file (to aid you-the-developer in debugging an application.)

Usage

pilot-getram /dev/tty?? [-c] [pilot.ram]

-c -- "I'm fetching this RAM for use with Copilot"

Notes

I haven't used it. The program will tell you

Warning: Please back up your Palm (with pilot-xfer) before using this program!

This program is really called "pi-getram" if you fetch and compile the pilot-link utilities yourself.


pilot-getrom

This utility will dump your ROM to a file (to aid you-the-developer in debugging an application.)

pilot-getrom /dev/tty?? [pilot.rom]

Notes

I haven't used it. The program will tell you

Warning: Please back up your Palm (with pilot-xfer) before using this program!

NOTICE: Use of this program may place you in violation of your software license agreement. Please read whatever legal foo came with your handheld device before running this program.

This program is really called "pi-getrom" if you fetch and compile the pilot-link utilities yourself.


pilot-install-datebook

This utility will install a text file(s) as a new datebook entry(s).

Usage

pilot-install-datebook /dev/tty?? file [file] ...

file [file..] -- You can install more than one file at a time, as multiple datebook entries. The file format is specified in the man page, more or less.

Notes

This utility is really called "install-datebook" if you fetch and compile the pilot-link utilities yourself.


pilot-install-memo

This utility will install a text file(s) as a new memo(s).

Usage

pilot-install-memo [-qrt] [-c category] /dev/tty?? file [file] ...

(Note: The [-qrt] is new, and the argument order seems to have changed.)

-q -- "quiet": do not prompt the user to press the HotSync button.

-r -- "replace". You must specify a category (with -c). It will delete all memos currently in that category, then install the new files as usual.

-t -- "title": use filename as memo title. (formerly default)

-c category -- May be a name (e.g. Personal) or number (index in your list of categories, counting from 1. I'm no longer sure what the ordering is.) If specified, the new memos will be filed in that category. If you don't use this switch, or if the category you specified doesn't exist on your Palm, the new memos will be filed in the "Unfiled" category.

file [file..] -- You can install more than one file at a time, as multiple memos, but they will all be the same category. The title (and first line) of each memo will be the name of the file it was created from.

Notes

Each memo is limited to 4096 bytes. (I suppose they are truncated, I haven't checked.)

This utility is really called "install-memo" if you fetch and compile the pilot-link utilities yourself.


pilot-install-todos

This utility will install a text file(s) as new todo items.

Usage

pilot-install-todos /dev/tty?? file [file] ...

file [file..] -- Each line of each file is made into a todo item.

Notes

All settings are currently fixed. (Apparently to priority 4, category unfiled, no due date, not private.)

This utility is really called "install-todos" if you fetch and compile the pilot-link utilities yourself.


pilot-install-user

This utility will modify user name settings.

Usage

pilot-install-user /dev/tty?? [User name [User id]]

Notes

I haven't tried on an actual Palm. A comment in the source file reports

Note: if you use this program to change the user name on the Palm, I _highly_ reccomend that you perform a hard reset before HotSyncing with a Windows machine. This is because the user-id information has only been partially altered, and it is not worth trying to predict what the Desktop will do.
I have tried it on xcopilot. You get entertaining output of this form:
 Card #0 has 950268 bytes of ROM, and 1048576 bytes of RAM (922842 of that is free)
 It is called 'PalmCard', and was made by 'Palm Computing'.
Through ReadSysInfo: ROM Version: 0x02003000, locale: 0x00010000, name: ''
ROM Version through ReadFeature: 0x02003000
NetSync: LAN sync = 0, Host name = '', address = '', netmask =''

You can use "<shortcut-character>.4" to view the Palm's current user name and number. (Also, HotSync will say "Welcome, Harry Q. Bovik.")

This utility is really called "install-user" if you fetch and compile the pilot-link utilities yourself.


pilot-mail

As the comment says:
/* pilot-mail.c: Make mail go voom-voom tween da Pilot an da Net */
This will allow you to send mail composed on your Palm, copy mail from an mh folder to the Palm, or (I haven't tried to) get mail from a POP3 host.

Usage

pilot-mail [options]

All options may be specified via environment variables. Defaults are "" unless specified.

-p port -- PILOTPORT -- Serial port.

-h host -- POPHOST -- POP3 host. If empty, mail won't be received.

-u user -- POPUSER -- POP3 user name.

-P pass -- POPPASS -- POP3 password.

-f address -- PILOTFROM -- Outgoing 'From:' line.

-s command -- SENDMAIL -- Sendmail command.
Default: /usr/lib/sendmail -t -oi
-t: sendmail will read the message to determine the recipients.
-oi: Dots on a line by themselves are not message terminators.

-k keep|delete -- POPKEEP -- Keep mail on POP server.
Default: keep.

-d keep|delete|file -- PILOTDISPOSE -- Disposition of sent mail.
Default: keep.
Keep means it stays in 'Outbox' and you get to delete it yourself. If you forget, it will be sent again next time you use pilot-mail. Delete will delete it for you: potentially annoying if something goes wrong. File will put it in 'Filed', which seems the best choice if you are both paranoid and forgetful.

-m mhdir -- TOPILOT_MHDIR -- MH directory to download to Palm.
For people who don't want to mess around with this POP business.

-t stampfile -- TOPILOT_STAMP -- For use when downloading mail to Palm.
If you are using, for example, "-m <folder>" and you also specify "-t <stampfile>", pilot-mail will check the dates in the headers of the messages in the "folder" directory, and will download only the messages that are more recent than the modification date of "stampfile". Use "-T" to automatically touch "stampfile".

-T -- TOPILOT_TOUCH -- For use along with "-t stampfile".


When pilot-mail is done checking the header dates against the modification time of "stampfile", this option will cause it to touch "stampfile" to the current time. (This will err on the side of not downloading. If you continue using -t, you won't download these messages again, but if you refile an "old" message into that folder, you won't download it either.)
This option will be in effect if TOPILOT_TOUCH is set to anything.

Notes

Original note: "pilot-mail (which requires a Palm with the Mail application, as well as sendmail and/or a POP3 server) is still in the experimental stage. Run with an argument of '-H' for help. While I don't expect it to lose data, (and by default mail is kept on both sides, not deleted) I can not and will not guarantee that you won't. Please back up your UNIX mailbox and Palm mailbox (via pilot-xfer) before experimenting."

I haven't tried to receive mail from POP, but sending worked. The "dump MH folder to Palm" worked too (but loses the CC field.) The messages remain in the mh folder, so you either have to clean it out yourself or use the -t,-T flags. Others report that the folder should be 'packed' (so it starts at 1 with no gaps.)

pilot-mail is patched from the 0.8.13 version so that it will word-wrap the body of your outgoing mail to 72 columns. FYI, this patch is also responsible for the -t and -T options.


pilot-makedoc

This utility will convert text files to Doc format (for Palm document readers, such as AportisDoc and TealDoc), and vice versa.

makedoc [-n] [-b] <text-file> <prc-file> <story-name>
                 convert text files to .PRC format
       makedoc -d [-b] <prc-file> <text-file>
                 decodes the PRC back into the txt file
       -n builds the .prc file without compression
       -b option compresses/decompresses binary

Notes

Does not use the serial port.

This utility is not part of the pilot-link.<version> tarball. It has its own version (0.7a or something) which I would not expect to change.


pilot-money2qif

This utility is for users of Stingersoft's freeware MoneyManager, formerly PilotMoney (to add to the confusion, Landware released a commercial version with more features and a PC conduit, called MicroMoney. And good luck finding any of them these days. Landware at least is still around but doing Pocket Quicken instead).
In any case, the database is MoneyDB. It is useful for keeping track of accounts (checking, savings, credit cards, etc.)

Usage

pilot-money2qif /dev/tty?? Account

"Account" is one of your categories, e.g. "Checking". This utility should convert the outstanding items in that category to QIF (quicken interchange format), and spew it to stdout.

Results clearly contain the right information, but I can't vouch for it being in the proper format, being unfamiliar with QIF.


pilot-read-addresses

This utility will spew your Palm's address database to stdout as text.

Usage

pilot-read-addresses /dev/tty??

Notes

The text is human-readable, like this

Category: Business
Last name: Bovik
First name: Harry
Work: 268-8101
Home: 555-2368
E-mail: bovik@cs.cmu.edu
Address: 17 Fig Newton Dr.
City: Pgh
State: PA
Zip Code: 15217

Has no effect on the database.

This utility is really called "addresses" if you fetch and compile the pilot-link utilities yourself.


pilot-read-expenses

This utility will spew your Palm's expense database to stdout, sort of as text.

Usage

pilot-read-expenses /dev/tty??

Notes

The format is not very human-readable, e.g.:

Orig length 20, data:
0000  bc a5 0f 01 17 5d 34 2e 30 30 00 74 72 75 63 6b   .....]4.00.truck
0010  00 00 00 00                                       ....
New length 20, data:
0000  bc a5 0f 01 17 00 34 2e 30 30 00 74 72 75 63 6b   ......4.00.truck
0010  00 00 00 00                                       ....
Category: Food/Drug
Type: 15, Payment: 1, Currency: 23
Amount: '4.00', Vendor: 'truck', City: ''
Attendees: '', Note: ''
Date: Tue May  5 00:00:00 1998
(This example was a $4 "Lunch" bought from a truck with "Cash" on May 5.)

Has no effect on the database.

This utility is really called "read-expenses" if you fetch and compile the pilot-link utilities yourself.


pilot-read-ical

This utility will print your Palm's datebook and (optionally) todo databases to a file, in ical 2.0 format. "read-ical and sync-ical will only run if you have ical-2.x installed and in the path."

Usage

pilot-read-ical [-d] [-p pubtext] [/dev/tty??] calfile

-d -- Examine datebook database only; omit todos.

-p pubtext -- Replace text of items not starting with a bullet with pubtext. (???)

calfile -- This file will be overwritten.

(Port defaults to PILOTPORT environment variable.)

Notes

It is one-way, Palm to ical, so it should be harmless, if you don't overwrite a file you wanted.

This utility is really called "read-ical" if you fetch and compile the pilot-link utilities yourself.


pilot-read-memos

By default, this utility will spew your Palm's memo database as text to stdout. There is now an option to write the memos as files instead.

Usage

pilot-read-memos [options]

(Port defaults to PILOTPORT environment variable.)

-q -- run "quietly", i.e. do not prompt for HotSync button press.

-p <port> -- Default is the PILOTPORT environment variable, if any, or /dev/pilot.

-d <dir> -- Instead of writing to stdout, save memos in this directory.

By default, the contents of your Palm's memo database will be written to standard output as a standard Unix mailbox (mbox-format) file, with each memo as a separate message. The subject of each message will be the category.

If -d is specified, than instead of being written to standard output, memos will be saved in subdirectories of <dir>. Each subdirectory will be the name of a category on the Palm, and will contain the memos in that category. Each memo's filename will be the first line (up to the first 40 characters) of the memo. Control characters, slashes, and equal signs that would otherwise appear in filenames are converted after the fashion of MIME's quoted-printable encoding. Note that if you have two memos in the same category whose first lines are identical (up to 40 chars), one of them will be OVERWRITTEN.

Notes

Has no effect on the database.

This utility is really called "memos" if you fetch and compile the pilot-link utilities yourself.


pilot-read-todos

This utility will spew your Palm's todo database as text to stdout.

Usage

pilot-read-todos /dev/tty??

The text is human-readable, like this

Category: Unfiled
Priority: 1
Completed: No
Due: No Date
Description: Send in Palm registration card
Note: Fill out and return your registration card or register by
(etc)

Notes

Has no effect on the database.

This utility is really called "read-todos" if you fetch and compile the pilot-link utilities yourself.


pilot-xfer

This utility allows you to up- and download applications and databases (in Palm .prc or .pdb format).

Usage

pilot-xfer [-p port] [command]

-p port -- Otherwise it uses the PILOTPORT environment variable, or defaults to /dev/pilot if PILOTPORT is not set. (Note that the port needs '-p' as of version 0.8.13. Previous versions had no flag. There is now a -v flag, so you can find out the version.)

-b backupdir -- Backup. This copies all the apps and dbs on your Palm into separate files in backupdir. (Yes, you should back up your stuff periodically.) Doesn't change anything on your Palm.

-u backupdir -- Update. This is like -b, except that it checks what you have backed up in backupdir previously, and it only backs up what has changed since then. (Everything, obviously, if backupdir is empty.. or if you last backed up with version 0.8.8 or earlier.) This should be a real time-saver. Doesn't change anything on your Palm.

-s backupdir -- Sync. This is like -u, except that if you have deleted an app or db on your Palm, it will delete the corresponding file from backupdir, if it is present there. Keeps the directory tidy for your next restore. Doesn't change anything on your Palm.

-r backupdir -- Restore. This copies all the stuff in backupdir back onto your Palm. It does not erase anything, but will overwrite databases if they already exist. Doesn't change anything in backupdir.

-i file(s) -- Install. Copies the named files, which should be in .pdb or .prc format, onto your Palm.

-m file(s) -- Merge. [I haven't really tried this]

-f dbname(s) -- Fetch. Copies the named database(s) from your Palm to file(s) in the current directory. E.g. "-f MemoDB" produces "./MemoDB.pdb". How do you find the name of the database? Either you know it from doing a full backup and listing the directory, or using "-l" described below.

-d dbname(s) -- Delete the named database(s). You might want to back it up first with "-f" in case you change your mind. :-)

-e file(s) -- Exclude. You can list things to "exclude" from backup, if you have a lot of stuff on your Palm and don't want to waste power backing up the things that you "know" haven't changed (-u will also help with this, but not if you've done a soft reset since your last backup.)
When you specify options, -e should come BEFORE the other stuff like -u or -b, or so I have experimentally determined.
In the file(s), you list names of apps/databases to exclude from backup, one name per line. The name should be what the file would be called in the backup directory, WITHOUT the ".prc" or ".pdb"; this is the same name it prints when you do a "-l", or you do a "-u" and it skips something, e.g. "No change, skipping 'RPN'."
One way you might trivially construct this file is to "ls -1 *.prc" in your backup directory, dump the output to a file, remove all .prc extensions, and then remove the names of any application you DO want to back up. (If you have some large unchanging databases too, e.g. books in DOC-format, you might start with "ls -1 *.prc *.pdb" but you can doubtless figure out things like that yourself.)
Hm. It seems to print out a heck of a lot of stuff. I should probably remove some printf and recompile (next time I'm in work-avoidance mode.)

-P -- Purge deleted records from databases. (Note this is -P as of version 0.8.13; in previous versions, it was -p. Use -v to check your version.)

-l -- List the databases/applications you have on your Palm. If you don't know the name of the db you want to backup singly with -f (fetch), use this.

-L -- "List all". This will list strange cruft you never heard of, in addition to what -l does. (New with version 0.8.13.)

-v -- Version. If you don't know which version you're running, use this. (Also new. Starting with version 0.8.13 you'll get a version number; for previous versions it will report "invalid option".)

The baud rate to connect with may be specified by the PILOTRATE environment variable. If not specified, it will default to 9600. Please use caution setting it to higher values, as several types of workstations have problems with higher rates.

Notes

"The Graffiti ShortCuts database often cannot be restored [because it is always open and thus locked]. You may install System Updates merely by installing the .prc file via -i, without any further action."


Useful Links

For random questions try the local faq.

Source is available at ftp://ryeham.ee.ryerson.ca/pub/PalmOS/ as pilot-link.X.Y.Z.tar.gz where X.Y.Z is the version number.

There is a Pilot-UNIX mailing list archived at http://www.acm.rpi.edu/~albert/pilot/.

XCopilot is a simulator. You can fetch the ROM/RAM contents from your pilot using pilot-get{rom,ram} for use with XCopilot.

J-Pilot is a GUI over the pilot-link library foo. "It is similar in functionality to the one that 3com distributes for a well known rampany legacy operating system."

KPilot is "intended to eventually provide all the functionality of the Windows software provided by 3-Com and more." It requires the KDE and Qt libraries to compile.

PilotManager is "a tool that allows you to synchronize databases on your 3Com PalmPilot with applications on your Unix platform." (Depending on whether there is a conduit written for that database/application pair.) It's Perl/Tk over the basic pilot-link library.

Something called Pilot-Sync has been "in extreme alpha" for approximately forever and may or may not still be alive.

To sync with ical, you can use syncal. Hint: to sync a cboard item, mark it as "personal copy" in the cboards menu.

BBDB syncing seems like an open problem (people haven't figured out a way to deal with the fact that BBDB has many more fields than the palm). A reasonable one-way tool is bbdbpalm, which also lists alternatives (in the comments of the file you download).

Vector-graphics maps can be found at mapopolis. They'll scroll, zoom, and so on. Too bad their "business" database is so poor. Anyway, they're free (for now?).

There are various web sites where Pilot apps are available. There are various other sites with information on writing your own.

You may also be interested in Calvin's FAQ and the official PalmOS page.


Bridget Spitznagel
Last modified: Tue Sep 12 12:20:56 EDT 2000