README

• Introduction
• Updating from previous versions of thelinkbox
• Portability
• Building on a *nix:
  • Requirements:
• thelinkbox Configuration
• Determining physical USB Addresses
• Testing
• Installation
• Commands
• Bugs/Features/known limitations
• Thanks
• How you can help

Introduction

Support: https://groups.io/g/thelinkbox/topics

Thelinkbox is an voice over IP (VoIP) radio linking package for ham radio operators that runs under FreeBSD and Linux, and hopefully other Posix compatible operating systems. It does not and probably never will run under Windows.

Thelinkbox is basically thebridge conferencing software with additional code to interface to radios. Although the primary purpose is for VoIP linking of a limited number of repeaters "off grid", i.e. separate from the EchoLink and IRLP networks it can also be used on the Echolink or IRLP networks when properly configurated.

Unlike some other VoIP systems thelinkbox also supports multiple radio ports. The ultimate goal is for thelinkbox to become a full featured multiport hub or repeater controller as well as a VoIP application. I believe the use of USB audio dongles under Linux will allow a modern PC to support a larger number of radio ports than are likely to be needed by even the largest repeater groups (> 16 ports), although I have yet to test the limit in practice.

Here are some features:

1. Support for multiple simultaneous connections using different codecs and protocols. Currently tlb supports ADPCM and GSM codecs and the Echolink, RTP, and Speak freely protocols. When multiple sources are active the audio is mixed.

2. The number of VoIP connections is limited only by system RAM and available bandwidth.

3. The number of physical radio ports is limited only by available hardware, OS hardware support and CPU processing power.

4. All ports are completely independent: Each port may have a unique set of DTMF commands. Each port can be connected to a distinct VoIP clients.

5. A full cross point matrix of connections between VoIP clients and RF ports is supported.

6. Does not require the use of a central server or authentication authority, all that is required is internet connectivity.

7. Support for either prerecorded PCM audio announcements or external text to speech systems such as Festival.

8. CW and voice IDs.

9. Flexible general purpose telemetry tone generator that can be assigned to various events and/or used by scripts.

10. "Permanent" connections, if a link is lost tlb will keep trying to reconnect indefinitely.

11. Builtin software based DTMF and CTCSS encoders and decoders.

12. Open source software written in C and C++.

13. Support for inexpensive USB audio dongles including PTT, COS and CTCSS sense and frequency control.

Updating from previous versions of thelinkbox

New versions of thelinkbox are usually backwards compatible with configuration files from earlier releases HOWEVER new configuration file variables are added frequently. Since the sample tlb.conf.sample file includes documentation on features which are not mentioned elsewhere it is worthwhile to review the sample configuration file with each release to discover new capabilities which you may want to take advantage of.

Portability

A quick word on portability: I've tried to the best of my ability and means to make thelinkbox as portable as possible. I've tested it under several versions of FreeBSD and Linux, however ALL testing has been on the Intel x86 architecture.

I've found that sound programming on Linux platforms can be very problematic.
Results are very dependent on the sound board and its driver. At least 50% of the sounds cards I've tested with had some issues that required special workarounds such as extra driver options. Additionally for portability thelinkbox uses the OSS sound system API supported by many platforms, not the Linux specific ALSA sounds system. Luckily the ALSA sound system includes an emulated OSS API for backwards compatibility.

At this time the USB subsystem is Linux specific. I tried to make the USB code portable by using libusb but I've run into a show stopper on FreeBSD, namely if the USB audio device is claimed by the kernel's audio driver then libusb is unable to access the device.

Building on a *nix:

Executive summary: (the usual)

"tar xzf thelinkbox-{VERSION}.tgz"
"cd thelinkbox-{VERSION}"
"./bootstrap.sh
"./configure" (or "./configure --enable-usb")
"make"
<edit the configuration files>
<test>
"make install"
<start the daemon>

Requirements:

The only known requirement to build thelinkbox is the GNU GCC C compiler, the GNU GPP C++ compiler or something compatible, a make program and a Bourne shell to run the configure script. GNU make is not required, any old make should be fine. I tried to avoid the use of exotic compiler features, hopefully any version of GCC will work.

On Debian, and perhaps other distributions:

apt-get update
apt-get install build-essential automake

If for some reason either configure or the make should fail please send me the details and I'll try to help you correct the problem.

Extract: The distribution tar file extracts into a version specific subdirectory so different releases do not conflict with each other. Substitute the actual version number for "{VERSION}" above. The ".tgz" extension signifies a Gzip'ed TAR file.

