Program your Palm in Java: The PalmOS Emulator

Palm connected organizers have proven successful beyond the dreams of even their most devoted followers. In a few short years, Palm Computing and licensees such as IBM, Symbol Technologies, QUALCOMM, and Handspring have gone through several generations of devices and built a loyal following of users and programmers alike.

With the thousands of programmers and millions of deployed devices have come tools and emulators of all sorts. The richness of the development-tool ecosystem for the PalmOS makes the devices prime candidates for introducing Java-device programming capabilities. That is why Sun has chosen PalmOS as the reference platform for the K Virtual Machine, and why I choose to launch the technical discussion of Java Device Programming with a strong focus on Palm tools and the use of Java with PalmOS.

KVM’s development cycles and the extreme velocity on the J2ME fronts being what they are, I’ve let far too much time pass since the last installment of Java Device Programming: I pledge not to let that happen again. Luckily, Chuck McManis, a fellow JavaWorld columnist, has in the interim written a nice article on the JavaOne preview of the KVM for PalmOS, so readers have not had to go completely wanting for Java-device programming information. I will refer to and expound on much of the material in Chuck’s article in this series, particularly when I get to a more in-depth discussion of the first public release of the KVM for PalmOS. (For Chuck’s KVM article, see “The K virtual machine and the Palm V, Part 1.”)

Since my own last column I have been working frantically to put together several device-programming resources that I hope will be useful for Java programmers. These resources include a Java-device programming FAQ and mailing list, as well as the KVM Archive, a list of public domain applications, tools, and related information on J2ME and KVM development.

I shall make liberal use of these resources in the Palm-programming series and will refer to many of them this month and again in the coming months, so please bookmark the URLs.

Let’s get started!

Major Java-device APIs and initiatives, take 2

A lot has transpired on the Java 2 Platform, Micro Edition (J2ME) front even in the few short months since JavaOne 1999. Therefore, before we dive deep into the Palm platform and Java, I would like to update my July column — “Program Java devices — An overview.”

Profiles and configurations

What I wrote then about J2ME profiles is still correct. These API groupings sit on top of underlying Java runtimes and provide a certain level of portability and interoperability within classes of devices targeted at specific markets or vertical industries.

In addition, however, Sun and the J2ME development community have also seen fit to carefully specify the underlying core technologies for families of Java-enabled devices in profiles known as configurations. Configurations are meant to specify the memory and CPU requirements for target devices as well as for one or more virtual machines (such as the KVM, PersonalJava VM, Classic VM, and so on) and for core J2ME APIs that may be used to implement the base J2ME functionality on these devices.

Developers are proposing that configurations become a part of the Java Community Process (JCP). As of early October 1999, two J2ME configurations were under consideration:

• The J2ME Connected Device Configuration, for applications requiring moderate amounts of memory and a midrange CPU, such as those for digital TV set-top boxes, Internet screenphones, and automotive entertainment and navigation systems.
• The J2ME Connected, Limited Device Configuration, for applications used by memory-, CPU-, and bandwidth-constrained networked devices such as mobile phones, pagers, mobile point-of-sale (POS) terminals, and PDAs.

The JCP site has recently posted the first J2ME application profile: the Mobile Information Device Profile, which Motorola and several other community members are beginning to work on. This profile will center on mobile phones and wireless application APIs. The APIs will be specified so that they can be implemented on devices built to include support for the J2ME Connected, Limited Device Configuration. (See Resources at the end of this article for more information on J2ME configurations and profiles, as well as a link to the JCP site.)

Always remember that for consumer devices, every hardware and software decision involves resource considerations and compromises. Configurations and profiles are an attempt to engineer reasonable sets of compromises for related families of devices and end user applications.

Keep these Java Specification Requests for configurations and profiles in mind as we discuss Palm devices. Palms are exactly the sorts of devices, along with Net-enabled mobile phones, on which you will begin to see widespread Java application deployment in the months ahead.

Related note: Free briefing on J2ME for Mobile Devices

