T H E  F I R M W A R E
                         ======================

                            AX.25 Version 2
                       Multi Channel TNC Firmware
                             Version 2.6



TheFirmware Version 2.6 DAMA/SMACK/XHOST (xx Channel)
   Copyright by NORD><LINK, xx-xx-xx
      Free for non-commercial usage

Checksum (xxxx) = xxxx

This is the startup message of TheFirmware in terminal mode, if the EPROM
TF2.6 is installed correctly in a TNC-2 (or compatible).
It is the newest "official" TheFirmware by NORD><LINK. The authors of the
software are not mentionend any longer in the startup message, because many
co-authors have updated the software and and the complete list is very long.
The main code was written by Michael, DC4OX, the DAMA-implementation was
done by Frank, DL8ZAW and updates were done by DB2OS, DF2AU, DK6PX, DL1MEN,
DF7ZE, DL9HCJ and many others.

We hope the version TF2.6 is now bug free. Many improvements were done
compared with older versions. Especially the DAMA-mode was updated. All
known bugs were removed and new functions, like the extended hostmode
by DG3DBI, were implemented.

The complete AX.25 protocol, Version 2.0, link layer, described in ARRL
specification of october 1984, is implemented in TheFirmware. The old
version 1.x is not implemented any longer. Up to 10 different connections
are possible with the version supplied as EPROM-data. In the sourcecode
the number of connections can be changed to any number.

TheFirmware version 2.6 is needed for digipeaters using the DAMA-protocol,
but it has some advantages for "normal" digipeaters or direct traffic, too.

TheFirmware detects the DAMA-mode automatically and changes its behaviour
in this case. DAMA-mode can be seen by a display of [DAMA] in the monitor-
headers. In DAMA-mode the TNC sends only, if it is forced by the
DAMA-master. If after a certain time no DAMA-traffic is monitored, the TNC
will switch back to normal behaviour.

The DAMA-protocol is described in cqDL 4/89 Page 230+ and in the HamRadio-
BBSs.

In addition the EPROM contains the improved KISS-mode with CRC called
SMACK by DL5UE and DK5SG. Using this mode, all parameters of TheFirmware
will not be destroyed, but the software-clock will not be updated.
The SMACK-command 255, leave SMACK is implemented.


A checksum is calculated after reset and the result is displayed in the
startup message. It must be equal to the value in brackets (even with
changed default-values in EPROM). In case the values are not equal, the
programming of the EPROM was not successful.

At the first start it might be useful to execute the command "<ESC> QRES"
in terminal mode to force a cold boot. In this case old data in the buffered
RAM will be deleted and can cause no trouble. QRES will set all parameters
to the default-value stored in the EPROM.

The EPROM data contains no callsign. With the 'I'-command it can be set.
In addition all other parameters can be changed. They are copied into the
buffered RAM and will stay active until the next coldboot with QRES.


Commands and data are transmitted to the TNC as lines. Each line can contain
up to 256 characters including the <CR> at the end of the line. If the 256.
character is no <CR>, it is ignored and a <BEL> is sent. The last entered
character can be deleted by <BS> (=08h) oder <DEL> (=7Fh). <CTL-U> or
<CTL-X> delete the entire line. <CTL_R> sets the cursor to the beginning
of the line without deleting the line. Now received data can be displayed.
A second <CTL-R> will restore the line. Between these two <CTL-R> all data
except <X-OFF> and <X-ON> will be ignored. <BEL> characters will be sent
as <BEL> charcters when entered or deleted. Lines beginning with <ESC>
(echoed as '* ') are interpreted as command lines. If a command is given
without a parameter the actual value is displayed. All lines without a
<ESC> at the beginning will be sent as data.


TheFirmware provides 11 logical TNC channels, which are numbered from 0 to
10. The terminal is logically connected to one of these channels, the
selection is done with the 'S'-command. Channel 0 is reserved for unproto
transmissions (CQ, Beacon). The destination for channel 0 is selected like
for the other channels with the 'C'-command. In terminal mode the channels
1 to 10 transmit entered data as unproto frames while they are not
connected. Connections can be built up on any of the channels as long as
it not already connected. Connect requests from other stations are put
on the first free channel as long as the maximum number of simultaneos
connections (command 'Y') is not reached.
Information received on a connected channel which is not the currently
active channel will be stored until the channel is selected. The 'L'-
command gives an Overview about the currently not displayed data.
Information will be send only on the currently selected channel. After
disconnect all received data will be stored until fetched by selecting this
channel. If the connection path shall be changed during the connection,
no disconnect is needed. A new 'C'-command will change the path without
a loss of data. But more than one connection to the same destination it
not possible. This can only be achieved by using different SSIDs.

