RDFMapper V2.

5 Documentation

RDF Mapper V2.5

Documentation
document version 1.0.1

Table of Contents
Introduction..........................................................................................................................................2
Stand-alone mobile RDF receiver....................................................................................................2
Stationary RDF receiver..................................................................................................................2
Stationary/mobile RDF receiver with additional remote bearings..................................................2
Basic Usage..........................................................................................................................................3
Starting the software........................................................................................................................3
General use......................................................................................................................................3
Stopping the software......................................................................................................................3
Navigating the map..........................................................................................................................3
Map Controls...................................................................................................................................4
GPS..................................................................................................................................................4
Manual pos/head..............................................................................................................................4
RDF..................................................................................................................................................5
Web upload/download.....................................................................................................................5
Stations on the map.....................................................................................................................6
Security.......................................................................................................................................6
Bearing Server......................................................................................................................................8
Troubleshooting....................................................................................................................................9
Browser Issues.................................................................................................................................9
Author and licensing...........................................................................................................................10

http://www.musther.net/RDFMapper Page 1
RDFMapper V2.5 Documentation

Introduction
RDFMapper is a software package for visualising bearings from radio direction finding (RDF)
hardware. This allows the bearings to be used to perform ‘visual triangulation’ of the location of a
transmitter source. There are various possible ways to use the software:

Stand-alone mobile RDF receiver

In this instance the software is used with RDF hardware to produce bearings on a map. As the
mobile RDF system is moved, multiple bearings taken from different positions provide an
indication of the source location.

Stationary RDF receiver

In this instance the software can only display bearings from a fixed location and so triangulation is
not possible. The software is capable of uploading the bearings to a ‘bearing server’.

Stationary/mobile RDF receiver with additional remote

bearings
This may be the most powerful instance. The software can be run on multiple systems (stationary
or mobile). The bearings from one or more of these systems can be uploaded to a bearing server.
The bearings on the server can be plotted on one or more systems, and therefore multiple RDF
receivers can be visualised simultaneously while they are in different locations. In fact the software
can be run without any RDF hardware, being used just to download and visualise bearings from
remote RDF receivers.

http://www.musther.net/RDFMapper Page 2
RDFMapper V2.5 Documentation

Basic Usage
Starting the software
RDFMapper is distributed as a single executable for Windows, MacOS X and Linux. In most cases,
simply running this executable (double-clicking) will be enough to get up and running.
The software is distributed in this way for ease of use, but the single-executable model does mean
that during start up various temporary files have to be created. As a result, start up times for
RDFMapper can be quite long. Please be patient, once the software has started it should run quite
quickly even on older hardware.
RDFMapper runs a small web server as it starts, this is where all the magic is performed. The
software then launches your web browser and points it to the web server. We’re then able to make
use of modern web-mapping tools to visualise the RDF data. For this reason, you may receive a
warning from Windows about the firewall – in order to use RDFMapper you must click ‘allow’.

General use
The user interface is handled entirely in the web browser as a single page. Closing or refreshing
this page will close the software (see below). The map on the left side of the window is where
bearings and remote RDF receivers are plotted, this map is entirely interactive (see Navigating the
map). On the right side of the window are the controls relating to GPS, RDF, location, bearing
plotting, web server uploading/downloading etc.

Stopping the software

Closing the web browser (or the tab) in which RDFMapper is running will automatically cause the
closure of the back-end. You should be warned before leaving the page or closing the browser, in
an attempt to prevent accidental closure.
In the event that the browser crashes or closes without communicating to the back-end that it is
closing, the back-end will automatically close after approximately 30 seconds. If you try to re-
launch the software within this time, you may find it doesn’t work.

http://www.musther.net/RDFMapper Page 3
RDFMapper V2.5 Documentation

Navigating the map