I am a big believer in free things. I love those T-shirts thrown at you from every direction at development conferences. But cool as T-shirts can be, I think free development tools and inside information are even better! I try to write about technologies that are available under open source or SCSL (Sun Community Source Licensing) or at least for some sort of free trialware period.

In keeping with that philosophy, I would like to share one more resource I have been working on over the last couple of months: A Sun-hosted briefing on the J2ME. This is an all-day event meant to give developers access to Sun engineers working on the APIs and implementations enabling J2ME-based devices and services.

If you can be in the San Francisco Bay Area on November 3, you might want to check out the Sun Headquarter Briefing on the Java 2 Platform, Micro Edition for Mobile Devices. Motorola and Nokia will make technical presentations on their involvement with Java and J2ME-enabled devices. In addition, you can hear Sun’s technical presentations on the J2ME, the KVM, configurations and profiles, and related subjects. If you are interested in attending, visit the Sun Headquarter Briefings page for the working agenda and registration information.

Now let’s turn our attention to this article’s main focus.

The Palm platform

The Palm platform consists of the core PalmOS, a set of applications included with each Palm device, and related hardware and software tools. For this series of articles, I assume that readers are either already familiar with the device, its HotSync cradle, and so on, or willing to browse through the numerous Web sites dedicated to Palm devices to learn the lingo and read up on Palm-related gadgets. (If you need to take the latter approach, a good place to start is the Palm Computing homepage, which is listed in the Resources.)

No discussion of Palm would be complete, however, without a brief rundown of the Palm devices in use and an attempt to alleviate some of the confusion over the names of the various generations of devices. Why has Palm Computing used Pilot, then PalmPilot, and now simply Palm for its devices? What do other manufacturers of PalmOS-based devices use?

The short of it is this: Palm Computing has released several generations of devices. Because of some legal issues, first with the Pilot Pen company and then with Microsoft, Palm Computing has had to carefully position and reposition their naming structure. (For more information, please refer to the “What’s in a Name — Is It a Pilot or a Palm?” in the preface of Palm Programming: The Developer’s Guide, available online for free from the URL in Resources.)

In any event, I will refer to all of Palm Computing’s devices, as well as those of the various other companies that have licensed and used the PalmOS to build their own devices, as Palm devices. I will refer to the PalmOS and its related tools collectively as the Palm platform.

The generations of Palm Computing’s own devices have so far included:

• Pilot 1000, Pilot 5000

• PalmPilot Personal, PalmPilot Professional

• Palm III (in many variations, such as III, IIIe, and so on)

• Palm V (with a sleeker case than those of previous generations, plus — finally — a rechargeable battery and recharger built into docking station)

• Palm VII (similar in form to the Palm III, but with hardware and software to access Palm.net wireless Web clipping services)

One gotcha to note here is that the release of a new generation of Palm devices does not preclude the continuing sale of previous generations. Palm III, V, and VII series devices are all currently available from Palm Computing. Users pick the model they want based on features and of course cost. In general, each new generation of Palm Computing devices has brought an increase in retail price for the new device along with steadily decreasing prices for previous generations (bless the economics of the computer industry!).

Some other Palm platform-based devices on the market:

• IBM Workpads

• Symbol barcode-scanning PDAs

• QUALCOMM’s pdQ smartphone (which includes a built-in Palm connected organizer and some custom applications that link the organizer functionality to the phone; you can tap on phone number to dial a contact, for instance)

• Handspring’s new line of Visor devices, including the Springboard expansion modules

Handspring is the newest entrant in the Palm arena. Cofounded by the creator of the Palm platform, Jeff Hawkins, Handspring announced new PalmOS-based devices, named Visor, in September 1999. I have included some Resources for more information on Handspring’s devices and, in particular, the Springboard expansion modules. Springboard promises to offer interesting opportunities for enterprising developers of both hardware and software in the coming months; stay tuned for more.

One of the beauties of the Palm platform is that, like the creators of Java, Palm Computing has expended a lot of effort to ensure the compatibility of new devices: Palm applications that run on one generation of devices should (with few exceptions) run unchanged on later generations. Java-based Palm solutions such as the KVM can therefore run on most Palm devices — unchanged. The cross-platform portability of Java is reinforced.