GNU configure: Thelinkbox uses a GNU autoconfig generated configuration script to generate a site-specific Makefile that is then used to build thelinkbox. The configuration script is written to be as portable as possible by only assuming the availability of the most generic Bourne shell features. A suitable shell should be available on just about every *nix system. It will certainly be available on any system using other GNU tools.

The configuration script provides a great deal of flexibility in the way the target program is built and installed, run "./configure --help" for the gory details. Luckily most of the features are seldom needed and running configure without any options is usually sufficient.

If you want to use an USB audio dongle for an interface specify the --enable-usb option when you run configure. In this case will need to have the libusb and it's header files installed on your system.

If you have the GNU readline library (libreadline) you can configure to tlbcmd to use it by specifing the --with-readline switch. The readline library adds features such as command history and curses based line editing tlbcmd and tlbchat.

Once the configure script has been run you should have a config.h and Makefile appropriate for your system.

Make: The generated makefile provides several useful targets, the default "all" builds thelinkbox and utilities. The other frequently used targets include "install", "clean", "distclean", and "uninstall".

There shouldn't be any errors or warnings displayed during the build process for the core source files. I've included several open source libraries with thelinkbox to try to prevent "dependency hell", some of those libraries generate warnings. If you get warnings or errors in the core source files I'd be interested in hearing about them.

The final output of the build process is the thelinkbox daemon "tlb" which is built in the linkbox subdirectory. We'll test it before installing it.
Before we test it we need to edit the configuration files.

thelinkbox Configuration

A least two text files "tlb.conf" and "tlb.cmds" that are needed to configure thelinkbox. The first file can contain all of the configuration necessary other than the mapping of DTMF digits to actions that are taken when the DTMF digits are received. The second file contains the mapping of DTMF digits to commands.

The port configuration can be included in the main file if desired, but it's probably cleaner and less confusing to have one configuration file per port. The port configuration files are then included from the main configuration file by use of the "include" directive.

The files files "tlb.conf.sample" and "tlb.cmds.sample" are provided as a starting point for your configuration files. Since the sample files include documentation on features that are not mentioned elsewhere it is worthwhile to review the sample configuration file with each release to discover new capabilities which you may want to take advantage of.

There are sample port configuration files for compatible interfaces included in the release, just make N copies of that file that matches the type of interface you will be using and them modify them as needed.

Fire up your favorite editor and change the various variables to appropriate values. Refer to the comments in the file for guidance.

cd /usr/local/etc
cp tlb.conf.sample tlb.conf
cp tlb.cmds.sample tlb.cmds
cp iMic.conf.sample Port1.conf
vi tlb.conf
vi tlb.cmds
vi Port1.conf
cp irlp.conf.sample Port2.conf
vi Port2.conf
cp cm108.conf.sample Port3.conf
vi Port3.conf

Lines beginning with ';' or '#' are comments, if you decide to set any of the optional settings be sure to delete leading ';' character before the configuration variable.

Since daemons are not connected to any console they must communicate with the sysop in some other manner. As with most *nix daemons thelinkbox can use the syslog system. Thelinkbox uses "LOG_LOCAL5" as the facility when opening the log and generates messages with priorities LOG_INFO, LOG_WARNING and LOG_ERR. It's up to the user to decide which message if any he wants to log, but unless you are a psychic I would strongly suggest that at least the LOG_ERR messages be logged.

Thelink box can also generate a local log file without using the syslog system. This has many advantages and is the recommended method. The configuration file variable LogFileRolloverType controls the logging method.

Determining physical USB Addresses

If you are not using multiple USB audio dongles you can safely ignore this section.

Since most USB audio dongles do not have a unique serial numbers we must resort to configuring thelinkbox using physical USB addresses. This means the physical port on the PC or USB hub that the USB audio dongle is plugged into determines the configuration address. Unfortunately it is not easy to determine this address without more documentation than is usually available for PCs. Even if documentation were available determining the correct address would be tedious and error prone.

Luckily there's an easier way!

1. Configure thelinkbox for a single USB port. Do no specify either AudioDongleSN or AudioDongleAdr.

2. Connect a compatible dongle to ONE port you wish to use. It's easy for the linkbox to find the port to use when there's only one dongle by searching all USB buses until a device is found.

