O'Reilly Network    
 Published on O'Reilly Network (http://www.oreillynet.com/)
 See this if you're having trouble printing code examples

Making the Palm/Linux Connection

by Chris Halsall

Also in Linux and Your PDA:

A Palm Introduction - The gizmo that's taken the handheld marketplace by storm

All Linux PDA: Fact or Fiction? - Have you heard about the Yopy?

Linux and Unix users are often pleasantly surprised by how much software is available to support PalmOS devices. In addition to the traditional graphical "Palm Desktop" environment programs like J-Pilot, there exists a large quantity of low-level and specialized tools for communicating with, managing, and even emulating the Palm.

Practical Pilot-Link

Included with most modern Linux distributions now is a package called "pilot-link," written by Kenneth Albanowski. This suite of tools and libraries enables communications between a Unix environment and a Palm though the serial port, and is used by many other programs to take care of the messy details. Language bindings exist for C, C++, Python, Tcl, and Perl. If you find you don't have pilot-link installed, or want to upgrade, download locations can be found at FileWatcher).

A few Pilot-Link tricks

There's a little bit of configuration needed to allow pilot-link to establish a connection with a PalmOS device, specifically dealing with the serial port the Palm is connected to. It's a good idea to set up a symbolic link from /dev/pilot to the proper serial port. For example, if your Palm Pilot's cradle is connected to the second serial port, execute the command ln -s /dev/ttyS1 /dev/pilot as root. To make sure every program can access the port, execute the command chmod 666 /dev/ttyS0 (again, as root).

The default communications speed used by pilot-link is a miserable 9600 baud. The environmental variable "PILOTRATE" can be set to the desired baud rate, such as 19200, 38400, or even 57600. Don't set this too high though, or communications errors will slow things down even worse. It's also possible to override the serial port used by setting the environmental variable "PILOTPORT." Since some other programs don't look at this variable though, I recommend having the sym-link set up as above as well.

The tools included in the pilot-link package over many different services, all command-line oriented. Be aware that some of them are experimental, so it's a really good idea to back up your Palm before using them. man pilot-link to see a list of all the included commands, what they do, and their stability status. Several of the commands also have man pages of their own.

If your Palm has never been used before, you will need to set the UserName on the device before any other communications can be done. This is done using the "install-user" command, and need only be done once. Unlike the other pilot-link components, the serial port must be explicitly passed, so install-user /dev/pilot yourname 500 would set the username to "yourname" and the UserID to 500. The UserID parameter is optional, but I like to set mine to be the same as my Unix user ID.

The Handy Pilot-xfer

The most useful tool included is probably "pilot-xfer," which has its own man page, and is able to do most of the data exchange needed day-to-day. To back up your Palm, for example, simply execute the command pilot-xfer -b BACKUP_DIRECTORY, place your Palm in its cradle, and press the hot-sync button. Every program (.prc) and database (.pdb) file on the Palm will be transferred and stored in the directory. To synchronize all the files, execute the pilot-xfer -s BACKUP_DIRECTORY command. To completely restore instead (for example, after a hard-crash), use pilot-xfer -r BACKUP_DIRECTORY.

It's also possible to install a new program or database file on a Palm by running pilot-xfer -i FILE. To see a list of all the files in a Palm's memory, execute pilot-xfer -l. Note that the list doesn't include the ".prc" or ".pdb" suffix, so when you fetch a file back with pilot-xfer -f FILE, FILE should not include the suffix. In fact, if it's given, the transfer will fail with "unable to locate database" message.

We have only really scratched the surface of what is possible using the tools inside the pilot-link package. As shown here, the package allows full, if only command-line, support of a Palm's file system. I encourage you to look at the pilot-link, pilot-xfer, and related man pages for additional tools and abilities. And if you're writing a user-space Palm-enabled application, you would likely save yourself a lot of development time by leveraging on the included libraries.

Cool Palm with Linux Tricks

All Palms sold today have the ability to establish a PPP (or [C]SLIP) connection though the serial or Infrared port. Some models go further, and have wireless Internet connectivity, which will become more common in the near future. If you don't have the luxury of a wireless connection, interesting things can still be done with the Palm networked through the desktop computer.

