
Configuration guide                                   Page 1
                    TheNet X-1J Release 4
                              
                 Configuration instructions

1. Introduction

     This    document   describes  the  build   process   for
     creating   a ROM image for TheNet X-1J release  4.  This
     process  differs from the early versions of TheNet-X  in
     that  it  is  delivered as two files rather than  three.
     This  is  in  response to a number  of  requests  for  a
     simpler  process.  In  addition  the  patcher  has  been
     considerably  changed and utilities for  hex  conversion
     are  included.  A routine to print out  passwords  in  a
     'user  friendly'  format  is included  together  with  a
     utility to change the help text in THENET2.X1J.
     
     BEWARE ! The files carry the same names as TheNet X-1J (
     original  release ). Be sure to use the correct  set  of
     files  !.  The files also carry the same names  for  the
     PK96   and   TNC2  versions  but  the  files   are   not
     interchangeable ( patch.* and sethelp.* are also version
     specific ).

2.   Files.

     The ROM image comes as two files,

           THENET1.X1J
           THENET2.X1J

     These two files are loaded into memory as described
     below.
     Before  loading them however, both should be  configured
     as described in section 3.
     
     In addition, the following files are also provided :
     
          PATCH.EXE
          INTEL.EXE
          MOTOROLA.EXE
          SETHELP.EXE
          PRINTPWD.EXE
          INTEL.C
          MOTOROLA.C
          SETHELP.C
          PRINTPWD.C
          X1JCONV.C
          X1JCONV.DOC
          X1JCONV.EXE
     
     PATCH.EXE  is the windowing patch utility  for  the  ROM
     images.  INTEL.EXE and MOTOROLA.EXE are  utilities  that
     are  designed to convert binary files into hex notation,
     in  the  Intel Intellec and Motorola S formats.  SETHELP
     changes  the  help screen and PRINTPWD does  the  pretty
     printing  by  extracting the password from  a  parameter
     save file created by PATCH.EXE.
     
     The  ROM image consists of two halves, one for the lower
     half  of  a 512K EPROM, and one for the upper half.  The
     files are loaded as shown :
     
           FILENAME           Load starting at hex
           =========================================
           THENET1.X1J        0000
           THENET2.X1J        8000

     No  information  on  how  to  load  the  files  into   a
     programmer  is  presented as all are different.  Typical
     scenarios are however given in section 5.
     
3. Configuration

     Each  of  the  two halves of the ROM image contains  two
     different  parts,  a common set of drivers  &  interrupt
     routines and part of the functionality of the node. Part
     1  contains  the level 2, 3 and 4 software plus  the  IP
     router.  Part 2 contains the switch. For the  TNC2  each
     must  be  patched  in an identical way  to  reflect  the
     desired  operation  as each part contains  an  identical
     section at the start of the file for configuration data.
     For  the  PK96 only the first file needs to be  patched.
     This  patching may be done manually or it  may  be  done
     with the patcher.

    The  first part of the ROM images is identical to  TheNet
    1.01  in  its    configuration.  These   parameters   are
    followed    by  additional ones for the extended  version
    as shown :
    
     HEX       FIELD
     LOCN      SIZE      DESCRIPTION

