868 MHz TTN Mapper

TTN version: TTNv3
Activation: ABP
Device Class: Class A
Last updated: January 23, 2023

This article provides instructions for using GPS Tracker as a TTN Mapper. If you don’t have a GPS Tracker, check out our GPS Tracker article.GPS_Tracker

TTN Mapper is used to map The Things Network coverage. This is done by sending location information to the TTS. This device sends latitude, longitude, altitude and hdop to TTS every + -15 seconds. There is a TTN Mapper integration to contribute data to the coverage map. An example of a coverage map is below. You can find the public coverage map at ttnmapper.org.

TTN_Mapper_map

 

Prepare

 

Arduino IDE setup

  1. Run Arduino IDE.
  2. In the Arduino IDE Library Manager search TinyGPSPlus by Mikal Hart and install it.
  3. Download as ZIP this Low-Power library by Rocketscream.
  4. In the Arduino IDE Sketch -> Include Library -> Add .ZIP Library… choose downloaded ZIP.

 

The Things Stack setup

  1. Login on The Things Network.
  2. Click on your username and choose Console.
  3. Select a network cluster.

Add application

  1. Go to applications.
  2. Click on button + Create application.
  3. Write something into Application ID.
  4. Click on button Create application.

Add end device

  1. In your application click on button + Register end device.
  2. Input Method – Choose Enter end device specifics manually.
  3. Frequency plan – Europe 863-870 MHz (SF9 for RX2 – recommended)
  4. LoRaWAN version – LoRaWAN Specification 1.0.3
  5. Click on Show advanced activation, LoRaWAN class and cluster settings
  6. Activation mode – Activation by personalization (ABP)
  7. Additional LoRaWAN class capabilities – None (class A only)
  8. Deselect – Use network’s default MAC settings
  9. Rx1 data rate offset = 0
  10. Rx1 delay = 1
  11. Resets frame counters – Enabled
  12. Rx2 data rate = 3
  13. Rx2 frequency = 869,525 MHz
  14. Add Frequency = 868100000
  15. Add Frequency = 868300000
  16. Add Frequency = 868500000
  17. Add Frequency = 867100000
  18. Add Frequency = 867300000
  19. Add Frequency = 867500000
  20. Add Frequency = 867700000
  21. Add Frequency = 867900000
  22. DevEUI – Generate
  23. Device address – Generate
  24. AppSKey – Generate
  25. NwkSKey – Generate
  26. End device ID – here you can name your device
  27. After registration – View registered end device
  28. Click on button Register end device
  29. Click on General settings
  30. Network layer – Expand
  31. Click on Advanced MAC settings
  32. Desired Rx1 delay = 1
  33. Adaptive data rate (ADR) – Dynamic mode
  34. Click on button Save changes

Payload formatters

  1. In TTS -> Applications -> YourAppName -> Payload formatters -> Uplink change Formatter type to Custom Javascript formatter.TTN_Mapper_Payload
  2. To Formatter code copy and paste code bellow: 
    function decodeUplink(input) {
   var data = {};

   data.latitude = (input.bytes[0] << 16) + (input.bytes[1] << 8) + input.bytes[2];
   data.latitude = (data.latitude / 10000)

   data.longitude = (input.bytes[3] << 16) + (input.bytes[4] << 8) + input.bytes[5];
   data.longitude = (data.longitude / 10000)

   data.altitude = (input.bytes[6] << 8) + input.bytes[7];
   data.altitude = data.altitude / 10

   data.hdop = input.bytes[8] / 10;

   return {
      data: data,
      warnings: [],
      errors: []
   };
}
  3. Save changes.

 

Program for sending coordinates to TTS

We have prepared program for sending latitude, longitude, altitude and hdop to TTS every +-15 seconds.

  1. Copy and paste GPS Tracker program to your Arduino IDE.
  2. In program replace NWKSKEY, APPSKEY and DEVADDR with keys of your end device registred in TTS. Keys are in TTS -> Applications -> YourAppName -> YourEndDeviceName -> Overview -> Session information.
  3. Set the switch on the GPS Tracker to the middle (OFF) position.
  4. Connect Adafruit Feather 32u4 using micro USB cable to your computer.
  5. In Arduino IDE click on Upload button to upload program to your Adafruit Feather 32u4.
  6. The LED should start flashing green and red.
  7. Set the switch on the GPS Tracker to the Tracking position (as shown bellow).GPS_Tracker_TOP
  8. The LED should start flashing green.
  9. If the GPS data are valid, then the LED flashes green at a longer interval and the data are sent to the TTS.
  10. In TTS -> Applications -> YourAppName -> YourEndDeviceName -> Live data you should every +-15 seconds see this:TTN_Mapper_live
  11. For more information on GPS Tracker operating modes, see the Operating Modes section.

 

TTN Mapper Integration

There are two types of integration – Experiment and Main map contribution. Both are described below.

The TTN Mapper documentation says:

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.

 

TTN Mapper Integration – Experiment

  1. In TTS -> Applications -> YourAppName -> Integrations -> Webhooks click button +Add webhook.TTN_Mapper_webhook
  2. Select TTN MapperTTN_Mapper_webhook2
  3. Write something in the Webhook ID and enter your Email address. If you are testing new device and don’t want your data to appear on the main map, write something in the Experiment name (our case). Then click on button Create TTN Mapper webhook.TTN_Mapper_webhook3

 

TTN Mapper – Show Experiment Data

  1. On the TTN Mapper website, select Advanced Maps.
  2. Scroll down to section Show Experiment Data.
  3. Write your Experiment name from above.TTN_Mapper_experiment
  4. Click on button View Map.
  5. An example map is shown below.TTN_Mapper_experiment_map
  6. If you are satisfied with the result of the experiment and meet the conditions for TTN mapping (above in section TTN Mapper Integraton), you can start contributing to the Main map.

 

TTN Mapper Integration – Main map

  1. If you have performed the TTN Mapper Integration – Experiment section, add a new Application and a new End device. Then reprogram your GPS Tracker with the new keys. (Repeat The Things Stack setup and Program for sending coordinates to TTS from above.)
  2. In TTS -> Applications -> YourAppName -> Integrations -> Webhooks click button +Add webhook.TTN_Mapper_webhook
  3. Select TTN MapperTTN_Mapper_webhook2
  4. Write something in the Webhook ID and enter your Email address. Leave the Experiment name blank. Then click on button Create TTN Mapper webhook.TTN_Mapper_webhook4
  5. The newly received data will appear on the TTN Mapper Main Map (This may take up to 24 hours).

 

TTN Mapper – Show Device data

  1. Real-time data can be viewed in Advanced Maps on the TTN Mapper website.
  2. In the Device Data section.
  3. Write your end Device ID.
  4. Click on button View Map.TTN_Mapper_Device_Data