3. Start thelinkbox in debug mode. Hopefully thelinkbox will find the dongle and display it's address. Make a note of the address displayed. A sticky label next to the port might be a good idea.

   [root@localhost ~]# /root/tlb -d -f /home/skip/tbd/tbd.conf.440 thelinkbox Version 0.13 compiled Dec 14 2007 16:24:36 16:40:07 thelinkbox V 0.13 compiled Dec 14 2007 16:24:36 initializing 16:40:07 EndPointInit: Initializing 440 port (0) 16:40:07 EndPointInit: called, TxKeyMethod: 5, RxCosMethod: 6 16:40:07 UsbInit: found USB device @ 1-1.2 16:40:07 UsbInit: USB audio device for 440 is /dev/dsp2 16:40:07 UsbInit: Changing audio device from auto to /dev/dsp2 16:40:07 FindDevByAdr: event device for "1-1.2" is /dev/input/event3 16:40:07 Fragsize: 256, fragstotal: 5, bytes: 1280 16:40:07 EndPointInit: returning 0

In this example the AudioDongleAdr that was discovered is 1-1.2.

4. Hit control C to shutdown thelinkbox.

5. Disconnect the dongle from the port just found and move it to the next port. Repeat steps 3 to 5 until the addresses for all of the ports that will be used have been determined.

6. Configure thelinkbox for multiple ports specifying the addresses found for AudioDongleAdr.

Testing

The daemon has two command line switches to aid testing. The first switch -f specifies where the tlb.conf configuration is located.

The second switch -d enables debug mode, causing the daemon to run in the foreground as a user process while displaying debug information on the screen. The debug switch may be used multiple times to increase the detail level of the information displayed up to a maximum of three times.

For our purposes a single -d suffices.

[root@localhost ~]# /root/tlb -d -f /home/skip/tbd/tbd.conf.440
thelinkbox Version 0.33 compiled May 14 2008 16:31:19
6:45:49 thelinkbox V 0.33 compiled May 14 2008 16:31:19 initializing
6:45:49 EndPointInit: Initializing 440 port
6:45:49 EndPointInit: called, TxKeyMethod: 5, RxCosMethod: 6
6:45:49 UsbInit: found USB device "440" @ 1-2.2
6:45:49 UsbInit: USB audio device for 440 is /dev/dsp2
6:45:49 UsbInit: Changing audio device from auto to /dev/dsp2
6:45:49 FindInputDevBySn: event device for "440" is /dev/input/event3
6:45:49 AudioInit#1586: opening "/dev/dsp2"
6:45:49 Fragsize: 256, fragstotal: 5, bytes: 1280
6:45:49 EndPointInit: returning 0
GenAVRS(): sending string:
)EL-wb6ymh!3345.88NE11820.19W0PHG8660/449220/131 On  @0645
PullerLoginAck(): Client 8 successfully updated status.
6:45:50 Msg from EchoLink: EchoLink Server v2.5.996
6:45:50 Msg from EchoLink:
6:45:50 Msg from EchoLink: ECHO4: Scottsdale, AZ USA
Full station list downloaded successfully, 8166 stations listed.

The message beginning with "PullerLoginAck():" indicates that the daemon was successful in logging into the EchoLink directory server.

The last message is the real good news, our directory request returned 7904 stations. If your callsign or password were not recognized no stations would be listed and you would see an error message from EchoLink simular to the following:

6:47:01 Msg from EchoLink: INCORRECT PASSWORD
6:47:01 Msg from EchoLink:
6:47:01 Msg from EchoLink: Please check the password
6:47:01 Msg from EchoLink: and try again. If you have
6:47:01 Msg from EchoLink: forgotten it, see the Validation
6:47:01 Msg from EchoLink: section at www.echolink.org.
Full station list downloaded successfully, 0 stations listed.

If you are not able to get a station list, check your callsign and password in the configuration file. You might also want to rerun the test using more "-d" switches to help determine what when wrong.

NB: thelinkbox makes NO attempt to control the sound card's mixer. You'll need to set levels manually with the mixer utility of your choice.

To test run thelinkbox in debug mode "linkbox/tlb -d -f tlb.conf". Log messages will be displayed on the console. Key a radio and hopefully you'll see "COS detected". Press some touchtone buttons and hopefully you'll also see them displayed.