Map navigation is very similar to any other web mapping system (e.g. Google Maps).
• Panning
◦ Click and drag
◦ Use the arrow keys
• Zoom
◦ Double click (zoom in)
◦ Scroll (using scroll wheel, track pad etc
◦ Click the + or – symbols in the top left of the map
The map style can be changed to various web sources, including satellite imagery. To select a style,
click on the layers symbol in the top right of the map window.

Map Controls
Clicking on the ‘Map Controls’ label in the menu on the right, will open these controls.
Clicking ‘Snap to current location’ (keyboard ‘c’) will cause the map to centre on the current GPS
location. If you don’t have any GPS input, you should not use this control as it will move to the
software default location (Wellington, New Zealand).
Checking the box ‘Follow GPS location’ will cause the map to centre on the GPS location every
time a new GPS fix is received.
Clicking ‘Clear bearings’ (keyboard ‘space’) will remove all current bearings from map.

GPS
Clicking on the ‘GPS’ label in the menu on the right, will open these controls.
‘Fixes for speed/heading’ is the number of fixes that are averaged to ascertain the current speed and
heading. If you have an RDF receiver mounted on a vehicle, the GPS coordinates are used to
calculate your speed and heading, which allows the bearings from the RDF to be correctly aligned
with the map. Increasing the value of this variable should provide a more stable heading/speed, but
it will also introduce a lag in the adaptation of the heading after you turn a corner.
‘Minimum speed (km/h)’ is the minimum speed required to accept a bearing from the RDF receiver.
If your current speed is lower than this value, bearings will not be plotted. This is used to ensure
that at low speeds, when GPS heading information is likely to be unreliable, erroneous bearings are
not plotted. Setting this variable to ‘0’ will plot all bearings.

http://www.musther.net/RDFMapper Page 4
RDFMapper V2.5 Documentation

‘GPS Port’ allows the selection of the serial port to which the GPS device is attached. The ‘GPS
baud rate’ allows selection of the appropriate serial baud rate. Every time one of these values is
changed, the system will connect to the port with the current settings. The status can be seen below
the ‘GPS baud rate’ box. If ‘Connected’ appears in red, this indicates that the port has been opened,
but that the expected data is not being received. This could mean that this is the wrong port, or that
the baud rate is incorrect. Once ‘Connected’ goes green, this indicates that valid data has been
received. If data is received but no location information is provided, the message will read
‘Connected (no signal)’ - this almost always indicates that the GPS device has no GPS lock.

Manual pos/head
Clicking on the ‘Manual pos/head’ label in the menu on the right, will open these controls.
Checking the box ‘Use manual input’ will cause the software to ignore the GPS settings and
received data, and rely instead on manual positioning and map alignment.
After enabling manual input, GPS settings are greyed out and manual settings are enabled.
The current location can be set by clicking on the map, which moves the red marker to the point that
was clicked.
The heading can be set in two ways, either by entering it manually in the ‘Heading’ box, or by
clicking on the map.
To set the heading on the map, press ‘h’ on the keyboard, and then click on a point along the
heading. You can also click the ‘set’ button and then click on the map (this is equivalent to pressing
‘h’).
Setting the position and heading this way allows for quick and easy establishment of the RDF
receiver’s location and rotation within the real world. As an example consider an RDF antenna
array is mounted on a vehicle with the front of the vehicle being 0 degrees. The user can drive the
vehicle to a specific location and then click that location on the map. Next the user would press ‘h’
and click a point on the map which is directly ahead of the car in the real world (like the far end of a
street). The RDF antenna array is now tied into the real world.

RDF
Clicking on the ‘RDF’ label in the menu on the right, will open these controls.
Checking ‘Single bearing mode’ will only plot one bearing at a time. Disabling this will plot
bearings whenever they’re received from the RDF receiver, and they will remain on the screen until
cleared. Single bearing mode is most useful with static stations and the continuous mode is most
useful when using a mobile receiver and wishing to plot bearings along a baseline for triangulation.
‘RDF Port’ allows the selection of the serial port to which the RDF receiver is attached. The ‘RDF
baud rate’ allows selection of the appropriate serial baud rate. Every time one of these values is

http://www.musther.net/RDFMapper Page 5
RDFMapper V2.5 Documentation

changed, the system will connect to the port with the current settings. The status can be seen below
the ‘RDF baud rate’ box. If ‘Connected’ appears in red, this indicates that the port has been opened,
but that the expected data is not being received. This could mean that this is the wrong port, or that
the baud rate is incorrect. Once ‘Connected’ goes green, this indicates that valid data has been
received. Note that this data will only result in a plotted bearing if in manual mode, or if the GPS
conditions are met (see GPS section).

Web upload/download
Clicking on the ‘Web upload/download’ label in the menu on the right, will open these controls.
This section allows the local system to upload bearings to the bearing server, and also allows it to
download bearings from the bearing server.
The ‘Bearing server’ is the address to the bearing server you wish to use. For more information on
setting up a bearing server, see the ‘Bearing Server’ section. When this address is changed, the
software will attempt to use it. At the bottom of the ‘Web uploading/downloading’ section are
status lines for upload and download. If the server address is wrong, it will be reflected here. Note
that the default server is ‘http://rdf.musther.net/’, this is a public server.
‘This station’s ID’ is the name given to the local station. This is used to register the station with the
bearing server, and is the name necessary for another system to download bearings from the server.
The default is ‘12345’ but note that as this is the default for all users so using this will lead to
strange results. You can use any alphanumeric characters for this name (e.g. JM544Home) – the
station name is case-sensitive (JM554Home is not the same as JM554home).
Checking ‘Enable bearing uploads’ will begin uploading bearings as they are received and plotted
locally.
Under ‘Add & remove stations’ is a drop-down box and a text box, with two buttons ‘Add’ and
‘Remove’. Typing a station name into the text box and clicking ‘Add’ will add it to the list. This
station will now be requested from the server. Stations currently in the list can be seen by
expanding the drop-down box and can be removed by selecting them and clicking ‘Remove’. If a
station name cannot be found on the server, a message will be presented in bottom right of the
window. This name will continue to be requested until the station is removed, so if you are waiting
for someone at a remote station to begin uploading, it is safe to leave the name in the list.
The ‘Update period (s)’ is the number of seconds between downloading bearings from the server.
The default is 5 seconds which should be adequate for most purposes. Decrease this if you need to,
but please consider the number of requests made to the server.

Stations on the map

Once a station is added to the list it will be plotted on the map. It will initially exist as coordinates
(0,0) which is off the west coast of Africa. As soon as data is received from the bearing server, this

http://www.musther.net/RDFMapper Page 6
RDFMapper V2.5 Documentation

station will move to it’s correct position. Clicking on the stations icon will open a popup
showing the station’s name and the age of the bearing plotted from it. Note that the age of the
bearings will not be correct if the computers being used do not have the time and timezone correctly
set.

Security
For ease of use there is very little security surrounding the bearing server. Anyone can upload
station and bearing data, and anyone with the name of that station can download it. The only
security is via the obscurity of the station names. The database itself is not available publicly, so the
name of a station is required to access its data, however the database is stored in plain text on the
server, so the server owner (and those with access) could see the data. An example of the database
is shown here to demonstrate what data is stored:
Station ID Timestamp Station Latitude Station Longitude Bearing End Latitude Bearing End Longitude
TSTA4 1529532418 -41.263954 174.655373 -26.621505 226.841775

http://www.musther.net/RDFMapper Page 7
RDFMapper V2.5 Documentation

Bearing Server
There is a publicly available bearing server hosted at http://rdf.musther.net
It is quite easy however to set up your own bearing server. You’ll need a publicly accessible web
server which supports PHP. Unzip the contents of the bearing server zip file into a publicly
accessible location on your web server. Then inside the ‘data’ folder, the ‘data’ file needs to be
made writeable by the web server. On a Linux server this command will work:
chmod a+x data
The bearing server includes the files:
• index.html
• read.php
• save.php
• data (folder)
◦ data
◦ .htaccess
The ‘read’ and ‘save’ php files perform the actions for uploading and downloading data. The
index.html file simply provides information if someone navigates to the base address. It also
provides some obscurity as to what files are in that directory by preventing an index listing.
The ‘data’ folder contains the ‘data’ file, which contains the database. The ‘.htaccess’ file in the
‘data’ folder prevents listing or access to the data file. As a result it cannot be accessed publicly but
only via the webserver, meaning only via the php scripts.

http://www.musther.net/RDFMapper Page 8
RDFMapper V2.5 Documentation

Troubleshooting
RDFMapper has been extensively tested, however if you find a bug, please report it with as much
detail as possible to [email protected]

Browser Issues
As RDFMapper uses your system browser for the user interface and map drawing, issues can arise
from using old or unusual browsers. If you experience missing parts of the user interface, or the
map does not load, it is quite likely that your browser is out-dated. The largest amount of testing of
RDFMapper has been conducted using Google Chrome, so we recommend you download and
install this. You will need to set the new browser as your system default so that it is opened when
you start RDFMapper.

http://www.musther.net/RDFMapper Page 9
RDFMapper V2.5 Documentation

Author and licensing

RDFMapper is written by Jonathan Musther with much help on all things RF from Wil (PA8W) –
check out his website: http://members.chello.nl/~w.hofman/pa8w/
RDFMapper is Copyright 2018 Jonathan Musther, and released under a single-user license (unless
otherwise specified.
Upon purchase, the user has the right to use RDFMapper on as many computers as desired,
providing that the user is the primary beneficiary of this use. The sharing of bearings between users
for RDFMapper is specifically exempted from this benefit.
You must not do, or allow others to do any of the following: modify, adapt, alter, translate, or create
derivative works of RDFMapper.
If you are in any doubt about your rights or responsibilities, please contact: [email protected]

http://www.musther.net/RDFMapper Page 10