Up and running with the PalmOS Emulator

Even though each new generation of devices costs more than the previous one, fear not: you need not lay out a single penny to get started with Palm programming in Java. All the tools you need are available for free from the Web.

The centerpiece tool is a software emulator known as the PalmOS Emulator, or POSE. Mimicking a Palm device, POSE is a Win32 Palm emulator supported by Palm Computing. It is based on an open source emulator called Copilot, developed by Greg Hewgill and others on the Web.

The core of the Copilot emulator, in fact, is still available as open source and is a central piece of many other emulators available on the Web. Though POSE is significantly slower on many machines (including my 266 MHz Pentium II system) than PalmOS running on relatively modest Palm devices, it does give you a lot of flexibility and debugging features useful in building Palm apps. I will use POSE for the articles in this series, but please feel free to use another Palm emulator if you like. URLs for downloading POSE and other emulators are available in Resources below.

POSE is, as far as I know, the only emulator supported by Palm Computing, so your mileage may vary if you use one of the others. I will be using POSE version 2.1 d29 for this series, unless otherwise noted.

When you download and unzip POSE, you will have a directory containing

• A Docs subdirectory (read through the documentation for more on the original design of Copilot and the use of POSE)

• Emulator.exe and Emulator_Profile.exe — the actual emulator executables

• ROM Transfer.prc — a Palm application that can download the ROM image from a Palm device for the emulator to use

• HostControl.h — a header file that we will not need

I placed POSE in C:PalmPOSE on my system.

There is one remaining requirement: before we launch POSE and develop and load applications into it, we need a Palm ROM image. For the Palm platform, the ROM image contains the guts of PalmOS. POSE, in fact, actually emulates the Palm device hardware; it runs the PalmOS loaded from the ROM image within itself while handling input and output to the POSE window on your workstation.

Because a Palm ROM image contains the actual PalmOS, Palm Computing does not bundle a ROM with POSE, but rather tracks its usage with a separate download, which requires a more intricate license agreement. Whereas you can click through the POSE license and download the emulator immediately, you have to agree to a more stringent set of stipulations and wait for Palm Computing to process your ROM license request before you receive your ROM image to enable POSE.

Luckily, developers who already own a physical Palm device have a way around this hassle and delay. You can simply download the ROM image from your Palm device and use it in POSE. To do this,

1. Load Rom Transfer.prc on your Palm device using Palm Computing’s Install tool

2. Execute Emulator.exe

3. Select the option to download a ROM from the Palm device

4. Follow the downloading instructions (select the COM port, speed, and so on) and save the ROM on your development system

If using your own ROM is so easy, why wouldn’t everyone simply do it? Two reasons:

1. Not everyone has a Palm device handy when they want to start using POSE.

2. Palm Computing provides a debugging-enabled ROM when you sign its license agreement. Some POSE debugging features will not be available if you do not use the debugging ROM from Palm Computing.

I will stick to using the ROM image from my Palm V unless I need to get a debugging ROM from Palm. Even though I am using my device’s ROM, I can still use many of POSE’s debugging features, including its interestingly named Gremlins, to generate random input. Try out as many of the POSE debugging features as you can. If you find you need access to one that does not work using a device ROM, you can sign the Palm Computing ROM agreement and use the debugging version.

Note: When I tried to transfer the ROM image from my Palm V to my workstation, I had some problems with IR Link, the software I use to do infrared HotSyncs. The ROM transfer application had some conflicts with IR Link’s use of the Palm’s communications systems. In the end I removed IR Link and everything proceeded fine, but I hope to find a workaround requiring less drastic action. I’d appreciate suggestions if anyone else has a more elegant solution.

After loading a ROM image into POSE, you can create a new POSE emulation session and start using the emulator. I called my session kDemos since I’ll be setting up some KVM demo apps.

