Regional administration

The Regional Admin console is the control room for FreqMapper regions and Region Groups. Open /region-admin and sign in with the FreqMapper profile that has regional access. The area chooser separates Region Groups from individual regions.

Regional admins can make changes. Regional moderators can review the same local information but cannot edit it.

Region Group admins and moderators inherit the same access level across every member region. The Region Group view provides combined map and leaderboard links and can publish its own official mesh radio settings. Open a child region to change settings owned only by that region. Both consoles place public About/links and official mesh settings together under Public info & mesh. See Region Groups for setup, scope, access, and public subdomains.

Region Group admins can also publish an About description and up to 12 public links from Public Region Group Info. This content appears above the combined coverage statistics and remains separate from every child region's own Public Region Info.

Warning

Keep invite keys, API keys, broker passwords, FreqMapper's private wardriving channel key, and private coordinates out of screenshots, public issues, and chat. A region's official primary mesh key is the exception only when its administrators deliberately enable Publish these settings; that key is intended for everyone joining the public mesh.

Overview

The overview is a quick health and readiness summary. It shows:

the region's public status;
whether a boundary is ready;
the number of admins and moderators;
the number of assigned Watchers; and
the number of regional MQTT brokers.

The console applies only to the selected region. If a shared wardriving channel is shown, treat it as read-only regional information.

The Section menu changes the current address, so a specific section can be bookmarked and the browser Back button works normally. An individual region has:

Section	Main job
Overview	Readiness, visibility, boundary, team, Watcher, and broker counts.
Public info & mesh	Public About text, links, and official community radio settings.
Region settings	Processing, public visibility, allowed missions, Position Packet coverage, and mobile enrollment limit.
Boundary	Draw, import, validate, export, save, and restore GeoJSON boundaries.
Watchers	Reveal the dedicated Watcher channel setup, approve gateways, and manage the Watcher directory.
Invite keys & radios	Create or revoke mapper enrollment keys and revoke enrolled radios.
MQTT brokers	Configure read-only sources and encrypted-channel decoders.
API access	Issue and monitor approved server-side coverage access.
Admin team	Add admins or read-only moderators.
Change history	Review who changed regional configuration and when.

A Region Group has Overview, Public info & mesh, Admin team, MQTT brokers, API access, and Change history. Boundary, Watcher, invite, and radio controls belong to each individual region.

Region settings

These fields control how the region appears and how mobile radios enroll:

Display name: the human-readable region name shown across FreqMapper.
Country: choose any country in the worldwide list. FreqMapper stores its two-letter ISO country code.
State, province, or area: United States, Canadian, and Mexican subdivisions have ready-made lists. For other countries, enter the local ISO 3166-2 suffix (for example, ENG for England or BY for Bavaria). This value organizes regions within the country; the uploaded GeoJSON remains the authoritative boundary.
Data processing: Active, Pending setup, or Paused. Active accepts new regional data; the other choices do not. Only use Active when the boundary and local evidence sources are ready.
Public visibility: Public or Hidden while building. A hidden Active region can continue ingesting while it is excluded from public maps, directories, leaderboards, and feeds. This is separate from data processing.
Allowed wardrive missions: allow mappers to choose Active Patrol + Silent Recon, or select Silent Recon only to stop the FreqMapper mobile apps from sending coverage-test packets in this region. Silent Recon receive activity remains separate from verified TX coverage.
Position Packet coverage: use the displayed default, enable it for this region, or disable it for this region. This controls collection and public display of dashed quality-colored cells created when approved Watchers hear normal Position Packets over radio. Existing evidence is retained while disabled.
Radios per mobile device: a soft enrollment limit from 1 to 100. Leave it blank to use the displayed default. Lowering the limit does not revoke radios that are already enrolled.

Select Save settings after reviewing the region name at the top of the page.

Public info & mesh

The Public info & mesh page keeps the two public-facing editors together. Each editor has its own Save button, so updating the About text or links does not silently change the official radio configuration.

Public Region Info

Use Public Region Info to introduce the local mesh on the map's Info panel. The description can explain the coverage area, community, events, or how to get involved. Public links use one line each in Label | https://address format; a region can publish up to 12 website, Discord, configuration, analyzer, or other useful links.

