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...


1 Copilot

1.1 What is Copilot?

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.

1.2 Copilot Features

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

1.3 The Copilot Package

The Copilot package includes the following files:

File    Description
Copilot.exeMain Copilot program.
Pilotcpu.dllThe part of Copilot that emulates the MC68328 DragonBall CPU.
Debugger.hlpDebugger help file (text file, not a Windows help file).
GetRom.prc/GetRom2.prcPilot program to send the Pilot.ROM file to your PC
GetRom.exe/GetRom2.exeProgram you run on your PC to receive Pilot.ROM from GetRom.prc.
Copilot.htmCopilot documentation (this file).
Readme.txtLast 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:

  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.


2 Using Copilot

2.1 The Copilot Display

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.

2.2 Hardware Buttons

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/offEsc
Date BookF1
AddressF2
To Do ListF3
Memo PadF4
UpPage Up
DownPage 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).

2.3 HotSyncing

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.

2.4 Loading Applications

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.


3 The Copilot Debugger

3.1 Starting the Debugger

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.

3.2 Debugger Commands

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.

Appendices

A Future Enhancements

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!

B Thanks to...

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.


Copilot is Copyright © 1996-1997 by Greg Hewgill
This document revised 6/10/97
Email: greg@hewgill.com
Copilot Home Page