This chapter describes how to use the Palm OS testing tools.
The Palm OS Developer Suite package provides the following testing tools:
- "Using Palm OS Simulator" describes how to use the device simulator, Palm OS Simulator.
- "Using Palm OS Reporter" introduces how to use Palm OS Reporter with Palm OS Simulator or Palm OS Emulator.
- "Using Palm OS Emulator" describes how to use the 68K device emulator, Palm OS Emulator.
- "Using Virtual Phone" describes how to use the mobile telephone simulator, Virtual Phone.
Using Palm OS Simulator
Palm OS Simulator is Palm OS recompiled for a desktop machine processor. Palm OS Simulator combines the following into a single execution environment:
Palm OS Simulator includes all of the built-in Palm OS applications, such as Address Book, Date Book, Memo Pad, and To Do List. The built-in Palm OS applications are included in the Simulator ROM file. You test your own applications by adding them to a Simulator session.
Palm OS Garnet Simulator
Palm OS Garnet Simulator is Palm OS Garnet recompiled to run on Windows. The Developer Suite package includes the most recent build of Palm OS Garnet Simulator, which corresponds to Palm OS Garnet release 5.4.
For more information on Palm OS Garnet Simulator, see the book Testing with Palm OS Garnet Simulator.
Palm OS Cobalt Simulator
Palm OS Cobalt Simulator is Palm OS Cobalt recompiled to run on Windows. The Developer Suite package includes the most recent build of Palm OS Cobalt Simulator, which corresponds to Palm OS Cobalt release 6.0.1.
For more information on Palm OS Cobalt Simulator, see the book Palm OS Cobalt Simulator Guide.
Creating a Palm OS Simulator Run Target
Developer Suite comes with two default Palm OS Simulator run targets already created:
- The debug version of Palm OS Cobalt Simulator version 6.0.1
- The debug version of Palm OS Garnet Simulator version 5.4
To create additional Simulator run targets, follow these steps:
- From the Developer Suite interface, select Window > Preferences. This opens the Preferences dialog box.
- Open the category Palm OS Development, and select Target Environment Settings.
- Select the Simulator item in the list, and click New to show the Simulator preferences.
- Enter a name for your Simulator Run Target.
- Click Browse to select a Simulator executable that you want to use for this Simulator Run Target.
- Enter any additional command line options in the Options entry field. (Command line options are listed in the Palm OS Simulator books.)
- Click OK to create your Simulator Run Target.
Using Your Palm OS Simulator Run Target
Now that you have created your Simulator Run Target, you can use it to test your application.
Testing 68K Applications using Palm OS Simulator
Palm OS Simulator runs 68K applications in PACE, the Palm OS Compatibility Environment.
- Compile your 68K application normally, using the
m68k-palmos-gcc
compiler. - In Developer Suite, select the 68K project or PRC file you want to run, and select Run. This opens the Run dialog box.
- In the notebook control, select the Target tab.
- In the Device list, select the name that you specified when you created the Simulator Run Target.
- Click Run to run your application on the Simulator Run Target.
Testing 68K Applications with PNOs using Palm OS Simulator
Although Palm OS Simulator runs 68K applications in PACE, the PNO component needs to be compiled into a DLL file using the gcc
compiler targeted for Windows.
Testing Palm OS Protein Applications using Palm OS Simulator
Palm OS Simulator does not run Palm OS Protein applications that have been compiled for ARM-based devices. To run a Palm OS Protein application on Palm OS Simulator, you need to compile the application into a DLL file using the gcc
compiler targeted for Windows.
Palm OS Simulator User Interface
The Palm OS Simulator display looks very much like a real Palm Powered handheld device, as shown in Figure 5.1. You can use your mouse to perform actions that you perform with the stylus on handheld devices, and you can use the menus to access Palm OS Simulator functions.
For more information on the user interface features, see the appropriate simulator book:
Figure 5.1 Palm OS Simulator user interface

Using Palm OS Reporter
Palm OS Reporter is a trace utility that can be used with Palm OS Simulator and with Palm OS Emulator. As an application runs on Simulator or on Emulator, the application can send information in real time to Reporter.
Figure 5.2 Palm OS Reporter main window

