AllStarLink Waterfall (allfall)
Willem A. Schreuder (AC0KQ)
This code is released under the GNU Public License Version 2

Version 1.0  April 23, 2021
Version 1.1  April 25, 2021
Version 1.2  May    1, 2021

DESCRIPTION

The program connects to the AllStarLink on the Manager port on the specified
AllStarLink nodes and retrieves the RSSI reading for every receiver.  The number
of samples per second is a command line parameter.  The waterfall displays the
maximum signal strength every second.

You can use the left and right arrow to go back and forward in time.  The - and
+ keys advances time a page at a time.  The history defaults to one hour (3600
seconds) but can be compiled to be a diffent value by changing the nsec
variable at compile time.

The program uses the ncurses library and runs in text mode in a terminal window.
The program will attempt to adapt the displays to the dimensions of the terminal
window.

CONFIGURATION FILE

The AllStarLink nodes to which to connect are specified in the configuration
file which is the specified on the command line.

Comment lines must have a # in the first column.  Comments can occur anywhere in
the file.  Data lines consist of a hostname or IP address, user name and
password.  The hostname can optionionally contain a port number separated from
the rest of the hostname using a colon, e.g. host:port.  If the port number is
omitted the default port is 5038.

COMMAND LINE PARAMETERS

-r  Scroll RSSI left to right.
-s  Number of samples per second.
-D  run headless (without display)
-v  version
-h  Display program help.
-p  Accept TCP/IP connections on port
-d  Connect to database

KEY BINDINGS

Up    Scroll Up
Down  Scroll Down
Left  Back up in time
Right Advance time
h     Display help
q     Quit program

SAVING RESULTS TO DATABASE

The -d parameter allows results to be saved to a MySQL or MariaDB database.  The
database connection is specified as host:database/user:pass.  For example, to
connect to the database server with IP address 10.11.12.13 running a database
named colcon as user allfall with password secret, the program would be run as
  allfall -d 10.11.12.13:colcon/allfall:secret
The structure of the database tables are shown in the supplied file allfall.sql.
The client table contains the clients, the rssi table contains all readings.
The rssi readings are saved with the rssi as the lower byte and the higher byte
is 1, 2 or 3 depending on whether the reading is a mx, voter or voted reading.

The allfall.sql script can be used to create the database.  Access to those
tables must be granted such that the allfall program can write to it.  Using the 
database name, user name and password above, this can be done using the commands
  CREATE USER 'allfall'@'%' IDENTIFIED BY 'secret';
  GRANT ALL ON colcon.* TO 'allfall'@'%';
The access can be further limited by not using @'%' which would allow the login
from any host if appropriate for your network.  Note that the database must
accept connections from other hosts in order to access it from another host.

As distributed, support for storing to a database is only supported in the
Linux version.  This is enabled by adding -DMySQL when compiling.  This could
be supported in the rPi, Windows and OSX versions if the appropriate libraries
are installed.

ACCESSING ALLFALL FROM THE WEB

The allfall program will accept TCP connections if the -p flag is specified.
This can be used by any program that want to use the allfall data, but was
specifically designed to provide access to allfall by a web interface.

When a connection is made, allfall spawns a thread that will listen for an
unsigned integers sent as a text string terminated by a LF character.  It will
then send all the client names a line starting with 0 (ASCII 48) followed by the
client names.  The 0 and client names are separated by a tab (ASCII 9) and the
line is terminated by a LF (ASCII 10).  This number is the number of seconds of
history transmitted initially, before sending one reading per second.  

The program will then send the RSSI readings as an integer time followed by the
readings.  The time is the number of seconds since 2020-01-01 00:00:00, in other
words the UNIX time minus 1577862000.  RSSI readings are a space (ASCII 32) if
no reading was reported or a minus (ASCII 45) if all readings were zero.  If a
signal was received, a two character string is provided.  The first chararacter
is a M (ASCII 77) if mixed, v (ASCII 118) if voting and V (ASCII 86) if voted.
The second character is 0 (ASCII 48) to 9 (ASCII 57) or # (ASCII 35), indicating
an RSSI of 0-255.  0 means an RSSI of 1-25, 1 means 26-51, 2 means 52-78, up to
9 meaning 229-254 and # meaning more than full scale (255).

The provided allfall.htm is an HTML file with a Javascript program that accepts
Server-Sent Events (SSE) in exactly the format sent by allfall and displays it
in a web browser in a format similar to allfal.  The server-sent events are
provided by the provided allfall.cgi program.  The allfall.cgi program need to
be modified to set the IP address and PORT to match the the allfall program
(line 11).  All the allfall.cgi program does is serve as an intermediary to
forward traffic via the web server to the HTML client.

The allfall.htm pogram can be configured using parameters passwd via the
browser.  For example
  allfall.htm?wid=60&nsec=900&hist=180
would set the width of the waterfall to 60 characters, maintain a history of 900
seconds and initially request the last 180 readings.

Where to install allfall.htm and allfall.cgi depends on your web server.  On a
Linux system allfall.htm  is typically in /var/www/html or an appropriate subdirectory.

The allfall.cgi script must be installed in the appropriate CGI script.  On a
Debian system or derivatives such as Ubuntu this is /usr/lib/cgi-bin.  To enable
CGI scripts run the command
   sudo a2enmod cgi
   sudo systemctl restart apache2
On RedHat or derivatives,CGI scripts are in /var/www/cgi-bin.  To enable CGI scripts
edit /etc/httpd/httpd.conf and uncomment the line
   LoadModule cgid_module modules/mod_cgid.so
and then do
   sudo systemcl restart httpd

INSTALLING ON LINUX OR OSX

Compile by simply doing 'make'.  To install do 'sudo make install'.  The INSTDIR
variable in the Makefile can be changed to install cping somewhere other than
/usr/local/bin.

INSTALLING ON WINDOWS

Extract allfall.exe and msys-2.0.dll from the ZIP file anc copy these files to
somewhere where the system can find it, probably C:\WINDOWS\system32.

Note that allfall is designed to run from the command line.  You can run it from
a desktop icon by right clicking the allfall.exe and doing 'Send to Desktop'.
This will create a shortcut on the desktop.  Right click on the icon and do
'Properties'.  You can then add the command line parameters of your choice and
change the icon. 

I compiled allfall with Msys because it supports Unix style networking.  However,
the ncurses library provided with Msys requires the Unix terminfo data which
makes it less convenient under Windows.  Fortunately PDCurses provides an
ncurses compatible version of curses that works well under Windows.  If you
want to recompile cping under Msys, the pdcurses.h and pdcurses.a files I used
are provided.   I compiled these files from source.
