Linux

Pilot to bombardier: Using command-line Pilot tools in Linux

Syncing a Palm Pilot with Linux can be as easy as syncing with Windows. In this Daily Drill Down, Jack Wallen introduces you to a new playground for your Pilot console, and he explains how to set up and use the pilot-link software package.

In previous Linux/Palm articles, I've talked about syncing your Pilot with both GNOME and KDE—the two prominent Linux GUIs. I've discovered that syncing a Palm Pilot with Linux can be as easy and as enjoyable as syncing in Windows.

This time, however, I’m taking you off the beaten path from Windows to discover a new playground for the Pilot—console! Yes it's everyone's favorite type-fest with a modern-day twist.

Why use console?
Using console for such a tool may seem to be a bit awkward (at best) and ridiculous (at worst). When all of what I am going to be discussing can be accomplished with the user-friendly GNOME or KDE desktops (via drag and drop or point and click), why would anyone want to revert back to console?

The most obvious point is security. I'm not talking about the kind of security involving hackers and ipchains. No. I'm talking about peace of mind. What happens if you get a hacker into your system and the only way you can boot your machine is through linux single? You can't get X to work and you've tried everything you can think of—it's looking like you're going to have to reinstall. So, you back up those critical ones and zeroes and reinstall. If you had only been using GNOME Pilot or Kpilot, you would be somewhat out of luck. With pilot-link, however, you would still be able to safely back up your Pilot data before having to commit to reinstalling your OS. Security plain and simple.

There are, of course, other reasons why you'd want to use console-based Pilot syncing applications, but why don't I just get on with it?

The software
The software we'll be examining is a complete package called pilot-link. This software can be retrieved from the author's (Kenneth Albanowski) FTP site.
This site receives high traffic and can be difficult to enter.
This application is completely command-line driven. There is no GUI, so be prepared to type. The commands are all fairly simple, but at the same time quite flexible.

Setting up the link
Before we move into the software zone, we first have to configure the OS to accept the connection between Pilot and PC. The first step in getting your Pilot to sync in Linux (regardless of which desktop environment you are using) is to successfully create the link to the /dev/pilot file. To do this, first you must determine to which serial port your Palm will be connected. Here's a list of which device files go with which ports:
  • ttyS0—Serial Port 1
  • ttyS1—Serial Port 2
  • ttyS2—Serial Port 3

or, depending on your distribution:
  • cua0—Serial Port 1
  • cua1—Serial Port 2
  • cua2—Serial Port 3
The cua* name scheme is being phased out of Linux so, although many distros still include the cua* devices, you should stick with the ttyS* devices.
The first step in creating the actual link is to create, as root, a new device file called /dev/pilot, along with the link to the ttyS* device with the following command:
ln /dev/ttyS* /dev/pilot

remembering to substitute the * with the number of the tty device to be used. Once this link is created, you are ready to link your Palmtop machine to your Linux machine. Put the device in its cradle and hit the sync button. You should hear the familiar tone and a window will appear on your desktop. Once you have created the link, you must make sure that users can read and write to the link. To give users read/write permission to your new link, you have to run the following command (as root):
chmod 666 /dev/pilot

Now, you can begin your first sync.

