                                 UIDIGI

                           Versione 1.6 TNC2

                 Copyright 2000 Marco Savegnago IW3FQG



Cos'e' UIDIGI?
--------------
UIDIGI e' un firmware da utilizzare con un normale TNC2 per realizzare
un digipeater packet radio con funzioni avanzate adatto all'uso come
digipeater APRS (APRS is a register trademark of Bob Bruninga WB4APR).



Perche' UIDIGI?
---------------
Perche' anche se e' possibile usare un normale TNC per realizzare un
digipeater, UIDIGI realizza un digipeater con una serie di funzionalita'
che lo rendono adatto a venir impiegato in una rete APRS complessa.


Le caratteristiche di UIDIGI
----------------------------
Il firmware puo' essere montato su un TNC2 o Clone compatibile al 100% con clock
della CPU a 2.4576Mhz, 4.9152Mhz 9,8304Mhz e 32K di RAM.
               
-  Supporta AX.25 versione 1 e 2.

-  Configurazione dei parametri AX.25 di comunicazione Timers, SlotTime
   Persistence etc direttamente nella EPROM.

-  Gestione della ripetizione del frame AX.25 UI indirizzati al nominativo o
   alias del digipeater.

-  Gestione della ripetizione del frame APRS (con possibilita' di selezionare
   l'algoritmo da usare) indirizzati a:
   RELAY, WIDE, TRACE

-  Gestione della ripetizione del frame APRS del tipo 'avanzato':
   WIDEn-n e TRACEn-n

-  Limitazione del rate di ripetizione di frame (funzione UIFLOOD).

-  Gestione remota protetta da password con possibilita' di conoscere alcuni
   parametri statistici relativi al funzionamento del digipeater.

-  Lista delle stazioni ascoltate.

-  Trasmette periodicamente il beacon con 120 caratteri di informazioni
   personalizzabili su un PATH ridefinibile.

-  Risponde ai frame di query APRS provenienti da altre stazioni.


La versione di UIDIGI
---------------------
Se nell'intestazione del programma a fianco al numero di versione compare la
dicitura ALFA, BETA o GAMMA significa che il firmware potrebbe (e sicuramente
potra'!) non essere ancora completamente a posto per cio' che riguarda il
funzionamento.
Cosa c'e' di piu' brutto di quando un programma ha dei buchi e si pianta???
Per questo tendo a rilasciare le versioni dei miei programmi solo quando sono
certo del loro funzionamento (o gran parte).


Perche' ancora il TNC2?
-----------------------
- Perche' sicuramente chiunque ha un vecchio TNC2 a 1200bd da riciclare!
- Perche' in cima a una montagna un TNC2 e' molto meglio di un computer!


A cosa serve UIDIGI ??
----------------------
Chiunque opera in una rete packet radio APRS sa' che il sistema funziona se
ci sono dei digipeater che indipendentemente dal loro nominativo siano in grado
di ripetere frame indirizzati a path generici tipo RELAY o WIDE.
Per far questo e' possibile usare un normale firmware, comprarne uno della
Paccom oppure comprare un KPC Kantronics...
Altrimenti si puo' usare UIDIGI che fa' le stesse cose di un normale
digipeater con in piu' le caratteristiche sopra elencate.

Come usare UIDIGI
-----------------
UIDIGI funziona come qualunque altro firmware per TNC2.
Modificate il file sorgente di configurazione, compilatelo e generate il
file binario che andra' scritto su una EPROM da 32K.


Gestione di ripetizione dei frame
---------------------------------
Il digipeater e' abilitato a ripetere solo i frame AX.25 di tipo UI (proprio
per evitare che il digipeater possa venir utilizzato per fare del normale
traffico AX.25) indirizzati al proprio nominativo, il proprio alias o
agli indirizzi generici: RELAY WIDE o TRACE.

Caso 1:

    Un frame del tipo:
    IW3FQG>APRS v RELAY, WIDE

    viene ripetuto dal primo UIDIGI:
    IW3FQG>APRS v RELAY*, WIDE

    il secondo invece effettuera' la sostituzione del nominativo:
    IW3FQG>APRS v RELAY, DIGI*

Caso 2:
    Un frame del tipo:
    IW3FQG>APRS v RELAY,WIDE1-1

    viene ripetuto dal primo UIDIGI:
    IW3FQG>APRS v RELAY*, WIDE1-1

    e dal secondo UIDIGI (viene decrementato l'ssid e NON viene settato il bit H):
    IW3FQG>APRS v RELAY*, WIDE1-0

    e dal terzo UIDIGI (non viene decrementato l'ssid perche' e' gia' zero e viene
    settato il bit H):
    IW3FQG>APRS v RELAY, WIDE1-0*

Caso 3:
    Un frame del tipo:
    IW3FQG>APRS v RELAY,TRACE1-1

    viene ripetuto dal primo UIDIGI:
    IW3FQG>APRS v RELAY*, TRACE1-1

    e quindi dal secondo digipeater:
    e dal secondo UIDIGI (viene decrementato l'ssid e viene inserito il call del
    digipeater con il bit H settato):
    IW3FQG>APRS v RELAY, DIGI1*, TRACE1-0

    e dal terzo UIDIGI (l'ssid e' a zero viene fatta la sostituzione del
    nominativo con quello del nodo e su questo viene settato il bit H):
    IW3FQG>APRS v RELAY, DIGI1, DIGI2*

L'interfaccia Sysop di UIDIGI
-----------------------------
Il sysop del digipeater puo' collegarsi direttamente al nodo con un programma
di terminale oppure attraverso la seriale del TNC2.
Nel primo caso come prima cosa e' necessario richiedere la procedura di
identificazione come sysop (con il comando SYSOP), con qualunque altro comando
il digipeater scolleghera' l'utente.

I comando a disposizione del SYSOP sono i seguenti:

CONNECT [nominativo]
- Permette di collegare un altro digipeater o utente

INFO
- Mostra le informazioni sul funzionamento del digipeater

PARMS   [numero parametro] [valore]
- Permette di modificare i parametri del digipeater

I parametri disponibili sono:
    1 Txdelay (1~255)
    2 Persistence (1~255)
    3 Slottime (1~255)
    4 Frack (1~15)
    5 Maxframe (1~7)
    6 Retries (0~127)
    7 Timer 2 (0~6000)
    8 Timer 3 (0~65535)
    9 Digipeater Enable (0~255)

    /* 0 = No digi
    /* bit 1 = Digipeated On AND RELAY          */
    /* bit 2 = Digipeated On AND WIDE           */
    /* bit 3 = Digipeaten On AND TRACE          */
    /* bit 4 = Digipeaten On AND WIDEn-n        */
    /* bit 5 = Digipeaten On AND TRACEn-n       */

    10 Digipeater Mode (0~255)

    /* APRS digipeater mode bit mask            */
    /* 00 = Use standard mode digipeating       */
    /* 01 = Use call substituition              */
    /* 10 = Use WIDEn-n algorithm               */
    /* 11 = Use TRACEn-n algorithm              */

    11 Beacon Enable (0~1)
    12 Beacon Interval (0~65535)
    13 UI Flood seconds (0~180)
    14 Reply to APRS query (0~1)

RESET
- Provoca un reset a caldo del digipeater

SYSOP
- Avvia da parte del nodo la procedura per identificare l'utente come SYSOP

TEST
- Avvia la procedura per il test del trasmettitore

USERS
- Mostra gli utenti collegati al digipeater

HIGH [0|1]
- Accende il LED (CON 0 o STA 1) del TNC2

LOW  [0|1]
- Spegne il LED (CON 0 o STA 1) del TNC2

K [hh:mm:ss]
- Imposta il clock interno del digipeater

MHEARD
- Mostra le stazioni ascoltate dal digipeater


La configurazione di UIDIGI
---------------------------
Il programma UIDGCFG serve a modificare i valori di default dei parametri
memorizzati nella EPROM.
Per modificare i parametri per prima occorre editare il file UIDGCFG.TXT
il cui nome puo' essere modificato) e modificare i parametri secondo le
esigenze.
Alla fine e' necessario usare il programma UIDGCFG.EXE per modificare il
file binario di destinazione che verra' usato per programmare la EPROM.

Come procedere:

nell'archivio di distribuzione sono presenti i file:
UIDIGI.BIN
UIDGCFG.TXT
UIDGCFG.EXE

Copiate questi 3 file da qualche parte nel vostro computer.
Rinominate i file UIDIGI.BIN e UIDGCFG.TXT con il nome del digipeater che
andate a realizzare es: IR3VIG.

Ora i file hanno nome:

IR3VIG.BIN
IR3VIG.TXT
UIDGCFG.EXE

Con un text editor qualunque modificate le impostazioni del file UIDGCFG.TXT
seguendo le indicazioni presenti nel file stesso per quanto riguarda i
parametri.

//  Imposta il nominativo del ax.25 (completo dell'SSID se necessario)

DigipeaterCallsign		=	IR3VIG

//  Imposta l'alias del digipeater (senza SSID)

DigipeaterAlias			=	JN55SN

//  Imposta l'indicativo di destinazione dei beacon del digipeater

BeaconDestination		=	APZ16

//  Imposta il percorso di invio dei beacon AX.25

BeaconPath				=	WIDE, WIDE

//  Imposta il Txdelay del digipeater (default 30 = 300)

TxDelay					=	25

//  Imposta se il digipeater funziona in Fullduplex (default 0)

FullDuplex                              =       0

//  Imposta PPErsistence (default 64)

PPersistance			=	64

//  Imposta Slottime (default 10)

SlotTime                                =       10

//  Imposta Frack   (default 5)
Frack                                   =       5

//  Imposta Maxframe (default 4)
Maxframe				=	4

//  Imposta Retry (default 15)

Retry					=	15

//  Imposta Timer 2 (default 100)

Timer2                                  =       100

//  Imposta Timer 3 (default 18000)

Timer3                                  =       18000

//  Imposta se il digipeater deve emettere Beacon (default 1)

BeaconEnable			=	1

//  Imposta l'intervallo di emissione dei Beacon (default 600)

BeaconInterval			=	600

//  Imposta l'intervallo minimo di ripetizione dei frame uguali (default 28 sec)

MiniDigipeatedInterval  =       28

//  Digipeater Enable Mask (default 31)

DigipeaterEnableMask    =       31

//  Digipeater Algorithm (default 149)

DigipeaterAlgorithm		=	149

//  Risponde alla Query APRS (default 0) Non ancora implementata

ReplyToAPRSQuery		=	1

//  Sysop Password fino a 80 caratteri

SysopPassword           =   abc01234

//  Digipeater Info Text fino a 80 caratteri

DigipeaterInfoText		=	UI DIGI 1.6 IR3VIG Vicenza (JN55SN)

//  Digipeater infotext fino a 120 caratteri

DigipeaterBeaconText    =   !4532.21N/01132.21E#PHG2260/Vicenza TEST APRS DIGIPEATER (UIDIGI 1.6)

Per impostare il testo del beacon seguite le indicazioni di WB4APR che seguono:

POSIT TEXT:  The posit text above is standard APRS posit as follows:

   !                    means it is a fixed, non moving posit
   DDMM.mmN/DDDMM.mmW   is LAT/LONG in degrees and minutes
   PHGphgd              where p is power as the SQRT of P 
                              h is log2(HAAT/10)
                              G is gain in dB
                              d is directivity in deg/45
   #                    means it is a digipeater
   /                    The separator between the LAT/LONG
                        should be:  / for WIDE or RELAYS
                                    \ for WIDE-RELAYS
                                    T for TRACE digis
                                    N for WIDEn-n digis
   /A=xxxxxx            is altitude in feet for 3D

You can see by the integers in the POWER-HEIGHT-GAIN (PHG) string, there 
are only 9 plus 0 possible values for each of these fields as follows:

  DIGITS   0  1  2   3   4   5   6    7    8    9  as used in the PHG field
  -------------------------------------------------------------------------
  POWER    0, 1, 4,  9, 16, 25, 36,  49,  64,  81  watts  SQR(P)
  HEIGHT  10,20,40, 80,160,320,640,1280,2560,5120  feet   LOG2(H/10)
  GAIN     0, 1, 2,  3,  4,  5,  6,   7,   8,   9  dB
  DIR   OMNI,NE, E, SE,  S, SW,  W,  NW,   N,   .  This offsets the range
                                                   circle in the indicated
                                                   direction
           
HEIGHT ABOVE AVERAGE TERRAIN:  Going out 10 miles in all directions, write
down the elevation every mile or so.  Average all of these points and
compare your elevation to the average.  You may be at 2000 feet above
sea level and have a 150 foot tower, but if the ground around you is at
2200 feet, then your HAAT is -50 feet!!!  Be honest!  Your circle should
go no further than the distance to which you can reliably copy an HT!  
Even though you have an OMNI antenna, if the terrain favors a certain 
direction, then put that in for your directivity.

    !DDMM.mmN/DDDMM.mmW#PHG5360/WIDE...(identifying comments)...
      |         |      | | ||||  |_____ makes station show up green
      |         |      | | ||||________ Omni (Direction of max gain)
      |         |      | | |||_________ Ant gain in dB
      |         |      | | ||__________ Height = log2(HAAT/10)
     LAT      LONG     | | |___________ Power = SQR(P)
                       | |_____________ Power-Height-Gain identifier *
                       |_______________ # is symbol for digipeater

     As you can see by the integers in the PHG string, there are only 10
     possible values for each of these fields as follows:

     DIGITS   0  1  2   3   4   5   6    7    8    9         Equation
     -------------------------------------------------------------------
     POWER    0, 1, 4,  9, 16, 25, 36,  49,  64,  81  watts  SQR(P)
     HEIGHT  10,20,40, 80,160,320,640,1280,2560,5120  feet   LOG2(H/10)
     GAIN     0, 1, 2,  3,  4,  5,  6,   7,   8,   9  dB
     DIR      0,45,90,135,180,225,270, 315, 360,   .  deg    (D/45)

     The DIRECTIVITY field offsets the PHG circle by one third in the
     indicated direction.  This means a front to back range of 2 to 1.
     Most often this is used to indicate a favored direction or a null
     even though an OMNI antenna is at the site.  Note that 0 means
     OMNI and 8 means 360 or a NORTH offset.

     HIGHTS are ABOVE-AVERAGE TERRAIN!  Not above ground or sea
     level.  Your antenna may be at 1000 ft above sealevel and be on
     a 100 foot tower.  But if you go out 10 miles in all directions
     and find that the average elevation is 1200 feet, then your
     height-above-averag-terain is less than ZERO!!!!




Normalmente modificate solo quello che vi sembra di dover cambiare quello
che non capite lasciatelo com'e'!

Compilate la versione con il comando:

UIDGCFG IR3VIG.BIN IR3VIG.TXT

Se non ci sono problemi il programma non da' nessun avvertimento, se ci sono
problemi ve li segnala.

Programmate una eprom che possa contenere l'immagine del file IR3VIG.BIN
montatela nel TNC2 e date fuoco (accendete).

Se tutto e' andato bene qualche istante dopo l'accensione il TNC2 emettera' il
beacon.



L'autore UIDIGI
---------------
Questo testo non e' stato scritto con l'intento di fornire un manuale
dettagliato per i meno esperti.
Il firmware viene fornito senza nessun supporto da parte dell'autore che si
riserva la possibilita' di modificarlo o di sospenderne la libera diffusione
futura in ogni momento.
Se qualcuno trova qualche errore o ha qualche buona idea o suggerimento
(non adattamenti personali!) me lo puo' far sapere a mezzo lettera o messaggio
SCRITTO, NON a parole (radio, telefono, citofono...).

Il mio indirizzo e':

        Marco Savegnago
        Stradella Ospedale 87
        36100 Vicenza

In Packet-Radio:

        IW3FQG@I3KUH.IVEN.ITA.EU

In Internet:

        msave@tin.it


Legal trademark
---------------
APRS is a register trademark of Bob Bruninga WB4APR


Copyright di UIDIGI
-------------------
Il firmware UIDIGI e le sue componenti sono liberamente copiabili e
distribuibili in qualsiasi forma e mezzo per scopi AMATORIALI e da cui comunque
non si possa trarre profitto.
Qualunque tipo di sfruttamento commerciale non espressamente autorizzato
dall'autore e' da considerarsi proibito! 

Fonti e riferimenti bibliografici
---------------------------------
-   Implementazione dell'AX25 del programma NOS di KA9Q

-   Implementazione dell'AX25 del programma TheFirmware del gruppo tedesco
    NORD><LINK

-   Tanenbaum, Andrew S., "Computer  Networks"    pp.  288-292.
    Prentice-Hall  1981.

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

