UIDIGI

Version 1.8 (20020608) TNC2

Copyright 2000~2002 Marco Savegnago IW3FQG

English Version



What is UIDIGI?

UIDIGI is firmware to use a TNC2 (or TNC2 clone) as an APRS packet digipeater with advanced functions.
(APRS is a register trademark of Bob Bruninga WB4APR)


Why UIDIGI?

Several reasons.  But the bottom line is cost, availability, and performance !!!  Cost because the TNC2/clone package is the cheapest (when time to assemble is included in calculations), they are widely available, and most importantly, UIDIGI brings features to the TNC2/clone that make it efficient for use in a complex APRS network.

What's new

Please read the file changes.txt to see the changes from version 1.7


The characteristics of UIDIGI

- The firmware may be installed in a TNC2 or 100% compatible clone with CPU clocks of 2.4576Mhz, 4.9152Mhz and 9.8304Mhz.  TNC2/clone must have at least 32K of RAM.

- Support AX.25 release versions 1 and 2.

- Full control of AX.25 link layer parameters. (Timers, SlotTime, Persistence)

- Repeat only AX.25 UI frame with PID 0xf0 (or any other user). 

- Supports digipeating of UI AX.25 frames addressed to the digipeater callsign or alias.

- Supports digipeating of UI AX.25 frames addressed to user definable (up to 8) generic callsign, with call substitution.

- Supports digipeating of UI AX.25 frames addressed a generic call (eg: WIDE) using flooding algorithm.

- Supports digipeating of UI AX.25 frames addressed a generic call (eg: TRACE) using trace+flooding algorithm.

- Ignore duplicated frames sent in a defined interval.

- Ignore digipeating of digipeater originated frame (beacon), frame already digipeated with call substitution or generic callsign.

- Support for handling different SSID meaning on destination call of the UI Frame (Directional Beacon)

- Support for preempted digipeating. 

- Remote management protected by password.

- Digipeater heard station list.

- Up to 3 user definable Beacons.

- Reply to the APRS query.

- Full configuration support via customized eprom image.

- Full control of configuration via radio link of all items (except Password and Full Duplex).

The release of UIDIGI

If the program version you are using is labeled ALPHA or BETA,  the version you are using is not considered to be a stable version.

Why still use a TNC2?

- Because TNC2's (and clones) are easy to get - both new and used.
- Because it's better than a computer if you have to mount a digi on top of a mountain!


How to use UIDIGI

UIDIGI EPROM image is distributed in binary form.
You must configure it before making an EPROM, to do this you change the configuration settings
in the file UIDIGI.TXT and then use the UIDGCFG program to make the binary image. 
Once you have the binary image you can burn the EPROM.


Handling of the UI FRAME

The digipeater is capable of repeating only the AX.25 UI type frames (this insures that the digipeater may not be used as a normal AX.25 digipeater).  As a UI frame digipeater, it only digipeats frames addressed to the callsign, the alias, or to the generic addresses (RELAY WIDE or TRACE) or to the special APRS addresses WIDEn-n TRACE n-n.


Method 1 (Specified Path):

        A frame like this:
        IW3FQG>APRS v UIDIGI, WIDE

        will be repeated from the digi:
        IW3FQG>APRS v UIDIGI*, WIDE


Method 2 (Generic Path):

        A frame like this:
        IW3FQG>APRS v RELAY, WIDE

        will be repeated from the digi:
        IW3FQG>APRS v UIDIGI*, WIDE


Method 3 (WIDEn-n Path):

        A frame like this:
        IW3FQG>APRS v RELAY,WIDE1-1

        will be repeated from the first digi:
        IW3FQG>APRS v RELAY*, WIDE1-1

        and then from the second digi:
        IW3FQG>APRS v RELAY*, WIDE1-0

        then the third make the call substitution:
        IW3FQG>APRS v RELAY, WIDE1-0*

Method 4 (TRACEn-n Path):

        A frame like this:
        IW3FQG>APRS v RELAY,TRACE1-1

        will be repeated from the first digi:
        IW3FQG>APRS v RELAY*, TRACE1-1

        and then from the second digi:
        IW3FQG>APRS v RELAY, DIGI1*, TRACE1-0

        and then from the third digi:
        IW3FQG>APRS v RELAY, DIGI1, DIGI2*

