Manual & FAQ

1 · What is the LoRa NextGEN Mapper?

The LoRa NextGEN Mapper is a self-hosted coverage map for The Things Network (TTN) / The Things Stack (TTS). It receives LoRaWAN uplinks with GPS coordinates (via webhook or MQTT) and displays the signal coverage on an interactive Leaflet map.

• Public map lookup by DevEUI or Gateway ID — no login required.
• Signal strength (RSSI), spreading factor and optional sensor values (temperature, humidity, pressure, battery) are stored per uplink and displayed colour-coded on the map.
• Multiple users can connect their own TTS applications (after registration).

2 · Home page & Overview map

The home page shows three key metrics (gateways, devices, total uplinks) and an overview map of all gateways and devices active in the last 7 days.

• ● Orange dots = Gateways (larger, fixed location).
• ● Blue dots = Devices / trackers (smaller, mobile).
• Clicking a dot opens a popup with name, ID, uplink count and last reception.
• Clicking the popup link navigates to the device / gateway detail page.
• The map automatically fits all visible points (auto-fit).

A DevEUI can be entered directly in the search box at the top (hexadecimal, 16 characters). Submitting navigates to the device page.

3 · Device lookup & Coverage map

URL pattern: /device/{DevEUI} — e.g. /device/0102030405060708.

Map

• Every uplink with a GPS fix is plotted as a coloured circle.
• Colour dropdown (top left): RSSI | Temperature | Humidity | Pressure. Options with no data are automatically disabled.
• Heatmap toggle: Overlays a heat map based on RSSI values.
• Time buttons (24 h / 7 d / 30 d / All): Filters the displayed uplinks by reception time — client-side, no page reload. The From/To date fields additionally let you pick a custom range (applies within the loaded uplinks).
• Sensor filter (collapsible): Min/Max input fields for temperature, humidity, pressure and battery voltage. Shows how many uplinks pass the filter. Reset button clears all filters.
• Popups show all available sensor values (🌡 °C, 💧 %, 🌬 hPa, 🔋 V).

Sensor history charts

Below the map, time-series charts are shown for temperature, humidity, pressure and battery voltage — provided the device sends these values.

Recent uplinks

A table of the latest 50 uplinks (timestamp, gateway, RSSI, SF, frequency).

4 · Gateway page

URL pattern: /gateway/{GatewayID}. Shows all uplinks received by this gateway.

• Same map controls as the device page: colour mode (RSSI/Temp/Humi/Pressure), heatmap toggle, time filter (24h/7d/30d/All), sensor filter.
• The gateway location is highlighted as a separate marker (📡), if known.
• Uplink table with DevEUI, RSSI, SF, timestamp.

The page /gateways lists all known gateways with uplink count and last reception.

5 · Compare map

URL: /compare. Multiple devices and/or gateways on a single map, each series in its own colour.

• DevEUIs or gateway IDs can be added using the form at the bottom of the page.
• Added entries appear as chips; clicking × removes them.
• Colour mode: Default = "Series" (each source its own colour). Alternatively, switch to a sensor mode (RSSI, Temp, Humi, Pressure) — the same colour scales as on the individual pages then apply.
• Sensor filter applies to all series simultaneously — shows the total visible points across all sources.
• The URL contains the selected entries as query parameters (?d=EUI1&d=EUI2&g=GWID) and can be shared directly.

6 · Statistics page

URL: /stats. System-wide statistics at a glance:

• Uplinks per day (last 30 days) as a bar chart (Chart.js).
• Top-10 gateways and top-10 devices by uplink count.
• RSSI distribution (histogram) and spreading factor distribution (donut).
• Longest active connection (device with the most uplinks over the longest period).

7 · Decoder library & Server-side fallback

URL: /decoders. Ready-made JavaScript payload formatters for common LoRaWAN devices that can be pasted directly into TTS.

Supported devices with ready-made formatters:

• Dragino LGT-92 (GPS tracker)
• Dragino LHT65 (temperature / humidity + external sensor)
• RAK7200 / RAK7201 (WisTrio)
• Seeed SenseCAP T1000 (A / B / C / E)
• Browan TBHV110 (Healthy Home Sensor)
• Adeunis FTD (Field Test Device, BCD-GPS)
• ELSYS (ERS / ELT / EMS generic)
• Cayenne LPP (generic)

Each decoder has a Copy button. Paste the copied code into TTS under Applications → Payload Formatters → Uplink → Custom Javascript Formatter and save.

Server-side fallback decoder

If no payload formatter is configured in TTS, the mapper automatically attempts to decode the raw payload:

1. Dragino LGT-92 heuristic (FPort 2, ≥10 bytes): lat/lon as int32 @ 1/1e6
2. RAK7200 heuristic (FPort 8, marker 0x09): int32 lat/lon, v1/v2 firmware scaling
3. Seeed SenseCAP T1000 heuristic (TLV format, Type 0x01 for GPS): int32 lat/lon @ 1/1e7
4. Cayenne LPP (generic, searches for GPS field 0x88)

⚠️ Server-side decoders are conservative — they validate coordinates and reject false positives (like (0,0) or out-of-range values). A proper formatter in TTS is recommended for reliable results.

8 · Data export (CSV / GPX)

Two download formats are available for each device:

Both endpoints are public and require no login.

9 · JSON API (v1)

All endpoints under /api/v1/ are public and return JSON. Base URL: https://ttnmapper.live/api/v1.

GeoJSON endpoints (for map clients):

