Copilot is a Windows program that emulates the Pilot handheld PDA from US Robotics. 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.

• Pilot lookalike display (it looks like a real Pilot attached to your monitor!)
• Mouse pointer simulates the Pilot pen
• Silkscreen and Graffiti area
• Hardware buttons (on/off, app buttons, up/down, reset, HotSync)
• Zoom display and optional backlighting for better readability
• Configurable memory card size (up to 8 MB)
• Communications port emulation for HotSyncing and modem communications
• Speaker emulation
• Keyboard mapping so you can enter text with your PC keyboard
• Display frames per second control

• Break into the debugger at any time
• Debug at Startup option to start debugger immediately
• Step into, step over, step out (of subroutine)
• Stack frame trace
• Disassembler with PalmOS API labels

The Copilot package includes the following files:

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.

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:

1. Install the GetRom.prc or GetRom2.prc file on your Pilot using the normal HotSync procedure.
2. Close HotSync (you'll be using the same serial port).
3. Run GetRom.exe or GetRom2.exe with the name of the port your Pilot is plugged into on the command line (ie. COM1 through COM4).
4. Run the GetRom app on the Pilot that you loaded in step 1 (it's the app that does not have an icon).
5. Press the Start button in GetRom on your Pilot.

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:

Reset

This is similar to pressing the Reset button on the back of your Pilot.

HotSync

Initiate a HotSync. This is the same as pressing the HotSync button on the Pilot cradle.

Load app

Load a Pilot application (PRC file) into Copilot. This is quick and easy and doesn't require a serial port.

Debugger

Immediately break into the Copilot debugger. This is useful when debugging a hung program.

Exit

Exit Copilot. The contents of the RAM are saved in a file called Pilot.ram, and this file is loaded the next time you start Copilot.

About Copilot

Displays Copilot program and copyright information.

Properties

Bring up the Properties page for the Copilot display.

The Properties page for the Copilot display allows you to change several aspects of the Copilot display and operation.

Zoom 2x

The Copilot display is increased in size by a factor of two. This option is useful if the normal size Copilot display is too small, particularly on a high resolution screen.

Realistic

This option is On by default. When it is turned off, a simpler Copilot display is used that shows just the display and Graffiti area, without the rest of the Pilot hardware.

Backlight

Provides a higher contrast display by changing the background color of the LCD display area to simulate backlighting.

Enable Sounds

Allows you to turn on and off Pilot sound emulation. You should only enable this if you are running Windows NT, because Windows 95 cannot reproduce the Pilot sounds accurately.

Frames per second

Controls the number of times per second the Copilot display is updated. This number may need to be decreased for machines with slower display hardware. Little benefit is gained from increasing this number beyond 20.

RAM size

Allows you to choose the memory size that you would like to emulate. When the memory size is changed, Copilot will use a different file on disk to store the contents of the Pilot memory. For example, the 128KB option will store the RAM in pilot128.ram, and the 1024KB option will store the RAM in pilot1024.ram. The pilot*.ram files are not interchangeable. When you change this option, you will need to shut down and restart Copilot for the new RAM size to take effect.

ROM file

This is the name of the ROM file that will be used by Copilot. You may specify either the original 512K ROM file or the new 1 MB ROM file here; Copilot can tell the difference.

Port

Selects the communications port that Copilot will use to emulate the Pilot communications port. For HotSync operation, you will set up the HotSync application to use a different communications port, and connect the two ports with a null modem cable.

Debug at Startup

Normally, the debugger is activated only on a Debugger command from the right mouse button menu. If you would like Copilot to always start in the debugger, select this option. This option will take effect the next time Copilot is started.

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:

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:

g

Go. Start execution at the current address. The debugger is not reentered unless you again select Debugger from the right click menu.

r

Registers. Show the current state of the machine registers, including the next instruction to be executed.

d <address>

Dump. Show the contents of memory starting at <address>. If <address> is not specified, the memory dump continues where the last d command left off.

u <address>

Unassemble. Disassemble instructions starting at <address>. If <address> is not specified, the disassembly continues where the last u command left off.

t

Trace. Single step over one instruction.

j

Jump. Jump over a single instruction. This command essentially does the same as an f command with the "next PC" value shown by the r command. At this time, this command is not smart enough to properly handle instructions like RTS and BRA that will never reach the next PC value.

f <address>

Forward. This command executes until the PC counter reaches a specified value, then breaks back into the debugger. This can be used as a primitive breakpoint mechanism.

s

Stack. This command dumps the current contents of the execution stack by tracing back through the linked A6 values.

h,?

Help. These two commands both show a short command summary on the console.

q

Quit. Exits Copilot completely.

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!

• Graphical debugger. While the console mode debugger is getting better all the time, it is sometimes nice to use a graphical debugger like Visual C++. A graphical debugger is in the works.
• Shades of gray. The Pilot display hardware supports shades of gray on the LCD screen. If anybody were to write an application that made use of this feature, Copilot would need to support it.

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.