Method 5 (SSID Path): (experimental)

This method follows the implementation that I've observed in the TM-D700

I've observed that when UISSID is ON the digipeater repeats all UI frames addressed to ANY CALL with SSID > 0 (not only the mycall or other generic call) and digipeats as follows:

From SSID > 0 and SSID < 8

The frame will be repeated with the SSID of destination decremented by one and the call of the digipeater will be put in the via list.

Example:

A frame like this (MYCALL is IW3FQG and UNPROTO is APRS-7):

IW3FQG>APRS-7:

will be repeated to:

IW3FQG>APRS-6, DIGI*:

With SSID > 8 the translation rules is different because there is the direction rule.

If SSID is equal to 8 (North direction)

If the digipeater hears an UI frame addressed to ANY call with a ssid = 8 it repeats the frame, puts the SSID of the  destination to zero, puts the digipeater callsign in the via list and attaches to this, if available, the path for North direction (NPATH parameter in D700).

Example:

A frame like this (MYCALL is IW3FQG and UNPROTO is APRS-8, NPATH in the digi is set to NORTH):

IW3FQG>APRS-8:

will be repeated to:

IW3FQG>APRS,DIGI*,NORTH:

If SSID is equal to 12 (North direction)

If the digipeater hears an UI frame addressed to ANY call with ssid = 12 it repeat the frame, put the SSID of destination the same as received, put the digipeater callsign in the via list and attach to this if available the path for North direction (NPATH parameter in D700).

Example:

A frame like this (MYCALL is IW3FQG and UNPROTO is APRS-12, NPATH in the digi is set to NORTH):

IW3FQG>APRS-12:

will be repeated to:

IW3FQG>APRS-12,DIGI*,NORTH:

The same rule is valid for South (SSID 9,13) East (10, 14) and West (11, 15).

I've observed that in all cases if the frame is sent with a digipeater to the via path (ex: APRS-8 VIA DIGI) the frame is not repeated.

IW3FQG>APRS-8,DIGI:

Is not repeated by the digipeater.

Method 6 (Preempt digipeating): (experimental)

The preemption process is a kind of frame preprocessing that removes unused digipeaters in the path.

When the digipeater hears a frame like this:

STATION1>APRS, PATH1, PATH2, PATH3

and has PREEMPT 1, PREEMPTCALLS PATH3, PREEPTADD (none)

before processing the frame with the standard digipeating rules changes the frame in:

STATION1>APRS, PATH3

then process the frame with the standard APRS digipeating rules.

With the parameter PREEPTADD NEW1

the frame will be STATION1>APRS, PATH3, NEW1

Please remember that the preemption process is a preprocessing so if after the processing the frameit is not to be digipeated UIDIGI doesn't send the frame.

Now consider the following example:

A station (IW3FQG) sends a frame like this:

IW3FQG>APRS,IR3VIF*, IR3VIG, IR3FAL

IR3FAL is a digipeater that heard this frame. Without preemption it don't
repeat this frame because first must be digipeated by IR3VIG.

With preempt ON, and IR3FAL in PREEMPTCALLS, IR3FAL digipeater pre processes
the frame like this:

IW3FQG>APRS,IR3VIF*,IR3FAL

and then repeats the frame:

IW3FQG>APRS,IR3VIF,IR3FAL*

Optionally with PREEMPTADD the digipeater may add new path so the same frame with PREEMPTADD PATH1, PATH2 become:

IW3FQG>APRS,IR3VIF,IR3FAL*,PATH1,PATH2


Method 7 (Local Preempt digipeating): (experimental)

