HAM Radio 1/HamRadio.cdr/packet/ezp140/ezp.txt

Text File | 1986-10-30 | 23KB | 458 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-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.

    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.


          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)