TTN Mapper Documentation

Logo

TTN Mapper is a tool to map the coverage of The Things Network.

View the Project on GitHub ttnmapper/documentation

ChirpStack integration

The HTTP Integration allows you to create a webhook for uploading data to TTN Mapper.

The goal of TTN Mapper is to provide a map of the actual coverage of the LoraWAN gateways. Contributors to TTN Mapper measure the performance of gateways in their vicinity and upload this information to the TTN Mapper website. Here the information is aggregated and shared with the TTN community.

Go to https://ttnmapper.org for the global coverage map.

Prerequisites

In order to use the TTN Mapper integration a LoRaWAN device with a GPS, capable of transmitting its GPS coordinates, is required. The minimal location information that needs to be sent by the device is its latitude and longitude. Preferably it should also send its altitude and HDOP values. If HDOP is not available, the end device should provide the accuracy of the GPS fix (in meters). As a last resort, if no accuracy can be provided, the satellite count can be sent. Devices that do not report a location are still used to determine if a gateway is online or not.

Note: If you don’t have a GPS enabled LoRa device, you can still contribute to TTN Mapper using your smartphone (Android or iOS) and any LoRaWAN device. See the “Using TTN Mapper on Android” lab. If you want to use the Things Node for mapping check out the “Mapping gateway coverage using a Things Node” lab.

Once the integration is enabled any message sent by the end device will also be published to the TTN Mapper website. In order for TTN Mapper to correctly interpret the incoming messages, a payload decoder needs to be configured.

If you are developing your own GPS enabled LoRa device please check the following Github repository for example end-device software and decoder functions to be used with them.

Create the integration

On the Chirpstack-UI, open your application and then click on the Integrations tab on top. Then click on HTTP. In the configuration page for the integration fill in the following:

Headers

Required

Optional

Click on “Update Integration”.

Verify the integration is working correctly

In order to verify whether the integration has been configured correctly, go to the Live Data page for your device on the Console. Switch on your device and make sure you see data appearing there. Now go to the TTN Mapper website and in the menu select “Advanced maps”. In the “Device data” section fill in the Device ID field. In the Start Date and End Date fields choose today. Click on “View map” and you should see the data points sent by your end device.

TTN Mapper’s support for Chirpstack is still a work in progress and therefore not all maps will show the collected mapping data. Using the per-device raw data map and csv is the most reliable way to make sure your data is accepted into the TTN Mapper database.

For troubleshooting please post your question in the #ttn-mapper channel on Slack.

Experiments

When should I use an “experiment” to map my coverage

An experiment is a way to keep unrealistic coverage measurements away from the main map. Experiments should be used when testing new hardware or coverage is mapped from aeroplanes, balloons or any similar unrealistic altitudes.

In other words logging to the main map should only be done from roughly 0.5m-2m above ground level. “Ground level” should be interpreted as any place easily accessible by a human - or any place where an IoT device would commonly be installed. The top of a skyscraper is only acceptable if the skyscraper has a viewing deck that is publicly accessible. Man made hills and natural mountains are acceptable. The roof of a car or small delivery truck is fine. The roof of a bus or 14 wheeler truck is not as that is not a average acceptable height at which a sensor will be installed. The dashboard of a truck or bus is however roughly 2m above ground and therefore acceptable.

Enable or disable logging to an experiment

To log to an experiment, we need to add a header to the HTTP integration which will tell TTN Mapper to log the data to an experiment.

To stop logging to an experiment, delete the TTNMAPPERORG-EXPERIMENT header entry.