To set things up on the Palm side, go to the Preferences application, Connection section. Select "Direct Serial" (or "IR to a PC/Handheld"), and click "Edit...". Set the Connection Method to be appropriate, if not already, and then click "Details..." and set the Speed to be the highest you've been able to communicate with the Palm reliably. Then click "OK" twice to return to the top level.

Next, go to the Network section, and select the UnixPPP from the Service pull-down menu. Leave "User Name" blank, Password as "Prompt", and set the Connection type to be "Direct Serial" (or again, "IR to a PC/Handheld"). Click on "Details..." and set the Connection Type, DNS, and IP Address fields as appropriate. Lastly, click on "Script..." and set the first statement to be "End". Click OK twice to return to the top of the Network section.

At this point, the Palm is ready to establish the connection. The next step is to set the Unix environment to host the connection. As root, run the command /usr/sbin/pppd /dev/pilot BAUDRATE HOST_IP:PALM_IP proxyarp passive silent persist local noauth, replacing BAUDRATE, HOST_IP and PALM_IP as appropriate. The command should return silently after a few seconds unless something went wrong. Additional run-time information is available in /var/log/messages. No other program can be using the serial port while this is running, so that's the first thing to check for if the command fails.

Lastly, if using the Serial port, place the Palm in its cradle -- or, if using IR, point the Palm's IR port at the computer's -- and press Connect. A small notice titled "Service Connection Process" will pop up reporting "Initializing", then "Signing on", and finally "Established". Then the notice will go away, the "Connect" button will change to be "Disconnect", and a small vertical light will blink in the far top, right-hand corner. To test your connection, try pinging the Palm's IP from the desktop machine. If the connect can't be established, check the log messages and double-check that the IP numbers given are correct.

Once the connection is up and running, you have a network between the Palm and the desktop computer. In order to allow the Palm to connect to other machines on the Internet, it needs to be routed appropriately. Network routing is beyond the scope of this article, but a simple example would be to execute the command /sbin/ipchains -A forward -j MASQ -s PALM_IP -d as root on the host machine, replacing PALM_IP as appropriate. Now the Palm is able to connect to any machine on the Internet, assuming the host machine is connected itself.

Don't let it power-off

One undocumented trick that is really handy when doing networking with the Palms is the .3 shortcut. Normally, the Palm will power off after one to three minutes of inactivity, but when networking, it's often desirable to have the unit remain on for an extended period. By entering the shortcut symbol (see your Palm manual or the Graffiti help), and then .3, the auto-power-off function is disabled. Be careful when entering this though, as some other .n shortcuts are rather dangerous.

Internet tricks

OK, so you've got your Pilot on the Internet. Now what? Well, by default a Pilot can't do much more than establish the connection. Actually using it requires third-party software. In additional to several commercial web-browsers for the PalmOS, there are also many interesting free and GPLed tools available. Two examples we'll look at briefly are a (very simple) httpd web-server, and a VNC client.

VNC Client screenshot

VNC Client -- Yes, that really is a Windows desktop you see on that Palm.

The httpd server for PalmOS, written by Jim Rees and Mark Eichin and available at Rees' site.), is a very specialized, minimalist server, and does not serve arbitrary files. Instead, it presents a series of web pages, which lets one drill down into the Palm's Datebook, Memo, and Doc Files. While it may seem like a strange idea, this actually presents a fairly handy way to gain access to documents on a Palm. Note that as masqueraded above, only the host computer would have access to the web server.

Another surprisingly useful, not to mention amusing, Internet tool for the PalmOS is a Virtual Network Computer (VNC) client. This little Palm application actually lets you access and control a VNC server on a Windows or Unix box. It's practical on the road (through a dial-up modem when no other option is available), but it can be even more fun to watch friends' eyes bug out as you show them what your Palm is currently doing.

There are many other Internet-enabled Palm apps available, some free but many commercial. Everything from News group readers to a simple network time protocol client. With most hand-held devices expected to have wireless Internet connectivity within a year's time, trying out what's available now helps us to see where things might go. Besides, it's just too fun, and too easy, not to do.

