tarpn_logo
 home    builders  

Packet Node Operator's manual

Document is under construction! -- March 2, 2015

Some material co-opted from John Wiseman, G8BPQ.
1Getting it to work
1aassumptions -- what you have for hardware
1binstructions
1creference manual -- same as 1b but sorted by topic
2Operating it
2aassumptions -- what you have for hardware
2binstructions
2cNode Commands Reference Manual
3Theory of operation
3aTheNET/G8BPQ nodes in general
3bLinux, raspberry PI, I2C, TNCs
3cDebug output - analyze G8BPQ operation
The linbpq node software which runs on the Raspberry PI can pass traffic through, or can serve as a command processor. When a station connects to the node the command processor delivers a prompt to the user, much like a Unix/Linux/MSDOS or CPM computer would. When a command is entered, the command processor interprets incoming commands and will either take action or will answer with a reply message, or it can take action and then answer with a reply message. Reply messages take the form of NODENAME:NODECALL-SSID} Answer

For example, if I connect to my own node via BPQtermTCP
*** Connected to switch
I can enter in a command of XYZ (an invalid command) and get back the answer
TADD:KA2DEW-2} Invalid command — Enter ? for command list

The list of valid commands includes commands that may only be handled after a password verification has taken place. There are some commands which have additional capability after password verification has been provided. Below is a complete list of commands. The table includes whether the command requires password or not, and what command group it is in. I will create a web page for each command group and explain the commands in that group including syntax and expected response.

"User" Commands -- no password required
Full command name Short description
? Requests list of commands
BYE Disconnect from this node.
CONNECT Connect from this node to some other station or node
INFO Requests text INFO file from node
L4T1 Requests the ISO-Level-4 Timeout #1 value. This is an init value and is always the same. Set globally for all nodes.
LINKS Requests information about current ax.25 sessions
MHEARD Monitor Heard -- Requests list of stations heard by the node on a particular port
NODES Requests a list of all nodes known by this node
NRR netrom route -- give with a destination node. This is like traceroute unix command. This sends a ping to a remote node and when it comes back, lists the path the ping took.
PACLEN Reads the packet length limit set in the node. I don't know why. Hint, it's 236
PASSWORDRequests access to password protected commands.
PORTS Requests list of ports (radios) configured for the node
ROUTES Requests list of neighbor nodes for this node
STATS Requests file of statistics for this node.
UNPROTO Enters UNPROTO mode, where you can send UI messages. The command format is UNPROTO Port CALL [Optional Digis]. When in Unproto Mode anything you type will be send as a UI frame to the port and destination you specified. This could be used in conjunction with the LISTEN command to have an multiuser conversation. Use Ctrl/Z to exit UNPROTO mode
USERS Requests list of stations connected into or through this node's command interpreter
 
