How FreqMapper works for mesh administrators

FreqMapper turns real Meshtastic traffic into a regional coverage map. It does not predict radio range and it does not trust a phone location by itself. The system combines information from a mapper's phone and radio with an independent report from an approved Watcher.

You do not need to replace your mesh, give FreqMapper control of routers, or run a separate FreqMapper server for your area. A local mesh administrator mainly helps define the region, arrange reliable read-only packet receipts, and coordinate who may map there.

The short version

For a useful regional map, FreqMapper needs:

A region with a name, short code, and reviewed boundary.
A local steward who can coordinate with the mesh community and maintain the regional setup.
At least one working Watcher that can hear the local mesh and send read-only MQTT receipts; two or more are strongly recommended.
A safe mapping policy that says whether mappers may use Active Patrol, or must use receive-only Silent Recon.
Mappers using the FreqMapper app with enrolled Meshtastic radios.

The boundary organizes the map. It is not a claim that the whole area has coverage.

Complete wardriving requirements

There are two wardriving modes. Active Patrol sends controlled mapping tests and listens for normal traffic. Silent Recon only listens. The region administrator decides whether both are allowed or whether the mesh must remain receive-only.

Requirement	Active Patrol	Silent Recon
Active FreqMapper region and enrolled radio	Required	Required
Connected, synchronized Meshtastic radio	Required	Required
Fresh, accurate phone GPS	Required	Required
Bluetooth and precise-location permission	Required	Required
Region's managed wardriving channel	Required	Not used for the trip
Approved Watcher receipt	Required to verify TX coverage	Not required to save eligible Received-here evidence
Phone internet	Required for first-time registration, enrollment, channel setup, and the first server-backed start. A short-lived saved approval can allow another offline start while the same radio, region boundary, and channel remain valid.	Required for first-time registration and enrollment. A previously configured app can record offline receive-only sessions.

Region and community setup

Before people wardrive, the mesh needs:

an active FreqMapper region with a reviewed boundary;
a regional administrator or other responsible local contact;
a clear decision that Active Patrol transmissions are acceptable, or a Silent Recon-only policy;
at least one approved, live Watcher for verified TX coverage, with two or more strongly recommended;
region invite keys for enrolling approved mapper radios; and
agreement on safe mapping practices, including local channel customs and where people may travel.

An invite key enrolls one connected radio into FreqMapper. It is not a Meshtastic channel key and should not be posted publicly.

The wardriving channel

Active Patrol requires the private shared FreqMapper wardriving channel. The mapper's radio sends controlled tests on this secondary Meshtastic channel, and Watchers used to report those tests must be able to receive the same channel. Mappers receive the approved configuration automatically during radio enrollment and should never publish its name or key.

The mapper does not need to copy the channel key manually. After the connected radio is enrolled, the FreqMapper app securely retrieves the region's channel configuration and adds or reuses it in an available secondary slot. The app:

never replaces the primary channel;
never overwrites an occupied secondary slot;
does not change the radio's LoRa region or modem preset;
does not change unrelated channels or MQTT settings; and
can remove only the matching temporary channel that it created when the mapper has enabled that option.

If the radio has no free secondary slot, the mapper must decide whether to remove an existing channel before Active Patrol can be prepared. FreqMapper will not make that decision automatically.

The radio must already use the correct LoRa region and a modem preset compatible with the local mesh. The mapper radio and Watcher also need the same exact wardriving channel configuration. A # may appear before the channel label in FreqMapper text, but it is not part of the Meshtastic radio channel name.

The channel name and key are private operational configuration. Mapper apps receive the configuration through enrollment. Regional administrators can reveal the Watcher setup from the Watchers section, with the reveal recorded in Change history. Share it only with approved Watcher operators—never in public Help, screenshots, issues, or chat.

Silent Recon does not transmit mapping tests and does not require the managed wardriving channel for that trip. It still requires an enrolled, connected radio because the app records eligible packets heard by that radio.

Mapper equipment and app setup

Each mapper needs:

the current FreqMapper app on a supported iPhone/iPad or Android phone;
a Meshtastic radio that can connect to the phone over Bluetooth and finish synchronization;
Bluetooth and precise-location permission enabled for FreqMapper;
the radio configured for the local mesh's LoRa region and modem preset;
a current region invite key for first-time enrollment;
a free secondary channel slot when Active Patrol must add the managed channel;
usable internet for first-time enrollment, channel retrieval, and the normal server-backed trip start; and
a fresh, accurate, non-simulated GPS fix when the trip begins and while evidence is recorded.

Once a connected trip is running, temporary phone internet loss does not stop radio mapping. The app queues supported trip records and uploads them after connectivity returns. Bluetooth, GPS, and the radio connection must remain available.

The mapper should confirm the expected region, Watcher status, mission, and radio readiness before leaving. A passenger should operate the app when interacting with it would distract the driver.

Watcher and MQTT setup

For controlled tests to become verified TX coverage, the region needs an independent evidence path:

a Meshtastic radio or gateway that can hear the local RF network;
the exact regional wardriving channel on that radio when reporting Active Patrol tests;
a reliable internet connection from the gateway to its MQTT broker;
permission from the broker/operator for FreqMapper to subscribe read-only;
an authorized decoder name and key for each encrypted mesh channel the source carries, unless the broker already provides decoded traffic;
a stable gateway ID that appears in the MQTT receipt;
actual recent receipts observed by FreqMapper; and
the Watcher assigned to the correct active region.