The PalmOS Emulator (POSE)

Palm simulation screen shot

Using a downloaded ROM image, a fully simulated Palm OS environment is available.

It's possible to completely simulate a Palm Pilot under Linux, using a GPLed program called the PalmOS Emulator, or POSE for short. POSE, supplied and actively supported by Palm Computing, was forked from XCopilot, a community project which was itself forked from the Amiga emulator UAE. Available in binary forms for Windows or Mac, or source code form for Unix, POSE provides a complete emulation of the various Palm Pilot hardware versions.

POSE uses the "Fast Light Tool Kit (fltk)", which is not commonly distributed with Linux. It is available from the (URL:fltk home page) and is quite simple to build. Be sure to install this first (or make sure you have it) before trying to build POSE, or it simply won't work.

To use POSE, download the Unix version and unpack in a temporary directory on a partition with at least 30 megabytes of free space. It will create a subdirectory starting with "Emulator_Src_". Change into this directory, and you'll see there are several subdirectories. The most important is "Docs", within which it is advisable to spend some time reading the excellent documentation.

The actual building of POSE takes place from within the "BuildUnix" directory. The usual ./configure will create a Makefile appropriate for the host environment. Providing there are no missing libraries or other errors, running make will, after a rather long time, build POSE and several support programs. make install as root will place the "pose" executable in the /usr/local/bin directory for general use.

It's important to note that POSE only simulates the Palm Pilot hardware, but doesn't include any of the PalmOS code. For this, a ROM image is required. These can be downloaded from a real Palm device using a Palm application called "ROM Transfer," included in the POSE package. Don't use the ROM transfer programs included with pilot-link on newer Palms, as the programs don't understand the larger ROM sizes. Alternatively, if you sign up as a Palm developer (no cost), you can download ROM images from the Palm Computing web site. Details are available here.

To download an image from your own Palm, first upload the "ROM Transfer.prc" application from the ROMTransfer/Source directory to your Palm, and then launch POSE. Right-mouse-button brings up a menu; select "File -> Transfer ROM...", or press Alt-D. A window will pop up with instructions. Follow these, and a few minutes later you'll have a ROM image on your hard drive. Developers often have several different ROM images available to test with.

Once a ROM image is ready, select "File -> New" from the menu, or press Alt-N, and you'll be able to select the Device type, the Skin, how much RAM is on the machine, and the ROM file to use. Using unmatched ROM to Device types can be unpredictable, so try to only use appropriate settings. Using a IIIe's ROM under the IIIc hardware doesn't work, for example.

Once you press "OK," and providing you've given a legal ROM image, the emulated Palm should boot up as if a real Palm had just been turned on for the first time. You can upload applications and databases from the menu, but you need to reset the device after uploading before they're seen.

POSE is a very useful tool, for both Palm developers as well as end users. If an application breaks the rules while running under POSE, the emulation is halted and an informative message is posted as to what went wrong. The user then has the option of continuing with the applications, or exiting. POSE also has something called "Gremlins," 1000 of them to be exact, which abuses applications in reproducible ways to try to break them.

The use for developers is obvious, but for end users who can't figure out why their Palm is acting strange, often only a few minutes with their regular applications within POSE will show which if any are misbehaving. Of course, in an ideal world, the end user would never have to do this, but reality being what it is, it's sometimes very handy.

Like pilot-link, all the abilities of POSE are beyond the scope of this article. The documentation included with POSE is of extremely high quality, although the best is only included in .pdf format.

Time to play

We've discussed a number of fun things to do while making the Palm/Linux connection. Now it's time to try them out for yourself. If you discover additional tips and tricks, send them to me, and we might just include them in our next Palm article.

Chris Halsall is the Managing Director of Ideas 4 Lease (Barbados). Chris is a specialist... at automating information gathering and presentation systems.

Discuss this article in the O'Reilly Network Linux Forum.

Return to the Linux DevCenter.


Copyright © 2009 O'Reilly Media, Inc.