Coconut documentation

Coconut

Coconut is an effort to bring back the memories of a great 8-bit computer of the eighties: the Color Computer, or CoCo for short. I got my CoCo (actually a Brazillian clone called CP400) on december 84. Now, almost 20 years later, I thought it would be cool to once again run some of the great CoCo software, and take it with me anywhere I go. So the idea of developing a CoCo emulator for PalmOS was born, and after a few weeks of work Coconut is ready for its first public release. There is still a lot to do, but I hope you enjoy it as much as I did.

Requirements

Beeing an emulator, the first thing you will need to run Coconut are ROM files. Because of copyright restrictions, ROM files are not distributed with Coconut, so you must obtain them somehow. To make things easier, Coconut accepts exactly the same ROM files used in MESS. So, if you can emulate a CoCo on your desktop with MESS, you will also be able to use Coconut.

The hardware requirements for running Coconut are on the high end of the Palm compatible devices. Please make sure you have ALL of these, otherwise Coconut will not run:

A Palm compatible device with PalmOS 5 and ARM processor. Coconut will not run on the PalmOS Simulator.
A high density color display (320x320).
A memory card (SD/MMC, Memory Stick, etc).

Configuration

Install coconut.prc on your Palm device just like any other application. Also make sure that a memory card is inserted on your device. The first time you run Coconut it will create the necessary directory structure on your card. You will see that now there is a directory called /PALM/Programs/Coconut/ROM. This is the directory where you must store your ROM files. PalmOS does not have a file manager application for memory cards, so you have to use other means to copy the files to the right directory.

As explained in the requirements, Coconut accepts the ROM files used in MESS, and also uses the same naming convetions for machines on that emulator. Below is the list of MESS machine names and the required ROM files:

coco: the original CoCo. Requires bas10.rom.
cocoe: the CoCo with Extended Basic. Requires bas11.rom and extbas10.rom.
coco2: the CoCo 2. Requires bas12.rom and extbas11.rom.
coco2b: the CoCo 2 with lower case support. Requires bas13.rom and extbas11.rom.
cp400: the Brazillian CoCo clone. Requires cp400bas.rom.
dragon32: the Dragon 32, a slightly incompatible CoCo clone. Requires d32.rom.
dragon64: the Dragon 64, another slightly incompatible CoCo clone. Requires d64_1.rom and d64_2.rom.

You will notice that those machines are the names that appear on the Coconut main screen drop down list. Once you choose one machine, Coconut will check if the necessary ROM files exist in the /PALM/Programs/Coconut/ROM directory on the memoty card. Each found ROM will be shown in the lower half of the screen with a green check mark. If a ROM is not found, it will be shown as a red X mark. Coconut will also show some information about the machine, like long name, company name and year of production. The start button will only start the emulation if all ROM files are found. In this screen you can also choose the amount of RAM memory on the emulated machine. Not all sizes are available to all machines, but in can be 4K, 16K, 32K or 64K.

Running the emulator

After choosing the machine, RAM size and pressing the Start button, Coconut will start emulation. You will see a familiar green screen with a flashing colorful cursor. Your device Grafitti or keyboard acts like the CoCo keyboard. Write a Graffiti letter and it will be like pushing a key on the emulated CoCo keyboard. Those keys only found on the CoCo keyboard can be pushed using the buttons on the lower right of the screen. The available keys are: Break, Clear, Inverse, Up Arrow, Down Arrow, Left Arrow, Right Arrow and Reset. The Inverse key was not a real key on the CoCo, but acts like a Shift-0 key stroke to activate inverse video. The lower middle portion of the screen contains a "touchpad" that acts like the CoCo joystick. Tap or move the stylus over the touchpad to emulate the joystick movements. The lower left portion of the screen contains the following controls:

	Stops the emulation and goes back to the initial screen.
	Completely restarts the emulation. It is an easy way to regain control if something goes wrong with the emulated machine.
	Allows you to change artifacting and joystick settings. Note that you use only one joystick at a time.
	Loads a previously saved Coconut snapshot.
	Saves a Coconut snapshot. Snapshots store the contents of the RAM memory, CPU registers, IO registers, and other information needed to later restore the emulation exactly at the same point.
	Inserts a tape in the virtual cassette player. Coconut accepts CAS files from other popular desktop CoCo emulators. You must install the CAS files in the /PALM/Programs/Coconut/Cassette directory on your memory card. Note that not all CAS files will work with Coconut.
	Loads a PAK file from other popular desktop CoCo emulators. You must install the PAK files in the /PALM/Programs/Coconut/PAK directory on your memory card. Note that not all PAK files will work with Coconut.
	Selects a "virtual" disk for use. Coconut does not support the CoCo floppy drives, but allows you to use files stored in the DSK disk image format. You must install the DSK files in the /PALM/Programs/Coconut/Disk directory on your memory card. Note that not all DSK files will work with Coconut. You can also create a directory under the directory above and store binary files there.
	Loads a binary (machine language) file stored inside a DSK file, or from a directory. Note that not all binary files will work with Coconut.