Everything in this section is public. Check every destination and remove expired invitations before saving.

Official mesh radio settings

These settings tell visitors which configuration the region currently uses and let the Android and iPhone apps warn when a connected radio differs. Set the LoRa regulatory region, modem preset, frequency slot, primary channel name, and Base64 primary-channel key. Frequency slot 0 means Meshtastic Automatic.

Use Add secondary channel for optional public community channels. Enter the channel name and Base64 key for each one; a region may publish up to seven. Remove a row before saving when that channel should no longer appear in Region Info.

Primary and secondary mesh keys are encrypted at rest but become public on the map and through the mobile API when Publish on Region Info and to mobile apps is enabled. They are separate from FreqMapper's private shared wardriving channel and never change that channel. FreqMapper reports differences in the official primary radio settings but does not automatically reconfigure a connected radio.

Region Groups can publish the same primary and secondary channel information from their control room. Group settings appear on that group's public Info panel and remain separate from every child region's settings; saving the group does not overwrite a child region.

Boundary

The boundary controls the public outline and position-based regional assignment. It is not a radio-coverage claim.

FreqMapper accepts GeoJSON Polygon, MultiPolygon, Feature, or FeatureCollection data when every included geometry is polygonal. Coordinates must be longitude/latitude in EPSG:4326. Points, lines, empty collections, and projected coordinates will not validate.

To adjust or replace a boundary:

Select Export current GeoJSON if you want an offline copy of the existing boundary.
Drag any cyan point on the boundary map to move it. Use Add point for a new corner, Delete point to remove the selected corner, or Draw new to replace the outline. Purple areas show neighboring public regions for context and are not changed.
For an existing GeoJSON workflow, expand Advanced GeoJSON import and choose a .geojson or .json file, or paste the complete GeoJSON.
Select Validate boundary and review the geometry type, vertex count, area, and bounds.
Select Save validated boundary only when the map and validation results match the intended region.

Editing the GeoJSON after validation requires another validation. Replaced boundaries remain in Rollback history. Select Restore beside an earlier version to make it current; the boundary being replaced is retained so the operation stays reversible.

Region admins edit the selected region in this map editor. Region Group boundaries are derived from their member regions and cannot be changed from the Region Group control room. If the Region Group outline or member list is wrong, contact a FreqMapper administrator or moderator for help.

For county-based planning, Boundary Maker can combine selected counties into a starting GeoJSON file. Review the resulting shape with the local community before importing it.

Admin team

Use Admin team to manage regional access by exact verified email address:

Admin can review and change regional data.
Moderator (read only) can review every section but cannot make changes.

Enter the account email, choose the access level, and select Add or update. The list shows whether the person's FreqMapper profile is linked or still awaiting first sign-in. An admin can remove another team member; the console does not offer a remove button for the currently signed-in account.

Watchers

A Watcher is the actual MQTT uplink gateway that received and reported a packet. The sender or a relayed node is not the Watcher identity.

Set up a dedicated Watcher radio

The top of the Watchers section shows the required FreqMapper channel name. An administrator—not a moderator—can reveal its Base64 PSK. Revealing it is recorded in Change history.

On the dedicated Watcher radio:

Add the shown channel as a secondary Meshtastic channel.
Use the exact displayed name and PSK.
Turn Uplink Enabled on so packets heard over RF can be sent to MQTT.
Leave Downlink Enabled off. FreqMapper never needs broker traffic retransmitted onto RF.

This channel belongs only on radios intentionally operated as FreqMapper Watchers. Do not add it to ordinary community radios or use it for chat. Keep the PSK out of screenshots, public issues, and general chat.

The Watcher radio still needs a working MQTT path. A channel alone does not make it visible or approved.

Understand detected and approved Watchers

MQTT Watcher — detected, not approved means FreqMapper has heard that gateway through a regional source, but it is not yet allowed to verify mapping evidence.
Region Watcher — position confirmed inside region means its own usable position placed it inside the boundary and it was approved through the regional process.
Region Watcher — manually approved means an administrator explicitly approved the node ID.

Use the directory search for radio name, node ID, or broker. Filter All MQTT Watchers, Region Watchers only, or Detected, not approved, and sort by name, recently heard, or recently discovered. NodeInfo, MapReport, administrator, or roster labels explain where the displayed name came from.