You will note that the new POSE session behaves just like a new Palm device, as seen in Figure 1. You have to go through the same pen-based input training and date/time setup. Since most development systems do not have pen-based input, POSE uses the input from your mouse as if it were the penlike stylus on a real Palm device.

You may also configure POSE to look like various Palm devices. I show a Palm III and a Palm V look in this article to illustrate this flexibility, but by loading custom faceplates you can also configure POSE to look like many whimsical Palm devices or an IBM Workpad (with a Japanese silkscreen). (Visit skinz.org from the Resources section to search for POSE faceplates, known on that site as skins.)

Note: POSE 2.1 d26 seems to have a bug that causes the Palm V faceplate to display incorrectly. On my development system, selecting the Palm V look under d26 still resulted in POSE’s emulating a Palm III. Upgrading to POSE 2.1 d29 fixed the problem for me.

You can right-click on the emulator to access its properties, save sessions, take screenshots (screen only), and turn debugging features on or off.

Now that you have POSE up and running, it is time to get a feel for Java on the Palm.

Loading a sample app: POSE and the preview KVM

Since Chuck McManis has done such a good job of introducing the early preview KVM for PalmOS, I will simply refer to his article. (As this Palm-programming series progresses, we will revisit KVM programming after a first public release is made available.) For this article, I will use the KVM for double duty, both as an example of how to load and execute a Palm application in POSE and also as an indicator of how Java performs on small devices like the Palm. We will first load the KVM into POSE, then load a few sample KVM applications (leaving code-level details for Chuck’s and my own future articles).

The JavaOne preview KVM will run in POSE and Palm devices provided they use PalmOS version 3.0 or later (equivalent to Palm III generation devices or later). In my case, the ROM image I loaded into POSE came from my Palm V organizer, so the KVM is compatible, no problem. The preview KVM has been posted to Sun’s kvm-interest list; therefore, it has been archived into the mailing list archives. I link to this from the KVM Archive (see Resources).

To install the KVM into POSE, you need to

1. Download the VM by saving the archived files KJavaVM.prc and KJavaVM.pdb: the former is the actual executable; the latter is a Palm database containing supporting J2ME and Palm-specific class files
2. Right-click on your POSE session, select Install Application/Database, select Other…, and choose KJavaVM.prc
3. Repeat step 2, then choose KJavaVM.pdb
4. Right-click on POSE and select Reset so that your new applications will show up in the emulator

Now that you have installed the KVM, it should be available from the Application launcher in POSE, from the Unfiled menu. On my POSE session, I have created a kDemos menu and moved the KVM and demo apps into that menu.

After we have installed the KVM itself, as seen in Figure 2, we are ready to install a few Java applications so that we can see simple examples of Java-enabled graphics and algorithms on devices like the Palm. I have picked three applications from the KVM Archive:

• PalmDuke, by John Riney III

• TripleTSZ, by Scotte Zinn

• kBioSig, by Michael Kroll

Note that the first time you execute the KVM, either directly or by executing a Java application that uses the KVM (such as the examples given above), you will need to accept Sun’s click-through Source Code Demonstration License Agreement. The usual caveats apply (read the whole thing, make sure you understand it, and so on). After that you will see a splash screen that indicates that the KVM is loading and preparing to execute Java code, shown in Figure 3.

Figure 4 shows the first of these example applications: PalmDuke, which demonstrates some simple interactive graphics.

In Figure 5, the second app — TripleTSZ — implements tic-tac-toe in Java and illustrates that you can build all sorts of interesting algorithms using basic programming know-how and the J2ME core libraries.

Finally, I have included kBioSig — seen in Figure 6 — as an example of how Java programming for the Palm can be used for more serious scientific and business applications, in this case for a signal-processing application.

I strongly encourage you to download and try out a number of the other applications in the KVM Archive. Most include source code and can give you a much better idea of the kinds of things that are becoming possible using Java and the J2ME on small devices like the Palm.

Additional help

For more in-depth discussions of device programming, please join the conversation on the Device Programming discussion on ITworld.com’s Java Forum. As always, if you have comments, requests, or suggestions for the column, please drop me a note.