Copilot User's Manual
Version 1.0 beta 9
Greg Hewgill <greg@hewgill.com>
Table of Contents
1 Copilot
1.1 What is Copilot?
1.2 Copilot Features
1.3 The Copilot Package
1.4 How To Get a Pilot.ROM file
2 Using Copilot
2.1 The Copilot Display
2.2 Hardware Buttons
2.3 HotSyncing
2.4 Loading Applications
3 The Copilot Debugger
3.1 Starting the Debugger
3.2 Debugger Commands
Appendices
A Future Enhancements
B Thanks to...
Copilot is a Windows program that emulates the Pilot handheld PDA from Palm. The Pilot is a flexible application platform - in addition to the standard PDA applications such as date book, address list, todo list, and memo pad, the Pilot can also run applications created by third party developers.
US Robotics provides Pilot development tools for the Macintosh platform. In addition to the Metrowerks CodeWarrior for Pilot compiler, a Pilot emulation library (for the Macintosh) and debugger (also for the Macintosh) are provided. This presents a problem for developers who don't have access to a Macintosh.
Darrin Massena's Pilot Software Development page discusses the problems faced by Windows based developers who want to develop apps for the Pilot. In his article Writing Pilot Applications Under Windows, Darrin presents a "wish list" of tools that would be part of a complete Windows based SDK for the Pilot. One of those items is a "Pilot Emulator", and that's where Copilot fits in. (I was reading Darrin's article and was inspired to write Copilot.)
Copilot allows Windows based developers to load applications they have created, run them right on their Windows desktop, and debug them with Copilot's built in debugger. If the application were being tested on a real Pilot, there is no way to look "inside" the Pilot to see what is really going on with the application, unless you're using US Robotics' debugger on a Macintosh. Copilot solves this problem.
Copilot has a number of features for accurate emulation of the Pilot hardware platform, plus additional features for debugging Pilot applications.
Emulator Features
Debugger Features
The Copilot package includes the following files:
| File | Description | |
|---|---|---|
| Copilot.exe | Main Copilot program. | |
| Pilotcpu.dll | The part of Copilot that emulates the MC68328 DragonBall CPU. | |
| Debugger.hlp | Debugger help file (text file, not a Windows help file). | |
| GetRom.prc/GetRom2.prc | Pilot program to send the Pilot.ROM file to your PC | |
| GetRom.exe/GetRom2.exe | Program you run on your PC to receive Pilot.ROM from GetRom.prc. | |
| Copilot.htm | Copilot documentation (this file). | |
| Readme.txt | Last minute notes and revision history. Be sure to read this file! |
Copilot requires either Windows 95 or Windows NT to run (it is a multithreaded 32-bit program). Copilot will not run on Windows 3.1, even with Win32s installed.
1.4 How To Get a Pilot.ROM file
Since Copilot emulates the Pilot hardware, all components of the Pilot hardware must be present. There is one component that I cannot distribute as part of this package: The actual Pilot ROM (as a disk file, not a chip). In order to use Copilot, you will need to obtain a copy of this ROM file yourself.
There are two ways to obtain this ROM file: Use the pair of programs GetRom.prc and GetRom.exe to transfer the ROM to your PC, or use Darrin Massena's PilotHack program.
NOTICE: Use of the GetRom program may place you in violation of your license agreement with US Robotics. Please read page 123 of your Pilot handbook ("Software License Agreement") before running GetRom.
With the introduction of the PalmPilot in March 1997, US Robotics has increased the size of the ROM from 512K to 1 MB. If you are using a PalmPilot Personal or Professional, you must use GetRom2.prc and GetRom2.exe instead of GetRom.prc and GetRom.exe. Be sure to use the correct version for your Pilot!
To use GetRom, perform the following steps:
At this point, the ROM file will be transferred in 128 or 256 4Kbyte blocks. If there is a communications error, either GetRom.exe on the PC will inform you of the error, or the status on the PC will quit incrementing the block counter. In either case, you will need to abort GetRom on the Pilot by pressing the Reset button on the back of your Pilot with a paper clip or thumbtack. If this happens, just try again. For some reason the GetRom.exe program is fairly sensitive (hey, it's just a run-once program), so it's best to close all other Windows applications, wait for disk activity to stop, and to not disturb your PC while GetRom.exe is running.
The other option is to use Darrin Massena's PilotHack program to HotSync a copy of the ROM to your PC. This procedure is explained in Darrin's Pilot Hack Tutorial page (it's the last section of the page, titled "ROMDump"). This is a rather cumbersome and time consuming procedure, but is useful if GetRom does not work for you.
Tip: When you are HotSyncing the 16K chunks of the ROM file to your PC, the process will be a lot faster if you turn off the automatic synchronization for the standard databases. To do this, go into the Pilot Desktop program, select HotSync/Custom, and change the "Action" items to "Do Nothing" for Date Book, Address Book, To Do List, and Memo Pad. Choose "Set as Default" for each item, otherwise they will reset back to their defaults after just one HotSync operation. Be sure to leave the "System" action as "Pilot overwrites Desktop", to allow PilotHack to transfer the ROMDump.PRC file. This will greatly speed up the process of transferring the ROM chunk files, since HotSync won't have to go through each database looking for new records. Don't forget to restore the original default settings when you're done.
The Copilot display looks much like a real Pilot. If you have used a real Pilot, the operation of Copilot will be obvious. To access the Copilot specific features, press the right mouse button anywhere in the Copilot window (for keyboard users, the F10 key will work too). The following selections are available on the right mouse button menu:
The Properties page for the Copilot display allows you to change several aspects of the Copilot display and operation.
The Pilot hardware buttons (on/off, the four application buttons, up, and down) are simulated on the Copilot display window. They are activated by clicking on the button image. Holding the mouse button down is the same as holding the corresponding Pilot button down.
The buttons are also simulated on the PC keyboard as follows:
| Pilot button | PC key |
|---|---|
| On/off | Esc |
| Date Book | F1 |
| Address | F2 |
| To Do List | F3 |
| Memo Pad | F4 |
| Up | Page Up |
| Down | Page Down |
An additional keyboard feature is that you can type on your PC keyboard, and characters you type will be automatically inserted into the Pilot event queue. This means that you can enter data with your keyboard instead of trying to do Graffiti strokes with your mouse (which is harder than it sounds).
Copilot includes support for emulating the Pilot serial port connection. This is achieved by mapping Pilot serial port operations to a real communications port on the PC. To perform a HotSync operation, you would connect two serial ports on the back of your machine together with a LapLink (or other null modem) cable. For example, the HotSync application would be communicating on COM1, and Copilot would be communicating on COM2. They would communicate through the null modem cable, and perform a HotSync operation just like a real Pilot would.
If you have just two serial ports and one of them is in use with a serial mouse, you can still HotSync with Copilot. You will first need to disable your mouse and restart Windows, this will allow you to use the serial port. Connect your serial ports together with a null modem cable. Start Copilot, and press F10 to get the menu, then H. This will start a HotSync operation. When it is completed, exit Copilot, reenable your mouse, and restart Windows again. I'm working on a way to make it easier to load applications into Copilot without the use of serial ports.
Tip: The first time you perform a HotSync operation with Copilot, the PC HotSync application will ask you to select a user name. It's probably best to create a new user account with a different name for Copilot. Although the Pilot Desktop software supports synchronizing a single Pilot with more than one desktop, I don't think it supports synchronizing multiple Pilots with a single Pilot Desktop.
Tip: The Pilot HotSync application (that runs on the PC) seems to be a CPU hog. This is fine when talking to a real Pilot, since the two devices are not trying to share the same CPU, but causes Copilot to run more slowly and sometimes the HotSync operation fails. A trick I've found to help this is to click on the Copilot window after the HotSync process starts; this brings Copilot back to the foreground and lets it use more of the CPU time. The whole process works better when you do this.
Copilot supports loading applications directly into the Pilot RAM without going through a HotSync operation. This is simple, fast, and makes the compile-load-test cycle much easier. When you select "Load app", a popup menu will appear with a list of the most recently loaded PRC files, and an "Other..." option to load any other PRC file. When you select a PRC file to load, it will immediately be loaded into the Pilot RAM if possible. Any existing application with the same identifier will automatically be deleted before the new version is loaded (if you're trying to replace an application that is currently running, Copilot will let you know).
Since this feature employs some trickery to load applications, it may not work in all cases. Before being moved to an application database in storage RAM, the PRC file is loaded into a scratch RAM area in the Pilot address space that does not normally exist on a real Pilot. I have loaded many applications using this method and have not yet run into any problems, but there is a possibility that this method will fail.
Note: If the debugger is running when you select a PRC file to load, the debugger will break at a SysTrap instruction during application loading. You should use the g command in the debugger to continue running after loading the application, otherwise the debugger will become confused.
The Copilot debugger is started by either selecting Debugger from the right click menu, or by selecting the "Debug at startup" option on the Debugger tab in the property page, and starting Copilot.
The Copilot debugger is currently a work-in-progress. Darrin Massena has added a number of new commands to the debugger, and the following command summaries may not reflect reality.
The Copilot debugger supports the following commands:
Here is a list of features that I would like to put into Copilot. If you have any features you would like to see in Copilot, please let me know!
Alan Chavis (The FTP Explorer) for the cool Copilot icon. Check out Alan's page for a really slick FTP client for Windows.
Darrin Massena (Pilot Software Development) for his encouragement and help while I developed Copilot. He was also my first alpha tester, and got to see some of the really early versions. (You mean that's it? I can't click on anything?)
Bernd Schmidt (UAE - Un*x Amiga Emulator) who wrote the Un*x Amiga Emulator (UAE) program. The Amiga and the Pilot are both based on the Motorola MC68000 CPU architecture, and his code was invaluable in creating the DragonBall CPU emulation.