Debug A Poor Link

Pardon the lack of organization here. This page will need polishing.

How to characterize a link

The neighbor on the other side of the link should show on the routes nodes list. From the TARPN-HOME Node pane, or from QTtermTCP, run the r r command.
See also G8BPQ R command.

r r
SPHEN:KA4QRT-2} Routes
> 1 K1QSY-2   200  14! 442  236  33% 0 0 19:41  6 200
> 2 WD1QRS-2  200  14! 221   17   7% 0 0 19:41  0 200
> 3 K2CC-2    200  12! 562    5   1% 0 0 19:42  1 200
  4 K7QTH-2   200   0!  55    0   0% 0 0 21:02  0 156

In the example above, port 1 K1QSY-2 shows a bad retry rate. Averaged over the 442 information frames (packet messages with text) the SPHEN:KA4QRT-2 node has transmitted since node-start, the SPHEN:KA4QRT-2 node has had to transmit 236 extra copies of information frames in order to get information frames across the link. That has resulted in a 33% figure. We like to keep the percentage number down to about 9% in an acceptable link. 3% is considered excellent. The higher the percentage number, the slower the link will seem.

The number of packet-messages-with-text counted in r r is ever incrementing starting with the node start. We have a command, trr which gives these counters over a more restricted period of time, which is handy, but trr actually sources its data from r r. The r r command is available from the moment the node starts, and accumulates data in real time where trr requires as much as 60 minutes in order to provide any data at all on a link. Understanding the advantages and disadvantages of r r and trr is very handy in network management. There is more on trr later in this page.

Also important in K1QSY's line is the 2nd to last figure. The 6 in this column means there are 6 messages waiting to go across this link. We'd like to see that figure at 0, or nearly 0, meaning little or no traffic waiting.

Further down in the R R result, port 4 really has a problem. The column before the ! shows 0 nodes sourced. That means the local node, SPHEN:KA4QRT-2, is not hearing the routing table "nodes" broadcast from K7QTH-2. Note that the percentage rate has been excellent. My guess in looking at this is that either SPHEN:KA4QRT-2 or K7QTH-2 suffered a catastrophic failure.

Catastrophic failed link: KA4QRT-2 ⇄ K7QTH-2

Here are some things to check:

See if K7QTH-2 shows on the MHL 4 list and how long ago K7TGH-2 was heard. This may be a clue if something 'interesting' happened around the last time the link was working.
See also G8BPQ M command.
Do mhl 4
That should result in a log of the callsigns heard on your link channel. The interesting callsign heard on your link channel would be your link neighbor dash two. K7QTH-2, in this case.
PATMH:K3PMH-2} Heard List for Port 1
TNC Feb 19 13:16:21 ← in the last few minutes
K7QTH-2 Feb 18 15:49:44 ← node-callsign - almost a day ago - important!
K7QTH-15 Feb 18 13:37:09 ← this callsign-15 is sent by the TARPNstat broadcast
Feb 17 07:06:53
K7QTH Feb 16 16:47:11
The results from mhl 4 show the local time (24 hour time) that you last heard each callsign.

Run QTtermTCP and make sure you are monitoring the channel for the link port you are investigating (port 4 in this case), with the Monitor options checked for Monitor Tx, Monitor Supervisory, Monitor Nodes Broadcast, Monitor the port in question, and uncheck Only Monitor UI Frames.
Tap the button on the NinoTNC.
Does the red Tx light come on?
Does QTtermTCP's top pane show message to CQBEEP? It should look like this:

16:19:50R KA4QRT-2>CQBEEP-5 Port=1 :
=FirmwareVr:3.42=SerialNmbr:=UptimeMilS:3606658C=BrdSwchMod:020A00A0=AX25RxPkts:00000000=IL2PRxPkts:000069C2=IL2PRxUnCr:00000000=TxPktCount:000076BB=PreamblCnt:00000005=LoopCycles:EAC45DF3=LostADCSmp:00000000

Can you tell from the transceiver if it transmits when the TNC button is pressed? Using a local HT or other radio tha can tune the link frequency, listen for your own transmission while you tap the red button on the NinoTNC.
If all that works, use QTtermTCP to send a test message. This will prove that the Raspberry PI still has access to the NinoTNC. Sometimes the USB driver in the Raspberry PI will forget a port. This is common when there is excess RF getting onto the USB cables.
Do C 4 !K7QRT-2
That should result in 20 messages on your link frequency. If the problem is one-way, i.e. your end is deaf, then K7QRT-2 should reply to the 20 messages, but your NinoTNC will not get the message. Listening on a radio could help you hear weak signals from the other end.

Your next move would be to contact K7QRT via other means and find out what is going on at the other end.

High Retries Link: KA4QRT-2 ⇄ K1QSY-2

Looking back at K1QSY-2. Connect across the link and see what the R R table on the other end shows.

