Lightweight CocoFLASH programming software for the Coco 1/2
The CocoFLASH is a nifty piece of hardware produced by Retro Innovations. It is a 8MB flash ROM cartridge for the Radio Shack Color Computer series. Its massive size allows for numerous titles to be loaded onto the cartridge and it includes a menu program for choosing the title at boot time.
CocoFLASH also comes with very nice software for reprogramming the ROM and customizing the menu. It allows the menu to be customized using BASIC and new software to be downloaded via DriveWire. Unfortunately these features require 64KB of RAM and Extended Color BASIC. Not all CoCos are as nicely equipped, especially my CoCo 2 with 16KB of RAM.
So, I have written a set of replacement tools that only require 4KB of RAM and Color BASIC. This should work on any model of CoCo, though it has currently only been tested on a 16KB CoCo 2.
The idea for this project came from the
c2t software used in the Apple II
world. To transfer software to the target computer, one simply connects a host
computer's sound card to the cassette port, types a single command on the
target computer, and plays back a single WAV file from the host. No further
user interaction is required. While the process is multi-stage, delays are
built into the WAV file to allow the target to do its work.
Running on the "lowest common denominator" CoCo hardware requires careful conservation of RAM. This means that:
- All target code is written in assembler.
- As much work as possible is offloaded to the host.
Sticking to assembler also eliminates compatibility differences between the different versions of BASIC.
The term "host" is used to describe the modern computer used to facilitate downloading of new ROMs to the "target" computer (a CoCo). Binaries are provided for Linux, Windows, and MacOS X. The host tools are written in "vanilla" C so any host with a C compiler should be able to be used. Obviously, this host must have a sound card and be capable of playing WAV files.
Programming a ROM
An audio cable is required to connect the host to the target. The original CoCo cassette cable should work. If you don't have one you can make your own or order a replacement from Cloud9.
Programming the CocoFLASH is a multi-step process:
- Download a ROM image to the host computer.
- Choose a target bank.
rom2wavto produce a WAV file.
CLOADM:EXECon the CoCo and press ENTER.
- Play loader.wav to download the programming software.
- Play the WAV file produced in step 2. This step can be repeated to do multiple ROMS.
- Press the RESET button to exit the loader.
rom2wav -b 28 EDTASM.ccc -o edtasm.wav
Will create generate
edtasm.wav from the
EDTASM.ccc binary and place it at
bank 28. Use
rom2wav with no arguments to see a full list of options.
By default, programming will fail if any block of the target ROM is already in use.
-e option will cause the target blocks to be erased first. Use with caution
as this could cause neighboring ROMs to be erased as well due to idiosyncrasies of the
CocoFLASH ROM and banking structure. Consult the CocoFLASH documentation for an explanation
of this or simply always choose a starting bank of 12 plus a multiple of 16.
If programming fails, you are prompted to press a key. If it succeeds, the loader listens for the next file. This allows for unattended operation which is useful since this process is a bit slow.
Updating the menu
This project also provides a replacement for the CocoFLASH's BASIC-based menu.
The layout of the menu is kept in a text file on the host computer. The host
regenerates the menu binaries and they are downloaded to the target using the
same process as ROM cartridges.
The text file is a simple comma separated value (CSV) file. The first field is the name of the entry the user will see. It should be 30 characters or less and will be translated to upper case. The second field is the bank number. It may be specified in decimal, hex, or octal using the C conventions (e.g. 123, 0x20, 0377). The last field is the "config" value. For more information on these values please consult the CocoFLASH manual.
Menu files may also contain blank lines or comment lines (prefixed with a semicolon). The parser is pretty lame, so don't get crazy with it :-)
Process for updating the menu:
menu.csvusing your editor of choice.
makemenu menu.csv menu.romto produce a ROM image.
rom2wav -b 0 -e menu.rom -o menu.wavto produce a WAV file.
CLOADM:EXECon the CoCo and press ENTER.
Users may find it more convenient to edit the CSV prior to downloading
target ROMs as it makes managing the banks easier. Also, the downloads
can be combined into a single session i.e.
Managing ROM Contents
An additional utility called
map.wav is included. This tool lets you view a map
of the CoCoFLASH ROM banks. Used banks are drawn with an X and free banks with a -.
The contents of a bank may be viewed in either hexidecimal or ASCII by pressing H
or A respectively.
The map tool can also be used to erase banks by pressing E. The surrounding banks affected by the erase operation will be highlighted and you will be asked to confirm the erase.
To run the mapper, type
CLOADM:EXEC on the CoCo, press ENTER, and play
from the host computer.
Keeping ROM tools in ROM
The loader and mapper tools may also be programmed into the CoCoFLASH ROM and
accessed from the menu. To accomplish this, ROM-friendly versions of these are
map.rom. These may be programmed using
loader.wav as included in
menu.csv as outlined in the previous section.
Use a config value of 2.
The ROM versions of these tools return to bank 0 (the menu) on exit.
Recompiling requires a standard
gcc toolchain plus the following tools:
makewavfrom the Toolshed project (https://github.com/boisy/toolshed).
After installing these prerequisites, simply type
make from the
The Win32 version is built by installing mingw-w32 on a Linux host system and
compling it using
mingw32-make OS=win32. If you don't have a Linux host system,
it should be a trivial exercise to compile them under MinGW on Windows or even
The idea came from Egan Ford's
c2t utility for the Apple IIs (https://github.com/datajerk/c2t).
The core ROM programming/erase routines came from the original CocoFLASH software written by Barry Nelson (https://github.com/go4retro/CocoFLASH).
rom2wav is based on
makewav from the Toolshed project (https://github.com/boisy/toolshed).