Using Reporter with 68K Applications
To use Reporter with 68K applications, add 68K trace calls to your application. These trace calls are listed in hostcontrol.h
, which is part of the Palm OS SDK. For more information about the Host Control API, see the book Exploring Palm OS: System Management.
Using Reporter with Palm OS Protein Applications
To use Reporter with Palm OS Protein applications, add Trace Manager calls to your application. These Trace Manager calls are listed in TraceMgr.h
, which is part of the Palm OS SDK. For more information about the Trace Manager API, see the book Exploring Palm OS: System Management.
Displaying Trace Information in Reporter
To view trace information in Palm Reporter, you need to do the following:
- Add trace calls to your application and build your application.
- Start a Palm Reporter session.
- If your run target is Simulator:
- If your run target is Emulator:
- Install your trace-enabled application in the Simulator or Emulator session.
- Run your trace-enabled application in the Simulator or Emulator session.
For more information about Palm OS Reporter, see Testing with Palm OS Garnet Simulator or Palm OS Cobalt Simulator Guide.
Using Palm OS Emulator
Palm OS Emulator is a hardware emulator program for the Palm Powered™ platform, which means that it emulates device hardware in software, providing you with the ability to test and debug Palm OS software on a desktop computer.
When you run a Palm OS application with Palm OS Emulator on your desktop computer, Palm OS Emulator fetches instructions, updates the handheld screen display, works with special registers, and handles interrupts in exactly the same manner as does the processor inside Palm Powered handhelds. The difference is that Palm OS Emulator executes these instructions in software on your desktop computer.
NOTE: Palm OS Emulator can run 68K applications; however, it cannot run applications that use PNOs or Palm OS Protein applications.
Creating a Palm OS Emulator Run Target
Developer Suite comes with a default Palm OS Emulator run target already created: Palm OS Emulator version 3.5. When you first run Palm OS Emulator, you select a ROM file. Developer Suite comes with two ROM files:
- PalmOS412_FullRel_EZ_enUS.rom, which is a Palm OS 4 release ROM file
- PalmOS412_FullDbg_EZ_enUS.rom, which is a Palm OS 4 debug ROM file
You can get other ROM files on the Palm OS developer web site:
http://www.palmos.com/dev/dl/dl_tools/dl_emulator/
To create additional Emulator run targets, follow these steps:
- From the Developer Suite interface, select Window > Preferences. This opens the Preferences dialog box.
- Open the category Palm OS Development, and select Target Environment Settings.
- Select the Emulator item in the list, and click New to show the Emulator preferences.
- Enter a name for your Emulator Run Target.
- Click Browse to select an Emulator executable that you want to use for this Emulator Run Target.
- Enter any additional command line options in the Options entry field. (Command line options are listed in the book Using Palm OS Emulator.)
- Click OK to create your Emulator Run Target.
Using Your Palm OS Emulator Run Target
Now that you have created your Emulator Run Target, you can use it to test your 68K application.
- In Developer Suite, select the project or PRC file you want to run, and select Run. This opens the Run dialog box.
- In the notebook control, select the Target tab.
- In the Device list, select the name that you specified when you created the Emulator Run Target.
- Click Run to run your application on the Emulator Run Target.
Palm OS Emulator User Interface
The Palm OS Emulator display looks very much like a real Palm Powered handheld device, as shown in Figure 5.3.
Figure 5.3 Palm OS Emulator user interface

You can use your mouse to perform actions that you perform with the stylus on handheld devices, and you can use the menus to access Palm OS Emulator functions. For more information on the user interface features, see Using Palm OS Emulator.
Using Virtual Phone
Virtual Phone is a tool which simulates a mobile telephone. Virtual Phone can help you develop and test applications which use the Telephony Manager API. Virtual Phone recognizes Telephony Manager AT commands and responds exactly the same as a mobile phone. Virtual Phone is also capable of simulating events like incoming voice calls and SMS messages.
Virtual Phone is designed to test applications which communicate with a mobile telephone. Virtual Phone is based upon the functioning of a standard GSM default phone driver. This means that any functions not supported by a standard GSM phone driver are not supported by Virtual Phone.
Launching Virtual Phone from the Workbench
Virtual Phone is included in the Developer Suite package, but to launch it directly from the Workbench, you need to define it as an external tool.
- Select Run > External Tools > External Tools... to open the External Tools dialog box.
- Select the Program category and click New to display the tool options.
- Enter a name for your tool configuration (replacing the text
New_configuration
). - Click Browse File System and select the
VirtualPhone.exe
file you want to use, either the version in the 68K SDK (sdk-5r4
) or the Palm OS Protein SDK (sdk-6
). - Click Apply to save the tool configuration.
- Click Run to run Virtual Phone.
Virtual Phone User Interface
Virtual Phone works with Palm OS Simulator to test telephony applications. Every time a Palm OS application calls a Telephony Manager function, the Telephony Manager issues one or more AT commands which are then sent to Virtual Phone. When Virtual Phone receives these AT commands it responses exactly like a real phone.
The Virtual Phone window, as shown in Figure 5.4, displays the text equivalent of the original Telephony Manager function, while the actual AT commands or traces are stored in a log file.
Figure 5.4 Virtual Phone user interface
Getting More Information
Palm OS Garnet Simulator is described in detail in the book Testing with Palm OS Garnet Simulator; Palm OS Cobalt Simulator is described in detail in the book Palm OS Cobalt Simulator Guide.
Palm OS Emulator is described in detail in the book Using Palm OS Emulator.
Virtual Phone is described in detail in the book Palm OS Virtual Phone Guide.