A special version with 27 channels is existing for the use with mailboxes.


Only version 2 of the protocol is supported, connect request with version 1
will be rejected. Version 2 is the better solution for networks and provides
a better throughput on busy channels.

In version 2 after the last transmission a timer is started. After a
configurable time the remote station will be polled to assure that the
connection is still available. With the 'N'-command the maximum number of
retries can be specified. After this number of retries the connection will
be disconnected. This covers the case that the remote station silently will
disappear during a connection.                                                                  


The values for 'F', 'I', 'N' and 'O' are stored seperatly for every channel.
They are initialized from the values of channel 0 after restart or
disconnect. Therefore these values can be changed during a connect to
different values without changing the values for other channels. After
disconnect the default values are available again. Executing a 'D'-command
on a not connected channel will set these values to the default values.


The 'M'-command allows to monitor all activity on the frequency. With the
given parameter the wanted information can be selected. The parameters
can be combined.

      Parameter     Packet-type
      ---------     -----------
          N         Monitoring off
          I         Information packets
          U         Unproto packets
          S         Supervisory packets
          C         Monitoring if connected
          +         only packets to or from specific stations (max. 8)
          -         suppress packets to or from specific stations (max. 8)

The parameters '+' and '-' must not be combined. They must be entered as
last parameter in front of the callsigns. Specifying no callsigns will
delete the entire list.

A '*' indicates which station has transmitted the data. The type of the
packet can be retrieved from the following list. 

          Name           Description
          ----           ------------
          RRa            Ready for next packet
          RNRa           Receiver busy
          REJa           Packet is rejected
          UI             Unproto frame (send to all)
          DM             No connection active
          SABM           Connect request
          DISC           Disconnect request
          UA             Confirmation of a request
          FRMR           Protocol error
          Iab            Information packet
          ?ccH           Not defined type

Additional description:
          a  = Number of the next expected packet
          b  = Number of the packet
          cc = Number in Hex-base

An additional character will give information about the used protocol-
version and the value of the poll/final and command/response bit.

    <empty> = Version 1 without P/F bit
          ! = Version 1 with P/F bit
          ^ = Version 2 command packet without poll bit
          + = Version 2 command packet with poll bit
          - = Version 2 response packet with final bit
          v = Version 2 response packet without final bit

The protocol identifier (PID) will be displayed in Hex-base.

CAUTION:
Monitoring will only be active if more than 256 buffers are free in the
TNC. Otherwise using slow computers or programs will lead to no
available buffers on a busy channel.


Using the 'U'-command an automatic connect text can be activated. This
text will be sent if a remote station will start a connect. Normally
this text can contain your name, qth, locator, e.t.c. and you don't have
to enter it manually. This feature does not change any of your possibilties
of entering text or bulding up connections.
You can provide a simple mailbox by this feature, too. You can tell in the
connect text that all text entered by the remote station will be stored.
If you leave then your terminal program with channel 0 selected, the
information of all connections received in TNC-only mode will be stored
and can be retrieved after the activation of the program by switching
to these channels. If selected with the 'Z'-command the output can be
stopped with <CTL-S> and continued with <CTL-Q>.

A new feature of the 'U'-command is parameter 2. If it is specified,
a packet with '//Q' at the beginning will start a disconnect. This is
useful, because the remote station will be reconnected to the last
digipeater and don't have to build up the whole path again.
This feature is only active in terminal mode.


The 'H'-command can activate a list of heard stations on the frequency.
The list implemented in TheFirmware is different to other implementations.
It is not a list of the last 20 heard stations because such a list is
not useful on a very busy channel. The implemented list is dynamical and
the maximum number of stations is limited by the RAM-memory or the given
maximum number (with the 'H'-command). For every callsign (including SSID)
the following values will be stored: 

           - Callsign and SSID
           - Date and time when first heard
           - Date and time when las heard
           - Number of received I-frames
           - Number of received RR-frames
           - Number of received REJ-frames
           - Number of received RNR-frames

Die digipeater path is not stored because of TheNet / NETROM digipeaters.
The number of received frames can be used for statistical investigations
concerning activity or quality of transmissions.

Because the list is a sequential list (dynamically allocated) for every
heard packet the list must be scanned. Therefore the speed of TheFirmware
is decreased by a large heard list. 'H 0' disables the update of the heard
list. The heard list is resident, it is not deleted after a restart, only
by a cold boot.