The local digipeater preemption feature was proposed by IK2YDM and IW2FUS
  both members of GAL (Gruppo APRS Lombardia).

  During the past TRACE2001 conference they ask to me to implement a new
  feature on the UIDIGI firmware to allow the use of the firmware in local
  digipeater (digipeater that serve local area like small valley).

  This feature is activated enabling the bit 1 of the PREEMPT (PREEMPT 2)
  comand or the corresponding parameter PREEMPTEDDIGIPEAT.

  In a small valley digipeater they need that when it receive an already
  digipeated frame from a wide digipeater it not propagate the frame as
  a normal APRS digipeater but simply repeat the frame locally.

  Eg:

  IW3FUS-11 is a local digipeater

  When it receive a frame like this:

  IK2YDM>APRS,RELAY,TRACE7-7

  it must repeat as usual the frame:

  IK2YDM>APRS,IW2FUS-11*,TRACE7-7

  if it receive a frame already repeated:

  IK2YDM>APRS,IW2FPO-11*,TRACE7-7
  or
  IK2YDM>APRS,IW2FPO-11*,TRACE7-6
  or
  IK2YDM>APRS,RELAY,DIGI1,DIGI2,DIGI3,DIGI4,DIGI5,DIGI6*,TRACE7-1

  it must repeat a frame like this:

  IK2YDM>APRS,IW2FUS-11*


The Local Sysop interface of UIDIGI

To logon locally, connect the TNC to a computer via serial port.
Check the speed in the hardware jumper of the TNC2, then using a terminal program open the com port with the following  communications parameters: <TNC speed > 8N1, local ECHO off.

To enter in the sysop interface use the follow command:

[ESC] C [ENTER]

Now you can send any of the following  command to the digipeater and get response.
To exit use QUIT command.

The sysop can connect directly the digipeater from the radio port or via the serial port.
In the first case (radio port) the sysop must send the password using the SYSOP command (using the
standard NETROM algorithm meaning password request will come as a random number representing the
number requested from the password).
Example: password: MYPASSWORD after the sysop command is issued via remote you will be prompted for something like 2 5 7 9. Your response would be YSWR 
From the local port the comm. Port is N81(speed in jumper setting in TNC)
Press [ESC] c [Enter] to logon locally

The commands available to the SYSOP are as follows:

AUXDEST [address]
- Sets the destination address for the beacon with aux input data 

AUXPATH [path]
- Sets the path for the beacon with aux input data 

AUXRATE [n]
- Sets the interval for the beacon with aux input data 

BDL [bnum] [path]
- Sets the beacon path (bnum = 1~3, path = AX.25 path)

BEACON [bnum] [n] (default 1-600 2-1800 3-3600)
- Sets the beacon interval (bnum = 1 ~ 3, n = 0 ~ 65535 sec)

BEACONOFFSET [bnum] [n] (default 1-0 2-0 3-0)
-Sets the beacon offset (bnum = 1 ~ 3, n = 0 ~ 65535 sec)

BTEXT [bnum] [text] (Up to 70 characters)
- Sets the beacon text (bnum = 1~3, text = beacon text)