The local mesh team is responsible for choosing, installing, securing, connecting, and maintaining that hardware and MQTT path. FreqMapper does not create or operate the node, gateway, broker, internet connection, or local mesh. Once the source works, FreqMapper can privately confirm the approved mapping channel and radio settings, MQTT requirements, regional approval, and receipt flow.

The Watcher does not have to be the node that relayed the packet, and it does not have to be positioned publicly. A saved configuration without recent receipts is not enough to verify mapping tests.

How a result reaches the map

Controlled mapping tests

During Active Patrol, the mapper's phone records its GPS location and the connected radio sends a paced, tagged test on the region's managed mapping channel. The app uploads the test's identity and the phone location.

An approved Watcher independently reports that it heard the same radio packet. FreqMapper matches the sender, packet identity, region, and allowed time window. Only then does the sent-test location become verified TX coverage.

The coverage point belongs at the mapper's phone location, not at the Watcher. If the packet was relayed, Watcher signal readings describe the final radio hop into that Watcher; they do not prove the complete route through the mesh.

Receive-only mapping

During Silent Recon, the driving radio listens without sending mapping-test packets. FreqMapper can record eligible traffic heard on any configured channel at the driving phone's location as Received here evidence.

Received-here evidence is useful for finding activity and gaps, but it stays separate from verified TX coverage and does not earn mapping credit. A region can require Silent Recon when controlled tests are not appropriate.

Normal Position Packets

When regional policy allows it, a normal Meshtastic Position Packet can create separate Position Packet coverage if an approved Watcher actually receives it over radio. FreqMapper uses the sender-reported position and the Watcher's receipt quality for this layer.

Position Packet coverage is shown separately from controlled mapping tests and does not award mapper credit. MQTT-proxy traffic does not qualify as radio evidence.

What a Watcher is

A Watcher is the Meshtastic MQTT gateway that received and reported a packet. Its Meshtastic device role may be ROUTER, CLIENT, or another appropriate role. Watcher describes the node's evidence role in FreqMapper; it does not mean that the node is a ROUTER.

A Watcher must:

reliably hear the local Meshtastic network;
publish usable receipt metadata through an approved MQTT path;
have a stable gateway/node identity that FreqMapper has actually observed;
be assigned to the correct FreqMapper region; and
have the region's managed mapping channel when it needs to report controlled mapping tests.

FreqMapper reads from the approved MQTT source. It does not publish messages back to the regional broker or transmit onto the mesh. A claimed node ID, a map position, or a green status light by itself is not proof that a Watcher is working; FreqMapper must receive real packet receipts from it.

A public Watcher position is helpful but not required for verification. Without a usable position, the Watcher can still verify evidence; it simply cannot appear as a positioned eye marker on the map.

What the regional administrator is responsible for

The regional administrator is the local steward inside FreqMapper. This can be the mesh administrator, or another trusted person working with them.

Typical responsibilities are:

agree on a practical boundary with nearby communities;
keep the region name, status, and mapping policy current;
keep data processing and public visibility deliberate while the region is being built;
publish accurate public information and official community radio settings;
confirm Watcher operators have consented and their sources remain healthy;
assign, replace, or remove Watchers when equipment changes;
create and revoke app enrollment invite keys;
remove old radio enrollments when appropriate;
add a regional MQTT source only when authorized to do so;
give read-only access to moderators who need to review the region; and
protect channel keys, broker credentials, invite keys, and API keys.

The Regional Admin console does not remotely control Meshtastic nodes. Revoking a radio affects its FreqMapper enrollment; removing Watcher approval stops future regional verification while preserving historical evidence.

Information to gather before requesting a region

Have the following ready:

Region identity: a plain-language name and proposed IATA-style short code.
Boundary: a reviewed GeoJSON polygon or a clear list of counties/areas from which one can be made.
Local contact: at least one person willing to maintain the regional setup.
Watcher plan: the node IDs and operators for at least one live candidate Watcher, plus how its receipts reach MQTT.
Broker authority: confirmation that the broker operator permits FreqMapper's read-only subscription, if a regional broker must be added.
Mapping policy: whether controlled Active Patrol tests are acceptable or the region should use Silent Recon only.
Mapper plan: a few people willing to enroll their radios and collect initial evidence.

Do not send broker passwords, channel keys, or other secrets in a public request. Private configuration is exchanged only through the approved setup process.

What is not required

A region does not need:

a separate FreqMapper deployment or public website;
administrator access to every radio in the mesh;
changes to unrelated primary channels, modem presets, or router settings;
every mapper to operate a Watcher;
a known public location for every Watcher; or
predicted propagation data presented as measured coverage.

FreqMapper is one shared system with regional views and policies. Mappers use their own phones and radios, while independent Watchers provide the evidence needed to keep the map honest.

Go-live checklist

A region is ready to become active when:

its name and boundary have been reviewed;
data processing is Active and public visibility is intentional;
a responsible regional administrator is assigned;
at least one Watcher is delivering real receipts and is assigned to the region;
the allowed mapping mode is set;
enrollment invite keys can be issued safely;
at least one mapper can connect an enrolled radio and start a trip; and
a controlled test can be matched to a Watcher receipt, if Active Patrol is enabled.

Two or more Watchers are strongly recommended. They improve resilience and provide more independent evidence, but multiple receipts still do not reveal the exact RF route.

Next steps

To propose a new area, follow Start a FreqMapper region. After regional access is granted, use Regional administration for every available console setting and safe operating step. For mapper setup, see Getting started.

Last updated: 2026-09-24