The Longley-Rice coverage maps on RabbitEars are produced with open-source software that is designed to be run on open-source operating systems. This page has been created to allow others to generate maps of their own, either for personal use, or to upload a map to an external server, such as the RabbitEars website.
There are several things you will need:
- An installed Linux operating system with these dependencies: (Package names may vary)
- postfix or sendmail (Only required if you wish to send e-mail notifications)
- libproc-simple-perl (May not be necessary)
- Bob Nelson's Files
- SRTM 3-Degree Terrain Data (This is several gigabytes.)
As I am a user of Sidux
Linux, I will present this guide in a manner that should make it simple for users of Debian
-based distributions, such as Debian, Ubuntu
, or Sidux.
The first step is to install your Linux environment, if it is not already installed. Installation of Linux operating systems is covered by a plethora of other tutorials, and thus is outside the scope of this guide. Once the installation has been completed, open a command line window and be prepared to either enter, copy and paste, or adapt the following commands for your own specific Linux distribution.
You will first want to make a directory for your mapmaking environment, and move into that directory:
mkdir splat && cd splat
It is necessary to install the dependencies, as noted above. If you are running Ubuntu, you will already have sudo configured out of the box. If not, you will need to use su
to elevate your permissions. Now, install the dependencies:
sudo apt-get install build-essential lzma perl imagemagick libbz2-dev libgd2-xpm-dev libgd-gd2-perl libmath-round-perl libwww-perl ncftp postfix libproc-simple-perl
On some systems I have configured for this process, I found it was unnecessary to install libproc-simple-perl. You will need to adjust your command accordingly. You will also need to configure postfix, if you choose to install it. The steps for doing so are also beyond the scope of this tutorial.
The next step is to download and unpack Bob Nelson's files as well as the files for compiling SPLAT:
wget -c http://www.ibiblio.org/pub/linux/apps/ham/splat-1.3.0.tar.bz2 && tar -xjvf splat-1.3.0.tar.bz2 && wget -c http://www.rabbitears.info/coverage/re_nelson_files.tar.lzma && lzma -d re_nelson_files.tar.lzma && tar -xvf re_nelson_files.tar
Next, you will need to patch SPLAT with Bob Nelson's patch and build it. The way SPLAT is coded when it comes raw out of the tarball, it spends processor cycles producing a map in PPM format on every run regardless of whether or not it is needed. For our purposes, it is not. This patch simply adds a flag that optionally prevents SPLAT from generating that map and thus wasting those additional processor cycles:
patch -Np1 -i ../splat.cpp.diff
At this point, the installer asks some questions. When it asks for the maximum analysis region, choose 8 both times. It should then build successfully. At the end, you will need to install the compiled program files. Once you've installed the files, you need to return to your splat directory:
sudo ./install all
Now it is time to download the terrain data. This can be a very slow process if your connection is slow. You will, however, need to keep an eye on it. After a while, it will finish downloading data for North America and begin downloading data for Africa; at this point, the process should be stopped by pressing Ctrl+C:
wget -rc http://dds.cr.usgs.gov/srtm/version2_1/SRTM3/North_America/
With the terrain data downloaded, we must process it in order to convert it into a format that SPLAT can understand and then put it in the proper directory. The tool that comes with SPLAT only provides for converting one file at a time. I wrote a script, that Bob cleaned up and improved, which automatically converts all of them with one command:
mkdir terraindata && ln -sf dds.cr.usgs.gov/srtm/version2_1/SRTM3/North_America && ./hgtstuff.sh
Once this is done, you can confirm that the terrain data is present and delete the original files. When you finish, create the four directories that Bob's scripts require to function properly in case they do not already exist, and you have a fully-functional mapmaking system prepared for use! =)
rm North_America && rm -r dds.cr.usgs.gov
mkdir -p fcc_data && mkdir -p input && mkdir -p output && mkdir -p output/html
Now that this environment is set up, you can begin actually generating coverage maps. There are three ways to do this:
- Singular retrieval from the database
- Multiple retrieval from the database
- Preparation by hand
I will attempt to walk you through all three so that you can choose the one best suited to your purposes. However, note that the walkthrough for the latter methods will depend on having read the instructions for the earlier methods.
1. Singular retrieval from the database
On RabbitEars, I have hosted a special page which exists solely to provide data from the RabbitEars database to Bob's scripts. We will be using this to generate the files necessary to create a map.
There are only a few pieces of data you need:
- FCC Application ID - A six- or seven-digit ID number that should not be confused with the Facility ID number.
- Site Number - Usually 0, but in the case of DTS or fill-in translators, this number may instead be 1, 2, etc.
- Range - SPLAT will only perform calculations out to a certain distance from the transmitter. You must provide it the distance in kilometers to which you wish to calculate.
- You will also want to decide on a Name for the file. The name has no bearing on the result.
You will also want to determine which additional options you want:
- -l - Sets the receiver antenna height. The default value is 4 meters, but this default can be adjusted in splat_runner.sh.
- -m - Sends automated e-mail messages to the addresses noted at the top of splat_runner.sh.
- -u - Uploads the resulting files to the server noted in splat_runner.sh, which is pre-set to upload to RabbitEars.
- -w - Generates an HTML page for viewing your map. This will be placed in the output/html directory you created earlier.
Then, simply run the following commands, modifying them to suit your purpose:
./fcc2qth.pl -f name_of_file -r range application_ID site_number
./splat_runner.sh -uwm name_of_file
When this is complete, you should have a copy of the map viewer HTML file available to you in your output/html
folder, a copy should have been uploaded, and an e-mail should have been dispatched to any e-mail addresses noted in splat_runner.sh
2. Multiple retrieval from the database
This method is the most efficient and borrows most of its functionality from the previous method by simply automating it. You need to make the same adjustments to splat_runner.sh
as noted above, and be familiar with the above options and switches.
The first step is to modify splat_iterator.sh
to reflect the command line switches you desire, as noted in the previous section. The default selection is -uwm. Once that is complete, then a file must be created in the input
folder with entries for each station to be run.
KTNL 1251149 0 128
KUBD 1246933 0 136
As you can see, it contains the same four pieces of information required in the previous method, just in a different order. First the Name
, then the Application ID
, Site Number
, and Range
. Each station needs to be on a separate line, as shown.
The RabbitEars website actually can generate these special input files on demand. You can see an example here
. Note that the site code attempts to guess the range by using the HAAT
field, though it sometimes fails if there is no HAAT or the HAAT given is below zero. Second, note that in order to change the market returned, you must use the internal ID number rather than the READS Rank for the given market.
Once you have created this file, generating your maps is as simple as running a single command and then letting it run until complete. If your file is named stationlist
, the command you will run is:
The output you will receive is exactly like the output from the previous method. The only difference is that the command line switches are controlled by what is entered in the appropriate part of splat_iterator.sh
instead of on the command line itself.
3. Preparation by hand
This method is the hardest, but it is the only method which will allow you to create maps for theoretical stations which do not yet exist or will not exist.