home    builders  

builders ➜ tarpn host & minicom

G8BPQ APIs, serial streams, Minicom, TARPN HOST command

The G8BPQ middleware provides APIs that manifest as virtual serial streams. Minicom is a terminal emulator that can connect to an TNC2 API serial stream. Using Minicom, a packet network operator can have a textual QSO with another packet network operator. This QSO is comparable to what's possible in CW or the PSK31 digital mode; however, the packet network is transporting the traffic between the two participants in the QSO.

The TARPN installation script configures Minicom to connect into the packet node using the com7 virtual serial port of the G8BPQ packet node application. The local user of the packet system can access Minicom by launching a terminal session on the Raspberry Pi and entering a tarpn host command. The operator will then be in the Minicom environment and will have a window for incoming connects from other stations on the network or to create a connection into the network. From the network side (over the packet network from another site) this connection is accessible using the host command or by connecting to the nodename piuser.

Let's try this.
The scripting makes this very easy. Use Putty or Terminal or something similar to open a terminal session into the Raspberry Pi. Either use SSH from another machine or go to the Raspberry PI desktop and launch Terminal there. Once you are at the Linux prompt
you can type the command
tarpn host
This will start the Minicom terminal emulator. The TARPN version of Minicom has been modified to do a RING whenever a control-G bell character occurs in the received data. This will occur when a connection to the host port is made while Minicom is running, whether the connection is made inbound, or outbound. The RING is played on the speaker port or the HDMI port (a configuration choice) of the Raspberry Pi, so that you can be notified of a connection even when you are not reading your Minicom screen.
See API details below.
Once Minicom has started, you are presented with the cmd: prompt.
The Minicom terminal is connecting to the TNC2 API in G8BPQ. One of the powers of this arrangement between Minicom and G8BPQ is that you can accept connections from other TARPN nodes. First I will show you how to do that. Later on this page I'll give a verbose technical description of all of the commands; the full set of commands will be necessary if you desire to write code to talk to the G8BPQ TNC2 API.

Using tarpn host to receive incoming connections

When you followed the instructions above, you used tarpn host to start Minicom. You are now presented with a cmd: prompt, and you are ready to receive a connection. To demonstrate this feature on your own node — a kind of loopback within your node — use BPQterm or TARPN-HOME to get into your node and issue the command host. This will instruct the node to make a connection to your host-port, which ends up at your Minicom window.

Here is a screen shot showing my going into BPQterm and typing HOST followed by some random text while the Minicom window is visible.

From the Minicom you can type a message back to the other window.
To tell Minicom to disconnect from your incoming caller, send control-C and type type d and return.
To exit from Minicom, send control A followed by X and then hit return.

Notice the text saying that Ring.wav was played? As described above, the sound file is output to the Raspberry PI's audio output jack or HDMI depending on your configuration.
You can replace the Ring.wav file from any of the wav files supplied in the /home/pi/ringfolder directory. To select the sound file presto.wav, copy and paste this text into a Linux-prompt terminal window:
mv /home/pi/ringfolder/presto.wav /home/pi/minicom/Ring.wav
and hit return. To test the soundfile, send this text to the Linux terminal window:
aplay /home/pi/minicom/Ring.wav

TARPN network user interfaces

As of this writing there are several different user interfaces available to the operators.

Verbose Description

This is a description of Minicom and the TNC2 API
Minicom is installed and maintained by the tarpn start, tarpn update and tarpn updateapps scripts. Minicom is installed twice during the tarpn_install script execution. The application is first installed using the apt-get package manager and then a modified copy of Minicom, called piminicom is placed in the /home/pi/minicom directory. piminicom is executed from the tarpn script when the command tarpn host is executed from a linux prompt. piminicom is launched with this command line and arguements:
/home/pi/minicom/piminicom -w -D /home/pi/minicom/com7 -S minicom.scr
The file minicom.scr, which is called out from the launch text, is read by Minicom and configures the TNC2 API by sending the text commands contained in the scr file. This is the contents of that file.
send "^C"
send "D"
send ""
send "autolf on"
send "cbell on"
send "echo on"
send "conok on"
send "mon off"
send "mall off"

The modified version of Minicom calls the Linux command aplay with the parameter of Ring.wav any time a control-G appears in the incoming data from the virtual serial port. .

You can send Minicom a command to quit or change parameters by typing control-A. control-A Z will give you help on keys. If you type text without sending a control-A, you will be sending commands into the TNC2 API.

At cmd: you can type these commands to the TNC2 API:

