Programmer 7500

home *** CD-ROM | disk | FTP | other *** search

/ Programmer 7500 / MAX_PROGRAMMERS.iso / PROGRAMS / UTILS / HAMRADIO / EZP.ZIP / EZP.TXT < prev next >

Wrap

Text File | 1986-09-06 | 25.0 KB | 471 lines

E Z PACKET A simple and easy packet radio program For the IBM PCs Version 1.40 Copyright by AA4L E Z Packet is a simple terminal program for IBM PCs and TAPR style TNCs. It is intended for packet radio use in the Amateur Radio Service only. The program may be freely copied and distributed for this purpose. Use for any commercial purpose, or sale of this program or any of the parts thereof is prohibited. The program will be of principal interest to beginners in packet radio. It does not have any advanced features. However, it is easy to learn and simple to use. Furthermore, it is reasonably compact, and should execute in small systems. Many thanks to Ed Stephenson AB4S for his beta testing, help and encouragement. GETTING READY TO USE E Z PACKET To use E Z Packet, your TNC should be set up with the following terminal to TNC communication paramaters: 1200 baud, 8 data bits, 1 stop bit, no parity. This is the best setup for all around use for most TNCs. E Z Packet normally expects the TNC to be connected to COM port COM1:.If you intend to use the file transfer features of E Z Packet, you should configure your TNC to use HARDWARE FLOW CONTROL. For the TNC 2 the commands are XFLOW OFF, STA 00, STO 00. Read your TNC manual or ask for help. RUNNING E Z PACKET To start E Z Packet, boot your system with DOS 2.0 or later, load the program disk in your active drive, and type "EZP <enter>". After you get rid of the hello screen, you will see a split screen display. Characters entered from the keyboard are displayed in the lower screen, and characters received from the TNC are displayed in the upper screen. The characters you type in the lower screen are NOT sent to the TNC until you strike the <enter> or carriage return key (or until you enter 255 characters without a carriage return). If you make a typing mistake, and the cursor is still on the same line, you can use the BACKSPACE key to back up and overwrite the error. None of the other DOS editing keys are functional. If you see the data you just transmitted from the lower screen appearing in the upper screen, your TNC is echoing, and you will probably want to turn the echo feature off. (ECHO OFF in the TNC2.) You are now ready to have keyboard QSO's with your packet buddies. Have fun! USING DIFFERENT COMMUNICATION PARAMETERS If you wish to change the communication parameters, you can enter the changes on the DOS command line (when you start EZP) as follows: COMMAND LINE RESULT ------------ ------ EZP com1, 1200 baud, N, 8, 1 EZP 2 com2, 1200 baud, N, 8, 1 EZP n 3 (n = 1 or 2) com(n), 300 baud, E, 7, 1 EZP n 24 com(n), 2400 baud, N, 8, 1 EZP n 48 com(n), 4800 baud, N, 8, 1 The 300 baud option is provided for the purpose of initializing a TNC from a "cold start". (Hardware and software reset.) FUNCTION KEYS Each of the forty function keys (1-10, shift 1-10, control 1-10 , and alt 1-10) can be programmed for your customized use. This is done through the use of the auxiliary program EZPKEYS.COM, which creates and/or modifies a diskfile FKEY.PRM which is read by E Z Packet. (E Z Packet expects to find FKEY.PRM on the active or default disk drive and in the active directory. If you keep it on the same diskette with EZP.COM you should not have any problems. If E Z Packet cannot find FKEY.PRM it proceeds without incident, and no function keys are set up.) You must exit E Z Packet to use EZPKEYS.COM. Each function key can be programmed with a string of up to 80 characters. Control keys may be inserted in the string using the convention "^X". For instance, if you want a carriage return at the end of your string, end the string with ^M. When E Z Packet is running, striking a function key will cause the string you have programmed to be entered into the lower window and sent to the TNC just as if you had typed it. Hence, the function keys are very useful for commonly used phrases and commands. Examples: "^C c k4iww-1 v ab4s,ai0k,wa4lpd-1 ^M" or "73 from Bob AA4L in Bay Leaf USA". EZPKEYS.COM has an option to list the function key contents to your printer, in case you have any problems remembering what you did. CAUTION: Don't try to use a text editor to create fkey.prm. It is not a text file. EZP expects a carriage return at the end of a line, and only at the end of a line. EZP truncates the function key string at the first ^M it sees. Since everything after a ^M is ignored, the remainder of the allowable 80 characters can be used for a comment which will appear only in the printed listing. If you want to enter multiple TNC commands from a single function key, you can use a "psuedo carriage return" which the program ignores but the TNC recognizes. The ascii character <141> is a "psuedo c/r", and ^<205> will also work. Enter the "psuedo c/r" into the fkey string by holding down the alt key and keying 1,4,1 in THE NUMBER PAD AT THE RIGHT OF THE KEYBOARD. Example: ^C MH<141>CONV^M (displays "calls heard" & returns to converse mode) Note that <141> represents the ascii character <141>, which prints on the screen as an <i> with a funny dot. If I were to include the actual character in this text, it might screw up your printer. DO NOT try to enter "<141>" in the fkey string. Use alt 1,4,1 as described. The parentheses above enclose a comment. The parens are for aesthetics only, and have no meaning to the program. They are NOT required. If your fkey string does NOT end with a ^M, and you wish to use the comment feature, you can use the <|> character as a delimiter. EZP will truncate the fkey string starting with the <|> character. You can also use this to force trailing blanks. ( <|> is ascii <124> and may be directly entered from the keyboard.) Example: 73 es CUL | (becomes part of current line with one trailing blank) EZP COMMAND SUMMARY All E Z Packet commands are entered via an alpha key in conjunction with the alt key. Example: Alt-Q exits the program. E Z Packet will display a list of the command keys at any time in response to the <home> key. COMMAND FUNCTION ------- -------- alt-A Receive (download) an ASCII file. See below. alt-B Toggles the BELL on or off. (Normally off). This prevents a received control-g character from beeping at you. It defeats the ding-dongs who are afraid nobody will notice them. Instead of a bell, a "+" character is printed. A "connect alarm" is provided which sounds a distinctive tone whenever the "connected to" message appears on the screen. The alt-B command has no effect on the connect alarm. alt-C Toggles the CAPTURE function on and off. When CAPTURE is on, everyhing received from the TNC is written to the capture file. CAPTURE is useful for receiving ASCII text files, and for creating a hard copy of channel activity. alt-D Displays a diskette directory for disk a:, b: or c:. Only the root directory is displayed. Also displays the remaining space on the disk. alt-K Receive a file (ASCII or binary) using the XPACKET protocol. (See below.) alt-L Locks the screen. When the screen is locked, you can review the last seven "pages" received with the PgUp & PgDn keys. The screen remains locked until you strike alt-L again. Alt-L redisplays the latest screen before unlocking. alt-N Allows you to name the capture file. You will be prompted for a filename. Enter the desired drive designator with the filename. Example: b:dnld.fil. If the file you name does not exist, it will be created. If the file does exist, newly received data will be appended to it. CAPTURE does not overwrite old data. The default name is "capture.txt" on the default drive. alt-P Toggles the PRINTER on and off. When PRINTER is on, everything received from the TNC is listed on the printer. This is useful for copying messages from bulletin boards. Continuous use of the printer may interfere with the ability of EZP to keep up with the received data from the TNC. alt-Q Exit from EZP and return to DOS. alt-R Receives (downloads) a file using the XMODEM protocol. Prompts you for the required information. See the XMODEM section. alt-S Sends a file (ASCII or binary) using the XPACKET protocol. (See below.) alt-T Transmits an ASCII Text file. ASCII Text files are "plain language" files like this one. Each line must be terminated with a carriage-return / line- feed sequence, and no line should be longer than 255 characters. You will receive prompts that tell you what to do. Sends a ^Z and ^K at the end of the file. alt-X Transmits a file using XMODEM protocol. See the XMODEM section. Prompts are provided. <end> key If for, for any reason, your TNC gets into TRANS- PARENT mode, the only way to return to COMMAND mode is to wait one CMDTIME (usually one second), send three control-C's,and wait another CMDTIME. No other characters may be sent during the whole period. Since everything sent from the lower screen is followed by a carriage return, you cannot send this sequence in the "normal" manner. The <end> key sends three control-C's without c/r's. CAUTION: The PCJR architecture does not not permit reliable data transfers between disk files and communications ports. If you are using a PCJR, you should install a virtual or RAM disk, and all will then be well. This applies to XMODEM as well as ASCII file transfers. NOTE: In order to maintain the simplest possible user interface, I chose not to support multi-level directories and PATHnames in EZP. All files are expected to be in, and will be written to, root directories. NOTE: CAPTURE vs ASCII RECEIVE (alt-A): Capture writes a copy of the screen to the capture file. If any line exceeds the screen width (80 char), a cr/lf sequence is inserted. The <alt-a> procedure writes the file exactly as received, and does not insert additional cr/lf sequences. The <alt-a> procedure terminates and closes the file upon receipt of a ^Z or ^G. (Both conventions are in local use.) Additionally, the received data is written to the LOWER screen so that the operator can monitor. The operator can terminate reception manually by use of the <!> key. THE XMODEM FILE TRANSFER PROTOCOL ***NOTE*** To use the XMODEM (and XPACKET) features of E Z Packet, you must have a TNC-1 (non WA8DED version), or TNC-2, or equivalent. The TNC should be set such that CMDTIME is equal to one second, and the command control character is hex 03 (control-C). These are the default values. ********** EZP contains facility for transfer of binary files using the XMODEM protocol. It will work with TNC-2s and TNC-1s. It will NOT work with The TNC-1/WA8DED. Binary files are non-text files, such as program files. They frequently have filename extensions such as ".com", ".exe", or ".bin". XMODEM is included because the WDCG BBS system operated by K4IWW-1 uses it, and because it is widely available in terminal programs designed for use with telephone line modems. There are several file transfers protocols which are much better suited to use with packet radio, but there is little standardization, and the net result is that both parties must run the same program to use them. XMODEM ain't much, but at least it's fairly "standard". XMODEM transfers data in blocks of 128 bytes. The receiving system is expected to verify each block and respond with an accept or reject message (ack or nak). This checking is highly reduntant to the checking performed by the TNC, and the XMODEM block lengths are not synchronized with the TNC packet lengths. Therefore, the file transfer tends to be rather slow. XMODEM was designed for use with full-duplex telephone line modems. Most versions of XMODEM incorporate a timing feature. Responses are expected from the other end within a certain period of time. Response times will be much longer in a half duplex packet radio system than in a full duplex telephone system. This situation gets worse if there is channel congestion or if digipeaters are used. The net result is that not all terminal program XMODEM versions will work on packet radio. Some terminal programs offer multiple XMODEM versions. In this case, the one with the longer timeouts is usually known as "relaxed XMODEM". The "relaxed" version is the one to use. In any case, XMODEM probably should not be used on a packet radio path which incorporates more than one digipeater. The XMODEM version in E Z Packet incorporates abnormally long timeouts, and should work better on packet radio than the versions supplied in most telephomne modem terminal programs. However, if the other station is using a version with shorter timeouts, E Z Packet can't fix it. ***NOTE*** The BBS may admonish you to be sure that your TNC is in transparent mode when performing XMODEM transfers. Don't worry about it. E Z Packet manages the transparent mode entry and exit for you. Just answer the BBS prompts to tell the BBS that you want to do an XMODEM upload or download. AFTER the BBS tells you that it is ready to receive or send the file, strike <alt-R> or <alt-X> and do what E Z Packet tells you to do. You do NOT have to use the same filenames as the BBS. Examples: you can download "whereis.com" to your file "c:findit.com" and you can upload your file "b:smart.bas" to the BBS as "stupid.bas". ********** ASCII Text Files may be transfered using the XMODEM protocol. However, there is no real reason to use XMODEM for this purpose on packet radio. As mentioned above, the packet protocol contains enough error checking procedures to make the error checking procedures of XMODEM totally unnecessary. The ASCII transfer procedure is very much faster. XPACKET FILE TRANSFERS The XPACKET packet radio file transfer protocol was developed by Carl Moreschi N4PY. It was first made available in his program PTP. I know of no program which supports XPACKET, other than PTP and EZP. XPACKET is the protocol of choice for transfer of any type of file between two stations which are using either PTP or EZP. It is much faster and reliable than XMODEM, and the self-synchronizing features eliminate the need for checking and editing which a straight ASCII transfer sometimes requires. To use XPACKET, the sending and receiving stations should strike alt-s and alt-k, respectively, at about the same time. Then just follow the prompts. Note that the file name is NOT entered by the receiving station, but is sent from the originating station. The receiving operator will be prompted to enter the designator for the disk drive to which he wishes to receive the file. TECHNICAL NOTES (For Hackers) E Z Packet is written in Version 3.01a Turbo Pascal. The principal reasons for writing it were to learn the language, and to provide a vehicle for developing terminal software which supports the WA8DED TNC1 software. That piece of it ain't done yet. However, as is, it may be a useful program for beginners for the reasons stated above. I want to keep it simple and avoid bells and whistles to keep from scaring off beginners. Turbo Pascal does not have native support for interrupt driven communications, so the communications routines in E Z Packet are homebrewed, and are written in in-line machine code and Pascal. There are no assembly langauge routines, per se. The receive interrupt driver uses a 4095 character (or byte) buffer. If the free buffer space gets down to 200 bytes, DTR and RTS are dropped. If this does not discourage the TNC, reception continues. When the buffer is completely filled, the last buffer position is repeatedly overwritten. There are no alarm indications, and the situation is self-healing, except for the data loss. This situation will not occur in normal use, but it can occur if you use the screen for something else (such as the directory function) for long periods of time. The transmit side is not interrupt driven or buffered. Output is directly to the com port. The buffered interrupt driven transmit routine was written and debugged, but there did not seem to be any practical benefit in using it in such a simple program. The program waits for the UART Transmit holding register to empty before passing the next character. The program also waits for RTS and DSR to be active for each character. If appropriate, it will wait FOREVER. (If this occurs during a file transfer, you can escape by keying the abort character.) E Z Packet strips line feed characters from incoming text. Carriage returns cause the program to write an (editor compatible) cr/lf sequence to the screen and capture file. E Z Packet uses a cr with NO lf end-of-line sequence for transmitted text. I believe this is compatible with most terminal and BBS software, and lf characters can be inserted by TNCs if needed. When transferring ASCII text files, an eof character (hex 1A) in the data stream will bring things to a screeching halt. While in "keyboard QSO" mode, E Z Packet's priorities are: (1) Send data to TNC; (2) Read and print data from TNC, (3) Manage keyboard. Therefore, in extreme cases, the keyboard could be locked out for up to a couple of seconds, or possibly more if the printer feature is in use. This is no problem for the average hunt and peck packeteer, but a competent touch typist could certainly overrun the 15 character DOS keyboard buffer. There are many public domain and licensed resident DOS extension programs which expand the DOS keyboard buffer to 128 or 256 bytes. If you have a problem, the use of one of these programs will fix it. Operating at 4800 baud may help, as it will allow EZP to get rid of outbound traffic quicker. There is a quirk in the Borland Turbo libraries for extended scan code keyboard entries. The net result is that under some conditions, an <esc> ($1B) character entered from the keyboard can be decoded, in combination with the following character in the keyboard buffer, as a function key or other "special" key entry. Hence, EZP might appear to lose a couple of characters, or think that you have issued it a command. This will NOT happen at "normal" keying speeds, and can be avoided by waiting for the escape (left arrow) symbol to appear on the screen before typing the next character. I wouldn't even bother to mention it, except that the WA8DED TNC requires that each command be preceeded by an escape character. Should this be a problem in your particular application, you can work around it by assigning the escape character to one of your function keys. (Use ^[ to load the function key.) Use the function key instead of the <esc> key to send an escape character, and the problem (if there is a problem) will go away. EZP ans EZPKEYS use the TURBO Read() and Readln() functions to ask the operator for keyboard data, such as file names and the fkey strings. These functions are similar to the BASIC INPUT function, however, the editing conventions available to the operator are strange and wonderful. The editing commands are summarized herewith: Esc or ctl-X : Erases the whole line ctl - r : Restores the line erased by Esc ctl - d : Restores one character from the line erased by Esc Backspace : Normal (cursor left and rubout) In TURBO, the "special" keys (fkeys, cursor arrows, del, ins, etc.) send a two-byte sequence starting with an esc character. Hence, attempting to use these keys to edit input will give unexpected results. Backspace and ctl-R will recover your data. The above does NOT apply to data keyed into the lower screen keyboard buffer for transmission. TURBO does not make it very easy to intercept I/O errors. I have done the best I can with the standard TURBO tools, plus a few of my own, but there are many errors, such as "disk not ready" that will show you a DOS or TURBO error message. I plan to tinker with this some more in the future. Meanwhile, the program, as is, is reasonably crash-proof. If you have a need for the Pascal source code, I am open to discussion. PACKET OPERATING PROCEDURES There are exceptions to every rule, and some forms of errant behaviour not acceptable in prime operating hours may be tolerated at 4:00am. However, adherence to the following rules of conduct will make life much more pleasant for us all: NEVER BEACON. NEVER, NEVER, NEVER, EVER BEACON THROUGH A DIGIPEATER. NEVER SEND "BELLS". If your TNC has a CWID feature, never use it. Better still, drive a stake through its heart. CWID is not required by FCC, and it is very impolite. Never try to work a DX mailbox except during off hours. Retries can tie up not only the BBS but the entire channel within hearing of the digipeaters involved. SysOps have a secret blacklisting society, and most mailboxes can be programmed to lock out selected callsigns. Stay on their good side! When you establish a "direct" connection, and you settle down for a long keyboard chat, QSY to .03, .05, .07, or .09. Always QSY from .01 for station to station file transfers. Pay strict attention to the adjustment of your equipment. A properly adjusted TNC can decode darn near anything that even twitches the S-meter. Yet, every night, my screen fills up with retry after retry from stations that are delivering S9 signals to each other. The problem is simply bad audio. Receive audio level to the TNC, and transmitter deviation level, are very critical. If you lack equipment and expertise, ask for help. Also pay strict attention to the optimum settings of the delay parameters in your TNC. If you clean up your signal you will have have more enjoyable contacts, more people will be willing to connect to you, and you will substantially reduce the congestion on .01. Your instruction book probably says that your TNC will work with "most" transceivers without further adjustment. It really means it might work with somebody else's rig. AUTHOR'S NOTE I hope you enjoy using EZP. Bug reports and suggestion for improvement are welcome. I have no way of debugging on non-IBM equipment, so if you have problems on an IBM "compatible", you have my sympathy and nothing else. 73 Bob Johnson AA4L 11305 Rums Hill Raleigh NC 27614 919 847 5606 (Bob from Bay Leaf USA)