Back to the software
The pilot-link software package is actually a group of conduits that aid in passing data to and from your Pilot. The list of applications looks like:
  • addresses—Dump Pilot address book into generic format
  • debugsh—Command-line interface to Pilot debug monitor
  • dlpsh—Command-line interface to Pilot HotSync protocol
  • getrom—Program to fetch ROM using getrom.prc or getrom2.prc
  • getrom.prc—Pilot program to help dump a 512K ROM
  • getrom2.prc—Pilot program to help dump a 1024K ROM (used for PalmOS 2.x)
  • ietf2datebook—Convert IETF calendar to format used by install-datebook
  • install-datebook—Import datebook records from a text format into Pilot
  • install-memo—Import memo records from a text format into Pilot
  • install-todos—Import to-do records from a text format into Pilot
  • install-user—Modify user name settings (and report lots of info) about Pilot
  • memos—Export memos from Pilot in mailbox format
  • pi-csd—Must be running to accept Network HotSync connects
  • pi-getram—Program that retrieves RAM from Pilot
  • pi-getrom—Program that retrieves ROM from Pilot (without getrom.prc)
  • pi-nredir—Program that accepts connections and redirects them via the Network HotSync protocol
  • pi-port—Experimental program to separate serial layer from pilot-link
  • pilot-addresses—Import and export address book
  • pilot-clip—Experimental program to import and export data from Pilot clipboard
  • pilot-debug—Graphical and command-line program to interface with the Pilot debug monitor
  • pilot-dedupe—Strips duplicate records from the Pilot databases
  • pilot-file—Disect .prc and .pdb files
  • pilot-mail—Import mail from POP3 mailbox into Pilot Pro's Mail application, and send mail via Sendmail
  • pilot-schlep—Store a single file on the Pilot
  • pilot-undelete—Turn archived records into normal records
  • pilot-xfer—Back up, restore, install, and delete Pilot databases
  • read-expenses—Export Pilot Pro expense database into text format
  • read-ical—Export Pilot datebook and to-do databases into an Ical calendar (Ical is required)
  • read-todos—Export Pilot to-do database into generic text format
  • reminders—Export Pilot datebook into a 'remind' data file
  • sync-plan—Completely synchronize the Pilot datebook with the Plan calendar via netplan

Quite a healthy listing for such a small package! Of course the majority of the above applications will be of no use to the average user. For this reason, we are going to take a look at the most useful tools from the above list—tools that you are sure to use with your Palm Pilot. Of the above tools, we will examine the following:
  • pilot-xfer
  • install-datebook
  • install-memo
  • install-todos
  • memos
  • pilot-addresses
  • pilot-mail

With the above list, you should be able to use your Pilot with near complete functionality within console mode.

pilot-xfer
This one is probably the most useful program within this suite of tools. The pilot-xfer allows the user to install databases contained in the standard .prc and .pdb formats into a Pilot, retrieve databases from a Pilot, list the databases contained in a Pilot, and backup or restore all of the databases at once.

The standard command for pilot-xfer is the following:
pilot-xfer [serial-device] [--exclude file] --backup | --update | --sync directory

or
pilot-xfer [serial-device] [ --restore directory | --list | --purge | --fetch dbname ...
 | --delete dbname ... | --install file ... | --merge file ... ] ...

Once the user has executed pilot-xfer you must invoke HotSync on the target device.
Breaking down the above command format is actually simpler than it looks. I'll take this one argument at a time.

[serial-device]
As it sounds, this argument tells the pilot-xfer application which port device the Pilot is connected to. If you followed the instructions above to create the link for your Pilot, then you will be able to use the default—/dev/pilot. With the default option (/dev/pilot) the command for a simple listing (using the -l switch) would look like so:
pilot-xfer -l

The above command would report the output like:
Waiting for connection on /dev/pilot (press the HotSync button now)...
Connected
Reading list of databases in RAM...
'Unsaved Preferences'
'Saved Preferences'
'Graffiti ShortCuts'
'Net Prefs'
'AddressDB'
'MemoDB'
'ToDoDB'
'MailDB'
'NetworkDB'
'DatebookDB'
'Giraffe High Score'
'ExpenseDB'
'VendorsDB'
'CitiesDB'
'ATool'
'LauncherIII'
'LauncherIII Icons'
'LauncherIII Tabs'
'LauncherIII Data'
'HackMaster'
'Extension Registry'
'DieRoller'
'PocketC'
'PcDB'
'Qed'
'QEDdata'
'untitled 1'
'Battery'
'Update 3.1.1'
'Update 3.0.2'
List done.