autolfDisplays or changes the automatic linefeed configuration. With a parameter of Y or N you may enable or disable automatic linefeed.
bbsmonMonitor callsigns only -- used to build the JA list in some BBS software?
cbellDisplays or changes whether a control-G is generated to the user when a connect occurs.
conokDisplays or changes the connect-OK configuration. If set to NO then nobody can connect in.
connectShows the current CONNECT state. If you are currently DISCONNECTED, then with a parameter this command will connect to a distant node, a server, or to switch, which represents your own node.
cAbbreviation for connect.
crI don't know what this does. I think it sets an option which will cause carriage returns to be generated in the inbound (text to user) stream when a control-M is received from node API.
convNeeds documentation!
cpactimeNeeds documentation!. I am guessing that this controls whether the transmit data (from Minicom) will be flushed to the network after a timeout, or not. This would be useful in transparent mode. I don't know how to set that timeout. I would have expected a PACTIME command but that doesn't seem to be a valid command.
dtell the API to DISCONNECT.
echoDisplays or changes the local echo configuration. With a parameter of ON OFF Y or N you may enable or disable local echo.
eThis is the same as echo.
kleave cmd: and start typing to the node.
mallLook at or change the state of the Monitor-All feature. With a parameter of ON OFF Y or N you may enable or disable Monitor-All. Monitor-All being ON says to include traffic sent unproto or to other stations, instead of just traffic to me, but only if the monitor feature itself is turned on. See next couple of commands. It is also unclear to your author if this command does anything at all in the context of a TARPN node.
mcomLook at or change the state of the Monitor-Comm feature. With a parameter of ON OFF Y or N you may enable or disable Monitor-Comm. This feature says that if ON you will see connect, disconnect, acknowledge, and busy packets when you are enabled to watch monitored traffic. If OFF you will only see Info Frames when you are enabled to watch monitored traffic.
mconLook at or change the state of the Monitor-Conn feature. With a parameter of ON OFF Y or N you may enable or disable Monitor-Conn. This feature says that if it is ON you will see monitor text even if you are in a connection to the node or to some server. This can be very confusing.
mcThis is the same as mcon.
monitorGlobally turns on or off monitoring.
monSame as monitor.
mtxMonitor transmit.
mycallDisplays or change the callsign assigned to the serial stream/API. The callsign appears to be set to the node callsign when the G8BPQ pilinbpq node starts up.
myThis is the same as mycall.
nodeThis is the same as k.
pDisplay the length of packets sent from this terminal. This command makes you think you can change that length by issuing p and a number. That features appears to not do anything useful.
sendpacThis may set the character (in hex) used to tell the API that the text typed so far is ready to be sent out as a packet.
transTransparent Mode. This tells the TNC2 API to send packets when the buffer is full or a timeout after the first character arrives in the buffer whichever comes first. I don't know how to specify the rate, yet. The API will ignore your control characters but will send them into the output stream verbatim. This is intended for binary file transfer. To escape from transparent mode, pause for several seconds, then send a control-C, followed by another 2 seconds, followed by another control-C, etc.. It should take 4 control-Cs with pauses to get back to the cmd: prompt
tSame as trans.
^CGet back to cmd:. Using control-C does not disconnect from the node or network or server. It redirects future traffic to the cmd: processor, stopping it from going into the network or node. The opposite command is K which tells the API to direct future traffic to the node or network (depending on the state of CONNECT).

WB9LOZ, Larry Kenny, has some information on the commands available to a typical TNC. The TNC2 API is attempting to emulate a TNC so Larry's document may be of some use. Introduction to packet radio part 13

TNC2 API details

Note that the node software and Minicom will only allow one connection into or out of the TNC2 port at a time using the com7 virtual serial port. See also the TARPN TX command for additional outbound connections.
The G8BPQ software can support multiple TNC2 API instances, each with its own vertual serial port. The directory mapping for the ports in the TARPN installation puts all of the G8BPQ middleware's virtual serial ports in the /home/pi/minicom directory. The mapping is performed in the /home/pi/bpq32.cfg file (down near the bottom) and that file is constructed by the TARPN scripts at the time when the G8BPQ node software is started.
As of this writing the TARPN-HOME application uses com4 com5 and com6.
Minicomm is called with com7.
com8 is instantiated but idle and is available for your experiments.


Other G8BPQ APIs

The node software we're using has several different APIs available, some of which also use the virtual serial port device driver model. See the G8BPQ resources page for John Wiseman's (G8BPQ) documentation.
© Tadd Torborg, 2014↝2017 -- all rights reserved