Mappers

The Mappers project is a crowd-sourced effort to build a true-signal coverage map of the Helium network across the globe.

The Mappers tool lets you see the areas that have been explored by participants in the project, and the Helium Hotspots that have provided coverage to those areas. By mapping real-world coverage, network users can understand where sensor deployments are proven to work.

How Does Mappers Work?

Participants use low-cost LoRaWAN devices to survey the real-world network created by Helium. Many contributors bring their mapper with them when they walk, hike, bike, drive, or even boat. They're small and fit well in a pocket or on a car dash.

In order to place a mark on the map, the mapper device sends out a signal with a GPS location encoded. If a Helium Hotspot "hears" that signal, data is passed through the internet and recorded in the Mappers database. The Mappers database uses the GPS information from the mapper to "light up" the hex on the map.

Why Contribute to Mappers?

For Hotspot owners: The collected data helps visualize the coverage provided by all Helium Hotspots — identifying areas where coverage is lacking or where Hotspot placements could participate in Proof of Coverage with other Hotspots. A marked hex on the map indicates that uplink signals from registered Helium LoRaWAN sensors have been proven to be "heard" by the Helium network somewhere within that hex-shaped area.

For network users: The map proves the real-world coverage that Hotspots provide. This real-world evidence at the scale and resolution offered by the map gives prospective network users the information they need to make decisions about their deployments.

How can I use Mappers for my own Hotspot deployments?

• Find new locations for Hotspots
• Get real-world information about how far your Hotspot reaches
• Learn RF data analytics in an interactive way

How can I use Mappers for my own sensor deployments?

Take a mapping device to the area where you want to deploy sensors and watch to see if it is picked up by a Hotspot. If it's picked up by only one Hotspot, decide if you want to deploy an additional Hotspot in that area for sensor connection redundancy. Look at existing mapped areas for confirmation that your sensors can be deployed in that area and how many Hotspots can pick them up.

Mappers API

The Mappers API accepts HTTP requests for submitting coverage data. No authentication is currently required.

Ingest Uplink

Submit geo-tagged uplinks from a mapper device.

POST https://mappers.helium.com/api/v1/ingest/uplink
Content-Type: application/json

Submitting from ChirpStack

Add an HTTP integration to a ChirpStack v4 application that holds your mapper devices:

• Event endpoint URL: https://mappers.helium.com/api/v1/ingest/uplink
• Payload encoding: JSON (Protobuf is not supported)

ChirpStack posts every event type to the endpoint. Only uplinks (up events) are mapped; other events are acknowledged and ignored. Keep mapper devices in their own application, since uplinks without a position are rejected.

The device profile's codec must decode each uplink into an object with these fields:

Field	Type	Description	Unit	Example
latitude	number	Device latitude	Decimal Degrees	37.795186
longitude	number	Device longitude	Decimal Degrees	-122.393844
altitude	number	Device altitude	Meters	10
accuracy	number	Device GPS accuracy	Meters	2.3

{
  "latitude": 37.795186,
  "longitude": -122.393844,
  "altitude": 10,
  "accuracy": 2.3
}

A codec may also set fixFailed: true when the device has no GPS fix, so a stale last-known position isn't mapped.

Hotspot locations come from the gateway metadata that Helium Packet Router adds to each rxInfo entry, so only uplinks heard by Helium Hotspots with an asserted location are mapped. Hotspots more than 500 km from the device are left out.

Helium Console format

Uplinks posted by a Helium Console HTTP integration are still accepted. The same fields go in decoded.payload.

Responses

• 200 — Uplink stored
• 204 — A ChirpStack event that isn't an uplink; nothing stored
• 415 — The body isn't sent as application/json
• 422 — The uplink can't be mapped. The body names the reason, e.g. {"error": "no_position", "detail": "..."}. Common reasons:
  • no_position — no numeric latitude/longitude, or either is 0
  • no_fix — the device reported fixFailed: true
  • decoder_error — the payload decoder reported an error
  • invalid_altitude / invalid_accuracy — missing or out of range
  • no_hotspot_location / no_valid_hotspots — none of the Hotspots that heard the uplink could be mapped (e.g. no location, or more than 500 km away)
  • unsupported_payload — the body is neither a ChirpStack uplink nor a Console uplink
• 500 — The uplink could not be stored

Development and Contribution

Any and all contributions from the community are encouraged.

• Guidelines for how to contribute to this repository are here.

Getting Started

1. First, clone the repository to your local machine and navigate into the folder. For example:

git clone https://github.com/helium/mappers.git
cd mappers

2. Second, install all the dependencies:

System dependencies:

• Xcode Command Line Tools (xcode-select --install)
• cmake
• postgres - add user/password postgres/postgres
• postgis

Application Dependencies:

• Install dependencies with mix deps.get
• Create and migrate your database with mix ecto.setup

macOS troubleshooting:

If the h3 native dependency fails to compile with 'stdio.h' file not found, set the SDK root:

export SDKROOT=$(xcrun --show-sdk-path)

If webpack fails with ERR_OSSL_EVP_UNSUPPORTED (Node 17+), set:

export NODE_OPTIONS=--openssl-legacy-provider

3. Edit your environment variables:

• Open the .sample.env file located at the root of the project
• Create a Mapbox account and copy your public access token
• Paste it in place of for the PUBLIC_MAPBOX_KEY variable. That line should now look like this:

PUBLIC_MAPBOX_KEY=pk.ey[...the rest of your access token...]

Rename the file ".env" (delete ".sample" from the file name)

4. Install Node.js dependencies with cd assets && yarn

5. Start development server:

• Start Phoenix endpoint with mix phx.server

Now you can visit localhost:4000 from your browser.

To Reset Database

• Run mix ecto.reset