[root@localhost ~]# /root/tlb -d -f /home/skip/tbd/tbd.conf.440
thelinkbox Version 0.13 compiled Dec 14 2007 16:24:36
16:48:41 thelinkbox V 0.13 compiled Dec 14 2007 16:24:36 initializing
16:48:41 EndPointInit: Initializing 440 port (0)
16:48:41 EndPointInit: called, TxKeyMethod: 5, RxCosMethod: 6
16:48:41 UsbInit: found USB device @ 1-1.2
16:48:41 UsbInit: USB audio device for 440 is /dev/dsp2
16:48:41 UsbInit: Changing audio device from auto to /dev/dsp2
16:48:41 FindDevByAdr: event device for "1-1.2" is /dev/input/event3
16:48:41 Fragsize: 256, fragstotal: 5, bytes: 1280
16:48:41 EndPointInit: returning 0
GenAVRS(): sending string:
)EL-wb6ymh!3345.88NE11820.19W0PHG8660/449220/131 On  @1648
PullerLoginAck(): Client 6 successfully updated status.
Full station list downloaded successfully, 7910 stations listed.
PollCOS: Node 440 COS active
PollCOS: Node 440 COS inactive
16:48:47 DecodeDTMF: Decoding "123"
16:48:47 RF user executing command "say I'm sorry dave I can't do that"

[much more to come ... stay tuned!]

Installation

Thelinkbox is designed to run as a system daemon, i.e. a background program that's loaded automatically by the system as part of the bootup process.

If you are not familiar with the system startup scripts or you are not comfortable starting thelinkbox automatically you can always start thelinkbox daemon manually when desired. Starting thelinkbox automatically is primarily needed when the host is unattended and it is desired to run thelinkbox 24/7. Refer to the "Running without Root access" section if you would rather not modify your system's startup behavior.

Unfortunately my installation rules and knowledge are not complete enough about all of the various *nix variations to complete the installation without manual assistance.

Most Posix operating systems start system daemons using approaches similar to either FreeBSD (i.e. the BSD camp) or RedHat (i.e. the System V camp). Scripts to install thelinkbox on FreeBSD, RedHat and Debian Linux have been provided. Start with the scripts that are the closest match to your system and then modify them if necessary. I will be happy to include installation scripts for other operating system that are sent to me with future releases.

Configuration files for daemons are kept in different places on different systems. It doesn't really matter where the configuration file is as long as tlb can find it. If you want to put it somewhere other than where the GNU autoconf tools think it belongs just specify the full configuration file path on the command line using the -f switch.

FreeBSD

Local (not part of the standard distribution) daemons on FreeBSD systems are started by placing a shell script /usr/local/etc/rc.d directory with an ".sh" extension. During startup each script is called with an argument of "start". During system shutdown they are called again with an argument of "stop".

If you are running on FreeBSD run the installation scripts from the FreeBSD subdirectory. The installation script will copy tlb, tlb.conf.sample and tlb.sh into the appropriate subdirectories. You will need to be root to when running the installation script.

%cd FreeBSD
%su
Password:
fastbsd# ./install
+ cd ..
+ make install
Making install in src
/bin/sh ../config/mkinstalldirs /usr/local/libexec
/usr/bin/install -c  tlb /usr/local/libexec/tlb
/bin/sh ./config/mkinstalldirs /usr/local/etc
/usr/bin/install -c -m 644 ./tlb.conf.sample /usr/local/etc/tlb.conf.sample
+ cd FreeBSD
+ cp tlb.sh /usr/local/etc/rc.d
fastbsd# 

Since the installation process only copies tlb.conf.sample (to prevent accidents when thelinkbox is updated in the future) we must manually copy our configuration file to the "standard place":

$ cp tlb.conf /usr/local/etc

Debian Linux

If you are running on Debian Linux run the installation scripts from the Debian subdirectory. The installation script will copy the tlb executable, tlb.conf.sample, and tlb shell scripts into the appropriate subdirectories.
It will then create links from /etc/init.d/ subdirectories the tlb shell script to start tlb in run levels 2, 3, 4 and 5 and to stop tlb in run levels 0, 1 and 6. You will need to be root to when running the installation script.

$ su
Password: 
[root@linux Debian]# cd Debian
[root@linux Debian]# ./install
+ cd ..
+ make install
Making install in src
make[1]: Entering directory `/home/skip/thelinkbox-0.10/src'
make[2]: Entering directory `/home/skip/thelinkbox-0.10/src'
/bin/sh ../config/mkinstalldirs /usr/local/libexec
/usr/bin/install -c  tlb /usr/local/libexec/tlb
make[2]: Nothing to be done for `install-data-am'.
make[2]: Leaving directory `/home/skip/thelinkbox-0.10/src'
make[1]: Leaving directory `/home/skip/thelinkbox-0.10/src'
make[1]: Entering directory `/home/skip/thelinkbox-0.10'
make[2]: Entering directory `/home/skip/thelinkbox-0.10'
/bin/sh ./config/mkinstalldirs /usr/local/etc
/usr/bin/install -c -m 644 ./tlb.conf.sample /usr/local/etc/tlb.conf.sample
make[2]: Nothing to be done for `install-data-am'.
make[2]: Leaving directory `/home/skip/thelinkbox-0.10'
make[1]: Leaving directory `/home/skip/thelinkbox-0.10'
+ cd Debian
+ ln -s /usr/local/libexec/tlb /usr/sbin
+ cp tlb /etc/init.d
+ update-rc.d tlb defaults
[root@linux Debian]# exit
$