Before a Watcher can be assigned, FreqMapper must already have heard that gateway ID through MQTT. Enter its node ID, such as !1234abcd, and select Approve Watcher manually. The directory shows its name, node ID, approval source, broker source, and latest packet time.

Available actions are:

Replace: move the regional assignment and historical evidence to a new gateway ID that FreqMapper has already heard.
Remove approval: stop the gateway from acting as a Region Watcher while keeping historical wardrive evidence. An active broker may continue to list it as detected.

Read the confirmation carefully before either action.

Invite keys and radios

Region invite keys

Invite keys enroll connected radios into the selected region. When creating a key, choose:

an optional Label describing its purpose;
an expiry of 24 hours, 7 days, 30 days, or Never expires; and
a use count from 1 to 10,000, or Unlimited.

The full key is shown after creation. Codes created with the current encrypted-storage format can be revealed again by an authorized administrator; each reveal is recorded in Change history and appears only in that browser until hidden or the page is closed. Older codes were stored only as one-way hashes and cannot be recovered, so replace one if its original value has been lost.

A code's expiration can be reset to 24 hours, 7 days, 30 days, or Never expires without changing its remaining use limit. A nonexpiring key remains usable until its use limit is reached or an administrator revokes it. Select Revoke to stop future enrollments immediately.

Enrolled radios

The radio list contains only registrations created with that region's invite keys. It shows the radio name and node ID, mobile platform, app version, last-seen time, and revocation state.

Select Revoke when a registration should no longer be valid. This affects that FreqMapper enrollment; it does not erase or remotely control the physical radio.

MQTT brokers

Add a broker only when the region already operates it and has permission to provide the traffic to FreqMapper. FreqMapper subscribes read-only and copies matching Meshtastic traffic into its own broker. It does not publish traffic back to the regional broker or onto RF.

For a broker shared by several regions, add it from the Region Group control room instead. One Region Group connection covers every active descendant region, so the same credentials and topic filter do not need to be copied into Utah, Idaho, or their individual regions. Region Group traffic must still resolve to one exact descendant boundary, and Watcher evidence remains isolated to the Watcher's assigned region.

Each broker has these options:

Name: a recognizable local label.
Broker URL: use mqtts:// or wss:// when the connection leaves a private network.
Topic filter: the MQTT subscription used by the actual feed. On the official Meshtastic broker, the shared preset should use msh/. FreqMapper suggests a likely path from the region's country and radio settings, but it does not enforce that hierarchy: enter any concrete suffix published by the broker. England commonly uses EU_868, producing msh/EU_868/#, while a narrower EU_868/GB subtree can be used when packets are published there. United States regions commonly use a state path such as US/TX. Broader roots receive more traffic, but FreqMapper still rejects mapped locations outside the configured boundary.
Username and Password: optional credentials supplied by the broker operator.
Enabled: whether FreqMapper should currently use the source.

Passwords are encrypted on the server and are never returned to the browser. When editing a source, leave New password blank to keep the saved password. Use Pause for a reversible stop, Resume to start it again, Save broker settings to apply changes, or Remove to delete the source.

If the broker carries encrypted Meshtastic channels, open Connection and channel decoders after saving the connection. Add one exact channel name and Base64 PSK per encrypted channel that FreqMapper is authorized to decode. The page shows only a key fingerprint afterward. Removing a decoder stops future decoding for that channel; already-decoded packets and coverage are not rewritten. Already-decoded broker traffic does not need a decoder entry.

A Region Group broker can include its first decoder when it is created and applies to all active descendants. A region-owned broker is saved first, then its decoder profiles are added from the broker editor. Never copy a decoder key to an unrelated region or publish it in support material.

FreqMapper records every actual MQTT gateway ID separately for that broker. If the gateway's own clear Position packet is heard by any gateway on the same regional broker, FreqMapper can correlate the two source-scoped facts and make it a usable Watcher only when the position is inside the owning region. NodeInfo names are correlated the same way. Traffic from one regional broker cannot corroborate another region.