===========================================================
     003B      6 BYTES   CALLSIGN OF THE NODE
     0041      BYTE      SSID OF THE NODE CALLSIGN
     0042      6 BYTES   ALIAS OF THE NODE
     004A      WORD      MIN AUTO UPDATE QUALITY
     004C      WORD      HDLC DEFAULT ROUTE QUALITY
     004E      WORD      DEFAULT RS232 ROUTE QUALITY
     0050      WORD      INITIAL NODE LIFETIME
     0052      WORD      MIN LIFETIME TO BROADCAST
     0054      WORD      BROADCAST INTERVAL IN SECONDS
     0056      WORD      LEVEL 3 TIME-TO-LIVE INITIALISER
     0058      WORD      LEVEL 4 TIMEOUT IN SECONDS
     005A      WORD      LEVEL 4 RETRIES
     005E      WORD      LEVEL 4 ACK DELAY IN SECONDS
     0060      WORD      LEVEL 4 WINDOW SIZE
     0062      WORD      NUMBER OF BUFFERED FRAMES PER CONNECTION
     0064      WORD      NO ACTIVITY TIMEOUT IN SECONDS
     0066      WORD      PERSISTENCE
     0068      WORD      SLOT TIME IN TENS OF MILLISECONDS
     006A      WORD      LEVEL 2 INITIAL T1 COUNTER IN SECONDS
     006C      WORD      LEVEL 2 WINDOW SIZE
     006E      WORD      LEVEL 2 RETRIES
     0070      WORD      LEVEL 2 INITIAL T2 COUNTER
     0072      WORD      LEVEL 2 INITIAL T3 COUNTER
     0074      WORD      LEVEL 2 DIGIPEAT ENABLE FLAG
                         0 = DISABLED, 1 = ENABLED
     0076      WORD      CALLSIGN VALIDATION, 0 = OFF, 1 = ON
     0078      WORD      BEACON MODE, 0 = OFF, 1 = AFTER TRAFFIC,
                         2 = ALWAYS
     007A      WORD      CQ ENABLE FLAG, 0 = DISABLED, 1 = ENABLED
     007C      BYTE      FULL DUPLEX FLAG, 0=SIMPLEX, 1 = DUPLEX
     007D      BYTE      SEND FLAGS IF NO DATA NEEDED, 1 = YES
     007E      BYTE      COMMAND LEAD-IN CHARACTER ( ESCAPE )
     007F      BYTE      TRANSMIT KEY-UP DELAY, 10's OF MILLISECS
     0080      80 BYTES  DEFAULT PASSWORD
     00D0      BYTE      NULL BYTE AT END OF PASSWORD
     00D1      80 BYTES  INFORMATION MESSAGE
     0121      BYTE      NULL AT END OF INFORMATION STRING
     0122      WORD      CW REPEAT RATE IN SECONDS. 0 DISABLES
     0124      BYTE      CW BIT SPEED IN 10's OF MILLISECONDS
                         6 = 20 WPM
     0125      BYTE      DEFAULT HOST MODE. 0 = NORMAL
                         1 = HARDWARE HANDSHAKE CONNECT CONTROL
     0126      BYTE      CROSSLINK PROTOCOL MODE CONTROL
                         0 = TheNet NORMAL CROSSLINK PROTOCOL
                         1 = USE KISS INSTEAD OF CROSSLINK
                         2 = AS PER 1, ALSO COPY NON NODE PKTS
                         3 = AS PER 2 BUT COPY ALL PACKETS
     0127      BYTE      MHEARD LIST LENGTH. 0 = OFF, MAX = 100
     0128      BYTE      NODE BROADCAST CONTROL. 0 = NO BCAST
                         1 = HDLC PORT ONLY, 2 = RS232 PORT ONLY
                         3 = BOTH PORTS
     0129      WORD      RS232 NODE BROADCAST INTERVAL ( SECS )
                         0 DISABLES
     012B      BYTE      NODE BROADCAST ALGORITHM CONTROL.
                         BIT 0 = HDLC, BIT 1 = RS232
                         WHEN BIT SET, IMPLEMENT VARIANT ALGO.
     012C      8 BYTES   OPTIONAL BEACON DIGI LIST, NULL TERM.
     0134      WORD      DEFAULT BEACON INTERVAL IN SECONDS
     0136      BYTE      CONNECT REDIRECTION, 0=HOST 1=BBS 2=DXC
     0137      BYTE      HASH NODE CONTROL. Each bit controls whether
                         nodes whose alias starts with a  '#'
                         are  included  in node broadcasts  on  a
                         specific port. Bit 0 determines  port  0
                         ( the radio ), bit 1 controls the RS232
                         port.  If  a bit is set, hash nodes  are
                         not broadcast.
     0138      4 BYTES   THIS IS THE NODE'S AMPRNET ADDRESS.
                     It  is  a  numeric address of  4  bytes.
                     Each  byte  corresponds to one  byte  of
                     the  address, for example if the address
                     is  44.131.16.31, then the  data  stored
                     at  each of the bytes 138, 139, 13A  and
                     13B  respectively will be 1F, 10, 83 and
                     2C.  Contact your local co-ordinator for
                     an address.
     013C      4 BYTES   THIS IS THE AMPRNET ADDRESS USED  BY
                         THE NODE TO
                     RECOGNISE   BROADCASTS.  The   data   is
                     stored  in  the  same  way  as  for  the
                     node's  address ( as shown  above  ).  A
                     typical address would be 44.131.0.0  for
                     the UK.
     0140      BYTE      IP PORT MODE CONTROL.
                     This  byte  controls the  default  modes
                     used  for AX.25 frames on each port.  It
                     is  bit  mapped, with bit 0  controlling
                     the  radio  port and bit  1  controlling
                     the  RS232  port. If a bit is  set,  the
                     default   mode  for  that   channel   is
                     datagram  ( UI frame ), if  not   it  is
                     virtual circuit.
     0141      BYTE      IP INITIAL TIME TO LIVE
     0142      BYTE      IP ENABLE FLAG.
                         If zero, the IP router is disabled.
                         If   not  zero  the  IP  router   is
                         operational.
     0143      BYTE      HELP MESSAGES CONTROL BYTE.
                    Each  bit enables or disables a different
                    type of help message as follows :
                    
                     Bit 0 - 'trying to connect' message
                     Bit 1 - sysop sees all commands in help
                     Bit 2 - give a 'good-bye' message to
                     users
                     Bit 3 - enables the connect text
                     message
                     Bit 4 - show nodes as alias:callsign
                     Bit 5 - pass 8 bit data in TALK if set
                     Bit 6 - Make node alias handling case
                     sensitive
                     Bit 7 - Enable TexNet interface handler
     0144      WORD   MTU_IP0
                     This is the MTU for port 0 Level 2
                     AX.25 ( the radio port ) for the IP
                     router.
     0146      WORD        MTU_IP1
                     This is the MTU for port 1 Level 2
                     AX.25 ( the RS232 port ) for the IP
                     router.
     0148      WORD       MTU_IPN
                     This is the MTU for the Net/Rom
                     subnetwork layer. It should NOT exceed
                     236 for compatibility with Net/Rom
     014A      WORD   MTU_I_MAX
                     This is the maximum number of data
                     bytes, plus one, that will be accepted
                     in a received L2 AX.25 packet. Above
                     this will cause an error.
     014C      WORD   MTU_L2_MAX
                     This is the absolute limit on the
                     number of bytes in a received AX.25
                     packet, counting the data, control, and
                     address information. It is set to 328
                     usually ( 256 data bytes, 2 control and
                     70 address ).
     014E      BYTE   Auto reconnect to node on remote dis if 1
     014F      BYTE   NoSlime -
                     Bit 0, if set, stops 'slime trails'
                     being displayed in the nodes table. Bit
                     1, if set, stops slime trails being
                     accepted by the node.
     0150      BYTE  Bit 0 if set bars digi L2 connects to the node.
                     Bit 1 if set bars digi downlinks from the node.
     0151      BYTE  DEVIATION METER DEFAULT.
                     This is the default value for the RX
                     Deviation meter.
     0152      WORD  METER FLAGS. Each bit controls a meter function
     0154      BYTE  S METER SIGNAL MINIMUM This parameter is the
                     ADC noise floor reading ( 0 to 255 )
     0155      BYTE  S METER MULTIPLIER This is used to scale
                     readings to give the S1-S9 style display
     0156      BYTE  DBM MULTIPLIER This is used to scale readings
                     to give the dBm style display
     0157      BYTE  DBM NOISE FLOOR This is the reading that
                     corresponds to no signal on calibration
     0158      BYTE  This is the voltmeter channel 1 scaling factor
     0159      BYTE  This is the voltmeter channel 2 scaling factor
     015A      BYTE  This is the voltmeter channel 1 offset value
     015B      BYTE  This is the voltmeter channel 2 offset value
     015C      BYTE  This is the voltmeter channel 3 scaling factor
     015D      BYTE  This is the voltmeter channel 4 scaling factor
     015E      BYTE  This is the voltmeter channel 3 offset value
     015F      BYTE  This is the voltmeter channel 4 offset value


     PK96  NOTE - Parameters at adresses 0x151 through  0x15B
     are  for  the meter control, which are not used  in  the
     PK96.  Instead,  the  default baud rate  parameters  are
     stored at addresses 0x151 and 0x152 as shown below :
     
     0151      BYTE       Radio port default daud rate
     0152      BYTE       RS232 port default baud rate
     
     The  patch utility will not assist in changing the  help
     text. That text is positioned at the end of THENET2.X1J.
     It  is  a null terminated string of characters. Newlines
     are  represented by the value 0xd ( decimal 13 ). It can
     be  as  long  or as short as you like, but don't  forget
     that  it causes the node to be a source of data  and  if
     very  long  could crash the node. ( Not likely  in  this
     version given the space available!). The easiest way  to
     change it is to use the SETHELP utility.
     
     Any problems, give me a ring !
     