Since the installation process only copies tlb.conf.sample (to prevent accidents when thelinkbox is updated in the future) we must manually copy or configuration file to the "standard place":

$ cp tlb.conf /usr/local/etc

RedHat Linux

If you are running on RedHat Linux run the installation scripts from the RedHat subdirectory. The installation script will copy the tlb executable, tlb.conf.sample, and tlb shell scripts into the appropriate subdirectories.
It will then create links from /etc/rc.d/rc*.d subdirectories the /etc/rc.d/init.d/tlb shell script to start tlb in run levels 2, 3, 4 and 5 and to stop tlb in run levels 0, 1 and 6. You will need to be root to when running the installation script.

$ su
Password: 
[root@linux73 RedHat]# ./install
+ cd ..
+ make install
Making install in src
make[1]: Entering directory `/home/skip/thelinkbox-0.10/src'
make[2]: Entering directory `/home/skip/thelinkbox-0.10/src'
/bin/sh ../config/mkinstalldirs /usr/local/libexec
/usr/bin/install -c  tlb /usr/local/libexec/tlb
make[2]: Nothing to be done for `install-data-am'.
make[2]: Leaving directory `/home/skip/thelinkbox-0.10/src'
make[1]: Leaving directory `/home/skip/thelinkbox-0.10/src'
make[1]: Entering directory `/home/skip/thelinkbox-0.10'
make[2]: Entering directory `/home/skip/thelinkbox-0.10'
/bin/sh ./config/mkinstalldirs /usr/local/etc
/usr/bin/install -c -m 644 ./tlb.conf.sample /usr/local/etc/tlb.conf.sample
make[2]: Nothing to be done for `install-data-am'.
make[2]: Leaving directory `/home/skip/thelinkbox-0.10'
make[1]: Leaving directory `/home/skip/thelinkbox-0.10'
+ cd RedHat
+ ln -s /usr/local/libexec/tlb /usr/sbin
+ '[' '!' -d /etc/rc.d/init.d ']'
+ cp tlb /etc/rc.d/init.d
+ ln -s /etc/rc.d/init.d/tlb /etc/rc.d/rc0.d/K73tlb
+ ln -s /etc/rc.d/init.d/tlb /etc/rc.d/rc1.d/K73tlb
+ ln -s /etc/rc.d/init.d/tlb /etc/rc.d/rc2.d/S73tlb
+ ln -s /etc/rc.d/init.d/tlb /etc/rc.d/rc3.d/S73tlb
+ ln -s /etc/rc.d/init.d/tlb /etc/rc.d/rc4.d/S73tlb
+ ln -s /etc/rc.d/init.d/tlb /etc/rc.d/rc5.d/S73tlb
+ ln -s /etc/rc.d/init.d/tlb /etc/rc.d/rc6.d/K73tlb
[root@linux73 RedHat]# exit
$

Since the installation process only copies tlb.conf.sample (to prevent accidents when thelinkbox is updated in the future) we must manually copy or configuration file to the "standard place":

$ cp tlb.conf /usr/local/etc

Commands

Since thelinkbox is based on thebridge conference server all of the command for thebridge are also available on thelinkbox. Please see the Command section in the documentation for thebridge (README.tbd) for details.

A few commands are unique to thelinkbox, only those commands are documented here. Most commands are applied to the current port which is selected by setting the port. (.port 2).

dtmfdecode <command>

The .dtmfdecode command allows a specified command to be interpreted as if it were entered by the RF user.

.id

The .id command forces the nodes ID to be sent.

.link [-m] [-p] <destination> [<source> ...]

The link command is used to connect nodes (RF ports and VoIP connections) together. Each linkage is bidirectional unless the -m (monitor) switch is used. For example if the system is a remote base and port "440" is it's input and port "144" is the remote 2 meter radio the command ".link -m 440 144" would put the remote base into 2 meter monitor mode. i.e. traffic on 2 meters would be repeated to 440, but traffic on 440 would not be repeated to 2 meters. The command ".link 440 144" would put the remote base into 2 meter transceive.