The broker panels show decoded and rejected packet counts, Position packets, Map Reports, accepted observations, boundary rejections, and the most recent useful packet. A broker that is connected but has no recently decodable traffic is shown as needing attention. Retained historical MQTT messages are ignored.

The broker list also reports connection and message activity when available. A broker that is saved but has no recent traffic may need its URL, credentials, topic filter, network reachability, or upstream publishing checked.

API access

Regional API access is for an approved server-side application that reads explicitly typed verified TX and passive RX coverage evidence. An individual-region key is limited to that region. A Region Group key covers the group's current member regions, including nested groups, and its readable scope follows membership changes automatically. The preferred endpoint supplies TX and RX through one cursor. Access does not include routes, packet identities or contents, private accounts, or Watcher identities.

Each regional console has its own API access section in the Section menu. A Region Group administrator uses the Region Group access rules both in the group console and when working in a member region. If the console does not offer an action to create a partner or replacement key, regional administrators can still review diagnostics and revoke existing keys. Contact a FreqMapper administrator or moderator when new access or a replacement key is needed.

To create partner access, provide:

an Application label;
an optional Purpose note; and
an initial key expiry of 90 days, 1 year, or No expiration.

Select Create partner and key. The full key is shown once and only its digest is stored, so copy it immediately to the application's server-side secret storage. Never put it in browser JavaScript, a mobile app, source control, screenshots, or support logs.

Issued access shows each partner, its purpose, creation time, key prefix, state, expiry, last use, and request count. Use overlapping keys for a safe rotation: create a replacement, confirm it works, then revoke the old key. Revoke partner disables every key belonging to that partner.

Expand Requests & settings for a key to manage and diagnose it:

set its rate limit from 1 to 10,000 requests per minute; the initial default is 120;
optionally reset the current request budget when saving;
view the latest 1,000 retained requests;
switch between all requests and errors only;
refresh or load older retained requests; and
review result codes, request type, duration, diagnosis, and request ID.

Request history does not store full keys, coordinates, raw cursors, or response bodies. Requests rejected before they reach the application may not appear there.

For the combined and type-specific integration contracts and response examples, see Partner coverage API.

Change history

Change history is the audit trail for regional administration. Use it to confirm who changed a setting, when it changed, and whether global-administrator preview authority was used. Sensitive values are not displayed as an ordinary history entry.

Important actions such as revealing a Watcher channel key are recorded. If you are diagnosing an unexpected change, note the time and actor before making another edit; that preserves a useful before-and-after trail.

Start-to-finish regional readiness checklist

Use this order for a new or rebuilt region:

Keep Data processing at Pending setup and Public visibility at Hidden while building.
Confirm the display name, country, mission policy, Position Packet policy, and mobile-radio limit.
Add and validate the boundary. Export or review the saved GeoJSON and check neighboring regions.
Add at least one other administrator or moderator so the region is not dependent on one account.
Publish a plain-language About section, current community links, and only the public mesh settings the community intends to share.
Configure a region or inherited Region Group MQTT source. Add only authorized channel decoders and confirm useful, current packet activity rather than relying on retained traffic.
Configure dedicated Watcher radios, then use the directory to distinguish detected gateways from approved Region Watchers with the correct regional placement.
Create a short-lived invite key, enroll one test radio, and confirm the mobile app prepares its managed channel without overwriting an existing one.
Run a controlled mapping test in a safe location. Confirm that the phone saved the test, a Region Watcher supplied the independent receipt, and the public details explain the result correctly.
Review Change history, the public Info panel, map layers, Watcher directory, and leaderboard scope.
Set Data processing to Active when ingestion is ready. Change Public visibility to Public only after the public pages are understandable and safe to share.

Do not activate a region based only on a connected broker. A usable region needs the correct boundary, current traffic, approved Watcher evidence, safe enrollment, and a verified end-to-end test.

Safe operating habits

Check the selected region before every save, import, replacement, removal, or revocation.
Export a boundary before replacing it when you want a separate offline copy.
Use labels that make invite keys, brokers, and API partners easy to identify later.
Prefer short-lived keys when long-term access is unnecessary.
Rotate credentials without creating an avoidable outage: add and verify the replacement before revoking the old value.
Report unexpected behavior with redacted screenshots and request IDs, never secrets.

Last updated: 2026-09-24