TTN Mapper Documentation

Logo

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

View the Project on GitHub ttnmapper/documentation

FAQ

License

All data from TTN Mapper (ttnmapper.org) should be considered under the PDDL v 1.0 license (http://opendatacommons.org/licenses/pddl/1.0/).

The source code for the TTN Mapper system is open source and available on Github.

How can I contribute data?

Using any LoRaWAN device and a smartphone

Also see this lab for more details.

Using a GPS tracker device, transmitting GPS coordinates in the LoRa payload

See the documentation here.

If you have a GPS tracker that sends its own location in the payload of the LoRa packet, it is as easy as enabling the TTN Mapper integration to contribute data to the coverage map.

The assumption is that your end device with a GPS on it sends at least its latitude and longitude, but preferably also its altidude and HDOP values. If HDOP is not available, the accuracy of the GPS fix in metres will be accepted. As a last resort the satellite count can be used.

Make sure you have a Payload decoder function enabled on the TTN Console that decodes the raw payload into a json object. The JSON object should contain the keys “latitude”, “longitude” and “altitude” and one of “hdop”, “accuracy” or “sats”. When using the Cayenne LPP data format, the GPS coordinates will be decoded into a different JSON format, but this format is also supported. Cayenne LPP does not contain a GPS accuracy, and therefore this data will be considered as inferior and will carry less weight in calculation of coverage, and will be deleted first during data cleanup.

On the TTN Console, open your application and then click on Integrations. Search for the TTN Mapper integration and click on it.

For more info see the following articles:

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 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.

Which spreading factor should I transmit on?

We recommend using SF7. This provides us with a map of “worst case” coverage. Due to the 1% duty cycle limit on transmissions, using the fastest spreading factor will maximize the number of measurements taken.

From experimentation it has been seen that slower spreading factors (like SF12) does not perform well when the device is mobile. This is likely due to path fading from obstacles in the radio path, causing bursts of interference (erasures) which the forward error correction can not deal with. When you are doing measurements while standing still higher spreading factors (SF9-SF12) will work, but when mobile it’s better to use SF7.

My results are not showing up on the map

New measurements take up to 24 hours to be processed and displayed on the main map. If you want to see if your data is being uploaded, use the advanced map options and filter by your device ID.

It is possible that the gateway that received your packets does not have its location configured. If you know the gateway owner, please ask them to configure it. See “My gateway is not showing on TTN Mapper”. If this is the reason for your measurements not showing, you can check under Advanced Maps, enter your node address, and view the map. If you now see circles without lines connecting them to a gateway, this issue is confirmed.

Did you mark your data as experimental? If so, the data will not show on the main map, but on a separate map containing only your experiment. Please disable experimental mode in the app so that you can contribute to the global map of TTN coverage.

While I was measuring I saw a lot of points on the app for locations I measured, but only a few points are shown on your map. Did some of the data points go missing, or not upload?

The most likely reason is that the GPS accuracy of your phone or device was not good enough. Make sure you have a location accuracy of less than 10 meters, or an HDOP of less than 2.

Data logged to an experiment will not be displayed on the main map. Use the experiments section to display your experiment’s data. Experiments have less strict location accuracy filters.

It is possible that some datapoints did not upload correctly to our server because your internet connection was intermittent. This is however unlikely as a working internet connection is needed to receive data packets from TTN.

My results were showing on the map before, but is gone now.

When a gateway moves more than 100 meters it is seen as a new installation with different coverage. All old coverage data is hidden because the old coverage is now invalid.

In a very few circumstances obvious incorrect measurements might be deleted from the map.

My gateway is not showing on TTN Mapper

For a gateway to appear on TTN Mapper its location needs to be known, and it needs to have at least one coverage mapping point uploaded to TTN Mapper. In other words if a gateway has not been measured yet, the gateway will not appear on TTN Mapper.

Make sure your gateway’s GPS coordinates are configured correctly on the TTN Console. Also make sure fake_gps is disabled in the gateway’s local_conf.json file.

Also check that your privacy settings make the status and location of your gateway public.

<img src="/resources/TTNConsolePrivacy.png" />

TTN Mapper will use the location configured on the TTN Console first. If the location is not configured there it will use the location which the gateway reports. That means that a gateway with a built in GPS will be located at the location set on the Console, not the location the gateway reports. Only if the location is not set on the Console the fallback location - the location reported by the gateway - will be used.

Can I integrate your data into my map?
Can I download my data which I uploaded to you?
Public API access.

The GEOJSON files used to draw the TTN Mapper maps are publicly available at http://ttnmapper.org/geojson.

Data is sometimes dumped into CSV files. The dumps are available at http://ttnmapper.org/dumps. If you want newer data than what there are dumps of, please contact me.

No public API access is given to the raw data. This is due to the amount of data and number of possible queries that won’t be possible to handle on the server. Please use the dumps and your own database.

I want you to remove my gateway or measurement points from your map (privacy, etc)

If you change your gateway’s location to another one more than 100m away, any old measurements for your gateway will be hidden automatically.

In any other circumstance, contact us.

How can I support the project

One way of supporting the project is by contributing to the open source code on Github.

The project however has a monthly running cost which was covered by The Shuttleworth Foundation up to 2018. At this point there is no financial support from any official sources. If you want to financially support the project there are a couple of methods:

For details contact us.

My question is not answered here