Downloading Programs to a CoCo

There are two problems to be overcome in downloading programs to your CoCo 1 or 2. The first is just getting your CoCo to listen to another machine; the second is getting it to recognize that the data it received constitutes a program, and not just a data file.

Note before proceeding that these programs were written for a CoCo 1 or 2 with a disk drive, to download ASCII BASIC programs. I doubt that they would work on a CoCo 3, they would need some small changes to be able to download tokenized BASIC, and they certainly won't work without a disk drive. (But if you want a cassette version, let me know, and I'll put it on my list of things to do.)

I have three programs freely available to handle these tasks. Unfortunately, these must be typed-in by hand. Even more unfortunately, one of them is a machine-language program, which means entering it by hand is tedious and error-prone. So, the first of these three is a small BASIC program that makes the machine-code entry easier.

That first BASIC program, called BINENTRY.BAS, reads its input one line at a time, and part of each line is a checksum. If any typos were made on a line, the checksum will not match, and the computer will beep and prompt you for the same line again. The task is still tedious, but at least you will know when you are done that it was done right.

The machine-code program that you then key in, COMM4.BIN, is a small communications program. It knows how to get data from the serial port at 9600 baud (eight bits, no parity, 1 stop bit). It simply leaves this sitting in memory, starting at address 4000 (hexadecimal). It is up to some other program to do something good with that. If you downloaded machine-code, you could just save it using the SAVEM command. However, if it was a BASIC program, there is just no built-in command to tell Color BASIC to save it from memory like that with the right file type.

The third program, SAVEBA2, calls COMM4.BIN, and then handles the saving-to-disk part. It reads through the memory buffer that the communication program filled, and writes it out as a data file. The clever bit is, after writing it out, it does some low-level work on the disk to find the directory entry for that file, and adjusts its file type to be BASIC saved in ASCII format.

All told, there are about ninety lines of BASIC you need to type, followed by about twenty-five lines of machine-code. Once that is done, you will be able to download programs to your Color Computer through its serial port! It still takes a little work, but you should never again need to key in another program that you find out there.

Details

  1. The wire

    You will need a cable to connect your CoCo to your other computer. Assuming that the other computer meets the RS-232C spec, and is wired as DTE, you would wire the cable as follows. The CoCo end is a DIN-4 connector, the other end is a DB-25:

    For a cheesy ASCII-art picture of the DIN connector pinout, see my description of the serial port, but note that the picture there is of the connector on the back of the machine; depending on which way you look at it, the connector that plugs into it will be numbered backwards. Be careful!

    I have found it tremendously useful to have one of those RS-232 line testers, with LEDs showing which lines are being driven high or low. Before connecting things together, I plug that into each of the two connectors, one at a time, and see that they are not both trying to transmit on the same wire. If they are, I know I need a null-modem in between them.

  2. Entering the programs

    This is the easy part. Tedious, maybe, but straightforward. Double-check for typos! These programs POKE bytes into memory, and do low-level munging on the disk's directory, so any mistakes could result in horribly trashed disks. Check your work! And test them on a scratch disk!

    Enter and save the two BASIC programs first: BINENTRY and SAVEBA2. Then run BINENTRY.BAS as follows to enter COMM4 in BINENTRY format and save it as COMM4.BIN as follows.

  3. Using BINENTRY

    This program wants a filename to save, and then a pile of binary (actually hexadecimal) data. Give it COMM4.BIN as the filename, and then enter the data. If you make a typo, it will beep and prompt you with the same line number again. Only when a line has been entered correctly (ie: only when the checksum matches) will it prompt you with a new line number. Don't ignore the beep or the line-number prompt! It will not accept the next line until the one that it is asking for has been properly entered.

    After you enter the last line, it will automatically save the data into the file you named.

  4. Using COMM4

    Although you could run COMM4.BIN by itself, and then do anything you like with the data that it leaves in its buffer, it is much easier to let SAVEBA2 call it and save the results for you. This is described next.

  5. Using SAVEBA2

    Despite the long description that follows, SAVEBA2 is easy to use. Run it, enter a filename, hit 'Enter' once or twice at the right times, and then enter 'Q' to finish. The main drawback is that it is very slow.

    SAVEBA2 uses COMM4.BIN to handle the reading of the serial port, but then does the extra work of saving the received program into a data file, and changes its type to BASIC ASCII.

    Since we have only a 16K buffer to work with, huge programs will have to be sent in chunks. SAVEBA2 will call COMM4.BIN repeatedly, appending all received data into the same file, until you tell it to stop. On the computer that is sending the file, you should edit it into pieces that are less than 16K each, and send them when SAVEBA2 is ready for them.

    When started, SAVEBA2 loads COMM4.BIN, asks you for a filename, and then goes into its "receive" loop. Each time around that loop, it waits for you to signal that you are ready to send by hitting 'Enter', calls COMM4.BIN to get a buffer full of data, and then (slowly) PEEKs that data from the buffer, lists it on the screen, and writes it into the file you named. Eventually, it will finish the entire buffer, and start the loop again. When there is no more data to send, enter the letter 'Q' before you hit 'Enter', and SAVEBA2 will break out of that loop, and finish up by adjusting the new file's type.

    While data is being accepted by COMM4, the activity indicator will blink much more rapidly than before. When no data is coming in, it goes back to its once-per-second rate. And once it has got some data, ten seconds with no data is enough to make it give up and return control to BASIC. You may have to watch carefully to see the indicator blinking at the faster rate; you would be surprised how fast a small file will fly by at 9600 baud! You could miss all the action if you look the wrong way for just a second!

    The tricky bit here, communication aside, is adjusting the file's type. Disk files written from BASIC programs are not normally recognized as BASIC programs; they are just data files. But SAVEBA2 is clever: it uses low-level disk operations to find the directory entry for the new file, and adjusts it to make the type into "BASIC ASCII". Just as an extra assurance that it did the right thing, it prints the message "FOUND file IN T,S" when it finds the directory entry to adjust, where T and S are the track and sector number that the directory entry was in. It should print this message exactly once.

    The only things to be careful about are to send only chunks of program that are less that 16384 bytes each; and to wait until SAVEBA2 has finished listing/saving each and prompts you for more, before you send the next chunk.

  6. Done.

    Break out the Doritos!

Please let me know how it goes! So far, I have no reports of anyone using this stuff. I hate to think that all this work was for nothing, or that some little problem might be making it unusable. I have tested these on my own machines, so they should work. If they don't, I really do want to hear about it, and get them fixed!

        Cheers!
        Bill.

Back to my top-level CoCo page


2-Apr-98
yakowenk@csx.unxc.edu
(remove all "x"s to get a valid address)