1.0. TRS-80* Color Computer Kermit Version 1.1, March 1985 Kermit-CoCo is a program that implements the KERMIT file transfer protocol for the TRS-80 Color Computer. The minimum system re- quirements are a Color Computer with 16K memory, one disk drive, and a 300 baud (Bell 103/113 compatible) modem. Kermit-CoCo runs under the Radio Shack disk operating system and uses the built-in RS-232 port. It therefore does not require OS-9, the "deluxe" RS-232 pack, or any other hardware or software add-ons. It uses the disk ROM for file I/O and is compatible with both versions 1.0 and 1.1 of the Radio Shack ROM. Kermit-CoCo lets your Color Computer communicate with other systems in three ways. First, it is a terminal program. Your computer can function as a terminal connected to a remote com- puter. Second, it permits uploading (sending) and downloading (receiving) text files to and from a remote computer. Third, it provides KERMIT protocol file transfers of both text and binary files to and from a remote computer running KERMIT. KERMIT is a protocol designed for reliable file transfer. It was developed at the Columbia University Center for Computing Ac- tivities in 1981-82 where Bill Catchings and Frank da Cruz designed the protocol and implemented it for DEC-20 and CP/M com- puters. The two computers exchange information in small packets. The sending computer transmits a packet, then waits for an acknowledgement before sending another. Each packet includes in- formation used to validate the packet contents. If a packet is received incorrectly, the receiving system requests retransmis- sion of the packet. In addition to reliability, an advantage of Kermit over raw data transfer is that it permits transfer of binary files. This means Kermit can transfer Color Computer machine language programs, even over 7-bit connections. Kermit-CoCo implements only basic functions of the Kermit protocol. It does not provide time out, multiple file transfers, or server mode communication and the user interface is not as sophisticated as in many versions. It is, however, sufficient for simple, reliable file transfers. ____________ TRS-80 is a trademark of Tandy Corp., Fort Worth, Texas Kermit-CoCo - 1 - 03/85 1.1. Running Kermit-CoCo Kermit-CoCo consists of two files. CCKERMIT.BAS contains a short BASIC program to configure memory, load, and execute the machine code file. CCKERMIT.BIN contains the actual Kermit machine code. If you have obtained Kermit-CoCo in some way other than on a diskette, see section 1.6, Bootstrapping Kermit-CoCo. Make sure your modem is connected, place the Kermit-CoCo disk in your machine, and type: RUN"CCKERMIT" This runs the BASIC driver program, which loads and executes the machine language code. You can exit from Kermit-CoCo, execute other commands, then return to Kermit-CoCo with an EXEC command. Kermit-CoCo initially displays the following summary of command codes and parameter settings. KERMIT-COCO 1.1 (PREFIX CONTROL OR COMMANDS WITH DOWN-ARROW) 0 EXIT, ? PRINT MENU 1 LOCAL ECHO (N) 2 PARITY (E) 3 AUTO LF (N) 4 JOURNALIZE (N) 5 WRITE BUFFER TO FILE 6 READ FILE INTO BUFFER 7 UPLOAD BUFFER 8 ERASE BUFFER 9 DEF CHAR/LINE DELETE (08,18) KERMIT: = SET, < RECEIVE, > SEND ()!-# BRACES BAR TILDE DEL The current settings are shown in parentheses, where Y=yes, N=no, and E=even. The character and line delete codes are shown as hexadecimal values. If the default settings are correct for the system you are calling, continue with your normal sign-on procedure. First, however, the are a few things you need to know. 1.2. Multi-key Sequences The Color Computer keyboard has only 53 keys. It lacks some of the keys found on terminals; the most important of these is the CONTROL key. Since CONTROL is normally located to the left of the letter A, Kermit-CoCo uses the key in this position, the DOWN-ARROW, to indicate control codes. 03/85 - 2 - Kermit-CoCo Several other keys not shown on the keyboard are documented in the BASIC manual that came with your computer. These include using SHIFT-0 as a caps lock, SHIFT-DOWN-ARROW for [, SHIFT- RIGHT-ARROW for ], SHIFT-CLEAR for \, and SHIFT-UP-ARROW for un- derscore (underscore prints as a LEFT-ARROW). 1.2.1. ASCII Control Characters Unlike terminals, on which you press some other key while holding down the control key, in Kermit-CoCo you press the DOWN-ARROW first, release it, then press the key you want it to modify. For example, DOWN-ARROW followed by A generates the hexadecimal value 01 which is the ASCII code for control-A. Throughout the remainder of this document, control sequences are printed as "CTL-character"; for example, CTL-A for DOWN-ARROW followed by A. ASCII control codes (hexadecimal 00 through 1F) are generated by the standard combinations: CTL-@ for 00, CTL-A for 01, CTL-B for 02, ... CTL-Z for 1A, CTL-[ for 1B, CTL-\ for 1C, CTL-] for 1D, CTL-^ for 1E, and CTL-_ (SHIFT-UP-ARROW) for 1F. 1.2.2. Other Special Characters A second use of the DOWN-ARROW prefix is to generate other ASCII characters not on the keyboard. These are: ` CTL ' (Prints as inverse @) { CTL ( (Prints as inverse [) | CTL ! (Prints as inverse \) } CTL ) (Prints as inverse ]) Tilde CTL - (Prints as inverse ^) Rubout CTL # (Prints as inverse LEFT-ARROW) To help you remember these, they are shown at the bottom of the menu display. Some terminals have a special key for the ASCII escape code. It simply generates CTL-[ with a single key. Another key on many terminals is LINE-FEED. Use either CTL-DOWN- ARROW or CTL-J to generate the ASCII line feed character. On the Kermit-CoCo screen, LINE-FEED moves the cursor to the beginning of the next line. The BREAK key generates a break by sending a long (about 1/4 second) series of 0 bits. When CTL-G (bell) is received or typed on the keyboard it generates a tone through the speaker on your monitor. The LEFT-ARROW key backspaces the cursor and transmits a user selectable character deletion code. SHIFT-LEFT-ARROW transmits a user selectable line deletion code. Kermit-CoCo - 3 - 03/85 The CLEAR key clears the screen and moves the cursor to the upper left corner. It does not transmit any character. 1.2.3. Kermit-CoCo Commands A final use of the DOWN-ARROW key is for Kermit-CoCo commands. These include modifying parameter settings and beginning special actions such as KERMIT file transfers. CTL-? displays the main menu with current parameter settings shown in parentheses. CTL-0 terminates Kermit-CoCo and returns control to BASIC. You can restart Kermit-CoCo by entering EXEC. Modify control parameters by pressing the DOWN-ARROW key, then the number of the option you want to change. For example, if local echo is on (Yes), pressing CTL-1 changes it to off (No). Pressing CTL-1 again turns local echo back on. CTL-2 toggles the parity setting between even and none. Kermit- CoCo cannot communicate with systems that require other parity settings. Although Kermit-CoCo can generate even parity output it always ignores the parity bit of incoming data. The bit is not used for either parity checking or 8-bit data values. CTL-3 toggles local line-feed generation. When it is set to Yes, Kermit-CoCo adds a line-feed to the display after each carriage return. It does not transmit the added line-feed. After modifying parameters, you can verify the new settings by pressing CTL-? to display the menu with the new values. Setting character and line delete codes is similar, but requires a series of keystrokes. These codes, displayed as hexadecimal values on the menu, are transmitted by the LEFT-ARROW and SHIFT- LEFT-ARROW keys. To change the settings, press CTL-9, then the keys for the values to transmit. For example, CTL-9 @ CTL-X sets the character delete symbol to "@" (hexadecimal 40), and the line delete symbol to control-X (hexadecimal 18). You are now ready to use Kermit-CoCo as a terminal. The fol- lowing sections describe file transfer. 1.3. KERMIT File Transfers Kermit file transfers require a copy of Kermit on the remote com- puter as well as Kermit-CoCo on your system. The remote can range from another Color Computer to a large mainframe. 03/85 - 4 - Kermit-CoCo Before beginning a transfer, configure any necessary parameters using the CTL-= command described below. The default settings of EOL, SOH, etc. are appropriate for Kermit-CoCo and many other systems, but check documentation for the remote Kermit in case it requires other values. These must be correct or no communication can take place. 1.3.1. KERMIT Parameter Settings Typing DOWN-ARROW followed by an equal sign displays the current KERMIT parameter settings and leaves the cursor under the first. Pressing ENTER leaves all settings unchanged and returns to ter- minal mode. Any other key indicates a new value for the parameter above the cursor. To leave a parameter unchanged, press the space bar. Pressing any other key changes the parameter to the ASCII value of that key. The cursor then moves to the next parameter until you have responded for each one. Kermit-CoCo then returns to normal terminal mode. Note that for any parameter except the first, ENTER is taken as a parameter setting. Parameters that can be set are: TYPE COCO File Type: 0=BASIC, 1=TEXT, 2=Machine Code MODE COCO File Mode: 0=Binary, FF=ASCII EOL End-of-line required by the remote system when receiving Kermit packets. NTRY Maximum number for transmission attempts for each packet. SOH Start of packet character required by the remote Kermit. DBUG Debug flag: 0=Off, anything else=On When the debug flag is on, each packet sent is displayed on lines 9-11 of the screen and each packet received is displayed on lines 13-15. For example, to change the number of retransmission attempts, press CTL-=. Kermit-CoCo displays: TYPE MODE EOL NTRY SOH DBUG 00 FF 0D 05 01 00 Press the space bar three times to leave TYPE, MODE, and EOL un- changed, then type DOWN-ARROW and J to change the retry setting to 10 (10 is the decimal value of control-J). Press the space bar two more times to leave SOH and DBUG unchanged. The display now shows: TYPE MODE EOL NTRY SOH DBUG 00 FF 0D 05 01 00 00 FF 0D 0A 01 00 The second line of settings appeared as options were changed. Kermit-CoCo is now back in terminal mode. Kermit-CoCo - 5 - 03/85 To prepare to receive a machine code file, set TYPE to 2 (CTL-B) and MODE to 0 (CTL-@). Type and mode are automatically set when sending a file. They must be manually set for receiving. One reason that the distinction between binary and ASCII files is im- portant is that the Color Computer indicates end-of-line with a carriage return. When transmitting ASCII files, Kermit-CoCo adds a line-feed after each one. When receiving ASCII files, Kermit- CoCo replaces each carriage return followed by a line-feed with a single return. It does not insert or delete line feeds when processing binary files. Also, the operating system requires certain file types for certain types of processing. LOADM, for example, requires that a file be declared as machine code binary. Setting the type and mode parameters permits Kermit-CoCo to create the proper type of file. In addition to the space bar for leaving values unchanged, and ASCII codes for setting other values, the BREAK key can be used to set a parameter to hexadecimal FF. Several Kermit parameter settings are defined internally, with no provision for change. These include # for control quoting, & for 8th-bit (binary) quoting, and hexadecimal 0D (carriage return) for end of incoming packet. 1.3.2. Sending A File With KERMIT Before transmitting a file, the remote KERMIT must be ready to receive it. This is done through a RECEIVE command to the remote KERMIT. Press CTL-> on your keyboard. Kermit-CoCo requests the name of the file to transmit. Enter the name, and Kermit-CoCo begins sending. As each packet is sent, the packet number is shown as a hexadecimal value. If debug mode is active, the packets are also displayed on the screen. When the transfer is complete, the message TRANSFER COMPLETE appears on the screen and the ""bell" beeps. If the transmission fails, the message TRANSFER FAILED appears. In either case, Kermit-CoCo returns to terminal mode. If a "deadlock" occurs-- both KERMITs waiting for a message from the other, the packet number will stop changing. To break the deadlock and resume transmission, press the ENTER key. Before doing this, wait long enough to make sure that a deadlock really does exist. 1.3.3. Receiving A File With KERMIT Before attempting to receive a file, make sure that the file mode and type parameters are set correctly. Issue a SEND command for the remote Kermit, then press CTL-<. Kermit-CoCo will request a name for the incoming file. Unlike most KERMITs, Kermit-CoCo ig- nores the name in the incoming transmission, and writes the data to the file you specify. 03/85 - 6 - Kermit-CoCo The display while receiving is similar to that during transmis- sion. A hexadecimal packet number display keeps you posted on the status of the transmission. If a deadlock occurs, you can break it by pressing ENTER. Kermit-CoCo will signal either TRANSFER COMPLETE or TRANSFER FAILED at the end of the transfer, and return to terminal mode. Some remote Kermits can transmit multiple files. Do not use this capability with Kermit-CoCo. It can receive only one file at a time. 1.4. Journalizing A Session Kermit-CoCo can use all memory above the high end of the program (&H2FFF) as a buffer to keep a copy of all characters sent or received. This facility is used primarily for raw ASCII file transfers, but can also be used to journalize (keep a copy of) your terminal session. CTL-4 turns on session logging when it is off, turns it off when it is on. CTL-5 prompts for a file name and saves the buffer onto the file. CTL-8 erases the buffer by resetting the buffer pointer to the beginning of the buffer. Note that the buffer cannot be used for both raw file transfer and session logging at the same time. 1.5. Raw ASCII File Transfer Kermit transfers are more reliable than raw data transfers. They also permit transfer of binary (8-bit) data. However, since such transfers require Kermit on both the sending and receiving systems, Kermit-CoCo also provides raw ASCII file transfer. 1.5.1. Downloading Files CTL-R (Hex 12) places the system in download mode. Actually, it turns on the session logging buffer regardless of its current state. It can be entered at the keyboard or transmitted from the host system. Characters received following it are placed into the buffer. This mode ends when CTL-T is received or entered at the keyboard or when the buffer is filled. On a 16K system the buffer holds 4K bytes. On larger systems it hold 20K bytes. The pointer to the current buffer position can be reset by en- tering CTL-8 from the keyboard. This is a local signal only. It is not transmitted. If multiple downloads are done without reseting the buffer pointer, they will be stored one after another in the buffer. Kermit-CoCo - 7 - 03/85 1.5.2. Uploading Files Entering CTL-7 from the keyboard begins transmission of the buffer. As the upload takes place, the text is displayed on the screen. To prevent overprinting, you should turn on local line feed (CTL-3), then turn it off after the transfer is complete. While uploading, all keys except BREAK are ignored. The BREAK key can be used to stop the upload process. The upload ends automatically when the portion of the buffer currently in use has been transmitted. Before the buffer is transmitted, the remote computer must be prepared to receive its contents. To do this, enter the neces- sary commands (these depend on the remote system) using terminal mode before starting the upload. 1.5.3. Reading and Writing the Buffer CTL-5 writes the contents of the buffer to a disk file. CTL-6 reads a file into the buffer. For either function Kermit-CoCo will prompt for a file name. 1.6. Bootstrapping Kermit-CoCo The easiest way to get Kermit-CoCo is on a diskette. However, Kermit is also distributed in other ways which permit ASCII-only transfer. To support such transfer mechanisms, Kermit-CoCo is available in Motorola S-record format, along with a program to convert S-records to a binary file. It is also available in ASCII source format for input to the EDTASM+ assembler. 1.6.1. Using the S-record File To convert the S-record code to binary, you need to transfer files "CCEXBIN.BAS" and "CCKERMIT.S" to your diskette. Running "CCEXBIN" generates file "CCKERMIT.BIN", the executable version of Kermit-CoCo. Each S-record contains checksum information. If you did not receive the S-record file properly, CCEXBIN will stop with an error message. Transfer a new copy of CCKERM.S and try again. After you have CCKERMIT.BIN, create CCKERMIT.BAS with the fol- lowing program: 10 PCLEAR 1: CLEAR 200,&H1FFF 20 LOADM"CCKERMIT": EXEC You are now ready to run Kermit-CoCo. 03/85 - 8 - Kermit-CoCo 1.6.2. Assembling the Kermit-CoCo Source The source for Kermit-CoCo is in two parts. The first, COCOTERM.ASM, contains all of the terminal functions and raw ASCII file upload and download. The second, COCOPROT.ASM, con- tains the Kermit protocol source. The source files were prepared and assembled using the Radio Shack EDTASM+ ROM pack assembler, modified for disk I/O. It should be usable as is with the standard disk-based version of EDTASM+. For other assemblers minor changes may be necessary. Comments at the beginning of each file describe assembly and loading. No linker program is necessary to combine the two modules. As- semble the files to COCOTERM.BIN and COCOPROT.BIN, respectively. Load COCOTERM.BIN then load COCOPROT.BIN and SAVEM the code from address &H2000 through the end of COCOPROT.BIN. This is &H2EFE as distributed, but may vary with different versions of the as- sembler and with user modifications. Create CCKERMIT.BAS as described above. ORG pseudo-ops enable the separately assembled modules to com- municate; however, these require some care when modifying the code. Note that COCOPROT code begins loading at &H2800. Modifications to COCOTERM must not make the address of ZZTOP go beyond &H27FF. Such modifications would require changing the ORG statement ahead of KERMR in COCOTERM and the ORG statement at the beginning of COCOPROT. Increasing the size of COCOPROT so that address ZZZTOP is greater than &H2FFF would required changing the EQU statement for TOP in COCOTERM to place the origin of the raw data buffer beyond the end of the Kermit packet buffers. Kermit-CoCo - 9 - 03/85