Palm OS 3.5 Development -- Part 1, Introduction to Palm OS

• Download demo project PRC - 0.9 Kb
• Download source - 1.46 Kb

Introduction

In this series of articles, I intend to demonstrate the still-useful Palm OS 3.5 as a development platform.

What? Palm OS 3.5? Isn't that an obsolete technology?

Well, yes, but old Palm handhelds are inexpensive, and still plentiful new and used, available in many models from Palm and competitors like Handspring, Sony, etc. and even in mobile phones. This is an excellent platform to hone skills on an embedded platform by developing handheld tools.

Of course, there are already a couple introductory articles on Palm OS at CodeProject. But, not to discredit the authors, I feel there are some details missing that I intend to convey in this series. What these articles intend to cover is to introduce the reader to the essential tools and techniques to coding your way into the Palm handheld platform. What these are not going to cover is using the Palm as a state-of-the-art PDA for personal organization, wireless communications, and gaming; because it is not.

I'll begin this introduction at a beginner level, giving the reader just enough to begin their own adventures, and then ramp up to intermediate in the following article. For example, I will use the Palm IIIc that I bought refurbished from eBay for under $100 shipped. It came with a HotSync cradle and charger. I added a HotSync serial cable for about $10 found on Amazon which plugs into the handheld without a cradle, ideal for connecting to mobile serial devices.

Background

With the release of Palm OS 3.5, the last release of the third major revision, the Palm OS platform is complete with features like: color, high resolution, expansion ports, etc. These run on Motorola 68000-compatible Dragonball chips.

The next major revision, Palm OS 4.0, released with the Palm m500 series, is downward compatible with 3.5 applications and adds some additional features, like SD card access and some UI improvements. Following 4.0 are, the Palm OS 5.0 Garnet release, and later the Cobalt version. With 5.0+, Palm handhelds switched to ARM processors and the OS became largely redesigned. Palm OS 5.0+ handhelds could run 68 K applications in a compatibility mode.

In these articles, Palm OS 3.5 was chosen as the most common of the 68 K processor models, most having enough memory and the basic features needed in a Palm for developing custom tools.

Technology Overview

Memory

Built-in memory varies, but most models have 8 MB. Some will have expansion ports that can take memory cards.

Graphics

The standard resolution for color and black/white Palms was 160x160, with the high resolution versions doubling that at 320x320. Black/white Palms have a momentary backlighting feature, but it's mostly useless as it doesn't stay on for long. Color Palms are the best choice as even its first iteration Palm IIIc includes a bright, easy to read color display.

Sound

Beep. Boop.

User Interface

Palm has always been known for its innovation in touch-screen input using its graffiti notation. The Palm has full touch screen resolution of its entire display plus the additional 'buttons' and graffiti drawing range. With some practice, you can easily write faster in graffiti than with a touch keyboard a-la Pocket PC. But, if you prefer, you can select an on-screen keyboard for 'tapping' input.

Interconnectivity

Most Palms running Palm OS 3.5 or newer will have at least two communication ports: infrared and RS232 serial. The infrared is usually located on the top of the unit and can be used for anything from Hotsync, Palm-to-Palm transfers, to TV remote control. The serial port can operate at common transfer speeds with the aid of a HotSync serial cable or standard cradle.

The Palm VIIx model has a wireless transmitter/receiver built in that communicates on a low-bandwidth cellular network, with a price.

Some of the later models have integrated Bluetooth wireless.

Battery

Some Palms take batteries, and others, like the IIIc, have a built-in lithium-ion rechargeable.

Getting Started with Palm OS Development

Requirements for Development

• Palm Desktop or Palm OS Conduit Development Kit (CDK).
• Cross compiler to Palm binary.
• Palm resource compiler and PRC build tools.
• Palm handheld and/or Palm Emulator.

Palm Desktop vs. Palm OS CDK

The Palm Desktop is the freely downloadable PC application that suits the handheld's PDA capabilities directly and includes PC-side PDA tools to maintain synchronized data. When you HotSync with the PC, the HotSync Manager, included with the Palm Desktop, will be able to read from the synced databases on the PC. No synchronization with other PIM software is necessary, unless you want to interface with them. The HotSync Manager is what you need to install compiled PRC and PDB files onto the Palm handheld.

