The Firmware DLL for SV2AGW’s AGW Packet Engine
by Ing. Pedro E. Colla
(LU7DID)
Adrogue – Buenos Aires - Argentina
Table of Contents
Check if there is a character ready
(TfChCk)
Configuration File (TF2AGW.INI)
TSTHWIN Versions prior to 2.21A
TSTHWIN Versions 2.21A or higher
Disclaimer and License Statement
TF2AGW is a Windows 95/98/NT DLL
(Dynamic Link Library) implementing The Firmwareâ (WA8DED mode)
for the AGW Packet
Engineâ.
a
32 bits AX.25 packet 32 bits platform developed by George Rossopoulos (SV2AGW).
It
is intended to be a direct replacement for F6FBB’s
TFWIN32.DLLâ
from the functional perspective, so any program communicating with a TNC thru TFWIN32.DLL
should be able to communicate transparently with AGWPE using this
DLL.
It
is intended to play the role of a migration tool in order to allow existing
programs to be easily as well as quickly adapted to access the functionality of
the AGW Packet Engine (AGWPE).
Nothing,
of course, prevents new programs to be developed using it, specially for
programmers that wish to leverage existing knowledge about the WA8DED Host mode
or not familiar with TCP/IP applications development; but for new programs the
direct usage of the AGWPE’s TCP/IP API would surely be
more efficient and it is certainly recommended.
TF2AGW.DLL uses the newly available TCP/IP
API of AGWPE and should run on any machine AGWPE could run,
you could download the latest version of the program as well as the TCP/IP API
related documentation directly from George’s home page at http://www.forthnet.gr/sv2agw
Since
it’s introduction this DLL has been under limited test with Mario Travaglino’s
(IK1GJK) TSTHWIN and J.P.Roubelatt’s (F6FBB) WinFBB 7.00E,
experiences with other packages or inquiries from authors are welcomed.
Warning - Notice
It’s likely that programs enabled for the F6FBB’s
TFWIN32.DLL are not really aware of this DLL, you could make them work by
renaming TF2AGW.DLL into TFWIN32.DLL after the installation, since the exported
functions are identical between both the programs, then should be able to
operate with this DLL even if it has no “official” support of it.
This installation method will override any previous version
of the original TFWIN32.DLL your system might have, make yourself certain you
backup it prior to implement the installation of TF2AGW.DLL.
To install the program the following actions has to
be performed:
IP_ADDRESS=nnn.nnn.nnn.nnn
where nnn.nnn.nnn.nnn is the IP
Address of the machine where AGWPE is running (you could
check which is the machine’s IP address with the Windows’s WINIPCFG
utility).
If you don’t know the IP Address and AGWPE
is running on the same machine you could try with IP_ADDRESS=127.0.0.1
(see the Troubleshooting section for further
details).
The program doesn’t alter any system resource nor configuration, it could be removed just deleting the following files:
c:\windows\system\tf2agw.dll
c:\windows\tf2agw.ini
The AGWPE version required is 2000.10 or later, it won’t work with versions prior to that, so if you have a prior version or you are not sure what version you have just play safe and download a fresh version from SV2AGW’s Home Page
TSTHWIN supports this DLL starting on version 2.21A, early versions of TSTHWIN might work as well but the DLL has to be renamed as TFWIN32.DLL for it to be recognized (see details on how to configure it at the documentation about the TSTHWIN.PRT file).
This package has been tested successfully with F6FBB’s WinFBB 7.00E (32 bits), early versions of the package has not been tested and might experience problems working with this DLL. Please note that the latest WinFBB version is 7.00G, however, this version doesn’t include the 32 bits binaries and this DLL will not work with the WinFBB 16 bits version.
*** Important Notice ****
TF2AGW.DLL interacts with AGWPE using it’s TCP/IP API, that requires the Windows 95/98/NT TCP/IP stack to be configured and functional. However, this is not related to the AGWPE TCP/IP drivers (for Windows 95/98) which are essentially a way to allow the Windows TCP/IP stack to operate over AX.25 radio links, the AGWPE TCP/IP drivers do not need to be installed for TF2AGW.DLL to work properly. Beware that the AGWPE TCP/IP drivers requires registration to work after a trial period, for details about the registration please see George’s (SV2AGW) Home Page.
The TF2AGW.DLL is an application
resource that could not be accessed directly by the user, it has
to be loaded, initialized and operated by the application program; in order to
verify that the pre-requisites are functional the following method is
recommended:
·
Configure
TSTHWIN, WinFBB 7.00E or other TFWIN32.DLL
compliant program that uses this DLL, follow the program
installation instructions for that, you will find
specific aids for TSTHWIN and WinFBB 7.00E in this document.
·
Load
and configure AGWPE, follow the intallation instructions for
that. Be sure the AGWPE.INI file has the following entry
[TCPIPINTERCONNECT]
ENABLE=1
·
Test
AGWPE to be functional with any of the provided programs such as AGWTerminal
or AGWMonitor, if they refuses to work it’s highly likely that TF2AGW.DLL
won’t work either.
·
Load
TSTHWIN, WinFBB 7.00E or other TFWIN32.DLL
compliant program that uses this DLL, it should work transparently. In case of
problems see the Troubleshooting section of
this document.
The
TF2AGW.DLL acts as ‘glueware’ between a TFWIN32.DLL
enabled program (which is a Windows 32 bits implementation of The Firmware API)
accessing the TNC thru the WA8DED (TF) protocol and the AGW Packet
Engine.
TF2AGW.DLL presents to the application program a DLL interface identical to the
one presented by TFWIN32.DLL, so other than the name the program
shouldn’t notice any difference between both.
For
programming purposes the the TF2AGW.DLL’s exported entries are:
Function
TfOpen (hWinHandler:HWND) : Boolean ; far ; stdcall ;
Function
TfClose : Boolean; far ; stdcall ;
Function
TfPut (InChar : Char) : Boolean ; far ; stdcall ;
Function
TfGet : Integer ; far ; stdcall ;
Function
TfChck : Boolean ; far ; stdcall ;
For a detailed description of each entry see the section Exported Functions in this document.
Requests
from the application program being generated using the WA8DED set of
commands are processed and eventually mapped as requests to the AGW Packet
Engine thru the TCPIP API it provides.
In
the reverse path, commands and information coming from the AGW Packet Engine
are received and handled by TF2AGW.DLL and translated/mapped into
messages following the WA8DED API format.
TF2AGW.DLL support the WA8DED HOST mode, very limited or no support
is provided for the WA8DED CONVERSATIONAL mode, so programs must
issue the JHOST 1 command before any interaction with TF2AGW.DLL.
Not
all the WA8DED command set is actually mapped into AGWPE
requests and viceversa, the following table illustrates the commands mapped in
both ways.
|
Mapped/Used |
Mapped |
Not Mapped |
|
AGWPE to WA8DED |
G,T,S,I,U,C,d,D,X,x,V,v,m,M |
Y,H,g |
|
WA8DED to AGWPE |
L,M,I,D,G,C,JHOST 1 |
@B,Z,Y,R,U,@V,O,F,N,T,P,@T2 |
All
Not Mapped/Discarded WA8DED commands returns a custom OK answer
to the program that sents it for compatibility reasons (Channel+0x01+0x00).
At
initialization, as much as 16 Virtual TNC channels are opened
within the TF2AGW.DLL, each one potentially capable to sustain an
independent dialog with the AGW Packet Engine.
The
Virtual TNCs are mapped one to one with WA8DED channels (Virtual Channel
0 is DED Channel 0, Virtual Channel 1 is DED Channel 1, etc).
Virtual
Channel 0 is for monitoring and unproto activity only while Virtual Channels
1-15 could be used for actual communications (connected sessions).
A
Virtual Channel is activated whenever the callsign+ssid associated with
(MYCALL , WA8DED I Command) it is initialized as non-blank, when
initialized the virtual channel registers the callsign+ssid with
the AGW Packet Engine[1],
any arbitrary assignement of callsigns to the channels could be done.
All
traffic between TF2AGW.DLL
and AGWPE is handled thru a single TCP/IP socket to preserve the
system resources, internally the
distribution of the information to the appropriate TF channel is managed as it
flows. Monitor frames are directed to the channel 0 (UNPROTO),
monitoring frames will not be received under any circumstances by the channels
1 to 15, the monitoring traffic actually passed to the application will depend
on the setting of the monitor status (WA8DED M Command),
the default at startup is IUSC (all monitoring frames).
All
trafic subsequently managed by the AGWPE directed to that callsign+ssid
will be directed to the now registered section of TF2AGW.DLL and
in turn, after appropriate validation and reformating to the application
listening on the WA8DED interface, when no channels are available to
attend the connection the DLL sends an inmediate Disconnection request to the
connecting station that has to be interpreted as a BUSY message.
The
callsign of a given channel could be changed at any time after the initial
setting by means of the I Command (or whatever the mapping of it the
application program provides, in the case of TSTHWIN would be AX
PORT n CALLSIGN-SSID), TF2AGW.DLL automatically detects
and perform the reconfiguration of the registration for the callsign with the AGWPE
whenever necessary.
The
lifespan of the virtual channel is as long as TF2AGW.DLL is
running, which in turns is as long as the application program that uses it is
running.
However,
if the connection with AGWPE is broken or become otherwise
unavailable (i.e. AGWPE comes down for some reason) the virtual
channels will still be operational but all ongoing connections that were
operational at the link failure will be forced disconnected and subsequent
interactions with the channel (commands) will return the message TNC BUSY
- LINE IGNORED as long as the communication with AGWPE
could not be re-established, the TCPIP connection is further monitored and
whenever AGWPE become available a connection is re-established
and all the registrations recreated according with the last callsign settings
performed.
AGWPE by itself could handle frames larger than 256 bytes while the WA8DED
spec could not, packet frames larger than 256 bytes will then be discarded by TF2AGW.DLL
and not passed to the application program.
The following functions are made available to the application program as a DLL exported functions by TF2AGW.DLL, this information is made available for application developers interested into adapting programs to work using this DLL, final users of applications should not be concerned by this section contents and might safely skip to the next.
Open
the TF interface, execute once at the beginning of the application program
usage.
BOOLEAN FAR
PASCAL _export TfOpen(HWND hWnd)
Where:
hWnd Is a pointer of the type Windows Handle, this handle
is not used by TF2AGW.DLL and included for compatibility only, any value of the
proper type will do even a Nil value.
Returns:
TRUE If
TF2AGW.DLL has been properly initialized.
FALSE If TF2AGW.DLL was unable to initialize properly.
Please
note that no attempt to establish communication with AGWPE is
made when this function is called, the AGWPE API Sockets will be opened later when the callsign for each channel is
set (I command). So failures reported by this function are related
mostly to constraints to establish the working environment (memory problems,
DLL physical file problems, etc).
The
DLL could be successfully open even if AGWPE is not functional,
even if it is not installed, however, all communications functions will fail
later if a successfully connection with the AGWPE could not be
established.
Close
the TF interface, execute once at the end of the application program usage.
BOOLEAN FAR
PASCAL _export TfClose(void)
No
arguments are given to this function.
Returns:
TRUE If
TF2AGW.DLL has been properly closed.
FALSE If TF2AGW.DLL was unable to close properly.
This
function triggers the orderly close up of all the TF channels, the sequence
followed during the clossure is:
Get
a character the from TF interface if available, -1 is returned if no character
is available.
int FAR PASCAL
_export TfGet(void)
No
arguments are given to this function.
Returns:
0..255 Character returned
-1 If
no character is available.
Please
note this is not a blocking function that will wait for a character to be
ready, it is the application responsibility to query this function and handle
the result. Also note that no indication of the TF channel who provide the flow
of information is selected nor returned in a direct way, it is the application
responsibility to buffer the stream of characters and decode them into one of
the defined type of data records defined by the WA8DED interface for further
processing.
The
character stream are held internally by AGWPE first, then sent
using a TCP/IP interface over a network where it will suffer an arbitrary an
mostly unknown delay on top of potential fragmentation issues, then buffered
internally by TF2AGW.DLL before to be finally delivered to the
application, so trying to establish any timming correlation with the real
packet sent over the AX.25 network will probably be a moot point.
Put
(Send) a character to the TF interface.
BOOLEAN FAR
PASCAL _export TfPut(char ch)
Where:
char Is
the character value to be sent.
Returns:
TRUE If
the character has been placed into the transmitting queue.
FALSE If the character failed to be placed in the transmitting
queue.
Please
note this function just report if TF2AGW.DLL has been able to
internally store the character sent using it, the function will return FALSE
values only if there is some sort of internal memory overflow (i.e. the
internal TF2AGW.DLL queue is full). TF2AGW.DLL
assembles internally the completed WA8DED records before any attempt to
interchange information with AGWPE. Problems developed during the
actually exchange with AGWPE will be handled internally by TF2AGW.DLL
without the program having control of that process.
Even
if the WA8DED interface is defined in terms of records the API only
allows to sent a character at a time, so it is the application responsibility
to actually build the required records internally and sent them serially a byte
at a time, don’t blame me for that, I didn’t develop the WA8DED
spec, only wrote a program that uses it.
Verifies
if a character is ready to be read from the TF interface.
BOOLEAN FAR
PASCAL _export TfChCk(void)
No
arguments are given to this function.
Returns:
TRUE If
there is a character ready to be read.
FALSE If
there is not a character ready to be read.
Most of the configuration needed by TF2AGW.DLL could be done thru WA8DED commands (or the implementation of them the application program provides, see the documentation of it for details) with some default values for each parameter being defined at initialization time.
However
there are information which is needed for the proper function of the program
and yet not enabled to be set thru WA8DED commands, this information is
held on a small configuration file named TF2AGW.INI that should be
placed into the C:\WINDOWS directory.
This
file is not used for any other program nor affects in any way the overall
behaviour nor the operation of the Windows environment, it could be removed as
a part of the uninstallation of TF2AGW.DLL withour any further
consideration.
However,
if not properly configured it is unlikely that TF2AGW.DLL could
work at all (and in some cases it would drive it to fail, see Troubleshooting for details), so attention has to
be pay to the settings defined on it.
The
overall format is that of any standard Windows .INI file, a section
named [AGWPE] followed by the parameters and their values, two
parameters
are actually defined:
IPADDRESS Defines the IP address of the
machine where AGWPE will be found (default 127.0.0.1)
TCPPORT Defines the TCP port used to
communicate with AGWPE (default 8000).
DEBUG This is an interim
configuration parameter that when stated as DEBUG=YES direct TF2AGW.DLL
to generate traces
of
its internal activity. Two traces are generated named TF2AGW.LOG and DEDVC.LOG.
In order to disable
the traces the line has to be set as DEBUG=NO or removed from the TF2AGW.INI file.
Warning: once the traces are activated the logfiles generated could become quite large (dozens of megabytes!!).
MESSAGES Enable (ON) or Disable (OFF)
special messages TF2AGW.DLL sends to the monitoring port, those
messages are
useful to know the current status of the communication between the DLL and AGWPE but now being defined as a
part
of the WA8DED protocol they might confuse some programs. If so, just
disable them. The default if the line is
not
present is OFF. The information is always sent to the channel #0 as a
link status message (type 4) and contains
connection
and disconnection events as well as port and version information of AGWPE.
If
the TF2AGW.INI file can not be found the default values are used by the
program, however those defaults might or might be not appropriate to your
particular configuration. Since the file is a normal ASCII file it could be
edited with any text editor such as Windows’s Notepad or Edit.
Follows a sample of the TF2AGW.INI
which I use (included in the distribution file).
[AGWPE]
IPADDRESS=127.0.0.1
TCPPORT=8000
DEBUG=NOT
MESSAGES=ON
The
TF2AGW.DLL is intended to be seen internally by the packet
application program, not by the end user, so most of its functionality will be
usually hidden and only of the interest and concern of the programmers who
wrote the application, the user has to ensure a correct installation and that
should lead for the front-end program to be able to locate and use it.
Since
TF2AGW.DLL remaps all the application requests into AGWPE
the application will see the set of communication resources managed by AGWPE
(any combination of hardware TNCs, sound cards, SCC cards, baycom modems and
even the internal loopback port) as one single huge multiport TNC, it is very
important for the end user to grasp the concept that a particular command for a
particular TNC probably won’t be flowed thru the real hardware but just trapped
by TF2AGW.DLL internally, all management of the actual hardware
has to be done directly using AGWPE functions.
However,
the way AGWPE manages the TNCs under its control will require
from the user to address the physical port to which a given connection is
intended, the formats recognized the TF2AGW.DLL and properly
mapped into AGWPE are the following for the CONNECT command:
C CALLSIGN-SSID
[CALLSIGN-SSID CALLSIGN-SSID…]
C n:CALLSIGN-SSID
[CALLSIGN-SSID CALLSIGN-SSID…]
Cn: CALLSIGN-SSID
[CALLSIGN-SSID CALLSIGN-SSID…]
Where
n means the AGWPE Port-1 (0=Port1,1=Port2,…
as listed in the AGWPE’s Properties dialog) the first CALLSIGN-SSID
(i.e. LU7DID-2) is the one intended to be connected and the remaining the
optional VIA path if digipeaters are used, if the SSID is omitted
an SSID=0 is assumed (i.e. LU7DID-0 or LU7DID).
The
numbering convention of the radioports to be in the range of [0..N] is for
compatibility reasons, hopefully the DLL will shadow any inconsistency
regarding that numbering convention.
The
monitored frames received by TF2AGW.DLL and mapped into the UNPROTO
channel (TF channel #0) are the following
n:fm {call} to {call} via {digipeaters} ctl {name} pid {hex}
Where
n is the AGWPE Port where the frame was originally
monitored, the Connection and Disconnection messages are mapped as follows:
n:
CONNECTED to n:{call}
n:
DISCONNECTED fm n:{call}
***
Warning ***
Please note that
even if the connection is performed thru digipeaters the connection message
will not reflect that to the application.
Where
again n is the AGWPE Port where the
Connection/Disconnection occurs, beware that this is not the WA8DED Channel
number but the port interface number as listed in the AGWPE Properties
dialog.
The
AGWPE Status Messages are generated by TF2AGW.DLL
based on internal information regarding the TCP/IP communications, those
messages are sent to the TF Channel #0 (Unproto/Monitoring channel) as
any other Unproto/Monitoring frame if the MESSAGES=ON configuration
enables them at the TF2AGW.INI file. These messages are not WA8DED
compliant and if your terminal software is not prepared for them in some
particular way it might be “confused”, so if you experience problems just
disable them by configuring the MESSAGES=OFF at the TF2AGW.INI
file or just removing that line (the default for this configuration is OFF).
The
messages sent in that regard are:
*** Registered with AGWPE
the callsign XXXXXX-nn
A callsign has been registered with AGWPE successfully.
***
Unregistered with AGWPE the callsign XXXXXX-nn
A callsign has been unregistered with AGWPE successfully.
*** Linked
with AGWPE at address nnn.nnn.nnn.nnn:pppp
The TCP/IP socket with AGWPE has been established successfully.
*** Link
with AGWPE is broken.
The TCP/IP socket with AGWPE got an unexpected error.
***
Available ports at AGWPE are:
Port
[n] XXXXXXXXXXXXXXXXXXX
List of the ports that AGWPE manages.
*** AGW
Version nnn.nnn initialized at dd-mmm-yyyy hh:mm.
Current AGWPE version as reported by the program.
The
WA8DED compliant messages returned by TF2AGW.DLL to the
application program in case of an error condition are:
INVALID CALLSIGN
INVALID PARAMETER
NO
SOURCE CALLSIGN
INVALID COMMAND: ?
NOT
WHILE CONNECTED
INVALID CHANNEL NUMBER
TNC
BUSY - LINE IGNORED
CHANNEL ALREADY CONNECTED
STATION ALREADY CONNECTED
The
error message would be directed to the WA8DED channel originating the
error, whenever it reflects a condition actually originated at the AGWPE
will be directed by TF2AGW.DLL to all the involved channels.
Historically, amateur radio applications has been run on a single computer, from simple terminal programs to DOS based relatively complex packages such as the G8BPQ Node software or the F6FBB BBS package; some limited implementation of phone, serial or ethernet connections to access the applications were developed over time, but in most cases that was just a different way to access the application as alternatives to the regular AX.25 packet network (i.e. for maintenance purposes, or for faster speed). This is adequate for most occasional uses, such as checking the mail on the home BBS or doing a file transfer, but has been a growing headache to operators trying to cope with high volume or network critical nodes where high availability is required such as NETROM nodes or BBS.
The
combination of the application program (i.e. TSTHWIN) with the
AX.25 Manager (AGWPE) and this TF2AGW.DLL still could run on the same machine, but for
the first time it not necessarily has to.
Users
could run all the programs under a single Windows 95/98/NT operating system on
the simplest configuration, however as long as there is a permanent TCP/IP
connection of adequate speed nothing prevents the application program and the
L2 Manager (AGWPE) to be on different
machines, when implementing distributed configuration TF2AGW.DLL
has to be installed only on the machine that hosts the
application program (i.e. TSTHWIN or WinFBB).
I
do estimate that over the time and thru experimentation hams will implement
very sophisticated and complex network topologies based on that facility, some
of them that could be truly not imaginable now. However some of the likely
scenarios would be:
The application program (i.e. TSTHWIN or
WinFBB), AGWPE and TF2AGW.DLL operates in
the same machine who also manages the physical AX.25 assets such as TNCs,
soundcards or Baycom modems.
One machine in a LAN hosts AGWPE and
the physical AX.25 assets such as TNCs, soundcards or Baycom modems while on
another machine the application software (i.e. TSTHWIN or WinFBB)
is run. Both machines has to have TCP/IP connectivity and be properly
configured for that, usually a network cabling of some sort has to be
implemented (such as a coax or UTP cabling). This could be a good solution for
both ocassional users that wish to keep the “hardware” stuff confined to a
machine (possibly at some remote location of the home) while still be able to
use the packet applications from the most often used machines as well as
operators of full fledged nodes that wish to spread the load among different
machines. Several programs using the TF2AGW.DLL could be run at
the same time connected with a single AGWPE instance provided
that all of them register different callsigns, that includes several BBS at
once or different kind of applications served from an arbitrary distributed set
of machines.
On the basic scenario despicted on the previous
configuration nothing forces the two machines to be physically close as long as
they could be accessed thru TCP/IP connectivity, besides some practical
considerations of costs and availability, nothing precludes those two machines
to be half world appart and linked thru the Internet.
A great deal of practical experimentation and real world needs will dictated which is the most likely scenario for the use of this program, but after all that is what amateur radio is all about, experimentation.
As
per the AGWPE side several fixes and modifications been made
during the development and test of this DLL, it plainly won’t work with older
versions of the program, so be sure you grab and install the latest version
before any attempt to use this DLL. AGWPE version 98-90
will work with this DLL up to version 0.9, however Version 1.0 or
superior must be used with AGWPE version 2000-10 or later because
of changes introduced on the TCP/IP API the DLL uses to communicate with the
engine.
So
far, a fair amount of satisfactory tests has been performed with TSTHWIN
V2.20 and 2.21. Albeit other packages using the TFWIN32.DLL
should work as well, there might be unknown dependencies yet to be discovered
that might impairs that.
Starting
on version 1.1 of this DLL a limited test has been performed with WinFBB
Version 7.00E (32 Bits) , also known as WinFBB32 , with
satisfactory results. This version had been available on the net from http://www.f6fbb.org but it has been withdrawn
from distribution lately, the latest distribution (WinFBB Version 7.00G)
doesn’t contains it, however the Version 7.00E which still included the 32 bits
version of WinFBB could be found at ftp://ftp.f6fbb.org/pub/f6fbb/distrib/win
as files named W700E-*.ZIP. Please check on F6FBB’s home page for availability
information on the 32 bits version since I’m no part of F6FBB team nor have any
further clue about the subject nor could get any of my notes to the team
answered.
Other
packages that already uses the WA8DED interface should be easy to modify
in order to use this DLL as long as they are written to run as a 32 bits Windows
application or are in the way to be ported. Programs written to be run under
older versions of Windows (commonly refered as “16 bits” applications or Win
3.x applications) could not use this DLL, neither could do older plain DOS
programs (including some of them modified or written to take advantage of the
32 bits addressability using extenders). If you’re trying to use the TF2AGW.DLL
with any other program and experience difficulties just drop me a note.
Of
course, if the application already has a native (built-in) support for the AGW
Packet Engine, either using the TCP/IP API or the older DDEML API this DLL is
not necessary at all, the native support should be used instead, on that regard
the DLL could be viewed as an interim porting tool.
The
DLL itself has been written using Delphi 4 (Object Pascal), however it could be
used from programs written in any language that supports the handling of
external DLLs such as MS Visual Basic, MS Visual C++ among others and (of
course) Delphi 4; in general any compiler that could generate 32 bits Windows
applications could take advantage of it.
Installation tips for TSTHWIN and WinFBB 7.00E (32 bits) are provided in order to use this DLL, this information assumes you already read the documentation of those programs and are familiar with it.
*** Warning ***
For all the supported
applications to work AGWPE must be up and running before the application is
started.
TSTHWIN recognizes the TF2AGW.DLL
starting on version 2.21A, however it could be make work with
prior versions. Being available a version with direct support for this DLL the
usage of the lattest version is highly advisable, however if you want to
perform a brief test with your currently installed version of TSTHWIN
proceed thru the following steps:
·
Install
TSTHWIN as indicated by the application instruction.
·
Install
AGWPE as indicated by the application instruction, ensure the TCPIPINTERCONNECT feature is enabled (ENABLE=1).
·
Verify
AGWPE is functional using AGWTerm or AGWMonitor.
#
tsthwin port definition file
#
# TYPE:
0=gkbiowin.dll
# Port: tnc comport 1...8
# Baud: tnc baudrate 110...256000
# TYPE:
1=tfwin32.dll
# Port: Ignored, use 0
# NumIntface: Set the number of blocks
enabled in tfwin.ini
# TYPE:
2=TFPCX and similar
# Irq : Tfpc irq vector, usually 253 for
tfpcx and 254 for tfkiss
# Baud: Ignored, use 0
# TYPE:
3=DRSI emulator
# Irq : Driver irq communication vector
# NumIntface: Set the number of port active
in your driver
#
# tfwin
example : 1 0 1
#
gkbiowin example: 0 1 19200, means com1, 19200 baud
# tfpcx
example: 2 253 0
#
# This
configuration is for AGWPE with 2 physical TNC plus the loopback
# port
defined (total = 3 ports).
1 0 3
TSTHWIN recognizes the TF2AGW.DLL
starting on version 2.21A, the main difference from that is that
you do not require to fool TSTHWIN into thinking it’s working
with
TFWIN32.DLL because given the proper
configuration it recognizes and loads TF2AGW.DLL directly. The
installation process is then simplified significantly.
·
Install
TSTHWIN as indicated by the application instruction.
·
Install
AGWPE as indicated by the application instruction, ensure the TCPIPINTERCONNECT feature is enabled (ENABLE=1).
·
Verify
AGWPE is functional using AGWTerm or AGWMonitor.
#
tsthwin port definition file
#
# TYPE:
0=gkbiowin.dll
# Port: tnc comport 1...8
# Baud: tnc baudrate 110...256000
# TYPE:
1=tfwin32.dll
# Port: Ignored, use 0
# NumIntface: Set the number of blocks enabled
in tfwin.ini
# TYPE:
2=TFPCX and similar
# Irq : Tfpc irq vector, usually 253 for
tfpcx and 254 for tfkiss
# Baud: Ignored, use 0
# TYPE:
3=DRSI emulator
# Irq : Driver irq communication vector
# NumIntface: Set the number of port active in
your driver
# TYPE:
4=AGW Packet Engine (TF2AGW.DLL)
# Port : 0 (don’t care)
# NumIntface: Set the number of ports enabled
on AGWPE
#
# tfwin
example : 1 0 1
#
gkbiowin example: 0 1 19200, means com1, 19200 baud
# tfpcx
example: 2 253 0
#
# This
configuration is for AGWPE with 2 physical TNC plus the loopback
# port
defined (total = 3 ports) on TSTHWIN version 2.21A or higher
4 0 3
*** Comment on TF2AGW.DLL
vs. TFWIN32.DLL***
I’ve received, so far, several comments on difficulties to make WinFBB32
work with the REAL TFWIN32.DLL (mean, the one supplied
originally with the package) which is intended to be used with hardware based KISS
TNCs. The comments ranges from instances where the BBS won’t work at all to
difficulties handling multiport TNCs (apparently that DLL was written to access
single port TNCs only).
While I could endorse none of those comments
without a direct hands-on experience, which I lack on the subject, I could tell
that I’m just taking advantage of a programming interface built into WinFBB
in the form of certain entries or calls performed by the program to “squeeze”
my DLL on it. Other than this I make no use of the actual TFWIN32.DLL
nor share any of it’s alledged limitations. TF2AGW.DLL could
access as many ports simultaneously as defined on the underlying AGWPE
and of course could handle (thru the power of AGWPE’s programming
API) the wide assortment of hardware TNC, boards (some of them frankly exotic),
sound cards, Baycom TNCs and whatever AGWPE could live with.
So, in a nutshell, TF2AGW.DLL
could (and probably would) work even on configurations that the “original”
TFWIN32.DLL failed to. The opposite is also true,
TF2AGW.DLL might have “bugs” or a
behaviour the original TFWIN32.DLL doesn’t have.
WinFBB
7.00E does
not recognize TF2AGW.DLL directly, it has to be fooled into
thinking it’s actually working with the F6FBB’s TFWIN32.DLL
supplied with the package, I’ll contact the author to see if incoming releases
of WinFBB makes that support explicit, but for the time being
things are the way they are.
The
full installation and configuration of WinFBB is a rather complex
process, far beyond the scope of this document to address, for a complete
description of it please refer to the apropriate WinFBB documentation
and help files. Follows some comments on aspects of the installation and
configuration which are relevant to TF2AGW.DLL.
·
Install
WinFBB 7.00E as indicated by the application instruction, be sure
to install the 32 bit version (dubbed as WinFBB32).
·
Install
AGWPE as indicated by the application instruction, ensure the TCPIPINTERCONNECT feature is enabled (ENABLE=1).
·
Verify
AGWPE is functional using AGWTerm or AGWMonitor.
·
Run
the WinFBB32 configuration program (this procedure assumes 1 port
defined on AGWPE, adapt it to your own configuration with as many
ports as you really have:
1.
Proceed
with “Next >>” till the “Communications Configuration”
panel.
2.
Select
COM1 and TFWin as the Interface.
3.
Select
all other COM2 thru COM10 and select None
as the Interface.
4.
Proceed
with “Next >>” till the “Ports Configuration”
panel.
5.
Select
PORT1, COM1, Mux 0, Number of Channels 2 (you could
play with those values later to suit your own needs).
6.
Set
the other values, those are not really important because the configuration that
WinFBB will perform with them won’t be actually propagated to AGWPE
which has it’s own way to set the TNC parameters, the most important value to
set is perhaps the label of the port for your user’s reference.
7.
Set
the mode of the port to WA8DED.
8.
Set
Users/Guest/BBS and the remaining checkboxes according with your own
configuration needs.
9.
Save
the configuration with File/Save and then Exit the
program with File/Exit.
#
FBB7.00
# File
for programming of channels and TNCs.
#
# Ports
: How many ports (COM1, COM2, Etc...)
# TNCs
: How many TNCs and modems in use. With multiplexer
# there
can be up to 4 TNCs per port.
#
#Ports
TNCs
1
1
#
#In
WinFBB ONLY THESE interfaces are available:
#
Interface : 2 = BPQ-node (BPQ in AA4RE-mode)
# 4 = DRSI
# 5 = TFPCR/TFPCX interface. Interrupt MUST be 0xFD or the same
# as stated in INIT.SRV, if
any..
# 6 = Windows-driver, replaces both
ESS, ESSKAM and FBBIOS.
# 7 = TCP/IP. Needs
WINSOCK.DLL. Put port-address as 17.
# TNC-emulation is T (see
below)
# 8 = TFWin.dll (Only WinFBB32)
#
BEWARE: The old interface 1 and 3 will NOT be used in WinFBB. Interface 6
# replaces both. (FBBCOMM.DRV). Neither ESS nor FBBIOS can be
# used with WinFBB !
#
#In
LinFBB ONLY this interface is available:
#
Interface 9 = Linux. Can work via serial port (D),via AX25 domain
# socket (X) or via Telnet port
(T).
#
#In
DosFBB ONLY THESE interfaces are available:
# Interface : 1 = Use external COMBIOS-driver
(MBBIOS, ESS etc)
# 2 = BPQ-node v 4.05 and up (BPQ
in AA4RE-mode)
# 3 = Telephone-modem with FBBIOS
# 4 = DRSI card with driver
# 5 = TFPCR/TFPCX interface. Interrupt MUST be 0xFD
#
#
Address : Address of port in
hexadecimal (Needed for multiplexer).
# In LinFBB:
# Address is the device name
(/dev/cua0).
# Be sure you have the rights to
access to the device (rw-rw-rw-).
# When using kernel AF_AX25 socket,
address is not used.
# When using Telnet, address is the
Telnet port in Hex (Hex 17 = Telnet port 23)
#
Baud : Ports baud rate. Ignored by
BPQ, kernel AF_AX25 socket and Telnet.
#
# Use
same number of lines as number of ports.
#
#Com
Interface Address (device) Baud
1
8 3f8 9600
#
#
TNC : Number on TNC in use. Use 0 for file-forward !
#
NbCh : Number of channels I want to use
in the TNC.
# Maximum available channels depend
on firmware.
#
Com : Number of the COM-port. Com1,
Com2 etc.
#
MultCh : Number of channel if
port-multiplexer is used, otherwise 1.
# In DRSI use values from 0 to 7, by
KAM use 1/VHF and 2/HF.
# With BPQ first TNC must have MultCh
0, the next 1, etc.
# When using kernel AF_AX25 socket in
Linux, MultCh is the
# interface name (eg: ax0)
#
Paclen : PACLEN on this TNC.
#
Maxframe: The maximum nb of frames the TNC will send at a time.
#
NbFwd : Number of channels for
OUTGOING forward at same time.
#
MxBloc : Size of forward-block in kb.
#
M/P-Fwd : Minute of the hour for start of forward, and period
# (how many minutes between each
forward-start).
# Port
mode, one of these:
# B : BBS-mode.
# G : "Guest"-mode.
# U
: Normal-mode.
# Type
host-mode, one of these:
# D : WA8DED
# K : KAM hostmode. Must use ESSKAM driver.
# P : PK-232
# Q : BPQ v 4.x
# T : Ethernet/TCP-IP
# X : AX25 domain socket (for Linux)
#
Addition: One or more of these letters can be used too:
# L : Send unproto beacon after each
arriving mail.
# M : Telephone-modem.
# Y : Yapp allowed on this QRG.
# W : Gateway allowed TO this QRG.
# R : Modem port allowed in Read-only
mode.
#
Freq. : Text to describe this port
(max 9 characters, no space)
#
# Same
number of lines as TNCs:
#
#TNC
NbCh Com MultCh Pacln Maxfr NbFwd MxBloc M/P-Fwd Mode Freq
0
0 0 0 0 0
0 0 00/01 ---- File-fwd.
1
2 1 0 230 4
1 10 30/60
DULWYR 145.15 Mhz 1200 bps
***
Warning ***
Depending
on your PATH configuration (where your machine looks for executables) it
might happen that if you have a copy of the real TFWIN32.DLL (the one supplied
with F6FBB) somewhere on the path with precedence from the copies you replaced
with the renamed TF2AGW.DLL during it’s installation it might happen that
WinFBB32 actually loads it instead of the renamed TF2AGW.DLL.
It would
be a good idea to scan your disk with the Win95/98 FIND facility looking for
tfwin32.dll and if you found copies of it that you didn’t replaced with a
renamed TF2AGW.DLL during the installation rename them (i.e. as TFWIN32.LLD) in
order to be sure that won’t be wrongly used.
·
After
a while with AGWPE not available the DLL traps.
·
On
NETROM frames being monitored the data part is usually truncated (does not
affect actual connected data, just monitored data).
·
Applications
relying on the monitoring of frames might have some trouble because of
differences in format and truncation of the information field.
If
the IP Address indicated in the TF2AGW.INI file yields an error when
used it will drive TF2AGW.DLL into a protection exception
condition, most likely this condition will occur when the program using
the DLL tries to setup the callsign of the channels (which is when the TCP/IP
socket is established). If that condition occurs proceed with the following
procudure.
·
Verify
you have copied the file TF2AGW.INI on the C:\Windows directory.
·
Make
yourself certain your application are using unique callsigns and SSID,
you could verify that prior to loading it looking at the AGWPE
menu on the About entry, the button named “Winsockets” will
display the currently registered callsigns, none of them should be used by your
application since when the duplicate callsign+ssid registration is attempted it
just will be ignored by AGWPE.
A word about IP Addresses
If your machine is not connected to a LAN and have assigned a
permanent address it is likely that even if your TCP/IP stack is configured you
don’t have a concrete IP ADDRESS to set this program. In that case you should
use what is known as the “loopback” IP Address, which is a
special IP Address that the TCP/IP stack in your machine uses to communicate
with itself. This loopback IP ADDRESS is usually either 127.0.0.1
or 128.0.0.1 and you should not need to configure anything to use
it, it is just there already defined for you. Be aware that if you configure
the loopback IP address all the programs must run on the same
machine, you can not go distributed (aka split the programs in several
machines) without properly configure them as a LAN each one with their own
addressable IP number.
You could tell if your TCP/IP stack knows about the loopback
address by doing on a MS-DOS session the following command
PING 127.0.0.1
If you get an answer such as:
Pinging 127.0.0.1 with 32 bytes of data:
Reply from 127.0.0.1: bytes=32 time<10ms TTL=128
Reply from 127.0.0.1: bytes=32 time<10ms TTL=128
Reply from 127.0.0.1: bytes=32 time<10ms TTL=128
Reply from 127.0.0.1: bytes=32 time<10ms TTL=128
Ping statistics for 127.0.0.1:
Packets: Sent = 4,
Received = 4, Lost = 0 (0% loss),
Approximate round trip times in milli-seconds:
Minimum = 0ms,
Maximum = 0ms, Average = 0ms
Your setup will probably work without problems, beware if you
get an answer like the
following:
Pinging 127.0.0.0 with 32 bytes of data:
Destination specified is invalid.
Destination specified is invalid.
Destination specified is invalid.
Destination specified is invalid.
Ping statistics for 127.0.0.0:
Packets:
Sent = 4, Received = 0, Lost = 4 (100% loss),
Approximate round trip times in
milli-seconds:
Minimum = 0ms, Maximum = 0ms,
Average = 0ms
In the unlikely
event that you try to run this program on an environment that allocates
dynamically the IP Addresses (i.e. using BOOTP or DHCP)
be aware that your IP Address might change over time and you should reflect
that on the configuration if trying to use the programs distributed on several
machines, however, even on such scenario using the loopback IP Address and
everything on the same machine should not create any problem. If you are not
working as a part of a big LAN, say a business environment, you should not be
worried about this scenario.
Please refer to the
documentation of your operating system on how to properly configure the TCP/IP
stack on your machine for further information.
Many
people contributed with this program on its different development stages, I
could not account for all of those that thru conversations (real, air or
E-Mail) contributed to create in my mind the original idea.
The
development itself wouldn’t be possible at all without George Rossopoulos
(SV2AGW) providing the AGW Packet Engine (AGWPE) in the first place,
extending the capability to interact with it thru TCP/IP as opposed to the
somewhat arcane DDEML original interface the program had and lately reacting
very promptly to make modifications and enhancements to AGWPE
during the development and test stages.
Also,
as a long time user of TSTHOST no little part of the drive to
write the DLL was the desire to run the most advanced TSTHWIN
program, Mario Travaglino (IK1GKJ) contributed in several stages of the
development providing insights of the usage of the WA8DED Host Mode that TSTHWIN
does as well as testing the early versions of this DLL with it and providing
useful feedback from that, to finally release 2.21a of the program to support
the DLL right away.
Version
1.1 of this DLL involved a lot of hard work, two major functional improvements
were made, and the aid from Karl Bilger (VK2DYX) resulted invaluable during the test of this release.
I
look forward for other people to actually use the DLL and provide positive or
critic feedback of it, for developers willing to use it as porting tool to
enable
your
application for the AGWPE just drop me a note with any special requirement or
problem you might have.
TF2AGW.DLL is free for radioamateur and experimental uses, commercial use
requires written permission from the author. The author bears no liability for
damages related to the usage of this program nor guarantees the proper
functional behaviour. I could certainly be more sofisticated in legal terms,
but in a nutshell use it at your own risk.
Publicly
available information has been used to understand the requirement of the WA8DED
interface (WA8DED21.DOC by R.E.Raikes WA8DED), the AGWPE TCPIP Interface
(AGWSockInterface.DOC by G.Rossopoulos SV2AGW), the The Firmware
Messages (TFPCX271.DOC by Henk de Groot PE1DNN) and the TFWIN32.DLL exported
interface and functional description (TFWIN.TXT by J.P.Roubelat F6FBB),
all code used to implement this program comes from my own development.
If
you need support, have suggestions, encountered some bug or just are willing to
provide feedback drop me a note at:
AX.25: LU7DID@LU7DID.#ADR.BA.ARG.SOAM
Inet: [email protected]
[1] You could see at any moment which callsigns+ssid are registered with AGWPE looking at the About/WinSockets dialog of AGWPE.