The 'H'-command is available in hostmode, too. But there are some things
which must be known. The first line will be returned with hostmode code
1 (success, message follows). The entire list will be returned on channel
0 like a header of a monitored packet (code 5 monitor data, null terminated,
Info follows). The last line will be returned with code 4 (monitor data,
null terminated). This handling is succesful with most of the existing
hostmode programs without a change.


TheFirmware provides a built-in software clock and calendar. All status
messages (connect, disconnect) and the monitored packets can be stamped
with date and time. The 'K'-command controls the stamping of messages,
the value 0 disables the feature, value 1 only enables the feature for
status messages and value 2 enables it for status messages and monitored
frames. A change of the value will be effective even for older messages
still waiting in the buffers of the TNC. Without parameter the current
date and time will be displayed.The date can be entered in european or
american format and the stamp will use this format. Date and time will
be deleted on a cold boot with QRES. After a restart the start time is
date and time when the TNC was last switched off. This allows to detect
a power failure during TNC-only mode. The software clock works almost
correctly without any corrections.


APPENDIX
--------
Short descriptions of all important changes:


1. Frame acknowledgement timer T1 (FRACK)
-----------------------------------------
There is not any longer a fixed FRACK-value, for every connection the
time between sending of a information packet and the receiving of the
acknowledgement is measured and will be used to calculate the current
value of the T1 timer.

The measured time RTT (round trip time) will be calculated to a SRTT
(smoothed round trip time) to reduce the changes of the T1-timer.

- increasing RTT:  SRTT' = ( a1 x SRTT + RTT ) / ( a1 + 1 )

- decreasing RTT:  SRTT' = ( a1 x SRTT + RTT ) / ( a2 + 1 )

SRTT is the value of the last calculation, RTT the measured time, a1 and
a2 are configurable parameters and SRTT' is the new value for the
smoothed round trip time.

The timer T1 is calculated from SRTT by:

  T1 = a3 x SRTT

a3 is a configurable parameter.


At the beginning of a connection SRTT must be initialized, because no
measuring is available. This is done with the value (IRTT, initial round
trip time) provided with the 'F'-command (steps of 10ms). The RTT-
calculation begins after the the acknowledge (UA) of the remote station
is received. Using several digipeaters the T1 timer is calculated according
to the following formula: 

         T1 = (2 x "Number of digipeaters" + 1) x IRTT

The values a1, a2 and a3 can be changed with the commands '@A1','@A2' and
'@A3'. Digipeater using hop-to-hop acknowledge and digipeater fields in
the packet (Flexnet, Baycom) forced the using of the SRTT.


2. DWAIT suggested by DL4YBG
----------------------------
Before the transmission is started the slottime is waited in every case
and then the p-persitance-algorithm is started. This is applicable in
all modes except DAMA. In DAMA mode slottime is changed internally to 0
and persistance to 255 to allow a transmission immediately.
This modification will reduce the possibiliy of collisions on the
frequency.


3. Polling using I-Frames suggested by DK6PX
--------------------------------------------
If an information packet is not acknowledged by the remote station, a
RR-frame with poll bit set ist send (polling). If the information frame
only contains a few characters the I-frame will not be much longer than
the RR-frame. Therefore I-polling is introduced where not a RR-frame is
sent, but the I-frame with the poll-bit set. The maximum number of
characters in an I-frame when this feature shall be used can be configured
with command '@I'. If you don't want I-polling it can be disabled by
'@I 0'. In DAMA-mode I-polling is generally switched off.


4. Dynamic MAXFRAME suggested by DK6PX
--------------------------------------
Tests show that this feature decreases the performance on bad links
or on shortwave. Therefore it is removed in TF2.6.


5. DCD/PTT-deadlock
-------------------
An error concerning a deadlock of the TNC when special DCD- and PTT-
states occur are removed (information by Y51GE). Another error concerning
a blocking of DCD is solved,too.


6. DAMA-parameter
-----------------
After leaving the DAMA-mode the parameters P,W,B,@T2 will be restored to
their original values. A change of P and W in DAMA-mode will not change
the actual values. The entered values will get active if DAMA-mode is
finished. 


7. Disconnect suggested by DL1MEN
---------------------------------
If the link setup is cancelled with the 'D'-command, a DISC-frame will
be sent. This is useful if only you were not able to receive the packets
of the remote station, but it has received the link setup and will send
poll packets until the maximum number of retries is reached.


8. Heard-list
-------------
The heard list is changed to overwrite the oldest entries, therefore the
heard list contains the last heard stations.



