├── .github └── FUNDING.yml ├── CNAME ├── DEVELOPMENT.md ├── FAQ.md ├── LICENSE ├── README.md ├── _config.yml ├── assets └── img │ └── logo.svg ├── integration ├── chirpstack.md ├── helium-flow-mappers-cargo.png ├── helium-flow.png ├── helium.md ├── ttn-integration-v2.md └── tts-integration-v3.md ├── private-network.md ├── project_status.md └── support-project.md /.github/FUNDING.yml: -------------------------------------------------------------------------------- 1 | # These are supported funding model platforms 2 | 3 | github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2] 4 | patreon: ttnmapper # Replace with a single Patreon username 5 | open_collective: # Replace with a single Open Collective username 6 | ko_fi: # Replace with a single Ko-fi username 7 | tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel 8 | community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry 9 | liberapay: # Replace with a single Liberapay username 10 | issuehunt: # Replace with a single IssueHunt username 11 | otechie: # Replace with a single Otechie username 12 | custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2'] 13 | -------------------------------------------------------------------------------- /CNAME: -------------------------------------------------------------------------------- 1 | docs.ttnmapper.org -------------------------------------------------------------------------------- /DEVELOPMENT.md: -------------------------------------------------------------------------------- 1 | # Documentation 2 | 3 | This repository tries to document how TTN Mapper works and how the different repositories on this Github organisation fits together. 4 | 5 | # Bugtracker 6 | 7 | * https://github.com/ttnmapper/bugtracker - All bugs can be reported here or on the respective repository if it is known where the issue is. 8 | 9 | # V1 - "old" PHP based system 10 | 11 | * https://github.com/ttnmapper/ttnmapper-web - This repo contains everything needed to spin up the PHP-based website on a LAMP stack. It also includes the processing scripts for aggregation of data, which is mostly written in Python. The current public production TTN Mapper runs this stack, along with some extras to make it more scalable. 12 | 13 | # V1 to V2 migration path 14 | 15 | * https://github.com/ttnmapper/mysql-insert-raw - This service runs as a docker container. It subscribes for new data on a V2 RabbitMQ broker and inserts the data into the MySQL database used by the V1 stack. 16 | 17 | # V2 backend microservices 18 | 19 | * https://github.com/ttnmapper/ingress-api - This is the api endpoint where data is received from the LoRaWAN server or the mobile phone apps. It's a centralised location through which any incoming data must flow. Data is received from the origin, it is validated and rewritten in a generic TTN Mapper format before it is published on a "new_packets" RabbitMQ fanout exchange. 20 | 21 | * https://github.com/ttnmapper/websockets-live - Allows the website to subscribe to a "live" data feed, allowing the lvie tracking of devices like high altitude balloons. This service has been created fro the balloon experiments, but could be used for any live raw data feed. 22 | 23 | * https://github.com/ttnmapper/postgres-insert-raw - Inserts all new packets into a postgres database. After the data is added it is re-published on a RabbitMQ fanout exchange "inserted_data" from where the aggregation services can receive it. 24 | 25 | * https://github.com/ttnmapper/gateway-update - Listens for all new packets and updates the last seen of gateways in the postgres database. Periodically the gateway list api endpoints of TTN is queried to get the location and description of gateways, as well as the last seen of all other gateways. When a gateway's location changes, and this change is more than 100m, a "gateway move" is registered. A gateway moved triggers old data for the respective gateway to be hidden. To acomplish this the gateway move data is published to a RabbitMQ fanout exchange "gateway_moved". 26 | 27 | * https://github.com/ttnmapper/postgres-insert-gridcell - Inserted data is aggregated into signal strength bins for a zoom level 19 slippy map tile, on a per gateway basis. This service subscribes to the "inserted_data" and the "gateway_moved" exchanges. When a gateway moves all previous aggregated data is deleted and all data since the move is used to re-aggregate. The result of this service is so-called gridcells which are used in visualisations like the heatmap. 28 | 29 | * https://github.com/ttnmapper/gateway-channels - This service subscribes to the inserted_data exchange. For every packet that is received a counter is incremented on a per gateway-frequency basis. The result is a table of gateway, frequency and number of times heard. This allows one to easily say how many channels a gateway listens on, and also will allow another service to guess which frequnecy plan(s) is used by the gateway. 30 | 31 | # V2 Frontend 32 | 33 | * https://github.com/ttnmapper/ttnmapper-web-v2 - A new frontend written using the React framework. The goal of the frontend is to replicate the current website feature set, but also allow users to log in using their TTN OAuth credentials. Logged in users can view and manage their own raw data. 34 | 35 | * https://github.com/ttnmapper/ttnmapper-api-v2 - A backend for the new frontend. 36 | 37 | # Mobile phone apps 38 | 39 | * Android: https://github.com/ttnmapper/ttnmapper-android-v3 40 | * iOS: https://github.com/ttnmapper/ttnmapper-ios 41 | * Cross Platform (work in progress): https://github.com/ttnmapper/ttnmapper-flutter 42 | 43 | # Hardware 44 | 45 | * https://github.com/ttnmapper/ttntrackernode - Hardware and firmware for an example tracking device that can be used for coverage mapping. 46 | 47 | * https://github.com/ttnmapper/gps-node-examples - Example firmware sketches, data encoding formats and decoders for a range of common off the shelf devices. 48 | -------------------------------------------------------------------------------- /FAQ.md: -------------------------------------------------------------------------------- 1 | # FAQ 2 | 3 | ## License 4 | 5 | All data from TTN Mapper (ttnmapper.org) should be considered under the PDDL v 1.0 license (http://opendatacommons.org/licenses/pddl/1.0/). 6 | 7 | The source code for the TTN Mapper system is open source and available on Github. 8 | 9 | 10 | ## How can I contribute data? 11 | 12 | Have a look at the [documentation index](https://docs.ttnmapper.org/) to find detailed information. 13 | 14 | ### Using any LoRaWAN device and a smartphone 15 | 16 | * A node transmitting to The Things Network. An Arduino with a RN2483 radio is ideal. Have a look at this library for example code and wiring instructions for the RN2483 and Arduino. Your node can however be any hardware and run any code, as long as you know the address the device use to transmit data to The Things Network. 17 | 18 | * An Android phone running the TTN Mapper App available on the playstore. -OR- An iPhone running the TTN Mapper app available from the iTunes store. 19 | 20 | Also see this lab for more details. 21 | 22 | ### Using a GPS tracker device, transmitting GPS coordinates in the LoRa payload 23 | 24 | See the documentation here. 25 | 26 | 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. 27 | 28 | 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. 29 | 30 | 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. 31 | 32 | On the TTN Console, open your application and then click on Integrations. Search for the TTN Mapper integration and click on it. 33 | * Process ID: fill in a unique string describing this integration. The value does not have an influence on the correct functionality of the integration. 34 | * E-mail address: fill in a valid email address. This email address will be used in the future to associate all data to you, and guarantee the quality of the data. 35 | * Port filter: This text field can be left empty in the most cases. If you are using your application for multiple purposes, and only send GPS coordinates on one specific port, you can use this field to specify the port on which the GPS coordinates are sent. 36 | * Experiment name: This text field can be left empty in the most cases. If you are measuring coverage that is out of the ordinary, like taking a GPS tracker on an aeroplane, strapping it to a balloon or drone, or climbing a high mast or tower that is not publicly accessible, your data should be logged to an experiment to keep it separated from the main TTN Mapper global coverage map. 37 | 38 | For more info see the following articles: 39 | * Hackster.io - The Things Network Node for TTNmapper.org 40 | * ESP32 TTN Mapper GPS 41 | * Adeunis Field Test device 42 | * Other examples 43 | 44 | 45 | ## When should I use an "experiment" to map my coverage 46 | 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. 47 | 48 | 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. 49 | 50 | 51 | ## Which spreading factor should I transmit on? 52 | 53 | 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. 54 | 55 | 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. 56 | 57 | 58 | ## My results are not showing up on the map 59 | 60 | 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. 61 | 62 | 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. 63 | 64 | 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. 65 | 66 | 67 | ## 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? 68 | 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. 69 | 70 | 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. 71 | 72 | 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. 73 | 74 | 75 | ## My results were showing on the map before, but is gone now. 76 | 77 | 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. 78 | 79 | In a very few circumstances obvious incorrect measurements might be deleted from the map. 80 | 81 | 82 | ## My gateway is not showing on TTN Mapper 83 | 84 | 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. 85 | 86 | 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. 87 | 88 | Also check that your privacy settings make the status and location of your gateway public. 89 | 90 | 91 | 92 | 93 | 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. 94 | 95 | 96 | ## Can I integrate your data into my map?
Can I download my data which I uploaded to you?
Public API access. 97 | 98 | The GEOJSON files used to draw the TTN Mapper maps are publicly available at http://ttnmapper.org/geojson. 99 | 100 | 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. 101 | 102 | 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. 103 | 104 | 105 | ## I want you to remove my gateway or measurement points from your map (privacy, etc) 106 | 107 | If you change your gateway's location to another one more than 100m away, any old measurements for your gateway will be hidden automatically. 108 | 109 | In any other circumstance, contact us. 110 | 111 | 112 | ## How can I support the project 113 | 114 | Please see [Support the project](support-project.md) 115 | 116 | 117 | ## My question is not answered here 118 | 119 | * Have a look at the rest of the documentation: https://docs.ttnmapper.org/ 120 | * Ask your question in the #ttnmapper channel on the TTN Slack. 121 | * Send a message to 122 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2018 ttnmapper 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # TTN Mapper Documentation 2 | 3 | * [Frequently asked questions](FAQ.md) 4 | * [Support the project](support-project.md) 5 | * [Mapper for private network](private-network.md) 6 | * [How to use the Android app video](https://youtu.be/bBDFxjr5xTQ) 7 | * [Using The Things Stack webhook template](integration/tts-integration-v3.md) 8 | * [Using the ChirpStack integration](integration/chirpstack.md) 9 | * [Using the Helium integration](integration/helium.md) 10 | * [Contribute to the software](DEVELOPMENT.md) 11 | -------------------------------------------------------------------------------- /_config.yml: -------------------------------------------------------------------------------- 1 | title: TTN Mapper Documentation 2 | logo: /assets/img/logo.svg 3 | description: TTN Mapper and CoverageMap.org are tools to map the coverage of LoRaWAN networks like The Things Network, The Things Stack, Helium and ChirpStack. 4 | show_downloads: false 5 | google_analytics: 6 | theme: jekyll-theme-minimal 7 | -------------------------------------------------------------------------------- /assets/img/logo.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | 6 | 7 | 8 | 9 | 10 | 12 | 13 | 16 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 34 | 35 | 36 | 37 | 40 | 42 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | -------------------------------------------------------------------------------- /integration/chirpstack.md: -------------------------------------------------------------------------------- 1 | # ChirpStack integration 2 | 3 | The HTTP Integration allows you to create a webhook for uploading data to TTN Mapper. 4 | 5 | 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. 6 | 7 | Go to https://ttnmapper.org for the global coverage map. 8 | 9 | > If you have a ChirpStack V4 server that has roaming set up with Helium and/or ThingsIX, mapping with your device registered in ChirpStack will also map the coverage of Helium or ThingsIX gateways that receives your device. 10 | 11 | ## Prerequisites 12 | 13 | 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. 14 | 15 | *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](https://www.thethingsnetwork.org/labs/story/using-ttnmapper-on-android)" lab. If you want to use the Things Node for mapping check out the "[Mapping gateway coverage using a Things Node](https://www.thethingsnetwork.org/labs/story/mapping-gateway-coverage-using-a-things-node)" lab. 16 | 17 | 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. 18 | * If your device is sending data in Cayenne LPP format, choose this decoder. 19 | * Otherwise create a custom javascript decoder which decoded the raw payload into one of these formats: 20 | 1. A JSON object containing the keys "**latitude**", "**longitude**" and "**altitude**". Some variations of these keys will also work. 21 | 2. In addition the JSON object should preferably contain one of the following keys "**hdop**", "**accuracy**" or "**sats**". 22 | 23 | If you are developing your own GPS enabled LoRa device please check the following [Github repository](https://github.com/ttnmapper/gps-node-examples) for example end-device software and decoder functions to be used with them. 24 | 25 | ## Create the integration 26 | 27 | 28 | ### ChirpStack V3 29 | 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: 30 | 31 | * **Payload marshaler**: Select `JSON` 32 | * **Headers**: See [Headers](#headers) 33 | * **Endpoint**: Add `https://integrations.ttnmapper.org/chirp/v3/events` 34 | 35 | ### ChirpStack V4 36 | In the ChirpStack web interface, choose applications, and then click on the application you are mappign coverage with. Go to the Integrations tab, and click on + under HTTP to add the HTTP integration. 37 | 38 | * **Payload encoding**: JSON or Protobuf - the Mapper supports both formats. 39 | * **Event endpoint URL(s)**: `https://integrations.ttnmapper.org/chirp/v4/events/` - multiple URLs can be added, separated by a comma. 40 | * **Headers**: See [Headers](#headers) 41 | 42 | ### Headers 43 | 44 | #### Mandatory 45 | * **TTNMAPPERORG-NETWORK**: Name of your network, for example: `my.network.name`. Try and make this unique, as this value will be used to distinguish your network's coverage and gateways from other ChirpStack networks' coverage and gateways. This header is a temporary workaround until a proper network identifier is added to ChirpStack. See [this Github issue](https://github.com/brocaar/chirpstack-network-server/issues/532) 46 | 47 | #### Optional 48 | * **TTNMAPPERORG-EXPERIMENT**: You only need to provide an experiment name if you are testing and do not want your mapping results to contribute to the main coverage map for the network. In other words, when you are mapping normally with a device that is between 1 and 2 metre above ground level, you can leave this field blank. If you are doing anything else like launching and tracking a balloon, please provide a unique experiment name here. Adding the date to the experiment name helps to find it again later. Also see [Experiments](#experiments). 49 | * **TTNMAPPERORG-USER**: Add your email address in this header to allow TTN Mapper to associate your coverage data with you. This will allow to easily find your data, and also verify when you request your data to be deleted. 50 | 51 | Click on "Update Integration". 52 | 53 | ## Verify the integration is working correctly 54 | 55 | 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](https://ttnmapper.org/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. 56 | 57 | > 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. 58 | 59 | For troubleshooting please post your question in the #ttn-mapper Slack channel on https://thethingsnetwork.slack.com/. 60 | 61 | ## Experiments 62 | 63 | ### When should I use an "experiment" to map my coverage 64 | 65 | 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. 66 | 67 | 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. 68 | 69 | 70 | ### Enable or disable logging to an experiment 71 | 72 | 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. 73 | 74 | To stop logging to an experiment, delete the `TTNMAPPERORG-EXPERIMENT` header entry. 75 | -------------------------------------------------------------------------------- /integration/helium-flow-mappers-cargo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ttnmapper/documentation/cb2c10b1633e5840d811f12f2c209a839047fb42/integration/helium-flow-mappers-cargo.png -------------------------------------------------------------------------------- /integration/helium-flow.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ttnmapper/documentation/cb2c10b1633e5840d811f12f2c209a839047fb42/integration/helium-flow.png -------------------------------------------------------------------------------- /integration/helium.md: -------------------------------------------------------------------------------- 1 | # Helium integration 2 | 3 | A HTTP Integration allows you to upload data to CoverageMap.net (aka TTN Mapper) 4 | 5 | The goal of CoverageMap.net is to provide a map of the actual coverage of Helium Hotspots. Contributors to CoverageMap.net measure the performance of Hotspots in their vicinity and upload this information to the CoverageMap.net website. Here the information is aggregated and shared with the community. 6 | 7 | Go to [CoverageMap.net](https://coveragemap.net) for the global coverage map. 8 | 9 | 10 | ## Prerequisites 11 | 12 | This guid is very similar to the [Quick Start guide for Helium Mappers](https://docs.helium.com/use-the-network/coverage-mapping/mappers-quickstart). The only difference is the address of the integration. 13 | 14 | 1. GPS tracker device 15 | 2. (optional) label to group mapping devices 16 | 3. Payload decoder 17 | 4. Integration 18 | 5. Configure Multiple Packets 19 | 6. Set up flow 20 | 21 | If you are already sending mapping data to https://mappers.helium.com/, you can skip to step nr 4 where we configure the CoverageMap.net integration. CoverageMap.net supports the same decoded payload format as https://mappers.helium.com/. 22 | 23 | ### 1. GPS tracker device 24 | 25 | In order to contribute to CoverageMap.net, 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. 26 | 27 | Regsiter your device on the Helium Console under `Nodes` -> `Devices`. 28 | 29 | ### 2. Label mapping devices 30 | 31 | It is useful to label your mapping devices. On the console under the devices page, there is a folder icon with a plus at the top. Click on it to create a label. Then go to All Devices, select your device, then click `+ Add label` and choose the label you just created. 32 | 33 | ### 3. Payload decoder 34 | 35 | On the console go to `Nodes` -> `Functions`. Create a new function `(+)`. Function type Decoder. If your device transmits using the Cayenne LPP format, choose that. Otherwise choose custom script and provide a valid decoder for your device. Make sure your decoder provides at least the Latitude and Longitude fields. 36 | 37 | Some standard payload decoders can be found on [Helium's GitHub](https://github.com/helium/console-decoders) 38 | 39 | The format and units of the expected fields in the decoded payload is the same as for [Helium Mappers](https://docs.helium.com/use-the-network/coverage-mapping/mappers-api/). Example: 40 | ``` 41 | "decoded": { 42 | "payload" : { 43 | "accuracy": 2, // meters 44 | "altitude": 2, // meters above mean sea level 45 | "latitude": 38.811706, // degrees, North is positive, South is negative 46 | "longitude": -121.607035 // degrees, East is positive, West is negative 47 | } 48 | } 49 | ``` 50 | 51 | ### 4. Integration 52 | 53 | On the console go to `Nodes` -> `Integrations`. Add a new integration. Choose `HTTP` under custom. 54 | 55 | End point details: 56 | * POST 57 | * Endpoint URL: `https://integrations.ttnmapper.org/helium/v1` 58 | * HTTP Headers: Key = `TTNMAPPERORG-USER`, Value = your email address 59 | * Name: CoverageMap.net (or any other name you prefer) 60 | * Add integration 61 | * Do not change the JSON message template. If you do, delete the integration and create it again. 62 | 63 | ### 5. Configure Multiple Packets 64 | 65 | On the console go the `Node` -> `Multiple Packets`. Add multiple packet config. 66 | * Multiple packet name: `All Available Packets` 67 | * How many to purchase: `All Available Packets` (move all the way to the right) 68 | * Create Multiple Packet Config 69 | 70 | ### 6. Set up flow 71 | 72 | On the console go to `Flows`. 73 | 74 | At the top left hand side click on Nodes, Labels, and drag the mapping nodes label you created in step 2 to the open space below. 75 | 76 | Then choose functions and drag the decoder you created in step 3 to the open space. 77 | 78 | Lastly, click on integrations and drag the CoverageMap.net integration to the open space. 79 | 80 | You should now have three blocks side by side in the window. 81 | 82 | Click on the device label. In the settings panel that opens on the right, click on the `Packets` tab. You should see the `All Available Packets` config you created in step 5. Enable it. Close the pane. 83 | 84 | Connect the label node to the decoder node, and then connect the decoder node to the integrations node. Like in the picture below. 85 | 86 | ![Helium flow](helium-flow.png) 87 | 88 | For a flow that contributes to CoverageMap.net, Helium Mappers and Cargo, it will look like this: 89 | 90 | ![Helium flow mappers](helium-flow-mappers-cargo.png) 91 | 92 | 93 | ## Verify the integration is working correctly 94 | 95 | In order to verify whether the integration has been configured correctly, go to your device on the Console. Switch on your device and make sure you see data appearing under real time packets. Now go to the ttnmapper.org website and in the menu select "[Advanced maps](https://ttnmapper.org/advanced-maps/)". In the "Device data" section enter your Device Name 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. 96 | 97 | ## Experiments 98 | 99 | ### When should I use an "experiment" to map my coverage? 100 | 101 | 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. 102 | 103 | 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. 104 | 105 | ### Enable or disable logging to an experiment 106 | 107 | * To log to an experiment, we need to add a header to the HTTP integration which will tell CoverageMap.net to log the data to an experiment, with Key = **TTNMAPPERORG-EXPERIMENT**. You only need to provide an experiment name if you are testing and do not want your mapping results to contribute to the main coverage map for the network. In other words, when you are mapping normally with a device that is between 1 and 2 meter above ground level, you can leave this field blank. If you are doing anything else like launching and tracking a balloon, please provide a unique experiment name here. Adding the date to the experiment name helps to find it again later. Also see [Experiments](#experiments). 108 | * To stop logging to an experiment, delete the `TTNMAPPERORG-EXPERIMENT` header entry. 109 | -------------------------------------------------------------------------------- /integration/ttn-integration-v2.md: -------------------------------------------------------------------------------- 1 | # TTN Mapper 2 | 3 | The TTN Mapper integration allows you to upload coverage information (location, rssi and snr) to TTN Mapper directly from the TTN backend. 4 | 5 | The goal of TTN Mapper is to provide a map of the actual coverage of the TTN 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. 6 | 7 | Go to https://ttnmapper.org for the global coverage map. 8 | 9 | ## Prerequisites 10 | 11 | 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. 12 | 13 | *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](https://www.thethingsnetwork.org/labs/story/using-ttnmapper-on-android)" lab. If you want to use the Things Node for mapping check out the "[Mapping gateway coverage using a Things Node](https://www.thethingsnetwork.org/labs/story/mapping-gateway-coverage-using-a-things-node)" lab. 14 | 15 | 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, the message payload should be structured according to one of following formats: 16 | 1. A JSON object containing the keys "**latitude**", "**longitude**" and "**altitude**". In addition the JSON object must contain one of the following keys "**hdop**", "**accuracy**" or "**sats**". Using a Payload decoder function the raw payload can be decoded into a JSON object with the required keys. 17 | 2. The Cayenne LPP data format. When using the Cayenne LPP data format, the GPS coordinates will be decoded into a different JSON format which is also supported. Cayenne LPP does not contain the 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. 18 | 19 | If you are developing your own GPS enabled LoRa device please check the following [Github repository](https://github.com/ttnmapper/gps-node-examples) for example end-device software and decoder functions to be used with them. 20 | 21 | ## Create the integration 22 | 23 | On the [The Things Console](https://console.thethingsnetwork.org/), open your application and then click on the *Integrations* tab. Search for the TTN Mapper integration and click on it. In the configuration page for the integration fill in the following: 24 | 25 | * **Process ID**: a unique string describing this integration. This is mainly for you to make a distinction between (possibly) multiple integrations you have configured. The value does not have an influence on how the integration works. 26 | * **E-mail address**: a valid email address. This email address will be used to associate all your data to you, and provides some guarantees on the quality of the data. 27 | * **Port filter**: the port on which the GPS coordinates are sent. This is an optional field that should be left empty in most cases. If your application is used for multiple purposes, and you only send GPS coordinates on one specific port, you can use this field to specify the port on which the GPS coordinates are sent, ignoring any other sensor data that is sent by your devices. 28 | * **Experiment name**: the name of the experimental dataset stored on the TTN Mapper website. This is an optional field that should be left empty in most cases. If you are measuring coverage that is out of the ordinary, like taking a GPS tracker on an aeroplane, strapping it to a balloon or drone, or climbing a high mast or tower that is not publicly accessible, your data should be logged to an experiment to keep it separated from the main TTN Mapper global coverage map. 29 | 30 | Click on "Add integration" and your application is now ready to contribute to TTN Mapper. 31 | 32 | ## Verify the integration is working correctly 33 | 34 | In order to verify whether the integration has been configured correctly, go to the Data tab for your device on the TTN Console. Switch on your device and make sure you see data appearing on the Data tab. Now go to the TTN Mapper website and in the menu select "[Advanced map options](https://ttnmapper.org/special_maps.php)". In the "Specific node" section fill in the Device ID in the "Node address" field. Leave the "Date" field as is - it is automatically set to today. Click on "View map" and you should see the data points sent by your end device. 35 | 36 | For troubleshooting please post your question in the #ttn-mapper channel on Slack. 37 | -------------------------------------------------------------------------------- /integration/tts-integration-v3.md: -------------------------------------------------------------------------------- 1 | # The Things Stack integration 2 | 3 | The TTN Mapper Webhook Template allows you to create a webhook integration for uploading data to TTN Mapper. 4 | 5 | The goal of TTN Mapper is to provide a map of the actual coverage of the TTN 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. 6 | 7 | Go to https://ttnmapper.org for the global coverage map. 8 | 9 | A video showing how to register and configure a GPS tracker to feed data to TTN Mapper can be found here: https://youtu.be/8KcHVzY-Yng 10 | 11 | ## Prerequisites 12 | 13 | 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 of a gateway is online or not. 14 | 15 | *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](https://www.thethingsnetwork.org/labs/story/using-ttnmapper-on-android)" lab. If you want to use the Things Node for mapping check out the "[Mapping gateway coverage using a Things Node](https://www.thethingsnetwork.org/labs/story/mapping-gateway-coverage-using-a-things-node)" lab. 16 | 17 | 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 on the console. 18 | * If your device is sending data in Cayenne LPP format, choose this decoder. 19 | * Otherwise create a custom javascript decoder which decoded the raw payload into one of these formats: 20 | 1. A JSON object containing the keys "**latitude**", "**longitude**" and "**altitude**". Some variations of these keys will also work. 21 | 2. In addition the JSON object should preferably contain one of the following keys "**hdop**", "**accuracy**" or "**sats**". 22 | 23 | If you are developing your own GPS enabled LoRa device please check the following [Github repository](https://github.com/ttnmapper/gps-node-examples) for example end-device software and decoder functions to be used with them. 24 | 25 | ## Create the integration 26 | 27 | On the The Things Stack Console, open your application and then click on the *Integrations* menu on the left. Then click on Webhooks. Search for the TTN Mapper webhook template and click on it. In the configuration page for the integration fill in the following: 28 | 29 | * **Webhook ID**: a unique string describing this integration. This is mainly for you to make a distinction between (possibly) multiple integrations you have configured. The value does not have an influence on how the integration works. 30 | * **Email address**: a valid email address. This email address will be used to associate all your data to you, and provides some guarantees on the quality of the data. 31 | * **Experiment name (optional)**: You only need to provide an experiment name if you are testing and do not want your mapping results to contribute to the main coverage map for the network. In other words, when you are mapping normally with a device that is between 1 and 2 metre above ground level, you can leave this field blank. If you are doing anything else like launching and tracking a ballon, please provide a unique experiment name here. Adding the date to the experiment name helps to find it again later. Also see [Experiments](#experiments). 32 | 33 | Click on "Create TTN Mapper webhook". 34 | 35 | ## Fix Base URL 36 | 37 | In the list of webhooks, click and open the newly added integration for TTN Mapper. Under Endpoint Settings, there is a Base URL. This value should read `https://integrations.ttnmapper.org/tts/v3`. If it's different, change it and then click save changes at the bottom of the page. 38 | 39 | ## Verify the integration is working correctly 40 | 41 | 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](https://ttnmapper.org/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. 42 | 43 | > TTN Mapper's support for The Things Stack V3 is still a work in progress and therefore not all maps will show the V3 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. 44 | 45 | For troubleshooting please post your question in the #ttn-mapper channel on Slack. 46 | 47 | ## Experiments 48 | 49 | ### When should I use an "experiment" to map my coverage 50 | 51 | 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. 52 | 53 | 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. 54 | 55 | 56 | ### Enable or disable logging to an experiment 57 | 58 | To log to an experiment, we need to add a header to the webhook integration which will tell TTN Mapper to log the data to an experiment. 59 | 60 | When you create a new webhook from the template you can specify an experiment name, which will automatically add the `TTNMAPPERORG-EXPERIMENT` header to the webhook. If you didn't add an experiment name when you created the webhook but wish to start logging to an experiment, you can delete the webhook and create a new one and specify an experiment name. 61 | 62 | Alternatively you can manually add the header by going to your application, Integrations, Webhooks, and open the previously added TTN Mapper Integration. Under Addition Headers, click Add Header Entry. In the first block (where Authorization is displayed in grey) type in `TTNMAPPERORG-EXPERIMENT`. In the second block (where Bearer my-auth-token is displayed in grey) fill in a unique name to identify your experiment. 63 | 64 | To stop logging to an experiment, delete the `TTNMAPPERORG-EXPERIMENT` header entry. 65 | -------------------------------------------------------------------------------- /private-network.md: -------------------------------------------------------------------------------- 1 | # Mapper for private networks 2 | 3 | The TTN Mapper system can be used to map the coverage of private LoRaWAN networks. Multiple options exist for this. 4 | 5 | ## The Things Stack 6 | 7 | The most The Things Stack instances exchange messages via the Packet Broker. 8 | TTN Mapper is able to detect the forwarding and the home networks for these messages. 9 | For networks like these a cloud offering is available which includes a white labelled map. 10 | The map is hosted under <name>.coveragemap.net, but an alias on your company domain can be set up. 11 | This solution starts at $50 per month, increasing with the number of gateways on your network. 12 | For the latest pricing details, please have a look at the description on [Patreon](https://www.patreon.com/ttnmapper). 13 | 14 | ## ChirpStack 15 | 16 | Some ChirpStack instances exchange data via the Packet Broker. For networks like these a SaaS solution like we have for The Things Stack is ideal. 17 | 18 | For free standing network servers a hosted solution is available which includes support. 19 | You can also deploy your own instance by using the open source code from Github, but this comes without any support. 20 | 21 | ## Helium 22 | 23 | The Helium network is currently seen as one big network server, and the coverage is available under https://coveragemap.net. 24 | When Helium matures and it becomes clear how private networks will operate, white labelled maps will be made available. 25 | 26 | ## Other 27 | 28 | It is possible to use the Mapper technology for any LoRaWAN network, or any wireless network for that matter. 29 | If you have a requirement for a coveragemap, please contact us and we can do a feasibility study and provide a quote. 30 | 31 | ## Contact Us 32 | 33 | {::nomarkdown} 34 | 35 |
39 |
40 | 44 |
45 |
46 | 50 |
51 |
52 | 53 |
54 |
55 | {:/nomarkdown} 56 | -------------------------------------------------------------------------------- /project_status.md: -------------------------------------------------------------------------------- 1 | # Project Status 2 | 3 | TTN Mapper is currently undergoing a major refactor to support The Things Stack (v3). To fully support TTS, TTN Mapper needs to be able to support multiple networks. 4 | This is a big change to the backend systems, and has already started in December 2018. The current major focus is uniquely identifying a network and gateways. After this is sorted out the focus will shift to the website. 5 | 6 | ## General 7 | 8 | - [X] Live mapping data feeds to new backend - since 2020-06-27 19:46 UTC 9 | - [X] Gateway updates from V2 and V3 into new backend - V2 since 2020-06-27 19:37 UTC, V3 since 2021-07-03 09:35 UTC 10 | - [X] Migrate old gateway locations from old to new database. Completed on 2021-09-04. 11 | - [X] Migrate old mapping data (before 2020-06-27 19:46 UTC) to new database. Completed 2021-09-18. 12 | - [X] Migrate old experiments (before 2020-06-27 19:46 UTC) to new database. Completed 2021-10-08. 13 | - [X] Clean up gateway moves: remove duplicate locations, using oldest entry. Done 2021-09-19. 14 | - [X] Heatmap plots from new backend. Shows only coverage for online gateways since 2021-11-14. 15 | - [ ] Add V2 to V3 coverage migrate form and script. Partial. Google form set up. 16 | - [ ] Generate radar plots from new backend 17 | - [ ] Circle plots, area plots 18 | - [ ] Website rewrite in JS framework - help wanted 19 | - [ ] Website user logins, network claims, private network subscriptions - help wanted 20 | - [ ] Simulation based coverage - research topic 21 | - [ ] Cross platform mobile app (Flutter) - help wanted 22 | 23 | ## The Things Network V2 24 | 25 | - [x] Data accepted and stored in TTN Mapper's database 26 | - [x] Android app support 27 | - [x] iOS app support 28 | - [x] Integration: available on v2 console 29 | - [x] Device raw data: available 30 | - [x] Gateway raw data: available 31 | - [x] Gateway markers: available 32 | - [x] Gateway online/offline status: available 33 | - [x] Radar plots: available 34 | - [x] Heatmap: available as a combined heatmap for all networks 35 | - [x] Area plots: available 36 | 37 | ## The Things Stack 38 | 39 | - [x] Data accepted and stored in TTN Mapper's database 40 | - [x] Android app support 41 | - [ ] iOS app support: not yet implemented - help needed 42 | - [x] Webhook Template: available on v3 console. See [V3 integration](integration/tts-integration-v3.md). 43 | - [x] Device raw data: Using the Advanced maps, one can view your device's raw data on the map. This will only show non-experimental points. The CSV option for per-device raw data will show experimental and non-experimental data. 44 | - [x] Experiment raw data 45 | - [x] Gateway raw data: available 46 | - [ ] Gateway markers: partial. V3 gateway markers are currently only shown per network on the heatmap. Homepage shows TTS-CE (TTNv3). 47 | - [x] Gateway status: gateway statuses pulls from Packet Broker mapping API 48 | - [ ] Radar plots: not yet implemented 49 | - [x] Heatmap: Data from all networks are currently used to draw heatmaps. This needs to change to be a per-network heatmap. 50 | - [ ] Area plots: not yet implemented 51 | 52 | ### Issues 53 | * Network identification 54 | 55 | ## Chirp Stack 56 | 57 | - [x] Data accepted and stored in TTN Mapper's database 58 | - [x] Android app support - partial, as network identification needs to be refactored 59 | - [ ] iOS app support 60 | - [x] Integration: TTN Mapper will ingest data from ChirpStack if a webhook integration has been set up, according to [ChirpStack integration](integration/chirpstack.md). 61 | - [x] Device raw data: available 62 | - [x] Gateway raw data: available 63 | - [x] Gateway markers: partially available 64 | - [ ] Gateway status: unsure if this is available 65 | - [ ] Radar plots: not yet implemented 66 | - [x] Heatmap: implemented, but only publicly available for Wolfsburg.Digital 67 | - [ ] Area plots: not yet implemented 68 | 69 | ### Issues 70 | 71 | * Identifying a network: https://github.com/brocaar/chirpstack-network-server/issues/532 72 | 73 | ## AWS IoT Core for LoRaWAN 74 | 75 | Not yet supported. 76 | 77 | ### Issues 78 | 79 | No easy way to get data out to a REST API and on an MQTT broker. 80 | 81 | ## Amazon Sidewalk 82 | 83 | Not yet supported 84 | 85 | ## Helium 86 | 87 | Not supported, and likely no need due to https://mappers.helium.com/ 88 | 89 | ## Sigfox 90 | 91 | Not supported, and will likely not be supported due to licensing restrictions. 92 | -------------------------------------------------------------------------------- /support-project.md: -------------------------------------------------------------------------------- 1 | # Support the TTN Mapper / CoverageMap project 2 | 3 | > **Current Funding** 4 | > * Patreon: 50% 5 | > * Ad revenue: 5% 6 | > * Loss: 45% 7 | 8 | The server hosting costs for the mapping system is a substantial amount each month. 9 | The project's future can only be guaranteed if these hosting costs are covered. 10 | 11 | The project's monthly running costs were covered by The Shuttleworth Foundation up to 2018. 12 | At this point there is no financial support from any official sources. 13 | 14 | There are two ways we are trying to fund the project: 15 | * Community support via donations 16 | * Selling white labelled private instances of the mapper 17 | 18 | 19 | ## Donations 20 | 21 | If you regularly use the mapping service, we ask that you seriously consider making a donation to support the porject. 22 | 23 | * We accept recurring donations via Patreon 24 | * Once-off donations can be made via PayPal 25 | * Direct bank payments can be made into a European bank account (IBAN). Please contact us for details. 26 | * Bitcoin (BTC): 36RvL4xZzfKvCsDgzvHvR7641aYLMrEhZQ 27 | * Ethereum (ETH): 0x401a057a896240C3881881d08aA0203534FC0801 28 | 29 | 30 | Invoices can be made out to companies in case they want to sponsor the project. 31 | 32 | 33 | ## Private instances 34 | 35 | Please see [Mapper for private network](private-network.md). 36 | 37 | 38 | ## Contact 39 | 40 | {::nomarkdown} 41 | 42 |
46 |
47 | 51 |
52 |
53 | 57 |
58 |
59 | 60 |
61 |
62 | {:/nomarkdown} 63 | --------------------------------------------------------------------------------