MIKEY:K1QSY-2} Routes
> 1 KA4QRT-2  200   8! 806    4  2% 0 0 19:41  0 200
> 2 N8DDK-2   200   4!1221  170  7% 0 0 19:41  0 200

This shows us that the failure is directional. Either the transmission from SPHEN:KA4QRT-2 is too weak, has bad audio, or maybe MIKEY:K1QSY-2 has an incorrectly set receive volume level?

Even if the R R table shows a good link to one of your neighbors, you should obtain the performance results from the other end of the link periodically. One way to do this is to connect across to the neighbor and do the R R command from their end. In our current environment we can't tell the entire story about a link without looking at both ends, though if you have a radio and antenna that can hear both ends, you can do a pretty good analysis just listening to a busy channel.

R R on both ends of the link at the same time
Every 15 to 18 minutes, the TARPN software grabs the R R results on your node and, for each link, transmits the value to the neighbor in a [TARPNstat] beacon. Also on each node is a listener for the [TARPNstat] messages. When a [TARPNstat] is received, the node grabs the R R for that link and stores both the local and remote-end figures into a file in the Raspberry PI. As of this writing, that file is /usr/local/etc/tarpn_home_linkquality.dat.
TARPN HOME reads that file and creates a graphical chart for each link presented under the Info tab.
TRR (called from QTtermTCP or Node pane) also reads that file and performs an analysis of that file. An advantage of TRR is you can connect to any node in the network and run the command, to analyze the performance of the links on that remote node, where-as the INFO tab only works for your local node.
trr
Connected to TRR
date: Wed 18 Feb 16:42:10 EST 2026
TRR v113 Results are in sets of 3: recent, hour, and longest
port call | Tx Rate | Tx Retries | Rx Rate | Rx Retries
1 K1QSY-2| 7.2 8.9 6.7| 22% 41% 41%| 10.1 8.1 7.2| 16% 25% 14%
2 WD1QRS-2| 30.3 22.7 23.2| 0 0 0 | 25.9 20.5 24.4| 0 0 0
2 K2CC-2| 30.3 22.7 23.2| 1% 1% 1%| 25.9 20.5 24.4| 4% 3% 1%
3 K7QTH-2| 0.0 0.0 0.0|---- ---- ----| 0.0 0.0 0.0|---- ---- ----
Returned to Node SPHEN:KA4QRT-2

The TRR display shows 4 sets of 3-columns per line, each line associated with a port on the node.
The columns are organized as the latest-data, data for the last hour, data for the last several hours.
Taking the port 1 link to K1QSY-2 for an example, the first number in the first column of Tx Rate shows how many packets were sent per hour by the SPHEN:KA4QRT-2 node to K1QSY-2.
1 K1QSY-2| 7.2 8.9 6.7| 22% 41% 41%| 10.1 8.1 7.2| 16% 25% 14%
The second set of 3 numbers, Tx Retries, shows the retry rate associated with the packets counted in the first set.
1 K1QSY-2| 7.2 8.9 6.7| 22% 41% 41%| 10.1 8.1 7.2| 16% 25% 14%
Then the next set of 3 numbers is the received packet rate, followed by the received retries.
1 K1QSY-2| 7.2 8.9 6.7| 22% 41% 41%| 10.1 8.1 7.2| 16% 25% 14%
For K1QSY-2, this node sent 7.2 packets per hour counted over 15 minutes in the last 30 minutes. The data for the other end of the K1QSY-2 link is sent to SPHEN:KA4QRT-2 by K1QSY-2, every 15 minutes, in a [TARPNstat] message. Since you can do the TRR command at any time, we don't know how long it has been since the last 15 minute [TARPNstat] message.

Required for a good link

20db quieting - the stations must be strong to each other with no buzzing or clicking
transmit modulation just below saturation of the transmitter
transmitted signal must match the bandwidth of the receiver (commercial radio wide vs narrow mode setting can screw this up)
audio must be relatively flat. The high tone can actually be a very different volume than the low town, but only if the other characteristics are spectacular
If you are connecting into the Mic and Speaker connectors on the radio at one end of the link, you should probably be doing the same at the other end. The aggressive audio roll-off on the Mic circuit would mostly be matched by the audio recovery in the speaker circuit of the other end. If using the data connector on one end, make sure the radio on the other end also has a data connector. This isn't a showstopper, but it could make the difference between, for instance, 25 watts on each end vs 100 watts on each end
During any packet transmission, the modem tones must be audible at the receive TNC's modem before the important bits of the packet start. This can be foiled by a slow squelch or too-short TXdelay
Radio should have low audio distortion. Some radios will distort the data enough that 15% is the best rate we'll get with big packets

See also QTterm.
See also TNC and Radio Adjust and Test
See also Configure NinoTNC

Things that can hurt the link