Compiled from various descriptions 
of the authors ................................ DJ1OR september/1992
Updated for TF2.6 ............................. DB2OS july/1993
Translated to english ......................... DL4YBG september/1994

                        DESCRIPTION OF COMMANDS
                        =======================

CAUTION: Every software depends on a proper setting of all parameters.
The value of many parameters can change according to the used digipeater
and/or baudrate. Therefore please read and accept hints from your local
digipeater sysop. Further information can be found in your local packet
radio mailbox.


ESC A [0|1]    Automatic insertion of LINEFEED-character <LF> after
               CARRIAGE RETURN <CR> (1=Yes, 0=No).
                                                                 Default: 1

ESC B [<n>]    If during this time no poll from the DAMA-master is
               received, the DAMA-mode is switched off. B 0 disables
               DAMA generally, although not needed, because DAMA is
               detected automatically and if no DAMA-master is active,
               the DAMA-mode is off. The display is in the following
               format: "initial value (actual value)".
               Example: "120 (93)"                               Default: 120

ESC C [Call]   Starts a link setup (connect) on the current channel. 
               If you specify a digipeater path no 'v' or 'via' is needed.
               While on channel 0 this command sets the destination of
               UI-frames.

ESC D          If a connection is active on the current channel, it
               will be disconneted. If there are any unacknowledged frames
               left, the disconnect is delayed until the last frame is
               acknowledged. A direct disconnect can be forced with a
               second 'D'-command.
               If the 'D'-command is entered during link setup or during
               disconnect, the TNC immediately returns to disconnected
               state and sends a DISC-frame to cancel transmissions of
               the remote station, if the TNC was not able to decode
               frames of the remote station.
               If the 'D'-command is entered in disconnect state, all
               parameters are initialized to the default values stored
               in channel 0.

ESC E [0|1]    This command controls the ECHO of characters typed.
               1=Yes, 0=No.
                                                                Default: 1

ESC F [<n>]    FRACK is the time between the transmission of an information
               packet and the acknowledgement of the remote station.
               Values >15 will be the initial round trip time (IRTT) and
               the unit is 10 milliseconds.
               For values <16 the unit is seconds and the value will be
               translated to the IRTT by multiplying it with 100 and dividing
               it through parameter A3.
                                                                Default: 250

ESC G [0|1]    Not applicable in terminal mode, used for polling of
               data in hostmode.

ESC H [<n>]    Configuration of the heard list.
               Examples:
                 H        -  display of heard list
                 H 0      -  disable update of heard list
                 H 1      -  enable update of heard list
                 H 2      -  erase heard list
                 H n      -  Set maximum number of calls in heard list 
                             (n > 2)

               The last heard calls will be stored, old entries will
               be overwritten. The heard list is resident, it is not
               deleted by reset or switching off.

               CAUTION: If the heard list contains many entries, a restart
               may take some time because of internal buffer linking
               during startup.
                                                                Default: 0

ESC I [Call]   Input of own callsign (MYCALL). The default value in the
               EPROM is all spaces. After disconnect the callsign of channel
               0 is copied to the actual channel.

               CAUTION: Without a callsign the TNC will not transmit
               anything.

ESC JHOST[0|1] This command switches between terminal- and hostmode.
               The hostmode is used by special programs.

ESC K [<n>]    This command controls the clock, calendar and the stamp-
               function.
               Examples:

                 K            -  display stamp and date/time
                 K 0          -  disable stamp
                 K 1          -  enable stamp for status messages
                 K 2          -  enable stamp for status messages and
                                 for monitor frames.
                 K 20.02.88   -  set date, european format
                 K 02/20/88   -  set date, american format
                 K 17:36:00   -  set time
                                                                Default: 0

ESC L [0..10]  This command shows the link state of one or of all (no
               parameter specified) channels. Following information will
               be displayed: connect-path (callsign and digipeater path),
               number of received frames, number of unsent frames, number
               of unacknowledged frames and the retry counter. The currently
               activated channel will be marked with a '+'.

ESC M [IUSCN+-]This command controls the display of monitor frames. The
               parameters specifiy the type of frames which shall be
               displayed.
               Examples:

                 N        no frame display
                 I        information-frames
                 U        unproto frames
                 S        supervisory frames
                 C        display during active connection
                 +        <list of up to 8 calls>: only frames of these
                                                   stations
                 -        <list of up to 8 calls>: no frames of these
                                                   stations

               A combination of '+' and '-' is not possible. If specified
               '+' or '-' must be the last parameter before the callsign
               list. Without a callsign list, the current list is deleted.   
                                                                Default: UI