"Password" Commands -- only if authenticated with PASSWORD.
Except as noted, none of these commands affect changes which are preserved through node restart.
Full command name Short description
BBSALIAS Reads or sets a port's acceptance of uplink connects to the BBS alias.
BBBSALIAS # reads a port's setting.
BBSALIAS # 1 sets the port to accept an uplink connecto to the BBS alias.
This would be useful in an HF BBS and we'd want to set this by default for the HF port.
As of oct 2019, this isn't a feature we've supported.
BTINTERVAL Beacon Text Interval, in minutes. This sets or reads the number of minutes between broadcasting the node's beacon text.
For a TARPN node, the beacon text contents are
callsign nodename http://tarpn.net ....................................................
DIGIFLAG Read or change the digipeat enable flag for one port.
digiflag port# to read. digiflag port# 0 to disable.
Not used in TARPN systems. Digipeat is always 0, meaning OFF.
If true, digipeat transmissions with this node's callsign or alias will be digipeated by this node, relaying out this port or another port enabled by digiport.
This is not used in TARPN systems and your author hasn't tested this feature.
DIGIPORT Read or change digipeater output enable flag for one port.
digiflag port# to read. digiflag port# 0 to disable.
If true, a digipeater packet to this node on any port will be emitted on this port.
This is not used in TARPN systems and your author hasn't tested this feature.
FRACK Queries or configures the Frame Acknowledge Timeout value for a port. This is in thirds of a second and indicates how long after a frame is sent before it will be retried if the acknowledgement has not been received.
Note that the units here and in the config files aren't the same!
FULLCTEXT I think this lets the operator read or change enable for sending connect text, by port
FULLDUP read or change enable for fullduplex, by port
HIDENODES Queries or enables the hide-nodes function which suppresses the display of NODES with an Alias that starts with a # sign. This was used on networks where TheNET nodes are also present. With TheNET nodes, only nodes which faced services or zoo channels had "visible" node names. Others had # in the first character.
IDINTERVAL read or change the automatic ID interval (in minutes) for all ports
L3ONLY Queries or sets the L3-only flag for a specified port.
L3TTL Sets or reads the node's L3 Time To Live. This number sets how many hops a packet can go before it is trashed.
L4DELAY Sets or reads the node's L4 Delay timer initilization. The L4 Delay is how long a node waits to send an acknowledgement for L4 packet addressed to that node. I presume the point of this is that acknowledgements for more than one L4 packet could be returned at the same time?
An L4 packet is one addressed from one network node to another, through the network. Packets sent through the network are acknowledged link by link, but also end to end. You can watch this process using BPQterm if you have 3 or more nodes in your network.
L4RETRIES Sets or reads the L4 retry limit for the node. If an L4 packet is sent across the network from this node, and the acknowledgement doesn't make it back before the timeout, this is how many times we can resend it.
L4TIMEOUT Sets or reads the L4 retry limit for the node. After an L4 packet is sent from this node over to some other network node, this is how many seconds the node will wait before deciding it is lost.
L4WINDOW Sets or reads the L4 window size for the node. If a connection is made from this node out to another network node, messages can be sent from here to there. Each message will be acknowledged and then another can be sent. L4 window-size decides how many messages this node can send to the distant node, for a given connection, before we must wait for the acknowledgements to come back. A larger L4 window allows a single connection to take more network resources. If the path has any chance of failure, a larger L4 window will waste resources. A smaller L4 window will result in an artificial slow-down of the traffic, especially if the network is lightly loaded.
LINKEDFLAG Sets or reads some number for the node. I think the number this value reads is decimal representation of an ASCII 'A'.
The value looks like it was used to decide of a BBS would accept a connection via a KA-NODE. In the source code this doesn't look like it is affective anymore. Dunno..
MAXFRAME Read or change number of packets sent in one transmission for one port.
maxframe port# to read. maxframe port# 4 to set to 4.
The default for 1200 baud TARPN ports is 1, meaning one transmission for one packet.
For faster modems, this might be set higher.
The good reason to keep this a small number is to limit the latency for packets crossing through this node.
If WEST is transmitting 7 packets in a row @ 1200bps, EAST has to wait up to 20 seconds before it's packet gets to go over the link.
The reason to set this to a higher number for faster bps modems is that transmit to receive to transmit switching time, can consume some of the channel time and the more bits are sent between tx/rx/tx switches, the more efficient the link will be.
MAXUSERS needs-description
MINQUAL Sets or reads the node's minimum-quality figure.
The node broadcast goes out according to a schedule. When the node broadcast is to be generated, the node gathers a list of all of the network node-callsigns and associated node-aliases it knows about which are above a certain quality level. The quality level listed for each node is based on the incoming node broadcast multipled by the link quality divided by 256.
When compiling the node broadcast, only those nodes whose resultant listed quality level is above the minimum-quality figure are included.
You can get the listed quality value for a network node by using the n nodename command.
NODEIDLETIME needs-description
NODESINT needs-description
OBSINIT Sets or reads the node's obsolescence initialization figure.
This figure is the initialization value for the obsolescence counter which counts how long it has been since the node received an update about a route back to a particular foreign-node.
Each time this node receives a node-broadcast from a link neighbor, it applies this figure to every foreign-node the link neighbor tells it about, attached to the route back to the foreign node which would pass through the neighbor.
Each time this node does it's own node-broadcast, it decrements the obsolescence figure for every foreign-node this node knows about.
When any obsolescence count reaches 0 (meaning we haven't heard a neighbor broadcast for that route), this node will delete the route back to the neighbor for the foreign-node.
OBSMIN Sets or reads the obsolescence minimum figure for the node.
This value is how low the obsolescence count can be for a particular foreign node in order for that foreign node to be included in this node's node-broadcast.
The foreign node, and the known routes back to it, will stay until the obsolescence count reaches 0, but this node doesn't tell it's neighbors about the foreign node if the obsolscence count falls below this minimum.
PERSIST Queries or changes the PPERSIST value for a single port. This command is invalid for TNC-PI and some other KISS TNCs because the PPERSIST value is set on the TNC where the node software can't read or write it.
PPACLEN reads or sets a port's maximum packet length. This value might, or might not, include callsigns and other overhead. Defaults to 236 in the tarpn boilerplate.
Use with port# to read, or port# and new value to set.
QUALITY Use with port#. Reads or sets the default route quality for unknown node whose node-broadcast is heard.
REBOOT Instructs the node software to quit immediately. On a TARPN node this triggers a rebuild of the configuration. This is handy if a global node configuration change is made since a rebuild can load the changes over the Internet.
RECONFIG no clue. Anybody know?
REMDUMP no clue. Anybody know?
RESPTIME Queries or configures the response-time for an individual port.
RESTART Send with a numeric parameter. This appears to reboot the Raspberry PI. I don't know how they do that. It wasn't well documented.
RETRIES Queries or configures the number of retries for a failed message for an individual port.
SAVENODES Tells the software to save the current nodes-list immediately for use next time the node software starts, i.e. after KILL or REBOOT. This is handy if the node-broadcast interval is long and the network rarely changes configuration.
SENDNODES Tells the node to send a nodes broadcast on each port. The send-nodes takes a few seconds to start.
SOFTDCD no clue. Anybody know?
STARTPORT This looks like it resumes parameter updates to a KISS port. startport port#
Your author hasn't tested this feature.
STOPPORT According to g8bpq, this makes a port available for another application. stopport port#
Your author hasn't tested this feature.
T3 This may have something to do with L2 Slot Time (clue from the g8bpq source code). This command sets or reads a value for the whole node. On my node it said 540. I set it to 2. Then back to 540. Dunno.
TXDELAY This sets or reads the txdelay for a single port.
This value is not affective on TNC-PI if they are configured as per the TARPN documentation.
On a KISS TNC this value sets how long the modem generates flags before sending real data.
You need this delay to be long enough so the transmitter is well and truly on before real data is sent.
The units for this control are poorly defined AND different than what is in the g8bpq config file.
TXTAIL This sets or reads the txtail for a single port.
This value is not affective on TNC-PI if they are configured as per the TARPN documentation.
On a KISS TNC this value sets how long the transmitter is left on after the modem is done sending its packet.
You need this delay to be long enough so the modem can finish sending the packet. The reason for this is that the TNC may be done loading the last transmit byte, and will unkey immediately if we let it. But, the radio may still take some time to get the audio out to the antenna. Leaving the radio keyed for a short bit is sometimes required, depending on the radio and the TNC. This command lets you impose a new delay, different than the defaults in the node configuration. I don't know the units. This is usually left at a value of 1.
The units for this control nat be poorly defined AND different than what is in the g8bpq config file.
VALIDCALL needs-description
XMITOFF Read or change the transmitter DISABLE flag for one port..
xmitoff port# to read. xmitoff port# 1 to disable a port.
The default is 0, meaning the transmitter not stopped.

From the G8BPQ documentation

Port Params

TXDELAY
MAXFRAME
FRACK
RESPTIME
PPACLEN
RETRIES
QUALITY
PERSIST
TXTAIL
XMITOFF
DIGIFLAG
DIGIPORT
MAXUSERS
VALIDCALL
L3ONLY
BBSALIAS
FULLDUP
SOFTDCD

The above display or update the corresponding parameter for a specified port,

eg PACLEN 1 100 PERSIST 2 50

If the third parameter is omitted, the current value is displayed.

It is not currently possible to update VALIDCALLS, but you can display the current setting.

*** Warning ***

At the moment the FRACK value is in 1/3sec units, and the TXDELAY is in 50ms units for HDLC cards, and 10ms units for KISS TNCs. I'll be sorting this out when I get the time to rationalize the timer code, but in the meantime, I suggest you make a note of the current values before you start fiddling.

Also KISS users should note that the params are only sent to the TNC every 5 mins or so, so the updated values may not take effect for a while.

System Params

REMDUMP
OBSINIT
OBSMIN
NODESINT
L3TTL
L4RETRIES
L4TIMEOUT
T3
NODEIDLETIME
LINKEDFLAG
IDINTERVAL
MINQUAL
FULLCTEXT
HIDENODES
L4DELAY
L4WINDOW
BTINTERVAL

The above display or update the corresponding Node parameter.

System Commands

SAVENODES
SENDNODES
RECONFIG
REBOOT

ROUTES

To update an entry, enter ROUTES Call Port Params

eg ROUTES G8BPQ-2 2 100 - Set quality to 100
ROUTES G8BPQ-2 2 ! - Toggle 'Locked Route' flag
ROUTES G8BPQ-2 2 100 ! - Set quality and toggle 'locked' flag

STOPPORT n
STARTPORT n

Close or reopen Port n (which must be a KISS Port). Enables another program to use the port to allow the tnc to be reconfigured without closing the node

© Tadd Torborg, 2014, 2015 -- all rights reserved