4. The PATCH utility

     The  patch utility is designed to help configure the two
     ROM  images  in a manner that is not as user hostile  as
     hand crafting a binary image ( only one file for PK96 ).
     It is invoked as follows :
     
          PATCH   [  file1 file2 ]
     
     If  no  parameters  are given, it will  look  for  files
     THENET1.X1J ( and THENET2.X1J for TNC2 ) in the  current
     directory. It will stop if it cannot load them.  If  the
     images are renamed, they may be given as parameters.  If
     this  is done, both files must be given for the TNC2  or
     just  file1  for  the PK96, with file1 corresponding  to
     part 1 and file2 corresponding to part 2. The program is
     menu  driven,  with  extensive  help  provided  on   the
     operation  of  the program and each parameter.  It  also
     tries to make sure that only valid data is entered.
     
     The  program  may also be instructed to  load  and  save
     textual representations of the parameters. These consist
     of  ASCII  files,  with  one parameter  per  line.  Each
     parameter  consists  of the name of the  parameter,  and
     equals  sign,  and  the value for  that  parameter.  The
     values  are  mainly numeric, with the obvious exceptions
     of  things  like  the  callsign, alias,  password,  info
     message  etc. To get an example of the format,  use  the
     patcher to dump a file and look at it. The idea of  this
     is not simply to load and dump whole images, but to load
     partial configurations such as passwords & info messages
     only  or  parameters only. The file  may  be  edited  to
     remove or add lines as desired. Note that each parameter
     MUST  only occupy one line. For the information message,
     whitespace  before  the  first  printable  character  is
     ignored  by  the  program, and if a  newline  is  to  be
     included,  it  is  denoted by the  sequence  \m  (  i.e.
     backslash  followed  by the letter m  ).  Similarly,  to
     include   the  backslash  character  itself,  a   double
     backslash must be entered, i.e. \\.
     