ESC N [0..127] Maximum number of retries (0 means try forever). This value
               can be changed for each channel independently, but will be
               restored to the value of channel 0 after reset or disconnect.
                                                                Default: 10

ESC O [1..7]   Maximum number of outstanding packets (MAXFRAME). This value
               can be changed for each channel independently, but will be
               restored to the value of channel 0 after reset or disconnect.
                                                                Default: 2

ESC P [0..255] Value for p-persistance algorithm. In DAMA-mode a value of
               255 will be used.
                                                                Default: 32

ESC QRES       Cold boot, uses default values stored in EPROM.

ESC R [0|1]    This command controls the digipeat function.
               1=Yes, 0:No.
                                                                Default: 1

ESC S [0..10]  Activation of a channel (0= unproto channel)
                                                                Default: 0

ESC T [0..127] Delay between start of transmission and start of data
               (TXDELAY). The unit is 10 ms. Please adjust to the lowest
               possible value.
                                                                Default: 25

ESC U [0|1|2]  This command controls the connect text feature (CTEXT).
               This text is sent if a remote station connects.
               The text will remain stored even if the ctext mode is
               changed. If mode 2 is selected and the terminal mode is
               active, a packet received with '//Q' at the beginning will
               disconnect the remote station. In hostmode this function is
               disabled.

               Examples:

                 U 1 Text          enter CTEXT
                 U 1               CTEXT will be sent
                 U 2 (text)        CTEXT and //Quit-function!
                 U 0               disable CTEXT 
                 U                 display CTEXT
                                                                Default: 0

ESC V          Displays the actual version of the software

ESC W [0..127] Value of the slot time of the p-persitance algorithm. The
               unit is 10ms.
                                                                Default:  10

ESC X [0|1]    This command allows to disable the transmitter.
               0= disable, 1= enable.
                                                                Default: 1

ESC Y [0..10]  Number of channel which will accept an incoming connect
               request. The display format is "max. channels (used
               channels)". Only works correct if the SSID are the same
               on every channel.
               Example: "4 (0)"                                 Default:   4

ESC Z [0..3]   With this command flow control and XON/XOFF-protocol can
               be activated.
               If flow control is activated no charcater is sent to the
               terminal during data input.
               If it is disabled all received data is sent immediately.
               If XON/XOFF protocol is activated data output can be stopped
               using <CTL-S> and continued with <CTL-Q>.
               Examples:

                 0             flow  off    , Xon/off  off
                 1             flow  on     , Xon/off  off
                 2             flow  off    , Xon/off  on
                 3             flow  on     , Xon/off  on
                                                                 Default: 3


Additional commands are available which starts with '@':


ESC @A1 [<n>]  SRTT calculation: change/display value for a1.    Default: 7

ESC @A2 [<n>]  SRTT calculation: change/display value for a2.    Default: 15

ESC @A3 [<n>]  SRTT calculation: change/display value for a3.    Default: 3

ESC @B         Display of available TNC-buffers.

ESC @D [0|1]   Disable/enable full duplex mode.                  Default: 0

ESC @I [<n>]   Change/display framelength for I-polling.
                                                                 Default:  60

ESC @K         Switch to KISS-mode.

ESC @M [0|1]   7-bit oder 8-bit terminal mode.
               In 7-bit mode a control code conversion is active, too
               which will display control codes with a leading '^'.
               In 8-bit mode all control codes are sent without translation.
               CAUTION: disable XON/XOFF in your terminal-program, otherwise
               a XOFF will stop the data flow. 
               Although 8-bit mode is the default mode the real advantage
               of TheFirmware is the *WA8DED HOSTMODE*. It is recommended
               to use it together with a special terminalprogram instead of
               using the terminal mode for binary transfers.
               0=7-Bit; 1=8-Bit (only terminal-mode)
                                                                 Default:   1

ESC @T2 [<n>]  Time between the receiving of a packet and the transmission
               of the acknowledgement (timer T2).
                                                                 Default: 150

ESC @T3 [<n>]  Time after which the connection is tested, if no data
               transfer was done (still alive timer, timer T3).
                                                                 Default: 18000

ESC @V [0|1]   Test if entered callsign is a valid callsign
               (1=Yes, 0=No).
                                                                 Default: 0


Compiled from descriptions of
DB2OS, DF2AU und DC4OX ........................ DJ1OR september/1992
Updated for TF2.6 ............................. DB2OS july/1993
Translated to english ......................... DL4YBG september/1994