The -p command line switch specifies a permanent link. Permanent links are not unlinked by .unlink all, .unlink rf, .unlink voip, or .unlink commands. The link can only be removed by an explicit .unlink command that specifies both ports.

The link command can also be used to link VoIP connections to RF ports. For example to link an EXISTING VoIP connection from W1AW to the "440" port: .link w1aw 440 (or .link 440 w1aw). VoIP connections are created when a remote node connects to our node or by use of the .connect command.

.link

To generate a list of current port linkages run the .link command without arguments.

.users [-b] [-c] [-q] [-t] [-T] [-v] [?]

The .users command lists the callsign of all VoIP connections order of login along with their attributes. This command is particularly useful for net control operators by enabling them to see more stations than will fit in the EchoLink client's info window.

The meaning of the attribute characters may be display by the ".user ?" command. They are as follows:

User attributes:
0 - User is usign the Speak Freely protocol
1 - User is using the RTP protocol
A - User is logged in as an administrator.
a - User is using the  ADCPM codec
B - User is running theBridge conference or thelinkbox.
C - User is a linked conference other than thebridge.
c - User's chat text is been suppressed
F - User is playing a file (using the .play or .test commands).
f - User is Full duplex
I - User is Isolated (not In conference)
K - User's has been Kicked (being disconnected).
L - User is a Lurker.
m - User's audio is muted.
M - User's audio and text are muted.
P - User is a permanent connection (connected by a .connect command).
R - User is in Receive only mode (being monitored)
S - User is logged in as a sysop.
T - User is currently Talking.
u - User is running the uLaw codec
x - User connection is inactive
! - User is an old version of thebridge which sent SDES packets containing 
a private "txt" extension field.

The -b (bare) switch suppresses the display of user attributes. The -c switch displays the amount of time the user has been connected. The -q switch suppresses logging of the .user command. This is useful when the .user command is used by AJAX scripts to prevent the log from being filled with less than interesting information. The -t switch displays the amount of time since user last transmitted. The -T switch sorts the user list by time since last transmission. The -s switch displays the user list in the same format as is presented to EchoLink users on the right hand side of their client. The -v switch displays the version number of user's client

.unlink all
.unlink rf
.unlink voip
.unlink <destination> [<source>...]

The unlink command is (much a you might expect) the reverse of the .link command, it desolves links established with the .link command. The "all" argument removes all links between both ports and VoIP connections.
The "rf" argument removes all links between RF ports, but leaves links between ports and Voip connections intact. The "voip" argument removes all links between ports and Voip connects, but leaves links between ports intact. If the argument is a single node name then all links to that node are desolved. Finally specific links can be desolved by specifing both the destination and source names.

.pcm record <test point>
.pcm close <test point>
.pcm

The .pcm command allows raw PCM data from various points in the signal path for the current port to be saved to disk. This command is primarily an debug aid. When the .pcm command is run without arguments a list of available test points is displayed.

.rxlevel
.rxlevel -c
.rxlevel -q

The .rxlevel command to displays received audio level statistics from physical ports or VoIP connections. This command displays the value of the minimum and maximum samples, the running total, the RMS level and the number of samples that were monitored. The values are cleared after each .rxlevel command and then new values are accumlated for about one second.
The -c switch enables a continous display of levels several times a second until another .rxlevel command is entered. The -q switch suppresses the column header line. For example:

tlb> .rxlevel
Min     Max     Total   RMS     Samples
-8230   7167    -46     4256    512

The maximum possible value for 16 bit sound cards is 32767, the minimum value is -32768. There is no formal standard value for "full modulation", but examining the reference IRLP and EchoLink audio recordings shows that peak "modulation" is about 80% of full scale or about +/-26000.

.script <path>

The .script command allows any program or script to be executed.
This command is only available for use by the DTMF command parser.
This provides a very powerful way to extend the functionality of thelinkbox by the addition of user programs.

.sendbeacon [-a] [-x]

The .sendbeacon command is used to send an AX25 broadcast packet or an update to the APRS-IS system.

The -x switch (the default if no switch is specified) sends an AX25 broadcast packet to the selected port. The contents of the packet are defined by the port's Ax25BeaconPath, Ax25BeaconText, and Ax25BeaconAPRS configuration variables. The beacon can also be sent automatically by setting the port's Ax25BeaconInterval variable. Automatic beacons sent when Ax25BeaconInterval expires are only sent when there is no other activity on the transmitter and it will not cause the transmitter to keyup. In other words automatic beacons are sent at the end of the transmitter's hangtime just before the transmitter would have been unkeyed.