Now, if you intend on developing HotSync conduits, you will want to consider installing the Palm OS CDK (Conduit Developer Kit) instead. This provides the same HotSync tools, also with some debugging functionality and SDK documentation, but no Palm Desktop. This is the topic coming up for part 2.

You should probably choose one or the other to install, because they both try to install using different Palm home directories, thus causing conflicts on where the user data and executable files are located. It is probably possible to have these coexist, but I will leave that as an exercise to the reader.

The Open Source Option: PRC-Tools

This series will be based upon Palm OS development using the open source PRC-Tools. This is a Cygwin add-on package that provides a GNU C/C++ cross compiler for the Motorola 68000, linker, and debugging tools.

Note: If any of the downloadable material is no longer available, please contact me so I can fix the links or provide other means.

First, install Cygwin. The default installation options will work fine.

Create a directory on your PC that will be the root of all Palm OS development. Call it PalmDev.

Download the latest available Palm OS SDK for 68K platforms and PRC-Tools from PalmSource. Note: You will need to register (for free) to access this link. Download one of the packages labeled for PRC tools and install it in your PalmDev directory, so that you have the SDK-5R3 (or whatever version is available) directory in PalmDev. The Windows installer .exe will give you useful tools, docs, and samples, but cannot be used alone for PRC-Tools because it is geared towards the Metroworks CodeWarrior development environment.

Then, follow the Cygwin installation instructions from the PRC-Tools site. Be sure to download all Palm OS related packages, complete the steps for creating the PalmDev tree, and then initialize the SDK with PalmDev-prep.

POSE: Palm OS Emulator

POSE may be your best tool for testing and debugging your code without wasting away the batteries in your Palm.

When installing POSE, be sure to also get the skins. What you won't get by default is a ROM image to run the emulator. You can get generic ROMs from PalmSource. Or, you can use the ROM Transfer.prc utility that comes with POSE to download the ROM of your unit.

Debugging with POSE

GNU Debugger

PRC-Tools includes the GNU debugger and it works just as well through POSE. It's terse, it's ugly, but it works.

Once you have built PRC with debugging enabled (-g option in GCC), install the PRC to POSE by drag and drop. Then, type this at your bash shell:

$ m68k-palmos-gdb helloworld
(gdb) target palmos
Remote debugging under PalmOS using localhost:2000
Waiting... (Press Ctrl-C to connect to halted machine)

Note: You will need to specify the compiled binary file without the .prc extension.

Now, gdb is waiting for POSE. Execute the application in POSE and gdb will wake up and begin debugging.

POSE Debugging Options

POSE itself provides many debugging options. By default, POSE will alert you when the application tries to access bad pointers, for instance. View all the options by right-clicking POSE and clicking Settings->Debugging...

PalmSource gives you the option to download debug ROMs for Palm OS. These give additional instrumentation by alerting the user of certain warnings that the release ROMs would not, or in some cases highlight the display with different colors to indicate control boundaries.

Hello World on Palm

helloworld.c:

#include <PalmOS.h>
#include "resource.h"

Boolean appHandleEvent(EventType *e);
Boolean mainFormHandleEvent(EventType *e);

FormType *mainForm;    /* Form handle to mainForm */

/* Program entry point */
UInt32 PilotMain(UInt16 cmd, void *cmdPBP, UInt16 launchFlags) { 
   EventType event;
   UInt16 err;

   switch (cmd) {
   case sysAppLaunchCmdNormalLaunch:
      FrmGotoForm(mainFormId); /* Start mainForm on app startup */

      do {  /* Event pump */
         EvtGetEvent(&event, evtWaitForever);

         if (!SysHandleEvent(&event) &&
            !MenuHandleEvent(NULL, &event, &err) &&
            !appHandleEvent(&event)) {
            FrmDispatchEvent(&event);
         }
      } while (event.eType != appStopEvent);

      FrmCloseAllForms();
      break;
   }

   return(0);
}

/* Application event handler */
Boolean appHandleEvent(EventType *e) {
   switch (e->eType) {
   case frmLoadEvent:
      /* Load form */
      switch (e->data.frmLoad.formID) {
      case mainFormId:
         /* Set event handler for mainForm, then make it active */
         mainForm = FrmInitForm(e->data.frmLoad.formID);
         FrmSetEventHandler(mainForm, mainFormHandleEvent);
         FrmSetActiveForm(mainForm);
         break;
      }
      break;

   case frmOpenEvent:
      switch (e->data.frmOpen.formID) {
      case mainFormId:
         FrmDrawForm(mainForm);
         break;
      }
      break;

   default:
      break;
   }

   return(false);
}