If you do not have your Pilot configured for /dev/pilot, then you will have to explicitly declare which port to use. Say, for instance, you have your Pilot configured to use /dev/ttyS1. To run the pilot-xfer application, you would use the following command:
pilot-xfer /dev/ttyS1 -l

which would bring about the same results. Of course, this simple listing is not very useful other than highlighting the functionality of the very basic command.

[--exclude file]
This particular option can be useful in certain situations (i.e., saving battery power, ensuring certain files are not modified, etc.). What this particular argument does is exclude certain files from the actions you declare.

To explain this argument, let’s assume that you have a directory of databases (I'll call it ~/pilot/work) you wish to transfer and back up to your Pilot. Within this directory however, there are certain databases (I'll call them ~/pilot/work/dbase1, ~/pilot/work/dbase2) you do not wish to transfer or back up (due to either their nature or security or whatever). To keep them from being acted upon, simply use the -e option, like so:
pilot-xfer -e ~/pilot/work/dbase1 dbase2 -b backup-directory

The above command will back up the entire pilot directory on your PC—excluding dbase1 and dbase2—in the backup-directory on the Pilot. As this transfer occurs, text (similar to the excerpt below) will scroll by.
Backing up 'backup-directory/NetworkDB.pdb'... OK
Backing up 'backup-directory/DatebookDB.pdb'... OK
Backing up 'backup-directory/Giraffe High Score.prc'... OK
Backing up 'backup-directory/ExpenseDB.pdb'... OK
Backing up 'backup-directory/VendorsDB.pdb'... OK
..........


Once your link is established, you are going to want to back up your Palm to your PC. To do this, you invoke the pilot-xfer command with the --backup option.
pilot-xfer -b ~/backup-directory

With the above command, your Pilot will back up to the backup-directory located in your home directory. When the command is run, you will first get this returned:
[jwallen@giles jwallen]$ pilot-xfer -b ~/backup-directory
Waiting for connection on /dev/pilot (press the HotSync button now)...


When the HotSync button is pressed, your Pilot will begin the backup process, and output will appear that looks a lot like this excerpt:
Backing up '/home/jwallen/backup-directory/DieRoller.pdb'... OK
Backing up '/home/jwallen/backup-directory/PocketC.prc'... OK
Backing up '/home/jwallen/backup-directory/PcDB.pdb'... OK
Backing up '/home/jwallen/backup-directory/Qed.prc'... OK
Backing up '/home/jwallen/backup-directory/QEDdata.pdb'... OK
Backing up '/home/jwallen/backup-directory/untitled 1.pdb'... OK
Backing up '/home/jwallen/backup-directory/Battery.prc'... OK
Backing up '/home/jwallen/backup-directory/Update 3.1.1.prc'... OK
Backing up '/home/jwallen/backup-directory/Update 3.0.2.prc'... OK
Backup done.

This operation (backup) must be specified after any exclude option.
One thing you will notice is the pilot-xfer tends to be much slower than many backup applications. This slower behavior can cause excessive battery wear because the Pilot is working the entire time. Due to this slowness, I wouldn't suggest backing up with pilot-xfer too often.

