UIDIGI Version 1.9 BETA 3 (20040101) TNC2 Copyright 2000~2004 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* (*) This method was removed in version 1.9B1 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: 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 _ 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 o r 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. Donation UIDIGI is free (but copyrighted!) software. You don't have to pay anything to use UIDIGI as Sysop or user. If you find it useful please send 10 Euros or US Dollars and a postcard of your city/country or QSL at the following address: Marco Savegnago Stradella Ospedale 87 36100 Vicenza Italy Thanks! 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>