/* mainForm event handler */
Boolean mainFormHandleEvent(EventType *e) {
   switch (e->eType) {
   case frmOpenEvent:
      FrmDrawForm(mainForm);
      return(true);

   default:
      break;
   }

   return(false);
}

helloworld.rcp:

#include "resource.h"

version "1.0"

/* Main form */
form id mainFormId at (0 0 160 160)
begin
   title "Hello World"
   label "Hello World" id helloLabelId at (center center)
end

From a Cygwin bash shell, run make to build helloworld.prc.

$ make
m68k-palmos-gcc -O2 -Wall -g -c -o helloworld.o helloworld.c
m68k-palmos-gcc -O2 -Wall -g -o helloworld helloworld.o
pilrc -q -allowEditID -ro -o helloworld.ro helloworld.rcp
build-prc -n helloworld -c helo helloworld helloworld.ro

Once built, you can load helloworld.prc into your Palm. Usually, you can do this by double-clicking the .prc file in Explorer and it will run the Palm Installer. On the next HotSync, the .prc will be loaded. Once done, you should be able to find the new application:

Basics of a Palm Application

Creator ID

Every application must have a unique Creator ID, a four character alphanumeric string. This ID is also placed on an applications database(s) that identifies which application it belongs to. It is important to use a unique Creator ID that no one else happens to be using, to prevent conflicts. For this reason, it's important to check the Creator ID Registration.

Memory Allocation

A special point on memory allocation in Palm OS is that memory is allocated in "chunks" using the Palm OS API, not malloc(). Chunks are allocated as either movable or nonmovable. Nonmovable chunks are created with MemPtrNew() and works just like malloc() in that it returns a usable memory pointer. However, movable chunks, allocated with MemHandleNew(), have the advantage of letting the OS move the memory chunk around the address space for optimization. When you want to access the chunk, you use MemHandleLock() to obtain the usable memory pointer. While locked, the chunk becomes temporarily unmovable.

More details about the memory architecture can be read in the Palm OS Programmer's Companion, vol. I.

Event Handling

Like the Windows API, a Palm application will contain an event pump, much like Windows' message pump. In the event pump contains a system event handler, menu event handler, and an application event handler. If none of these catch, it goes to FrmDispatchEvent(), which will send the event to the current form's handler.

Data Storage

Data are stored as files, but the underlying mechanism is a database. In each database are any number of records, which contain an ID and a memory block. The application is responsible for breaking the memory block into usable fields.

Palm OS 3.5 only supports one database type: Classic. The SDK may describe extended and schema database types, but these are supported only on Palm OS 5.0+.

You can use the freeware Filez utility to browse and edit the file structure on the handheld.

Conclusion

You now have the knowledge and resources to begin coding your Palm handheld. The excellent documentation on Palm's website explains all the bells and whistles of the software and hardware components of any Palm model.

In the next part, I will cover the HotSync conduit platform to connect your Palm data with the PC.

References

• Palm Desktop
• Palm OS SDK (requires free registration).
• Cygwin.
• PRC-Tools site.
• PilRC site.

  Note: You can find the reference docs to PilRC installed via Cygwin at /usr/share/doc/pilrc-3.2, or via Windows at c:\cygwin\usr\share\doc\pilrc-3.2.

• POSE: Palm OS Emulator.
• Palm OS SDK documentation: The programmer's companion and reference are most useful, also check the User Interface Guidelines.
• Mailing lists for Palm OS technologies.
• Creator ID Registration: guarantee your ID is unique.
• "Palm OS Programming: The Developer's Guide" by Neil Rhodes and Julie McKeehan, O'Reilly, ISBN 1-56592-856-3.

A great example of ingenious use for a Palm is Dmitry Yurtaev's MMCd Datalogger, an open source project using Palm handheld to log diagnostics of pre-OBDII model year Mitsubishi cars. A screenshot is seen at the top of this article. I use this tool for my own 1991 Mitsubishi Galant VR-4.

History

• 2005.12.19: Published.