update
The pilot-xfer program comes complete with an update application that backs up the Pilot into the specified directory (which will be created if it does not already exist). Any Pilot databases which have not been modified or created since the last backup will not be backed up.
This operation (update) must be specified after any exclude option.
The only difference between update and backup is that backup will back up all databases (even if they've not been modified), whereas update will only back up those databases that have been modified since the last backup.

The update command structure is similar to backup:
pilot-xfer -u backup-directory

sync
The sync optjon works just as you would expect. Running the command:
pilot-xfer -s ~/PILOT_DIRECTORY
Where it says PILOT_DIRECTORY, you would enter the explicit path to the directory where your Pilot dumps its files. For example: with GNOME the path is ~/MyPilot; with KDE it is ~/.kde/share/apps/kpilot/DBBackup/USERNAME.
If you don’t already have a sync directory, you should create a default directory with a name similar to ~/PilotSync.

Installing files with pilot-xfer
What good would a Pilot application be without the ability to install programs or files? Installing can be done with pilot-xfer. To install a file with pilot-xfer, you simply use the application with the -i switch like so:
pilot-xfer -i file

The above command will install the file onto the Pilot. As it is installing, you will see:
[jwallen@giles palm]$ pilot-xfer --install WhatzUp.prc
Waiting for connection on /dev/pilot (press the HotSync button now)...
Connected
Installing WhatzUp.prc... OK
Install done


install-datebook
The install-datebook command allows the user to write one or more datebook entries from one or more source files. The command structure is this:
Install-datebook /dev/pilot filename

Once install-datebook is started, the user must invoke HotSync on the target device.

The format of the source file contains one datebook entry on a line with four tab-separated fields. The fields are start date/time, end date/time, alarm settings, and the description of datebook entry. This program doesn't yet support repeated entries. The date and time must be in a format understood by parsedate.y. The following formats are understood:
August 11, 1997 0800 GMT+300
1997/08/11 08:22:33 GMT+300


If the either one of the date and time fields is empty, the entry is installed without time. If the alarm field is empty, the entry is installed without alarms. The alarm field can contain a number followed by "m" (minutes), "h" (hours), or "d" (days).

install-memo
The install-memo application has a very similar setup to the above applications. This particular command will install a memo onto the Pilot from a text file. The file can be pretty much any ASCII text file and, through the command, it will be categorized.

The basic command structure is:
install-memo /dev/pilot -c category_type file

where category_type is a user-defined category (from the standard Pilot list) and file is the user-defined file to be installed. Let's run through a simple example. We have the following file called memo in our home directory:
This is my sample memo.

What we want to do is install this memo onto the Pilot under the personal category, and we do so with this command:
install-memo /dev/pilot -c personal ~/memo

Once you type the command, hit [Enter], and then press the HotSync button on the Pilot for the memo to install.
With the install-memo command, you do not get a warning to push the HotSync button.
install-todos
The install-todos has the same functionality as the install-memo application (minus the category). With a command structure that looks like:
install-todos /dev/pilot file

you can install a basic to do onto your Pilot.

The one feature missing from install-todo is the ability to categorize the to-do lists. However, the basic functionality of the to-do list is there with install-todo. To demonstrate, I'll have a file called todo in our home directory with the following text:
This is my new todo Scooby Doo!

When we enter the command:
install-todos /dev/pilot ~/todo

followed by hitting [Enter] and pressing the HotSync button, your new to-do list will be installed onto your Pilot. Pretty simple stuff!

memos
The memos application writes the content of your Pilot’s memos to stdout. The stdout tool allows you to output your memos from your Pilot to your PC. This output can be either to stdout (the screen) or to a file. The command is very simple:
memos

You will then be asked to press the HotSync button on the Pilot. If you do not give any options, the memos tool will output the memos to the screen for your viewing pleasure.

There are, of course, options to send with the basic memos command. These options are:
  • -q—Do not prompt for HotSync button press
  • -p port—Use device file <port> to communicate with Pilot
  • -d dir—Save memos in <dir> instead of writing to stdout

With the first option, you will still be required to press the HotSync button on the cradle. What you will not see when passing the -q option is the following warning:
Please insert Pilot in cradle on /dev/pilot and press HotSync button.

The -p option allows you to explicitly declare the port used for the Pilot. Like all the other applications within pilot-link, the default is /dev/pilot.

The last option, -d, allows you to specify where the content of the Pilot memos is to be output. Specifying a directory will give you the option of keeping this file, where the default will only allow you to read the output as it scrolls by on the screen.

pilot-addresses
One of the more useful tools within the pilot-link suite is the pilot-addresses tool. This particular tool allows you to bring your addresses to and from the Pilot and install new entries.

Like all others, the command structure is quite simple:
pilot-addresses [-qprw] | port | dir

The above command gives you all the possible options. The first argument to send with pilot-addresses is –q, which tells the application to not ask the user to press the HotSync button.
Although you will not be prompted to press the HotSync button (when sending the -q flag), you will still need to press the HotSync button on the cradle.
The next argument, -p, is to explicitly declare which port to use for the cradle. Again, the default is /dev/pilot.

The -r argument allows you to read records from a file and install them onto the Pilot. Knowing the structure of the records is the most important part of this command. A standard record for the address book is a long list of comma-delineated entries with each entry encased in quotes. A typical entry will look like:
"Wallen","Jack","Editor in Chief of Linux Content","TechRepublic",
"555-111-1212","555-111-1313","555-111-1414","jwallen@techrepublic.com",
"3333 Notastreet Lane","Bigcity","State","00000","USA","B-Day:
This 00/00/00","Anniversary 00/00/00","Vegetarian","","",""


The above entry is fairly self-explanatory. With the exception of the final three entries, the entries in each address book are standard:
  • Last name
  • First name
  • Title
  • Company
  • Work phone
  • Home phone
  • Fax
  • Other
  • e-mail
  • Address
  • City
  • State
  • Zip
  • Country
  • Custom 1
  • Custom 2
  • Custom 3

The final three entries are not used and although the Pilot itself has space for four custom entries, it will only accept three from the pilot-addresses application.

With this tool you can easily enter new address entries via a standard Linux text editor. By following the entry above, you can create any number of entries on your console machine and sync them with your Pilot.

pilot-mail
The pilot-mail application is actually quite a useful tool for polling a mail server and downloading mail onto your Pilot.

With this application there are a number of arguments to use. Fortunately, only a select few are truly useful. To run this command, you simply need to send the command along with the following arguments (and their variables):
  • p—Port to be used
  • h—Mailserver name
  • u—Username
  • P—Password

So the basic command for pilot-mail would look like:
pilot-mail -p /dev/pilot -h mail.domain.com -u USERNAME -P PASSWORD
The above command requires some user-defined entries.
When you enter the above command (with the proper user-defined entries), you will then need to press the HotSync button. Once the sync process is in action, the command will poll your mail server and download all incoming mail to your Pilot.
By default, all mail is deleted from the server. To disable this feature, you'll want to pass the -k argument along with the command.
Conclusion
The pilot-link software suite allows you the full functionality of syncing with your Pilot without the complicated setup/configuration of the GUI. This application is well built and operates perfectly, efficiently, and cleanly. If you like Linux and your Palm to be as flexible as possible, learn this set of tools! Although pilot-link may not be for everyone, it just might serve you when the GUI fails.
Be sure to check out my other articles on Linux/Pilot software. The first article steps through syncing your Pilot in the GNOME environment, and the second works with KDE. Both desktop environments proved remarkable in collaborating with the Palm Pilot.

Jack Wallen, Jr., editor in chief of Linux content, was thrown out of the "Window" back in 1995, when he grew tired of the Blue Screen of Death and realized that "computing does not equal rebooting." Prior to Jack's headfirst dive into the computer industry, he was a professional actor, with film, TV, and Broadway credits. (Anyone see “The Great Gilly Hopkins”?) Now, Jack is determined to use his skills as a communicator to spread the word—Linux. Ladies and gentlemen, the poster boy for the Linux Generation!

The authors and editors have taken care in preparation of the content contained herein but make no expressed or implied warranty of any kind and assume no responsibility for errors or omissions. No liability is assumed for any damages. Always have a verified backup before making any changes.

About

Jack Wallen is an award-winning writer for TechRepublic and Linux.com. He’s an avid promoter of open source and the voice of The Android Expert. For more news about Jack Wallen, visit his website getjackd.net.

0 comments