The -a switch forces an status update to be sent to the APRS-IS system if APRS-IS support is enabled.

.shutup

The .shutup command kills any announcements for the RF user that are queued.

.say [-c] [-s] <text phrase>
.say [-c] <wavefile>

The .say command generates audio for the currently selected port. If thelinkbox has been configured to use an external voice synthesizer then any text phrase is may be used. If the linkbox is not configured to use a voice synthesizer then thelinkbox attempts to find prerecorded PCM audio files containing audio matching the requested phrase.

The -s option specifies that the should be treated as a callsign i.e. spelled out rather than spoken.

.sweep <frequency>
.sweep <frequency> <end frequency>
.sweep <frequency> <end frequency> <sweep time>
.sweep <frequency> <end frequency> <sweep time> <number of sweeps>
.sweep <frequency> <end frequency> <sweep time> <number of sweeps> <level>

The .sweep command is used to generate an audio test tone or audio frequency sweep for testing transmit level on an RF port. The level is the maximum value of the generated PCM wave so it has the range of 0 to 32768. We (the VoIP community) badly need to coordinate on what constitutes 100% modulation. If there is a standard I'm unaware of it.

.tonegen [ID <id> ] [TF1 <freq> [EF1 <freq>]] [TL <level>] [TF2 <freq>]
         [TL2 <level>] DUR <duration> [RPT <count>] : ...

.tonegen [ID <id> ] [TF1 <freq>] [TL <level>] [WPM <speed> ] CW <cw message>:

.tonegen [ID <id> ] [TL <row level>] [TL2 <column level> ] [DUR <active time>]
         [PAUSE <pause time>] DTMF <dtmf buttons> :

.tonegen [ID <id> ] FILE <path to file>:

.tonegen [ID <id> ] AX25 <packet data>:

.tonegen #<id>

.tongen !<id>

ID <number>    Assign a reference number the tone for future reference.

TF1 <freq>     Set Tone 1 frequency, 0 = no tone

EF1 <freq>     Set Tone 1 end frequency for sweeps (starts at TF1)

TL <level>     Set Tone 1 and 2 level

TF2 <freq>     Set Tone 2 frequency, 0 = no tone

TL2 <level>    Set Tone 2 level

DUR <duration> duration of tone segment or the DTMF digit active time 
               in milliseconds.
           
PAUSE <time>   The amount of silence in milliseconds between DTMF digits.

WPM <speed>    Set speed of CW message in words per minute.

CW  <cw msg>   Send specified message in morse code at speed specified by WPM
               using a tone frequency specified by TF1 and tone level specified
               by TL.
           
DTMF <dtmf>    Send DTMF tones <dtmf> with tone level specified by TL and TL2,
               active duration specified by DUR and interadigit time specified 
               by PAUSE.  If DUR is not specified the active duration is 
               defined by the configuration file variable DtmfEncodeDuration.  
               If PAUSE is not specified the intradigit time is defined by
               the configuration file variable DtmfEncodePause.
           
#<id>          Play saved ToneSpec <id> which was previously stored by the
               tonespec configuration variable.

!<id>          Cancel ToneSpec <id> if it is running

FILE path      Tone segment is contents of specified 8 Khz wav file.

RPT <count>    repeat pattern from the beginning or last rpt count times.

The .tonegen command is used to generate tones for various purposes such as courtesy tones, command acknowledgements, invalid command indication, timeouts, DTMF cover tones, busy tones, dial tones, etc.

Tone specifications can be stored for future use by providing an ID field and assigning them to the ToneSpec configuration file variable. Stored tones can be played back by referencing the ID for example .tonegen #123. Additionally many internal events may automatically trigger tones which are assigned to the event. Tones that are assigned IDs may also be cancelled before they complete by referencing the ID. For example ".tonegen !123".

Tone specifications are made of one or more segments which are played in order. Multiple segments are separated by ':'. Each tone segment must have an "DUR", "DTMF", "FILE", "CW" or AX25 field, all other fields are optional.

Tone segments may be repeated a specified number of times by the use of the RPT specification. When encountered in a tonespec the RPT field will cause the tone generation to repeat from the beginning or after the end of the previous RPT sequence for the specified number of times.

Tone frequencies are set to zero after each segment is generated, but tone levels are only changed when explicitly modified.

