home    builders    Search

builders ➜ tarpn host & minicom

G8BPQ APIs, serial streams, Minicom, TARPN HOST command

The G8BPQ middleware provides APIs that manifest as virtual /dev serial streams. Minicom is a terminal emulator that can connect to the 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 execute using the com7 serial stream of G8BPQ. A network operator 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.

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 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. (Technically, each new connection will will result in the Linux command aplay being launched with the parameter of Ring.wav.) Note that the node software and Minicom will only allow one connection into and out of the host port at a time. See also the TARPN TX command for additional outbound connections.
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

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. 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.

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 one of these commands:

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?
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 may cause carriage returns to be generated in the outbound (transmit to node) stream when a control-M is received from user application (as if being transmitted to the node).
convNeeds documentation!.
cpactimeNeeds documentation!.
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

Other G8BPQ APIs

The node software we're using has several different APIs, some of which also use the virtual device driver model. See the G8BPQ resources page for more of John Wiseman's (G8BPQ) documentation.

Minicom information

Minicom is installed twice during the tarpn_install script execution. The first installation uses apt-get package manager. The second installation is the delivery of G8BPQ's piminicom which gets stored 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 text:
/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"
© Tadd Torborg, 2014↝2023 -- all rights reserved