Weak signal
too long a path or too much in the way
Local interference to the receiver on one end or the other
Bad radio on one end or both ends
In-band desense from another local transmitter
multipath
TxDelay is too short
FRACK is too short - causes FRMR and REJ errors visible in QTtermTCP
Receive audio level from the radio to the TNC is too high almost non-existant
Transmit level from TNC to radio is too high or too low
RFI (from one of your transmitters) affecting the modem
Receive squelch taking too long to open
Radio shutting off its receiver to save power
Automatic Gain Control messing up the modem (this was a problem affecting DireWolf)
radio off frequency
Wiring error
Not enough voltage during transmit
Radio turned off
Temperature affecting something
Hidden transmitter causing collisions
Hidden transmitter causing your receiver to start receiving a packet before the desired link starts
Some radios will distort the data enough that 15% is the best rate we'll get with big packets

The way packet radio links over FM behave at the receiver is disconcerting in that the digital link can be on the threshold of failure, yet to the node the link appears to behave perfectly. Then when they cross the threshold into failure, the link appears to fail completely, only to recover suddenly shortly after. This can happen on a several‑second cycle; or minutes; or hours; or entire seasons.
To a human brain this is akin to having a great big suspension bridge across a river be there one day, having it missing completely for a couple of hours the next day, then suddenly re-appear after lunch.
Well, we're talking about radio here. If this was voice radio, we'd be able to understand signals that were rough to hear but were still useable. They'd dip into being really rough once in a while. Being gone suddenly and completely for a short period is just not natural.
So.. when debugging a packet radio link, falling back to listening to the link with our ears is a good plan.

Steps to debug a link

Verify the routes and port numbers on each side.
With the receiver driving a speaker on one side, have the other transmit a signal. It should be full quieting. Repeat with the other direction.
Set up a monitor receiver to listen to both ends at the same time. The receive signal from the distant station need not be full quieting to the monitor receiver, you just have to be able to hear the entire packets from the other end.
Verify that the TXDELAY leaves an audible lead-in tone from each station to your monitor receiver. Set the TXDELAY long, just to make sure.
Run BPQterm on each end.
Set the transmit audio on each end such that the audio is not distorted on a receiver at the transmit site. Do this with tarpn linktest <portnum> while listening on a local receiver. To set the transmitter, turn on a receiver on that frequency and set the volume on the HT so you can hear it. Adjust the transmit level across its entire range and verify that you can tell the changes in transmit level on the HT. Set the transmitter TNC so it's transmit level is just below the maximum (from the HT's receive perspective) that you can set it to. There is a point in the transmit audio level control, where the level will top out and everything beyond that is "overdriving" which will just be distorted and useless at the receive end. Set the transmitter audio level control to just below the point where the level tops out.
Send packets from the transmit end, using Linux command tarpn linktest <portnum> . Alternatively you can connect over the radio to the other end and request stat.
If you are using a Mic/Speaker connector radio, you should open up the squelch all the way and then adjust the audio until the left-most light on the NinoTNC (labelled CRC) just barely flickers when no packet is being received.
Observe the TNC's Good Packet light. You'll want to see that light turn on for every packet you hear on the monitor receiver. Run QTtermTCP (g8bpq program installed on the Raspberry PI Desktop) and turn on monitoring. See the page under builders for QTtermTCP for configuration instructions.
Repeat on the other end
No receiver method: Observe the QTtermTCP monitoring the link. On the other end of the link start a transmit cycle connecting to a non-existant callsign, as above, but now observe the timing of the transmits. At the receive end watch for packets which do not show on the QTtermTCP by looking for gaps in the expected traffic. You should be able to listen to the other end transmit and know if there are any changes in the period between packets. Fine tune the receiver's volume knob to optimize until no packets are missed.
Repeat in the other direction
Connect to both ends of the link and grab the current numbers from R R for the link you are working on.
Now connect to the far end, connect back, connect out, back, out, back. Now do a stat command.
Listen to the exchanges and verify that there are no times of dead air until the stat is fully received at your end
Use QTtermTCP's monitor window to verify that every transmit has a response. See whose messages are being sent but not being received at the other end.
Observe the INFO-frames sent value vs the INFO-frames-retried value. Compare against the starting value. You can use these values from both ends and identify which side is having difficulty sending to the other.
There are still several things that can go wrong, including multi-path distortion. The clue that there is multipath is that the received signal from the other end of the link sounds distorted, but when listened to at the transmit end, is not distorted. Multipath can be caused by having a reflection which is as good as the direct path. It can be exacerbated by badly aimed directional antennas, or a major RF attenuator or hill directly in line between the two sites. Horizontal directional antennas are a good thing to combat multipath. If the antennas can't be moved or improved, the best thing to do is to change frequencies or even bands between the sites.
If you do get it to work well, set the TXDELAY down to where it the lead-in is noticeable but not finicky short and not tedious.

---

to be continued