• GET /api/activity.geojson?days=7 — active gateways + devices
• GET /api/gateways.geojson — all gateways as GeoJSON
• GET /api/device/{eui}/coverage.geojson — coverage points for a device
• GET /api/gateway/{id}/coverage.geojson — coverage points for a gateway

10 · Account, Profile & Offline notifications

Registration

An account can be created with e-mail and password at /register. If an SMTP server is configured, the e-mail address must be confirmed before the first login (link via e-mail, valid for 24 h).

Login & sessions

After logging in at /login, a session is created (valid for 30 days). Active sessions are visible on the profile page and can be revoked individually.

Profile page (/profile)

• Account details and last password change.
• Your TTS applications with the timestamp of the last uplink.
• Login history: Last 10 successful logins (time, browser·OS, IP address) — helps identify suspicious access.
• Active sessions (browser · OS · IP · login time) — current session highlighted in green. All or individual sessions can be revoked.
• Device offline notifications: E-mail alerts when a monitored tracker stops sending uplinks.
  • Configurable per device (threshold: 15 min / 1 h / 6 h / 24 h / 7 days).
  • E-mails on online → offline transition and back (with downtime shown).
  • Pause button to mute temporarily.
• Change password (current password required).
• Delete account (requires typing "DELETE" to confirm).

Forgot password

A password reset can be requested at /forgot-password. The reset link is valid for 1 hour and can only be used once.

11 · Connect TTS applications

TTS applications can be added at /applications (login required). Each application receives a unique webhook token and optionally MQTT credentials.

Webhook test

A test button (🧪 Test) can be triggered for each application. This sends a synthetic uplink through the ingest pipeline and shows the result in a modal:

• Loading state: Data is being processed (spinner)
• Success: DevEUI, reception time, GPS coordinates (with altitude if available), decoded JSON payload (copyable), "View on map" link
• Error: Error message from the server with option to retry

12 · My Coverage

At /coverage (login required), all GPS uplinks from all linked TTS applications are shown together on a single map. This gives a complete picture of your LoRaWAN range — regardless of how many gateways received a signal.

Best-of-gateway logic: Each uplink is plotted with the RSSI of the strongest receiving gateway. This shows the maximum achievable range, not the weakest link.

Map controls

• Colour mode (dropdown): RSSI · Temperature · Humidity · Pressure · Per Device (each device gets a unique colour from a 10-colour palette; sidebar dots and legend update accordingly).
• Heatmap toggle: Switch between dot view and RSSI heatmap.
• Time-range buttons: 24 h / 7 days (default) / 30 days / All — filtered server-side, no page reload needed. The From/To date fields let you query any historical range (re-fetched server-side).
• Sensor filter (collapsible): Min/Max inputs for temperature, humidity, pressure and battery. The header shows an "(active)" badge when a filter is set.
• 📡 Receiving gateways (toggle): Shows all gateways that have received at least one uplink from your devices (lazy-loaded, orange 📡 icon, popup shows uplink count and last reception).

Device sidebar

• Lists all devices with app name, uplink count, last timestamp and last RSSI (colour-coded).
• Checkbox per device: show/hide on the map.
• Clicking a device name zooms the map to that device's points.
• In "Per Device" mode, a coloured ● dot next to each entry shows the assigned map colour.
• "All" / "none" toggles all devices at once.

Stats strip

After loading, a line below the map automatically shows: X gateways heard · Best RSSI: −XX dBm — computed from the loaded data.

13 · Setting up webhook ingest

1. Create an application at /applications and copy the webhook URL (https://ttnmapper.live/webhook/v3/{token}).
2. In TTS: Applications → Integrations → Webhooks → Add Webhook → Custom Webhook.
3. Paste the webhook URL, select format JSON, and enable only the event type Uplink message.
4. Save — all GPS uplinks are now forwarded to the mapper immediately.

14 · Setting up MQTT ingest

As an alternative to the webhook, the mapper can communicate directly with TTS via MQTT. This requires an API key with specific permissions.

Step 1: Create API Key in The Things Stack

1. Go to The Things Stack Console → your application → "Collaborators"
2. Click "Add Collaborator"
3. Select "Create API Key"
4. Set permissions: The following rights are required:
   ✓ Required permissions:

   • application.traffic.read — Read uplinks (MQTT traffic)

   Optional, but recommended:

   • application:devices:read — Read device metadata
5. Copy the generated API key (used as password later)

Step 2: MQTT Settings in Mapper

In your mapper application (Profile → Applications) enter the following values:

• Enable MQTT: Check the box
• Broker Host: e.g. eu1.cloud.thethings.network
  Check your region: eu1, nam1, au1, etc.
• Broker Port:
  • 1883 — unencrypted (TCP)
  • 8883 — encrypted (TLS, recommended)
• Username: {app-id}@{tenant-id}
  Example: myapp@tenants.thethingsstack
• Password: The API key you generated above

Step 3: Automatic Connection

• The MQTT manager checks the settings every 30 seconds
• Upon successful connection, uplinks are automatically ingested
• Automatic reconnect on connection loss
• In your profile (under "Applications") you'll see "Last active" — this shows the last webhook/MQTT uplink

15 · Light / Dark theme

The theme can be toggled using the 🌙/☀️ switch in the navigation bar.

• For guests, the preference is stored in a cookie (1 year).
• For logged-in users, the preference is saved permanently in the account.
• Default: Light.

16 · Frequently asked questions