5. Programming examples

     There   are   two   utilities  included  to   facilitate
     conversion  to  hex for use in programming  eproms.  The
     source  of  both  is  also included if  anyone  wants  a
     different  file  type. The programs have  been  compiled
     with Turbo C++.
     
     Each has the same method of invocation,
     
          INTEL infile outfile [ address ]
     
     or
     
          MOTOROLA infile outfile [ address ]
     
     These  create  INTELLEC or S1 type records respectively.
     Each  reads  an  input binary file  and  outputs  a  hex
     version. The starting address assumed for the file  will
     be 0000 unless specified otherwise in the command line.
     
5.1 Intel format, loading as two halves

     1. Use the patch program to create the desired image.
     2. execute :
          INTEL TheNet1.x1j part1
          INTEL TheNet2.x1j part2
     
     3. load part1 into the programmer and program the lower
          half of the ROM.
         load part2 into the upper half.
     
5.2 Motorola format, loading as one image

     1. Use the patch program to create the desired image.
     2. Execute :
          MOTOROLA TheNet1.x1j part1
          MOTOROLA TheNet2.x1j part2 8000
          COPY part1+part2 romimage
     
     3. Edit romimage with a text editor to remove the
        intermediate end of file ( S0... ) marker.
     4. Load romimage into the EPROM in one go & program it.

