My LoRaWAN Signal Mapping MSc summer project. This is a copy of the actual repository with personal information removed.
Go to file
2019-09-09 12:35:22 +01:00
client_src Tweak the scale a bit 2019-08-27 14:45:07 +01:00
common Reduce distance range again, because ti doesn't appear to be working right. 2019-08-06 15:49:52 +01:00
images Talk more about the IoT device program structure. 2019-09-06 13:41:25 +01:00
iot Move circuit diagram to dedicated folder 2019-08-05 16:01:05 +01:00
lantern-build-engine@617fcdb5b9 Create initial report template 2019-05-03 13:59:37 +01:00
server Fix remaining bugs in unified training mode 2019-08-06 13:18:40 +01:00
.gitignore Remove output files from repo 2019-09-02 13:24:18 +01:00
.gitmodules Add TinyGPS as it's got a smaller program size then TinyGPS++ 2019-06-28 13:34:13 +01:00
.tern-project Try to add an additional input to the neural network, but it's not working. 2019-07-29 14:17:28 +01:00
build Add user manuals as appendices 2019-09-02 13:23:22 +01:00
compile_flags.txt Start weaving the libraries together, but there's quite a ways to go..... 2019-06-12 20:18:37 +01:00 [final report] More minor fixes 2019-09-02 16:23:35 +01:00
Initial Report Spec.pdf Add initial report spec 2019-05-02 15:57:41 +01:00
LICENSE Add LICENSE 2019-09-09 12:11:11 +01:00
msc-project-md-pdf.ikopCXS Add user manuals as appendices 2019-09-02 13:23:22 +01:00
package-lock.json Bugfix: Fix client-side Brain.js crashes 2019-07-30 18:38:44 +01:00
package.json Bugfix: Fix client-side Brain.js crashes 2019-07-30 18:38:44 +01:00
print.css Cleanup for the BFG repo cleaner 2019-09-09 11:58:28 +01:00 Add LICENSE 2019-09-09 12:11:11 +01:00
rollup.main.config.js Bugfix: Fix client-side Brain.js crashes 2019-07-30 18:38:44 +01:00
rollup.plugins.config.js Bugfix: Fix client-side Brain.js crashes 2019-07-30 18:38:44 +01:00
rollup.worker.config.js Bugfix: Fix client-side Brain.js crashes 2019-07-30 18:38:44 +01:00 Create shel script proxy for server script access 2019-07-24 18:09:06 +01:00
ttn-listener.conf rsyslog: Fix syntax 2019-07-16 17:53:06 +01:00
ttn-listener.service Add logging.colour settings option 2019-07-16 18:01:17 +01:00


My Msc Summer Project

This repository contains my Masters-level summer project. The title is LoRaWAN Signal Mapping. The software contained here provides a complete system for mapping and visualising the signal coverage of The Things Network.


The system is split up into 2 primary parts:

  1. An Arduino program that collects the data.
  2. A Node.js program that stores and analyses the data

It's best explained with the aid of a diagram or two:

![](images/Manual Diagrams-Workflow.png)

The above flowchart describes the workflow when using the system:

  1. First, the IoT device is turned on and the TTN Listener is launched.
  2. Then, the IoT device is taken around the target area that needs mapping. This can be done by anyone - the device does not require operation beyond turning it on and off once provisioned.
  3. Once the device has been carried around the target area, the DATA.TSV file on the IoT device's microSD card is copied off and placed on the server.
  4. The server data processor is then run to fold the data into the database.
  5. The AI trainer is now run on the collected data
  6. The data is displayed in a web browser, with the help of a web server

The flow of data during use can be shown using a diagram:

![](images/Manual Diagrams-Data Flow.png)

System requirements

This software has a number of requirements in order to function properly:

  • A Linux-based server (Ubuntu Server LTS is recommended), with the following installed:
    • Node.js v10+ with npm 6+ - see this website for instructions on how to install a recent version of Node.js (for the various application server stuff)
    • Git (for cloning the code repository)
    • awk (for text processing by the build script)
    • Bash v4+ (for the build script)
    • PHP (for the temporary test web server; not otherwise used any static web server will do)
  • Arduino IDE (for programming the IoT device)
  • Git (for cloning the code repository)

Getting Started

Step 0: Initial setup

Before doing anything, clone this git repository to both the server (for the TTN listener etc.) and your local machine (for programming the IoT device):

git clone

If you have somehow obtained a static copy of the code (e.g. through the University's marking system), then skip the above and use that instead.

Next, cd to the root of the repository and then run the setup task of the build script:

./build setup

On Windows, this should be run in Git Bash (accessible from the start menu when Git is installed - don't forget to cd to the root of the repository).

Step 1: Build a device

First, a device must be built and provisioned. See in this repository for detailed instructions on how to do this.

Once built, copy iot/main/settings.custom.cpp.example to iot/main/settings.custom.cpp and follow the instructions fill in the fields there. To do this, you'll need to register the device using ABP (Activation By Personalisation) on The Things Network. This guide tells you how to do this.

It is suggested that the following Bash one-liner be used to generate a new encryption key in the right formats:

head -c16 /dev/urandom | od -tx1 | awk '{ gsub(/^0+\s+/, "", $0); toml=$0; gsub(/\s+/, "", toml); print("settings.toml format: " toml); arduino=toupper($0); gsub(/\s+/, ", 0x", arduino); print("settings.custom.cpp format: 0x" arduino); exit }'

(Paste it into a terminal and hit enter)

Then, review iot/main/settings.h to make sure it matches your setup (e.g. all the pin numbers are correct)

Next, copy the folders in iot/libraries to your Arduino IDE libraries folder.

Finally, open iot/main/main.ino in the Arduino IDE and program the IoT device itself.

Step 2: The Things Network Setup

This step should be completed on the server.

Once a device has been constructed, running the The Things Network listener is next. This requires giving the system the The Things Network credentials.

Edit the file called settings.toml in the root of this repository (or create it if it doesn't exist), and make sure it contains the following:

app_id = "{APPLICATION_ID}"
access_key = "{TTN_ACCESS_ID}"

encryption_key = "{ENCRYPTION_KEY_FROM_STEP_1}"

port = 8883
tls = true

devices = [ "{DEVICE_NAME_FROM_TTN}" ]

The app_id and access_key can be obtained from The Things Network Console:

The device name can be obtained from step #1, when you registered the device with The Things Network. Alternatively, if the device is already registered, it can be obtained from the device list if you click the "X registered devices" text.

With settings.toml filled in, you can now start TTN Listener:

./build ttn-listener will display an error message if you forgot a value.

Now that the TTN listener is running, the IoT device can be carried around and data collected.

Step 3: Processing the data

This step should be completed on the server.

Once data has been collected by the IoT device, it can then be processed by the Node.js server application.

Copy the DATA.TSV file from the IoT device's microSD card to the root of the repository on the server. It is suggested that scp (Linux) or WinSCP be used to do this.

Next, fold DATA.TSV into the database like so:

./build process-data

Then, train the AIs on the collected data like this:

./build train-ai

The architecture of the neural networks trained can be customised by editing settings.toml. Check server/settings.default.toml for a guide on the different options available.

Step 4: Viewing the AI output

With the AIs trained, the browser-based web interface can be used to display the output as a map. Any static web server will do, but the build script has one built-in (if PHP is installed) for convenience:

./build server

If an alternative server is to be used, it should serve the app/ directory that can be found in the root of this repository.


IoT Device

Node.js Server

Web Interface


Pepperminty Wiki is released under the Mozilla Public License 2.0. The full license text is included in the LICENSE file in this repository.

Tldrlegal provide a useful summary of the license here.