BUDLIST [callsigns]
-Sets the callsign that will be ignored by digipeater (all SSID's of base call)

CHECK [n] (1-65535msec) (default 18,000)
- Sets the LinkCheck parameter
- Defines the SysOp No-Activity Period

CLOCK [hh mm ss]
- Set the internal clock of digipeater

CONNECT [call]
- Connects to another station

DIGIALIAS [call]
- Sets the digipeater alias
- Up to 6 characters

DIGICALL [call]
- Sets the digipeater callsign
- Up to 6 characters + SSID

DIGIPEAT [n] (n=0,1) (default 1)
- Global Enable Flag for digipeater
- Enables (1) or Disables (0) Digipeating

DUPLIST
-Shows the duplication list 
-With DU _ the sysop can clear the list

EPATH [path]
- Sets the path for East destination (SSID 10|14)
- Up to 8 hops

FRACK [n] (n=1-15sec) (default 5)
- Sets the FRACK
- Frame Acknowledgement Timeout

HIGH [n] (n=0,1)
- Turns ON the TNC2 Led's (CON 0 o STA 1)

INFO [text]
- Shows the digipeater info
- Up to 80 characters (text shown at initial beacon and on screen)

LED
- Show the state of the TNC2 Led's

LOW  [n] (n=0,1)
- Turns OFF the TNC2 Led's (CON 0 o STA 1)

MAXFRAME [n] (n=1-7) (default 4)
- Sets the MAXFRAME
- Limit of Unacknowledged Frames

MHEARD
-Shows the last heard station list
-With MH _ the sysop can clear the heard list

NPATH [path]
- Sets the path for North destination (SSID 8|12)
- Up to 8 hops

PERSISTANCE [n] (n=1-255) (default 64)
- Sets the PPersistance
- Parameter for channel access timing 

PREEMPT [n] (n=0-3) (default 0)
- bit 0 Enables(1) or Disables(0) Preemted Digipeating
- bit 1 Enable (1) or Disables(0) Local Preemted Digipeating

PREEMPTADD [calls]
- List of Callsigns (all SSIDs of base call) for Digi to add after preempt

PREEMPTCALLS [calls]
- List of Callsigns (all SSIDs of base call) for Digi to search for preempt

QUIT
- Disconnect from digipeater

RESET
- Resets the digipeater

RESPTIME [n] (n=0-6,000ms) (default 100)
- Sets RESPTIME
- Mininimum delay imposed on acknowledgement packets

RESTART
- Restart the digipeater
- restart using parameters from PROM

RETRY [n] (n=1-127) (default 10)
- Sets the RETRY
- Maximum number of retry attempts

SLOTTIME [n] (n=1-255 x100ms) (default 10)
- Set the SLOTTIME
- Selects Length of delay between channel access attempts

SPATH [path]
- Sets the path for South destination (SSID 9|13)
- Up to 8 hops

SYSOP
- Start the authentication process to access to the sysop interface via radio link
  With ? the digipeater shows the result of sysop authentication 

TEST
- Starts the TEST of the digipeater

TXDELAY [n] (n=1-255 x10ms) (default 10)
- Sets TxDelay

UICHECK [n] (n=0-250sec) (default 28)
- Sets number of seconds that the digipeater uses to ignore duplicate packets
- Minimum period between between digpeating of duplicate packets

UIDIGI [calls] (default relay, wide, trace)
- Sets the generic calls (up to 8) that digipeater uses to digipeat UI frames

UIDCSB [n] (default 1) 
- Enables call substitution in frames addressed to callsigns defined in UIDIGI command 
- Enables (1)/Disables(0) Callsign substitution for UIDIGI Calls

UIFLDFL [n] (default 0)
Se the UIFLOOD Algorithm flags:
        bit 0 make call substitution after the last WIDEn-n digied
        bit 1 insert callsign before WIDEn-n

UIFLOOD [call]
- Sets the generic call that will be used in the flooding algorithm
- Up to 6 characters

UILOOP [n] (n=0-3) (default 3)
- Sets the Loop Packet Suppression Interval Mask
    0x01 = Do not repeat frame with source address equal to digipeater call or alias
    0x02 = Do not repeat frame with the digipeater call in the already digipeated via list

UIMSG [n] (n=0-1) (default 1)
- Enable UI-VIEW Station Message frame to be digipeated without SSID decrement (0 disable this feature)

UIONLY [n] (n=0-1) (default 1)
- Enable digipeating of only UI AX.25 (0 disable this feature)

UIPID [n] (n=1-255) (default 240)
-Enables frame filtering algorithm based on PID of frame (0 disables this feature)

UIQUERY [n] (n=0,1) (default 1)
- Sets if the digipeater replies to generic query (with beacon 1).
- Enables (1) or Disables (0) TNC response to ?APRS? query

UISSID [n] (n=0,1) (default 1)
- Sets if the digipeater processes the incoming UI frame using destination SSID
- Enables (1) or Disables (0) SSID Digipeating mode

UITRACE [call]
- Sets the generic call that will be used in the TRACE algorithm
- Up to 6 characters

UITRFL [n] (n=0,1) (default 0)
- Enables (1) or Disables (0) Callsign substitution after last TRACEn-n digipeated

UNPROTO [call]
- Sets the beacon destination
- up to 6 characters + SSID (AX.25 destination address for UI beacons)

WPATH [path]
- Set the path for West destination (SSID 11|15)
- Up to 8 hops

Note: on all path or callsign command (BDL, BTEXT, BUDLIST, DIGIALIAS,  DIGICALL, EPATH, MHEARD, NPATH, PREEMPTADD, PREEPTCALL,  SPATH, UIDIGI, UIFLOOD, UITRACE, UNPROTO, WPATH) to delete all the strings stored use the character '_'
Eg: NPATH _ <enter> deletes the contents of NPATH.
Special case MHEARD where, MHEARD _ clears the heard list 

The Remote Sysop interface of UIDIGI

In order to logon remotely the sysop must first connect to the digipeater.
After the connection is established, the sysop must send "SYSOP" command and get the response (netrom password request) from the digipeater. 
UIDIGI use standard NETROM algorithm to authenticate a user as SYSOP. 
This means that password request will come as a random number representing the number requested from the password).