6. The SETHELP utility
            
     The SETHELP utility simplifies the editing of the help  text 
     which is stored at the end of THENET2.X1J. It is invoked  as 
     follows :
     
          SETHELP   bin2input bin2output newtext

     If an invalid number of parameters are given, a few lines of 
     help text will be printed on the screen and the program will 
     terminate without making any changes. Likewise, the  program 
     will stop if it cannot load the two input files or write the 
     output file. 

     The  command  line parameters represent the names  of  three 
     files  complete  with  extensions. Using  the  above  names, 
     bin2input is the name of the ROM file that contains the help 
     text (THENET2.X1J if it wasnt renamed or copied). The second 
     command  line parameter, bin2output, represents  a  filename 
     that  will be created upon completion of SETHELP. This  name 
     can  not be identical to the bin2input filename.  The  third 
     command line parameter, newtext, is the name of a file  that 
     contains  the  new help text. This file must be  created  in 
     advance of running SETHELP and it should only contain  ASCII 
     characters  (no formatting characters). If a word  processor 
     is  used to create this file, be sure to save the file as  a 
     flat  ASCII  file.  When  the  file  is  prepared,  a  quick 
     verification  of the file content can be made by  using  the 
     DOS TYPE command to display the help text on the screen.

     When  SETHELP  is  executed with  the  proper  command  line 
     parameters, it will report either the number of unused bytes 
     in  the  EPROM  image or the number of bytes  that  were  in 
     excess.  If the new help text exceeded the available  space, 
     edit  the  help  text  file reducing  its  size  and  re-run 
     SETHELP.  When  re-running SETHELP, it is not  necessary  to 
     delete  the bin2output file because SETHELP will  over-write 
     it  automatically.  For this reason, please be sure  of  the 
     command line parameters before running SETHELP.

     Each  version  (TNC2  or  PK96) of  the  code  has  its  own 
     associated   SETHELP.EXE  file.  SETHELP   is   specifically 
     compiled and released with each revision (X1JR2,X1JR4, etc.) 
     and version (TNC2 or PK96) of the firmware. The program  has 
     built-in knowledge of the help text starting address  within 
     the  EPROM.  To  prevent  users  from  mixing  revisions  or 
     versions of SETHELP, a built in checksum routine checks  the 
     bin2input  file for the expected contents. If an attempt  is 
     made  to run SETHELP with an incorrect release or  the  PK96 
     version  of SETHELP on the TNC2 code or vice versa, it  will 
     refuse  to  modify  the file and report  an  error  message. 
     Executing  SETHELP without any command line parameters  will 
     report  the  expected firmware revision and version  on  the 
     screen.

     Since SETHELP may add or delete bytes in the EPROM image, it 
     is  normal  for  the bin2input and bin2output  files  to  be 
     different  in  size. It does not matter if  SETHELP  is  run 
     before or after the patch utility.
            
            
7. Acknowledgements

     Intel and Intellec are trademarks of the Intel
     corporation
     Motorola is a trade mark of the Motorola company.
     
     My thanks to KH6ILT for the bug fixes to MOTOROLA.C and
     to John Bednar WB3ESS for the SETHELP utility (
     originally named HELPX1J ). N8PTT also deserves credit
     for X1JCONV.*.
     