In a DTMF string one or more '+' character may be used to extend the duration of the next digit. For example +++1234 = generates a '' digit with 4 times the normal duration and before generating 1234 with the normal timings.
The default DTMF digit timings are defines by the DtmfEncodeDuration and DtmfEncodePause configuration variables. The default timings may be overidden by specifying a DUR and/or PAUSE in the tone spec.

For the AX25 "tone" is text used to generated a 1200 baud AFSK AX.25 UI frame in the following format:

">" [,] " "

For example:

W1AW>QST Code practice tonight at 11:00 on 146.52. The TL parameter may be used to adjust the amplitude of the generated AFSK tones. By default the tone level is set by the port configuration variable Ax25ToneLevel of the currently selected port.

For the AX25 "tone" is text used to generated a 1200 baud AFSK AX.25 UI frame in the following format:

">" [,] " "

For example:

W1AW>QST Code practice tonight at 11:00 on 146.52. The TL parameter may be used to adjust the amplitude of the generated AFSK tones. By default the tone level is set by the port configuration variable Ax25ToneLevel of the currently selected port.

.port [<port name>]

The .port command selects the active port for commands such as .id, .say, .tonegen, etc. When run without arguments the .port lists all ports with current port status. For example:

tlb> port
Available ports:
144 Rx
> 440 Tx
WR7NV-R
tlb>

This shows that port "144" is receiving a signal and the port "440" is transmitting. Additionally the '>' character displayed in front of the 440 port indicates that it is the port currently selected for control.

.rxfrequency <frequency>

This command sets the frequency of the receiver of the selected port if frequency control is supported by the hardware. The frequency is specified in Mhz (146.52).

.txoffset <transmitter offset from receiver frequency>

This command sets the transmitter's frequency in relationship to the receiver's frequency. The offset is specified in Mhz (-.600). Changing .rxfrequency does not effect the transmitter offset.

.rxtone <ctcss tone frequency>
.rxtone search
.rxtone any

This command sets the CTCSS tone of the receiver of the selected port if CTCSS tone control is supported by the hardware. The frequency is specified in hz (131.8), a tone frequency of 0.0 selects carrier squelch.

If the port is configured to use the internal software CTCSS decoder rxtone may be set to "search" to have the CTCSS decoder determine the CTCSS tone in use by a channel by monitoring. When a CTCSS tone is decoded the decoder exits search mode and begins decoding only the tone that was found. If thelinkbox is configured with an EventScript a "ctcss_decode" event is generated.

If the port is configured to use the internal software CTCSS decoder rxtone may be set to "any" to have the CTCSS decoder decode for any CTCSS standard CTCSS tone. This mode is primarily for testing.

.txtone <ctcss tone frequency>

This command sets the transmitter's CTCSS tone on the selected port if CTCSS tone control is supported by the hardware. The frequency is specified in hz (131.8), a tone frequency of 0.0 disables CTCSS generation.

.frequency [<rx frequency> [,<tx offset> [,<tx tone> [,<rx tone>]]]]

This command allows all parameters of the selected port to be set in one command. If no arguments are specified the current values are displayed if available. If the transmitter offset is not specified it defaults to 0 (simplex). If the transmitter tone is not specified it defaults to disabled. If the receiver tone is not specified it defaults to carrier squelch.

Bugs/Features/known limitations

1. Consider this software to be mature and stable.

2. Security is weak. Currently EchoLink's security is based on passwords which are sent in clear text on over the Internet and the relative obscurity of the system. Security through obscurity is no security at all!

3. If the RunAsUser feature is used under Linux core dumps are disabled. This appears to be a security feature inherent in Linux. If thelinkbox stops running for unexplained reasons please consider running it as root long enough to get a core dump to assist with correcting the problem.

Thanks

Special thanks to K7KAJ, N7LF, VK3JED and OH2LAK for helping me debug and test the pre-release versions of thelinkbox.

Special thanks to WD5M for ongoing support and bug fixes.

Thanks to the fine folks at sourceforge and github for hosting this and literally thousands of other open source projects.

How you can help

1. Report all bugs. Please provide details on the version of thelinkbox, the operating systems, and operating conditions. Log files and core dumps are not only helpful but in many cases essential.

2. Developers are welcome! If you have ideas and would like contribute to the development please contact me.

3. Documentation. It's a well known fact that most programmers/engineers hate documentation and are usually poor writers. We need to document the programs and protocols used by thelinkbox as well as other programs that will be written. The CQiNet web site could certainly use some input and a webmaster. If your language of choice is not a programming language you can still help !

[email protected] March 16, 2021