Example: 
if the password stored in the eprom is MYPASSWORD after the sysop command is issued via remote you will be prompted for something like 2 5 7 9. Your response would be YSWR 

The User interface of UIDIGI

A user can connect the digipeater to get basic information about the digipeater (location power or other info that the sysop or get heard list.
In order to logon remotely the sysop must first connect to the digipeater.
After the connection is established, the user can send "Info" or "Mheard" command to see the information or the heard list.

The heard station list

UIDIGI stores up to 100 stations in the callsign heard buffer from the radio port. If a station was heard via a digipeater, the callsign is followed by an asterisk. Each callsign is followed by the time when was heard, the time value is taken from the internal clock value of the digiperater. If the UIDIGI clock was not set by the sysop all the time values will be wrong. 
The sysop may use the command MHEARD _ to clear the list.


Frame duplication check

The digipeater stores hash value of all digipeated frames in a circular buffer with 128 slots (FIFO).
It never repeats an equal frame within the period defined in the parameter UICHECK 
Since the digipeater performs call substitution on generic calls (RELAY, WIDE, TRACE ... up to 8 and sysop definable) the digipeater does not repeat frames with source address equal to digipeater call or alias (its beacon) and
also does not repeat frames with the digipeater call in the already digipeated via list.


Beacon timers handling

    With:

    Beacon1Interval=300, Beacon2Interval=600, Beacon3Interval=900
    Beacon1Offset=0, Beacon2Offset=0, Beacon3Offset=0

    At  00:05:00  (Beacon1Interval+Beacon1Offset expire) Beacon 1 will be sent
    At  00:10:00  (Beacon1Interval+Beacon1Offset expire and
                  Beacon2Interval+Beacon2Offset expire and )
                  Beacon 1 and Beacon 2 will be sent
    At  00:15:00  (Beacon1Interval+Beacon1Offset expire and
                  Beacon3Interval+Beacon3Offset expire and )
                  Beacon 1 and Beacon 3 will be sent
    At  00:20:00  (Beacon1Interval+Beacon1Offset expire and
                  Beacon2Interval+Beacon2Offset expire and )
                  Beacon 1 and Beacon 2 will be sent
    At  00:25:00  (Beacon1Interval+Beacon1Offset expire) Beacon 1 will be sent
    At  00:30:00  (Beacon1Interval+Beacon1Offset expire and
                  Beacon3Interval+Beacon3Offset expire and )
                  Beacon 1 and Beacon 3 will be sent

    With:

    Beacon1Interval=1200, Beacon2Interval=1200, Beacon3Interval=1200
    Beacon1Offset=0, Beacon2Offset=300, Beacon3Offset=600

    At  00:20:00 (Beacon1Interval+Beacon1Offset expire) Beacon 1 will be sent
    At  00:25:00 (Beacon2Interval+Beacon2Offset expire) Beacon 2 will be sent
    At  00:30:00 (Beacon3Interval+Beacon3Offset expire) Beacon 3 will be sent

    At  00:40:00 (Beacon1Interval+Beacon1Offset expire) Beacon 1 will be sent
    At  00:45:00 (Beacon2Interval+Beacon2Offset expire) Beacon 2 will be sent
    At  00:50:00 (Beacon3Interval+Beacon3Offset expire) Beacon 3 will be sent


The configuration of UIDIGI

The UIDGCFG program must be used to change the values of the default parameters stored in the in the image of the EPROM.
To change the parameters you need to edit the UIDIGI.TXT file with a simple text editor.
Then you must process it with the UIDGCFG.EXE program that stores the configuration in the
destination binary image.

Proceed as follows.

In the file of distribution there are the following files:
UIDIGI.BIN
UIDIGI.TXT
UIDGCFG.EXE

Copy these 3 lines in any directory of your computer disk.
Rename the UIDIGI.BIN and UIDIGI.TXT with the name of the digipeater that you are 
setting up (e.g.: IW3FQG).

Now the files have the names:

IW3FQG.BIN
IW3FQG.TXT
UIDGCFG.EXE

With a text editor change the entries in IW3FQG.TXT line following the indication 
written in the file.

You compile the file with the command:

UIDGCFG IW3FQG.BIN IW3FQG.TXT

If there are no problems the program won't give any warnings, if there are problems it will show it.

Now you can program the EPROM with the binary image stored in the IW3FQG.BIN.

Install the EPROM in the TNC2 and turn it on.

If everything is ok, the digipeater will emit a beacon.

Try it.


The UIDIGI author

This text is not written with the intent to furnish a complete and detailed manual  for the inexperienced user or sysop. 
The program comes furnished without any warranty (written or implied) and the author can decide to alter it any time or drop the free distribution at any moment.
If anybody finds any error or has any good ideas or hints (not personal adaptations please!) send me a letter or WRITTEN message, NO SPOKEN Messages (radio, telephone, intercom.).

Please, before writing me directly READ this entire manual, the FAQ's, read the messages or post a message in the UIDIGI mailing list: http://www.yahoogroups.com/group/uidigi. Thanks.


My address is:

        Marco Savegnago
        Stradella Ospedale 87
        36100 Vicenza
        Italy

In Packet-Radio:

        IW3FQG@I3KUH.IVEN.ITA.EU

In Internet:

	iw3fqg@amsat.org


Coordinate:	

Latitude: 	45( 33' 24" N
Longitude: 	11( 32' 34" E


Where to find the software

UIDIGI archives may be downloaded following the link that you can find at
the following URL:


http://space.tin.it/computer/msavegna/uidigi.htm (best)
or
http://www.ir3ip.net/~iw3fqg/uidigi.htm 

or in the files section of UIDIGI mailing list


UIDIGI mailing list

If you want to be informed about news and talk with other UIDIGI sysops subscribe to
the UIDIGI mailing list at:

http://www.yahoogroups.com/group/uidigi

Legal trademark

APRS is a register trademark of Bob Bruninga WB4APR


Copyright of UIDIGI

The UIDIGI program and its components are freely copyable and dispensable in any form = but only for amateur radio purposes and only where no profits or financial gain are involved.
Is also forbidden to use this program for demonstrations in commercial private and public business, institutional, towns, regional, state and other governments.
Any type of commercial exploitation not expressly authorized from the author is considered forbidden!
No responsibility is attributable to the author if the program during its execution causes the loss of data or malfunctions of the computer.

Copyright (c) 2000~2002 Savegnago Marco. All right reserved.

Free contribution
This is a free (but copyrighted!) software project. However if you find it useful and you want to encourage the author in future enhancement a free contribution is always accepted!!

Special thanks

Thanks:

Greg Noneman WB6ZSU for the support in debugging, testing and for the original UIDIGI command spreadsheet  
Allan Sadowski AH6LS for checking and correcting my original version of this text
Mark Cheavens KC5EVE for the correction and changes to this manual
Tim Cunningham N8DEU for his firmware setting page at http://www.qsl.net/n8deu
Kitahashi Akito JO3SEN for the japanese traslation of the UIDIGI documentation

All others who have reported bugs, suggestions, etc.



Fonts and bibliographic references

-      AX.25 Link Access Protocol for Amateur Radio version 2.2 november 11 1997 TAPR

- Implementation of AX25 in the NOS program of KA9Q

- Implementation of AX25 of the TheFirmware program of the group German NORTH><LINK

- Tanenbaum, Andrew S., "Networks Computer"  1st ed Prentice-Hall 1981.

- Tanenbaum, Andrew S., "Computer  Networks" 3st edPrentice-Hall  1996.

- X.25 MADE EASY Nicolas M.Thrope, Derek Ross Prentice-Hall 1992.

