MagicBox Version 1.0 Experiments Running the NET/ROM Node G8BPQ under the AGW Packet Engine By Pedro E. Colla (LU7DID) 2001 Abstract ======== The AGW Packet Engine is a Win9x/WinNT 32 bits AX.25 controller supporting an incredibly high number of hardware, software and someware AX.25 gear. In the other hand,the old and popular AX.25 Switch and NET/ROM node implemented by G8BPQ is a legacy DOS application. As such one could not work with the other directly since there is no direct way they could communicate. Please have clear that this document refers to the DOS G8BPQ implementation; for some time a 32 bits version of it (dubbed as BPQ32) had been around but this package WILL NOT work with it. None of the packages had been written with the least intend to co-exist; one because of the age (G8BPQ) and other because of the technology (AGWPE). The main attractive of such a configuration is the ability to run DOS-era packages which are prepared or enabled to run under G8BPQ which had not been ported or rewritten into the equivalent 32 bits versions. There are ways (kludges actually) to run the G8BPQ software on a Win9X environment, but when doing that no other package could control the TNCs at the same time and there is no way this setup will ever co-exist with a 32 bits native AX.25 controller such as AGW PE. To add some challenge to the configuration it's not really simple to communicate programs running under the DOS VDM (Virtual DOS Machine) implemented by Win9x and programs natively written as 32 bits applications, they just don't share a whole lot in common in terms of the way they execute. This is strictly an experiment, it's not intended to be reliable nor to be placed into stringent operational requirements; it's just a way to see if it could be done..... I don't really plan at this point to continue the effort on this package beyond the point it's now, unless, of course I do receive feedback on good reasons to do otherwise. You're assumed to know to a fair extend the implementation of AGW Packet Engine and the G8BPQ switch; both are assumed to be configured properly to a functional level; little or no clues are provided on this file about that. Implementation, Technical Details ================================= This part is boring, but if you are unable to follow it probably this highly experimental setup isn't for you!!! This implementation is actually an exercise of integration rather than a true development; I just developed code to glue several different things together. The G8BPQ allows the definition of 'external drivers', pieces of software intended to allow developers to add support to 'rare' hardware pieces not natively supported by the G8BPQ switch itself. Details of the interfaces for such a driver could be found on the EXTERNAL.DOC document of the G8BPQ package. So I wrote one of those drivers named AGWPORT.COM; it's a TSR (DOS Terminate and Stay Resident) program that must be loaded BEFORE the G8BPQ switch; it's extremely simple and with a very small footprint in terms of memory. The driver sits on the Interruption 0FDh listening for requests from G8BPQ (basically three, See the STATUS, POLL for data and SEND buffers). But the driver itself is also a DOS application and as such it is unable to talk with a 32 bits application. I grabbed then a third party package named NetModem32 to jump the wall between the two worlds. NetModem32 isn't really intended to be used on Packet Radio but it's a tool also intended to integrate old DOS legacy applications into the 32 bits world. What NetModem32 originally intends to do is to add a Telnet interface to old DOS BBS from the pre-Internet era; they look to the outside world as a Telnet Server while to the inside they look to the DOS software like a FOSSIL driver. For those not familiar with the term, the FOSSIL driver was a High Performance Serial port driver specification to which most dial-up BBS do comply; essentially it provides a good implemented Int 14H interface (as opposed to the one provided natively by DOS which sucks, the Win9x emulation of it sucks too). So, the AGWPORT.COM driver talks to the outside world thru the NetModem32 VxD thinking it's just a fast (albeit completely simulated) serial port; NetModem32 in turn transforms it into data exchanged thru a TCP/IP Socket as a Telnet connection. Still, AGWPE knows nothing about simulated serial ports or telnet connections so a third piece is needed to complete the integration. It's a 32 bits windows program named MagicBox; it behaves essentially as a bridge. In one side it establishes a connection with the driver running under the DOS box by means of a Telnet connection. At the same time it establishes a client connection with AGWPE (using the Winsocks API). When both connections had been established it just passes data transparently in both directions. So the end-to-end chain looks like Application | | (G8BPQ Programming API) | V G8BPQ AX.25 Switch | | (G8BPQ External Driver API) | V AGWPORT | | (FOSSIL Int14H API) | V NetModem32 | | (Telnet Connection) | V MagicBox | | (WinSocks API) | V AGW Packet Engine Quite a journey for the data!!! Still, the process do occur in a relatively seamlessy way and it's not as inefficient at it might sound from looking at all the jumps the data performs (all are quick memory transfers). Data flows exactly thru the same path but on opposite direction to transfer AGW Packet Engine | | (WinSocks API Event) Frame | V Magic Box | | Telnet TCP/IP Socket | V NetModem32 | | (FOSSIL Int14H API) | V AGWPORT | | (G8BPQ External Driver API) | V G8BPQ AX.25 Switch | | (G8BPQ Programming API) | V Application Please note that even if both flows shows one of the ends being an "application" nothing prevents it to be the switch itself (after all, programs like PAC4 or TERM4 are just applications of the switch). The real meaning of this integration is to be able to run an application which has no 32 bits equivalent, there is not much of a point (other than to experiment a little) into just running the switch itself as a pure router. Installation ============ The installation is not particularly straightforward, and probably won't ever will be. Three components will be required appart from the AGW Packet Engine and G8BPQ Switch themselves; AGWPORT.COM, NetModem32 and MagicBox. None of the components had been made particularly strong in terms of verification and user friendliness, so be careful on the configuration or nothing will work. All of them had been packaged here; however it's strongly encouraged to get the latest version of NetModem32 which might not be the one included on this package. For NetModem32: The author can be reached at: EMail: drip@cris.com You can use any of the following sites to reach the NetModem page. Primary Sites: http://www.cris.com/~drip http://netmodem.home.ml.org Mirror Sites: http://bxm170.rh.psu.edu/netmodem <- See "NOTE" http://www.personal.psu.edu/bxm170/netmodem <- See "NOTE" Of course, the author of NetModem32 knows nothing about this particular usage of his program and probably he's clueless on the very existence of the AX.25 packet network; so don't contact him except for very pure NetModem32 queries. NetModem32 Installation & Configuration --------------------------------------- The package is installed unzipping the content and executing SETUP; a normal Window installation process will take place. You'll be asked to reboot your computer for the installation to be made effective. Under Windows 98 a patch has to be applied (also included) which essentially replaces the NETMODEM.VXD file; it has to be done AFTER the installation had been completed. The NETMODEM.VXD originally installed (and to be replaced) sits on the directory where you instructed the installation program to install NetModem32. It doesn't hurt to take a look at the relatively small documentation of NetModem32 (NETMODEM.DOC) which also sits on the same directory. The configuration for this setup is rather simple: - Execute NetModem32 (an entry on the Start/Programs list had been created during the installation). - On Config/Comports select COM7, 19200 and press OK. - If everything is Ok the dialog should say 'Online-Accepting connections'. Please note that the COM port selected MUST NOT exists on your machine (I've selected COM7 as a default since it would be enough strange for a machine to have that many serial ports defined); this "COM Port" is faked, imaginary, an illusion. Please note that the unregistered version only accept connections to port 23 so if you have a telnet server running in your machine it will conflict with it ; there is not a workaround for that, you've to turn your telnet server off if you want to continue. BPQ Configuration ----------------- Install the BPQ AX.25 switch according with the instructions, the main thing to consider is how to code the BPQCFG.TXT file, here is a sample of mine: ; For Version 4.08 ; ; ; CONFIGURATION FILE FOR G8BPQ SWITCH SOFTWARE ; ; The program which converts this text file to binary ; form is currently very crude - be VERY careful when ; editing this file! ; ; ; The order of parameters in not important, but they ; all must be specified - there are no defaults ; ; ; HOSTINTERRUPT=127 ; Sets the Interrupt used to access BPQ Host Mode. Will ; normally be 127, but may be changed if this clashes with ; other software. BTRIEVE seems to use 127, so if you are ; using it, try INTERRUPT=126 ; Memory Usage. If EMS=1, the system will attempt to put its ; data area into EMS Memory. At the moment it makes no attempt ; to manage sharing of the EMS window, so you must not run any other ; software using EMS. ; ; Setting EMS=1 seems to cause problems with Desqview. I suggest it ; is only used with non-DV installations. ; ; EMS=1 ; dont use EMS RAM ; ; I seem to have problems with systems not using DESQVIEW - especially ; NNA BBS's. The DV calls SHOULD be ignored if DV is not loaded, but ; just in case, if you set DESQVIEW=0, the 'Release Timeslice' call ; wont be used. MAKE SURE that you set DESQVIEW=1 if using DV, or ; performance will be seriously affected. ; DESQVIEW=0 ; ; ; Station Identification. ; ; If a user connects to the NODE Callsign or Alias, he is linked ; to the switch code, and can use normal NetRom/TheNet commands ; ; If he connects to the BBS Callsign or Alias he will be connected ; directly to a BBS port. If none are available, the connect will ; be rejected. ; ; Note that of you are running only a NODE (ie BBS=0), or ; or just a BBS (NODE=0), then you must still put in two pairs of calls, ; but they MUST be the SAME. ; ; If you are running both, the calls MUST be different NODECALL=LU7DID-3 ; NODE CALLSIGN NODEALIAS=TBROWN ; ; 'ID' MESSAGE - SENT EVERY IDINTERVAL MINS ; ; WILL BE ADDRESSED FROM THE PORT CALLSIGN (IF DEFINED) ; ELSE FROM THE NODE CALL ; ; The following format allows KA nodes to include your system in ; their 'Nodes' lists. ; IDMSG: [GF05TE] Pedro-Adrogue-BA Node: LU7DID-3 (TBROWN) *** ; UNPROTO=ID ; DEFAULT UNPROTO ADDR ; 'I' COMMAND TEXT ; ; Note that the bit about needing a port param in connects is only ; necessary if you are running more that one (radio) port. ; INFOMSG: ABROWN Net/Rom Packet Switch, Adrogue, BA, Argentina (GF05TE) Aplicaciones Disponbles *** ; ; CTEXT - Normally will only be sent when someone connects to ; the NODE ALIAS at level 2. If FULL_CTEXT is set to 1, it ; will be sent to all connectees. Note that this could confuse BBS ; forwarding connect scripts. ; CTEXT: Bienvenido al Packet Switch TBROWN en Adrogue,BA Tipee ? para obtener la lista de comandos disponibles, 'I' para Informacion. *** FULL_CTEXT=1 ; SEND CTEXT ONLY TO L2 CONNECTEES TO ALIAS ; Network System Parameters ; OBSINIT=5 ; INITIAL OBSOLESCENCE VALUE OBSMIN=4 ; MINIMUM TO BROADCAST NODESINTERVAL=60 ; 'NODES' INTERVAL IN MINS IDINTERVAL=60 ; 'ID' BROADCAST INTERVAL (UK Regs require ; an AX25 ID every 15 mins) ; BTINTERVAL=60 ; NO BEACONS L3TIMETOLIVE=25 ; MAX L3 HOPS L4RETRIES=16 ; LEVEL 4 RETRY COUNT ; ; I have seen suggestions that L4TIMEOUT should be increased to very ; high values (even as long as seven mins). Although 60 may be a bit ; short in some cases, I STRONGLY advise that you dont go much above ; 120 secs unless you understand ALL the implications. ; ; I've set TTL and TIMEOUT to the values agreed by the latest SYSOPS ; meeting - this does not imply that I agree with them! ; L4TIMEOUT=120 ; LEVEL 4 TIMEOUT L4DELAY=10 ; LEVEL 4 DELAYED ACK TIMER L4WINDOW=4 ; DEFAULT LEVEL 4 WINDOW ; MAXLINKS=15 ; MAX LEVEL 2 LINKS (UP,DOWN AND INTERNODE) MAXNODES=60 ; MAX NODES IN SYSTEM MAXROUTES=15 ; MAX ADJACENT NODES MAXCIRCUITS=32 ; NUMBER OF L4 CIRCUITS MINQUAL=2 ; MINIMUM QUALITY TO ADD TO NODES TABLE BBSQUAL=10 ; BBS Quality relative to NODE - used to ; limit 'spread' of BBS through the network ; to your required service area. I've been ; asked to set a low default to encourage you ; to think about a suitable value. Max is 255 BUFFERS=255 ; PACKET BUFFERS - 255 MEANS ALLOCATE AS MANY ; AS POSSIBLE - NORMALLY ABOUT 130, DEPENDING ; ON OTHER TABLE SIZES ; ; TNC DEFAULT PARAMS ; PACLEN=150 ; MAX PACKET SIZE ; ; PACLEN is a problem! The ideal size depends on the link(s) over ; which a packet will be sent. For a session involving another node, ; we have no idea what is at the far end. Ideally each node should have ; the capability to combine and then refragment messages to suit each ; link segment - maybe when there are more of my nodes about than 'real' ; ones, i'll do it. When the node is accessed directly, things are a ; bit easier, as we know at least something about the link. So, from ; Version 3.11 onwards, there are two PACLEN params, one here and ; one in the PORTS section. This one is used to set the initial value ; for sessions via other nodes, and for sessions initiated from here. ; The other is used for incoming direct (Level 2) sessions. In all cases ; the TNC PACLEN command can be used to override the defaults. ; ; The main reason for changing this now was a request from someone ; wanting to run an HF port. ; ; ; TRANSDELAY=1 ; TRANSPARENT MODE SEND DELAY - 1 SEC ; ; Level 2 Parameters ; ; T1, T2 and N2 are now int the PORTS section ; T3=180 ; LINK VALIDATION TIMER (3 MINS) IDLETIME=200 ; IDLE LINK SHUTDOWN TIMER (15 MINS) ; ; ; Configuration Options ; BBS=0 ; INCLUDE BBS SUPPORT NODE=1 ; INCLUDE SWITCH SUPPORT ; HIDENODES=0 ; IF SET TO 1, NODES STARTING WITH # WILL ; ONLY BE DISPLAYED BY A NODES * COMMAND ; ; THE *** LINKED COMMAND IS INTENDED FOR USE BY GATEWAY SOFTWARE, AND ; CONCERN HAS BEEN EXPRESSED THAT IT COULD BE MISUSED. I RECOMMEND THAT ; IT IS DISABLED IF NOT NEEDED. ; ENABLE_LINKED=N ; CONTROLS PROCESSING OF *** LINKED COMMAND ; Y ALLOWS UNRESTRICTED USE ; A ALLOWS USE BY APPLICATION PROGRAM ; N (OR ANY OTHER VALUE) DISABLE ; ; ; ; ; 'COMBIOS' Port definitions. ; ; This section defines the virtual TNC's that the code supports. ; ; The basic format is: ; ; TNCPORT ; COM=n ; COMBIOS port number ; APPLMASK=nn ; Defaults to 1 (BBS) ; APPLFLAGS=nn ; Defaults to 6 ; ENDPORT ; ; See APPLS.DOC for details on use of APPLFLAGS and APPLMASK ; ; Only TNC2 applications are supported through this interface. ; For information on using KISS or DEDHOST applications, see file ; DRIVERS.DOC ; ; Dont try to define more than 16 ports. ; TNCPORT COM=2 ENDPORT ;TNCPORT ; COM=2 ; TYPE=TNC2 ; APPLMASK=01 ; APPLFLAGS=06 ;ENDPORT ;*--- Virtual TNC Port for YAPP Server ;TNCPORT ; COM=3 ; TYPE=TNC2 ; APPLMASK=$10 ; APPLFLAGS=$00 ;ENDPORT ;*--- Virtual TNC for THUNDER ;TNCPORT ; COM=5; ; Virtual COM assigend to port 5 THUNDER ;ENDPORT ;*--- Virtual TNC for THUNDER ;TNCPORT ; COM=9; ; Virtual COM assigend to port 5 THUNDER ; TYPE=TNC2 ; APPLMASK=06 ; APPLFLAGS=06 ;ENDPORT ; ; AX25 PORT DEFINITIONS ; ; These define the external links - normally to radios, but possibly ; to other computers, modems, etc. ; ; The hardware type and protocol are now defined separately, but ; at the moment only a limited number of combinations are possible ; ; Interrupt levels may be shared by any cards with suitable ; hardware. Examples are all but the earliest DRSI cards, and ; a MS400 modified as described by AA4RE in his MBBIOS documentation. ; ; There is a significant overhead in using the shared interrupt ; feature - try to use it on relatively low speed links, and ; wath out for TX underruns/RX overuns. ; ; ; See file PORTS.DOC for full details of available paramters. ; ; Note that all timer values are in ms intervals. Most TNC's ; use different units for the various timers, so be careful! ; ; The timings are all derived from the PC's timer interrupt, ; who's frequency is about 18.2 HZ, so the resolution is only to ; approx 50ms. ; PORT ID=AGWPE 1 145.15 Mhz 1K2 TYPE=EXTERNAL PROTOCOL=KISS INTLEVEL=253 CHANNEL=A SPEED=9600 QUALITY=90 MAXFRAME=2 TXDELAY=1000 SLOTTIME=50 PERSIST=250 FULLDUP=0 FRACK=2000 RESPTIME=1500 RETRIES=32 PACLEN=150 MINQUAL=50 QUALADJUST=25 ENDPORT ; ; ROUTES TO LOCK IN ; ; specify Callsign, Quality and Port. You can now also specify ; MAXFRAME, FRACK, PACLEN (in that order) to override the port ; defaults. ; ROUTES: *** ; ; APPLICATIONS SUPPORTED ; ; UP TO 8 ENTRIES OF UP TO 12 BYTES EACH ; ; THE FIRST 3 ARE RESERVED FOR BBS, HOST, AND REMOTE SYSOP - YOU ; CAN DEFINE THE OTHERS AS YOU LIKE. ; ; FOR COMPATIBILITY WITH EARLIER VERSIONS, JUST ENTER APPLICATIONS=BBS ; ; NAMES STARTING WITH * ARE NOT INCLUDED IN 'VALID COMMANDS' DISPLA ; ; ; NOTE THAT THE LAST ITEM CREATES A 'COMMAND ALIAS'. IF THE USER ; ENTERS 'CHAT' THIS IS CONVERTED BY THE SWITCH TO 'C NMCHAT'. THE ; TOTAL LENGTH OF THE PAIR CANNOT EXCEED 15 BYTES ; The actual AX.25 parameters might not suit your local network, so play with them at your heart contents. The actually important meat on this file is how the ports are configured. You could see they are referred as TYPE=EXTERNAL and had it marked as CHANNEL=A. The driver will support one Port, just one, and it will be mapped to the AGWPE port to be used by means of MagicBox the AGWPE configuration. Remember to 'compile' this configuration with BPQCFG to be actually used by G8BPQ. MagicBox Configuration ---------------------- The configuration of MagicBox is made thru the MAGICBOX.INI file which sits on the same directory where it executes; the format for it is: [MAGICBOX] AGW_ADDRESS=127.0.0.1 AGW_PORT=8000 TELNET_ADDRESS=127.0.0.1 TELNET_PORT=23 PORT_TO_MAP=1 The AGW_ADDRESS/AGW_PORT should point to the IP Address and TCP Port where AGWPE listen; the ones indicated above occurs if MagicBox runs on the same machine where AGWPE is, but not necessarily has to. The TELNET_ADDRESS/TELNET_PORT should point to the IP Address and TCP Port where the NetModem32 engine is running; the ones indicated above occurs if it runs on the same machine but not necessarily has to. PORT_TO_MAP indicates which AGWPE port will be mapped into the G8BPQ interface; it could be any of the defined ports on the AGWPE. Running Everything together --------------------------- * After the installation NetModem32 should be activated automatically, if not start it thru Start/Programs/NetModem32/NetModem32 * Open a DOS Window, ensure it has the 'Always Suspend' checkbox UNCHECKED (Properties/Misc) otherwise the BPQ node won't work when the DOS windows is on the background (i.e. without the focus). * On Start/Run Execute NU 1 /L to activate the NetModem32 driver. * Execute AGWPORT, it will wait till MagicBox is started to complete (actually... it will wait FOREVER if MagicBox is not activated!!). * Execute MagicBox, this must produce AGWPORT to terminate Ok at the first frame received. * Go Back to the DOS Window and start the G8BPQ (BPQCODE) and any relevant application you want. If everything goes Ok you should be able to interact thru the BPQ interface using the AGW Packet Engine. In case you want to start everything automatically (?) you might create a .BAT file like this to be executed on the DOS Window (assumed everything is on the C:\BPQ directory) @Cd C:\BPQ NU 1 /L AGWPORT /I253 BPQCODE Once started BPQCODE has no way to uninstall it, AGWPORT doesn't have any either; so the way to terminate everything is closing the DOS window. Beware that when you close the DOS window you might catch NetModem32 in the middle of something and that could lead to the "dreaded blue screen"; it seems to be harmless, just hit ENTER to clear it (NetModem32 will abnormally terminate with it, but you're willing to exit don't you?). Beware that even if I got half a dozen of those 'harmless' errors without consecuences I could tell you nothing about ill interactions with your particular configuration (as in any experiment a good backup prior to it isn't completely out of the question!). MagicBox will terminate itself also when the connection is closed with it's DOS peer. Integrating with other BPQ Applications --------------------------------------- You have the possibility to define just ONE (1) port on the G8BPQ environment, hardly an exciting setup. You could assign this port to be a radio port and the G8BPQ will present itself to the network and actually be connected from the outside, remember to select a CallSign-SSID for your G8BPQ node different from anything being at use in any other application under AGWPE. Another possibility is to define that port to be the AGWPE LoopBack port and run this setup together with Digiplex; the G8BPQ will broadcast their routes which in turn will be picked by Digiplex and re-broadcasted to the network so your applications will (should? :-)) be accessible thru this indirect way. You could also make the G8BPQ node a "managed application" of Digiplex (when defined thru the loopback port) and then access it thru the Digiplex CLI. Known Problems and Limitations ------------------------------ - The startup process is a little tricky, it has to be done in the proper order for everything to work (1-NetModem32,2-NU/AGWPORT,3-MagicBox). - There is sometimes a little delay between the moment a frame is made available for applications running native on AGWPE and thru this interface. - Using this setup makes AGWPE not to control the AX.25 flow, all frames generated by G8BPQ are Raw (KISS) frames and AGWPE is forced to transfer them blindly. The AX.25 link will be controlled by the parameters set into G8BPQ not the ones ruling AGWPE. Uninstalling ------------ When the experiment is over you might wish to clean your machine up, it's rather easy: * Delete AGWPORT.COM and MAGICBOX.* wherever you installed it. * Uninstall NetModem32 (Start/Programs/NetModem32/UnInstall), a reboot probably will be necessary to complete the removal of all components. * Erase the G8BPQ files as appropriate if you don't want to keep them. Disclaimer ========== As stated before this is strictly an experiment, so do it at your own risk; I would not be held responsible for any damage related to the usage of this program; I experienced none using this program but I could not rule out a particularly ill interaction between your configuration and all the packages needed for this setup. NetModem32 is a shareware licensed product and you should comply with the license terms under your own responsibility. All other code used is from my own original development. The whole setup other than NetModem32 is freeware for radio amateur purposes and it's commercial usage is forbidden without written consent from me. Have fun, this what radio is for! 73 de Pedro.