diff --git a/docs/admins.md b/docs/admins.md index 41b303f..7ae9523 100755 --- a/docs/admins.md +++ b/docs/admins.md @@ -6,7 +6,7 @@ The **MeshMapper Admin Portal** is a restricted area designed for region maintai Access to the Admin Portal is strictly controlled. It is not available to general users. - - **How to get access:** Reach out to one of the [MeshMapper administrators](https://wiki.meshmapper.net/administratorlist/) to get credentials. + - **How to get access:** If the region has an administrator, ask them for an invite. If it has no administrator, ask a Moderator in the MeshMapper Discord for help with access. See [Finding Your Region's Administrators](administratorlist.md). ## Dashboard & Active Sessions @@ -32,6 +32,10 @@ This tab allows granular control over individual data points (pings). ### Repeaters Manage the repeaters database. +If an unknown repeater appears, first check whether an observer has received an advert with a valid name. A repeater heard only in wardriving discovery can appear as a **Ghost** without a name or fixed location. An admin can add or correct its record in the **Repeaters** tab, then check whether it is **Pending**, **Inactive**, or **Excluded**. Do not assign a guessed location to a moving device. + +A repeater can appear on a grouped map because that map reads the group's member regions. Its region record is separate from the region your browser is showing. Check the region column before editing it. After a repeater moves, a new advert can update its position unless **Lock GPS Coordinates** is on. Earlier pings do not move with it. + - **Add/Edit:** Manually register repeaters or update their details (Name, Location, Power, Hop Bytes). - **Status Control:** - **Active:** The default state. The repeater is visible on the map, included in leaderboards, and actively associating with coverage pings. @@ -125,28 +129,19 @@ The **Administrators** tab displays all admin accounts that have been granted ac - **Name:** The username of the administrator account. - **Contact:** The contact information on file for the administrator (e.g., Discord handle, email). - **Region:** On multiregion admin panels, each administrator's entry will display which sub-regions they have been granted access to. - - **Status:** Indicates whether the administrator has completed registration. - - **Active:** The administrator has claimed their account and set a key. - - **Pending Registration:** The administrator has been invited but has not yet claimed their account. + - **Status:** Shows whether access is active or the invitation is still pending. #### Adding a New Administrator -Region admins can invite new administrators directly from this tab by clicking **+ Add Administrator**. - - 1. **Username** *(required)*: Choose a username for the new administrator. If the administrator already has an account, a notice will appear and the form will switch to "Grant Access" mode — submitting will add your region to their existing access. - 2. **Contact Info** *(required)*: Enter the new administrator's contact information (e.g., Discord handle or email). - 3. **Region Assignment** *(required)*: Select which region the new administrator should have access to. On multiregion admin panels, you can assign the administrator to the multi-region group or to an individual sub-region. +In your region's **Administrators** tab, click **+ Add Administrator**, enter the person's email address, and select a region you administer. MeshMapper emails an invite bound to that address. If email delivery fails, the panel shows a link you can pass to that person. The invite expires after seven days. A global administrator can also grant a region directly to an existing verified MeshMapper account. -For **new administrators**, an invite link will be generated. Copy the link and send it to the new administrator. Invite links expire after **7 days**. For **existing administrators**, a confirmation will display that access to the region has been granted — no invite link is needed. - -Pending invites are displayed below the administrators table, showing the username, region, who sent the invite, and when it expires. Invites can be deleted before they are claimed. +Pending invites can be revoked or resent from the panel. #### Registration -New administrators claim their account by visiting the invite link sent to them. The link opens a confirmation page showing their username, assigned region, and who invited them. Clicking **Accept Invite & Create Account** generates their password. +Open the invite with the matching email or Discord account. Sign in to your existing MeshMapper account, or create one and choose your own password. Accept the invite to add the region. Sign in to the admin panel with that same account. -!!! warning "Password" - The password is shown **only once** during registration. The new administrator must copy it immediately. After logging in for the first time, they can change their password from the **User Settings** tab. +Forgot your password? Use **Forgot password** on the [portal](portal.md). If your account uses Discord sign-in, choose **Sign in with Discord**. The bot does not issue replacement credentials. ## Maintenance Tools @@ -352,6 +347,8 @@ See [Pending Repeater Links](#pending-repeater-links) for how to resolve the ale #### Stale Ping Cleanup (Auto-Delete Orphaned Pings) +To clear coverage left behind by a repeater that moved or was removed, first review the **Stale Ping Cleanup** preview. Save a retention window for automatic cleanup, or use **Backfill Purge Now** for eligible old orphaned pings after reviewing its count. The purge is permanent; do not use it merely to hide a repeater from the map. + **Default: Disabled. Options: Disabled / 30 / 60 / 90 days. DESTRUCTIVE.** Ages out **orphaned** pings — ones whose repeater has moved more than 100 m away or vanished entirely. These are the pings the map already shows as **"(Gone)"**. A ping only counts as orphaned when *every* repeater on it is gone; anything still resolving is kept. @@ -488,4 +485,4 @@ Link your Discord to MeshMapper to receive DM's from the MeshMapper bot. These events are also available as **webhook** subscriptions, configured separately in the Settings tab. See [Webhooks](https://wiki.meshmapper.net/webhooks/). -Webhooks can also be configured per-region to send these same notifications to any HTTPS endpoint (Slack, Home Assistant, custom automation, etc.). See [Webhooks](https://wiki.meshmapper.net/webhooks) for setup instructions. \ No newline at end of file +Webhooks can also be configured per-region to send these same notifications to any HTTPS endpoint (Slack, Home Assistant, custom automation, etc.). See [Webhooks](https://wiki.meshmapper.net/webhooks) for setup instructions. diff --git a/docs/app_connection_guide.md b/docs/app_connection_guide.md index 9592667..ceae901 100644 --- a/docs/app_connection_guide.md +++ b/docs/app_connection_guide.md @@ -72,6 +72,8 @@ When you tap a device, MeshMapper runs through nine steps automatically. You can ## Zone Authentication +If **Zone check failed** appears, wait for an accurate, current GPS fix and confirm that your location is inside an active MeshMapper region. The app may report a stale clock, weak GPS, a disabled region, or an unreachable server as separate errors. If your area has no region, use [onboarding](onboarding.md) rather than choosing an unrelated region code. + MeshMapper uses a zone-based authentication system. The server checks your GPS coordinates and tells you which zone you are in (if any). Each zone has a code (like "YOW" for Ottawa) and a set of rules configured by the regional admin: **Session permissions:** diff --git a/docs/app_getting_started.md b/docs/app_getting_started.md index b856b51..c5b8f57 100644 --- a/docs/app_getting_started.md +++ b/docs/app_getting_started.md @@ -22,6 +22,13 @@ Welcome to MeshMapper, a community-driven wardriving app for MeshCore mesh netwo - You can also grab the [APK from GitHub](https://github.com/MeshMapper/MeshMapper_Project/releases/) if you prefer sideloading - **iOS:** [Get it on the App Store](https://apps.apple.com/us/app/meshmapper/id6758073991) +**Beta releases:** + +In the MeshMapper Discord server, open **Channels & Roles** and select **Yes** for beta testing. Then choose your platform: + +- **iOS:** [Join the beta in TestFlight](https://testflight.apple.com/join/PXxfr5Jr). +- **Android:** [Download the beta APK from GitHub](https://github.com/MeshMapper/MeshMapper_Project/releases/), or [add MeshMapper to Obtainium](https://apps.obtainium.imranr.dev/redirect?r=obtainium://app/%7B%22id%22%3A%22net.meshmapper.app%22%2C%22url%22%3A%22https%3A%2F%2Fgithub.com%2FMeshMapper%2FMeshMapper_Project%22%2C%22author%22%3A%22MeshMapper%22%2C%22name%22%3A%22MeshMapper%22%2C%22preferredApkIndex%22%3A0%2C%22additionalSettings%22%3A%22%7B%5C%22includePrereleases%5C%22%3Atrue%2C%5C%22fallbackToOlderReleases%5C%22%3Atrue%7D%22%2C%22overrideSource%22%3A%22GitHub%22%7D) to follow prereleases. + **Web (Chrome/Edge only):** - [wd.meshmapper.net](https://wd.meshmapper.net) diff --git a/docs/app_troubleshooting.md b/docs/app_troubleshooting.md index 286b072..9a83ce0 100644 --- a/docs/app_troubleshooting.md +++ b/docs/app_troubleshooting.md @@ -144,6 +144,10 @@ This is **normal behavior**: ## Data Upload Issues +If your phone has internet but the app says **Server Unreachable**, the app could not reach MeshMapper's services. Try again after checking [system status](systemstatus.md), or use offline mode and upload the saved session later. A working browser connection alone does not prove the MeshMapper service is reachable. + +If pings are missing from the map, check that the upload queue has cleared, the correct region map and time filters are selected, and your session was inside an active region. The map and leaderboards update on different schedules. See the upload checks below before repeating a drive. + ### Queue keeps growing but nothing uploads **Causes:** diff --git a/docs/botcommands.md b/docs/botcommands.md index 822621e..320cc1e 100644 --- a/docs/botcommands.md +++ b/docs/botcommands.md @@ -20,7 +20,7 @@ For example, both of these work: | `!bug {description}` | Submits a bug report to GitHub. Can also reply to a message to use its content as the description. The bot first asks you to confirm (react ✅) after checking the [Troubleshooting](troubleshooting.md) page. The bot uses AI to generate a concise title. Rate limited to 5 per user per hour. | | `!issue {description}` | Alias for `!bug`. | | `!feature {description}` | Submits a feature request to GitHub. Works like `!bug` but creates a feature request instead (no confirmation step). | -| `!resetpassword` | Resets your own admin password if your Discord name matches an account in the system. New credentials are sent via DM. | +| `!resetpassword` | Points you to **Forgot password** on the MeshMapper portal. If you use Discord sign-in, no password is needed. The bot does not reset passwords or send credentials. | | `!myissues` | Lists your bug reports and feature requests that were submitted through the bot and their current status. | !!! note "Additional Commands" diff --git a/docs/embedding.md b/docs/embedding.md index 7c72ab0..09fb1d5 100644 --- a/docs/embedding.md +++ b/docs/embedding.md @@ -97,6 +97,8 @@ https://yow.meshmapper.net/embed.php?lat=45.4034&lon=-75.7258&geofence=0 ## Repeater ID Grid +Use this grid to check whether a repeater ID prefix is available, already deployed, in conflict, or reserved. Open a cell to inspect its current status before choosing a prefix for a new repeater. + You can also embed the Repeater ID Usage grid — a 16×16 visual showing which first-byte repeater IDs are available, deployed, in conflict, or reserved in a region. ### Embed URL diff --git a/docs/faq.md b/docs/faq.md index fd9b9e1..a3b80ac 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -11,7 +11,7 @@ MeshMapper is completely free to use. The platform is community-driven and maintained by volunteers. ??? question "How do I get my region added to MeshMapper?" - Visit the [Onboarding New Regions](https://wiki.meshmapper.net/onboarding) page for a step-by-step guide on how to request a new region. You'll need to join the MeshMapper Discord server to get started. + Use the [new region form](onboarding.md). You need a valid email address and an observer sending data to the MeshMapper or LetsMesh MQTT broker. Linking Discord is optional. ??? question "What is a region?" A region is a geographic area on MeshMapper that has its own map, administrators, and settings. Regions are typically centered around a city or metropolitan area. Some regions are grouped into multi-region setups that share a single map view. @@ -63,6 +63,9 @@ ??? question "Do I lose leaderboard points when Smart Pinging holds a ping?" No. Each square where a ping was held is reported to MeshMapper, checked against the region's own coverage data, and credited at 1.5 points once verified. Verified squares also count toward the Airtime Saver, Airtime God and Airtime Legend awards and the Top Airtime Savers board. Like the rest of the leaderboard, the credit appears after the next daily update. +??? question "Do coverage tiles expire when a repeater moves or disappears?" + Coverage remains until its underlying pings are removed or filtered out. An admin can enable [stale ping cleanup](admins.md#stale-ping-cleanup-auto-delete-orphaned-pings) for pings whose repeater moved or vanished, or preview and confirm a one-time purge. A time filter can hide older tiles without deleting their data. + --- ## Mobile App @@ -73,19 +76,119 @@ ??? question "How does the app connect to my MeshCore device?" The app communicates with your MeshCore device over Bluetooth. See the [Connection Guide](app_connection_guide.md) for pairing instructions and troubleshooting tips. +??? question "How do I join the app beta?" + In the MeshMapper Discord server, open **Channels & Roles** and select **Yes** for beta testing. Then use [TestFlight for iOS](https://testflight.apple.com/join/PXxfr5Jr) or the [GitHub APK for Android](https://github.com/MeshMapper/MeshMapper_Project/releases/). Android users can also [add MeshMapper to Obtainium](https://apps.obtainium.imranr.dev/redirect?r=obtainium://app/%7B%22id%22%3A%22net.meshmapper.app%22%2C%22url%22%3A%22https%3A%2F%2Fgithub.com%2FMeshMapper%2FMeshMapper_Project%22%2C%22author%22%3A%22MeshMapper%22%2C%22name%22%3A%22MeshMapper%22%2C%22preferredApkIndex%22%3A0%2C%22additionalSettings%22%3A%22%7B%5C%22includePrereleases%5C%22%3Atrue%2C%5C%22fallbackToOlderReleases%5C%22%3Atrue%7D%22%2C%22overrideSource%22%3A%22GitHub%22%7D) to follow prereleases. + +??? question "How do I claim a repeater I administer?" + Sign in to your MeshMapper account in the app, connect your companion, select the repeater on the map, then tap **Manage**. Sign in with the repeater's admin password and tap **Claim**. The claim lists your account as a repeater administrator on the map. + +??? question "Why does the app say my companion is unknown?" + The server has not recognized that radio's public key yet. Use the official MeshCore app to advertise the companion on the mesh, wait for an observer to receive it, then reconnect to MeshMapper. Check that you are in an active region with an observer. + +??? question "Does MeshMapper work with CarPlay or Android Auto?" + The iOS Live Activity can appear as a small CarPlay dashboard card on supported iOS versions. There is no full CarPlay map or Android Auto screen in the app. Android audio is designed to duck and release car audio during app sounds. + +??? question "What happens when I drive across a region boundary?" + The app pauses if it is outside every active region. When it enters another region, the server can transfer the active session to that region and the app resumes after zone authentication. A multiregion group provides a shared map for neighboring regions. Keep GPS accurate and watch the zone indicator on a long drive. + +??? question "Can I wardrive from an airplane?" + No. The app blocks or ends wardriving when GPS indicates aircraft travel. The server also flags suspiciously fast uploaded sessions for administrator review. Map an area from the ground instead. + --- ## Administration ??? question "How do I become a region administrator?" - Region administrators are assigned during the onboarding process when a new region is created. If you'd like to help administer an existing region, reach out to the current administrator or a Moderator on Discord. + For a new region, volunteer in the [onboarding form](onboarding.md#volunteer-as-region-administrator). For an existing region, ask its administrator for an invite. If the region has no administrator, ask a Moderator in the MeshMapper Discord for help with access. ??? question "Where can I find my region's administrator?" - A full list of region administrators is available on the [Administrator List](https://wiki.meshmapper.net/administratorlist) page. + Open **Region Info** on your region's map. See [Finding Your Region's Administrators](administratorlist.md) for other ways to reach them. ??? question "I'm an admin. Where do I manage my region?" Region administrators can manage settings, repeaters, and sessions through the Admin Portal. See [Admin Portal](admins.md) for details. +### Region setup and access + +??? question "How do I rename my region?" + Ask a global administrator to change its display name. The region editor in the global admin panel controls the name; the region's own settings panel does not. + +??? question "What if my region's administrator is inactive?" + Contact a Moderator through the [administrator contact guide](administratorlist.md). A global administrator can grant region access to another verified MeshMapper account, so an inactive administrator does not have to issue the invite. + +??? question "How do I split or merge regions?" + Coordinate the new boundaries with neighboring admins, then ask a global administrator. The global panel can merge whole regions, including their sessions, or move pings within a selected area. An area transfer does not move whole sessions. Changing a boundary alone does not move earlier data. + +??? question "How big should my region be?" + Draw a boundary around the mesh you expect to map and coordinate it with nearby regions. The onboarding form checks for substantial overlap, and the MeshMapper team reviews each request. See [Defining the Boundary](onboarding.md#defining-the-boundary). + +??? question "Can I use any three letters as my region code?" + No. Pick a recognized IATA airport code near your area. The form checks that the code is available and geographically appropriate; it will suggest nearby codes when one is too far away. See [The Onboarding Form](onboarding.md#the-onboarding-form). + +??? question "Why does the form say my code is already used or pending?" + A code can belong to only one active or pending region. Open that region's subdomain to check its pending status, and contact a Moderator if the request appears stuck. Do not submit another region with a made-up code. + +??? question "Why did my onboarding submission fail?" + Read the error shown by the form. It checks the airport code, region name, email, coordinates, radius, boundary polygon and overlap with existing regions. Correct the reported field and retry; if the form says you have submitted too often, wait a few minutes. + +??? question "Does my area already have a region?" + Check the [MeshMapper region map](https://meshmapper.net) before starting a request. If a nearby region can reasonably expand to include your area, contact its administrator first. The new-region form checks for overlap with existing boundaries. + +??? question "My observer is online. Why is onboarding still pending?" + The pending request must receive observer reports tagged for its region code through a supported MQTT broker. A connected observer that has sent no matching reports does not complete verification. Check the pending status page and [observer setup](mqtt-main.md), then wait for manual approval once verification passes. + +??? question "Which code should an observer use? Can a region have aliases?" + Set the observer's IATA topic to the region code shown in MeshMapper. Each region has one code; a multiregion group joins separate coded regions for a shared map. If you need the code changed, ask a global administrator instead of publishing under an unrelated code. + +??? question "How do I get a Discord region-admin role?" + Admin panel access and the Discord role are separate. The bot assigns the role when a Moderator grants access through the bot, but an email invite may not update Discord. If your admin access works and the role is missing, ask a Moderator to check it. + +??? question "Why has my admin invite not arrived?" + Check the email address used by the inviting admin and your spam folder. The inviter can resend or revoke a pending email invite from the admin panel. Bot-issued invites go by Discord DM, so allow DMs from the server if that route was used. + +??? question "Why am I no longer listed as an admin?" + Sign in with the MeshMapper account that received the invite and check that it was accepted. If the region is absent from that account, ask a global administrator to check its current region access. The admin panel checks current permissions when you open it. + +??? question "How do admins work in a multiregion group?" + A group administrator can work across the group's member regions; a member-region administrator keeps access to that region. Ask a global administrator to grant the group or additional region to the right verified account. See [Multiregion Administration](multiregions.md#administration). + +??? question "What if my admin login stopped working after an account change?" + Use the [portal](portal.md) **Forgot password** flow or **Sign in with Discord** for the account you linked. If login succeeds but your region is missing, ask a global administrator to check its access grant. The bot cannot reset an admin password. + +??? question "Is a separate portal account needed for each region?" + No. One verified MeshMapper account can hold access to several regions. The same login works on the portal and on each admin panel you are allowed to use. + +??? question "Why do my region's wardriving settings revert?" + If your region belongs to a multiregion group, its radio presets are controlled by the group and copied to member regions. Change them in the group admin panel, or ask a group administrator. For a standalone region, save the preset in its own **Settings** tab and check for any save error. + +??? question "What does the traffic scope setting do?" + **Wardriving Scope** is the scope the app sends its own pings in. **Scopes to Monitor** controls which scopes the map looks for in heard traffic. The wardriving scope and scopes reported by local repeaters are included automatically; add other scopes only when you need to track them. + +??? question "Can my region keep wardriving traffic within its own scope?" + Set the **Wardriving Scope** in the region or group admin settings for the radio preset your app uses. This chooses the scope of the app's outgoing pings; **Scopes to Monitor** only affects what the map tracks and does not constrain those pings. + +??? question "Why does my region map open in the wrong place?" + A single-region map starts at the region's stored centre; a group map starts around its members. Your browser may also remember a zoom level. A region admin can adjust the boundary editor's centre pin; ask a global administrator if the region's stored centre or name needs correction. + +??? question "Where do I edit my region description, contact details or channels?" + Open your region's admin panel and use **Settings** for the region message, links and public channels. Your own contact details are under **User Settings**. Ask a global administrator to change the region's display name. + +??? question "How do I group several companions under one contributor?" + Link your own devices to one [portal account](portal.md#linking-your-companion-devices). Region admins can also group companions in the admin panel's **Users** tab so their contributions appear together on leaderboards. + +??? question "Can duplicate leaderboard entries or old device data be merged?" + Link the devices you still control to one portal account. If the old device cannot be linked, ask a region administrator to inspect its companion record and the **Users** grouping. Do not delete an account or device record to try to merge history. + +### Portal accounts + +??? question "Where do I link Discord, and is it required?" + Sign in to the [portal](portal.md), open your account settings, and choose **Connect Discord**. It is optional for an ordinary account. A Discord-bound admin invite must be accepted while signed in with the invited Discord account. + +??? question "Why did Discord linking fail?" + If the portal says that Discord account is already linked elsewhere, sign in to the other MeshMapper account or ask a Moderator for help. If the sign-in expired or was cancelled, start the connection again from the portal. Do not create a third account to work around it. + +??? question "Can I merge or remove duplicate MeshMapper accounts myself?" + There is no account-merge button in the portal. Pick the account you want to keep and ask a Moderator to review the duplicate before deleting anything. A Discord account and a companion device can each be linked to only one portal account at a time. + --- ## Support & Contributing @@ -115,9 +218,9 @@ The publicly available API's are [listed here](https://wiki.meshmapper.net/coverage-api) and require the use of a provisioned API key. ??? question "Can I have access to the MeshMapper MQTT broker or raw data?" - No. MeshMapper is not a data broker. + MeshMapper does not offer a public raw MQTT feed. For tools that need map coverage data, use the documented [Coverage API](coverage-api.md) and request an API key. A region admin can configure a broker that sends observer reports *to* MeshMapper; that is separate from read access to MeshMapper's collected data. ??? question "Is MeshMapper open source? Can I run a local copy?" The MeshMapper wardriving app for Android and iOS is open source. It can also natively be configured to send wardriving data to additional endpoints outside of MeshMapper. - The MeshMapper web interface is not open source and cannot be run locally. The MeshMapper development team has put time, effort, and money into developing a tool that can be used and is accessible to all globally without the requirement/complexity/cost of any per-region/local configuration of code, servers, MQTT engines, hosting, etc. Part of MeshMapper's appeal is global leaderboards and comparing region by region, which is not possible unless made a global platform. \ No newline at end of file + The MeshMapper web interface is not open source and cannot be run locally. The MeshMapper development team has put time, effort, and money into developing a tool that can be used and is accessible to all globally without the requirement/complexity/cost of any per-region/local configuration of code, servers, MQTT engines, hosting, etc. Part of MeshMapper's appeal is global leaderboards and comparing region by region, which is not possible unless made a global platform. diff --git a/docs/layers.md b/docs/layers.md index ddade1a..db39680 100755 --- a/docs/layers.md +++ b/docs/layers.md @@ -209,6 +209,8 @@ The search functionality combines quick lookups with powerful filtering options. ### Filter Map Data Clicking the **Filter** pill (tune icon) in the navigation bar opens the **Filter Map Data** panel. Filters are applied server-side — the coverage grid, click popups, charts, and ping history all reflect the same filtered dataset. Active filters appear as removable chips, and the Filter pill shows a count and lights up cyan while filters are active. +To see several neighboring regions together, open their [multiregion group map](multiregions.md) if one exists. The global homepage is a region index; use a region or group map for its coverage tiles. + - **Time**: - **Show data from**: All time, Last 30 days, Last 90 days, or Last year. - **From date / To date**: Specify a custom date range. diff --git a/docs/mqtt-main.md b/docs/mqtt-main.md index c3423b4..6df9d1b 100644 --- a/docs/mqtt-main.md +++ b/docs/mqtt-main.md @@ -1,6 +1,6 @@ # MeshMapper MQTT Setup -An **MQTT observer** is a MeshCore node that acts as the "ears" of MeshMapper — it listens for mesh traffic and publishes it to an MQTT broker, where MeshMapper picks it up for processing. Each region needs at least one observer connected to the **MeshMapper** broker. +An **MQTT observer** is a MeshCore node that acts as the "ears" of MeshMapper. It listens for mesh traffic and publishes it to an MQTT broker, where MeshMapper picks it up for processing. A new region needs at least one online observer sending to either the **MeshMapper** or **LetsMesh** broker. MeshMapper recommends its own broker. ## MeshMapper Broker @@ -35,8 +35,7 @@ This method runs directly on a Heltec V3 or V4 board with no companion device ne - **Requires**: A Heltec V3 or V4 with the MQTT-enabled firmware flashed - **Best for**: The simplest hardware setup, since no secondary computer is needed -!!! note "Coming Soon" - Documentation for native MQTT firmware setup is in progress. +Community MQTT observer firmware is available for supported boards, including Heltec V3 and V4. One option is [Offband observer firmware](https://github.com/OffbandMesh/meshcore-firmware), which provides build, flashing and configuration instructions. Check its supported boards and broker settings before flashing. MeshMapper does not maintain that firmware. If you prefer a supported setup without custom firmware, use [MeshCore Packet Capture](mqtt-python.md) or [PyMC](mqtt-pymc.md). ### 4. PyMC @@ -45,3 +44,13 @@ This method uses the PyMC software, which handles MQTT configuration directly fr - **Requires**: A Raspberry Pi running PyMC - **Best for**: Anyone already running a PyMC repeater - **Guide**: [PyMC Repeater MQTT Setup](mqtt-pymc.md) + +## Common observer questions + +**Should I send to MeshMapper, LetsMesh or both?** Either broker can supply reports for MeshMapper. You may publish to both; MeshMapper combines reports from its configured brokers. One working broker is enough for onboarding. + +**Can I use a mobile observer?** It can submit reports while online, but a fixed, always-on observer is a better choice for a region's required listener. A mobile receiver cannot verify a new region while it is offline or away from that region. + +**Why is my observer not listed?** A broker connection by itself is not an observer report. Check that it publishes `status` or `packets` on the `meshcore///...` topic, using the region's code. Then check the region admin panel's **Observers** tab and the broker checkmarks. Allow time for the first report to arrive. + +**Can I run a regional MQTT broker?** A region admin can register a broker in **Settings**. Provide a reachable host and port, WebSockets transport, and its required authentication credentials. MeshMapper subscribes only to that region's topics; see [Observer verification](mqtt-pymc.md#verifying-your-observer) after saving. Do not publish broker credentials in a public channel. diff --git a/docs/mqtt-pymc.md b/docs/mqtt-pymc.md index 17ebece..1fa14ac 100644 --- a/docs/mqtt-pymc.md +++ b/docs/mqtt-pymc.md @@ -91,3 +91,5 @@ sudo journalctl -u pymc-repeater.service -f | grep MeshMapper ## Verifying Your Observer Once your observer is running and connected, it will appear in your region's **Admin Portal** under the [Observers tab](admins.md#observers) once packets have been received (repeater or companion adverts, or wardriving pings). You should see a checkmark under the broker(s) your observer is connected to. + +If PyMC says it is connected but MeshMapper shows no data, check PyMC's service logs for MQTT errors, then confirm the broker host, WebSockets, TLS and MeshCore token settings above. Confirm its IATA code matches the region and that it is publishing `status` or `packets`. An observer may appear before any repeater does: repeaters need a valid name and an advert received by an observer, and a region may hold new repeaters in **Pending** until an admin approves them. diff --git a/docs/mqtt-python.md b/docs/mqtt-python.md index 834e3bb..da234b0 100644 --- a/docs/mqtt-python.md +++ b/docs/mqtt-python.md @@ -63,6 +63,8 @@ For serial connections, the script will automatically detect connected devices. Enter your region's **3-letter IATA code** (e.g., `SEA`, `LAX`, `YOW`, `LON`). This identifies which MeshMapper region your observer belongs to. +Use the code of the region that should receive the observer's reports. MQTT topics carry this code, and MeshMapper's subscriber uses it when choosing a region. If your receiver covers several regions, coordinate with their admins rather than assuming one code will place the same report in every region. + ### 7. Owner Information (Optional) You may optionally configure: @@ -140,4 +142,4 @@ The systemd service includes built-in safeguards: ## Verifying Your Observer -Once your observer is running and connected, it will appear in your region's **Admin Portal** under the [Observers tab](admins.md#observers) once packets have been received (repeater or companion adverts, or wardriving pings) You should see a checkmark under the broker(s) your observer is connected to. \ No newline at end of file +Once your observer is running and connected, it will appear in your region's **Admin Portal** under the [Observers tab](admins.md#observers) once packets have been received (repeater or companion adverts, or wardriving pings) You should see a checkmark under the broker(s) your observer is connected to. diff --git a/docs/onboarding.md b/docs/onboarding.md index 89e53c8..cf4ba56 100755 --- a/docs/onboarding.md +++ b/docs/onboarding.md @@ -27,9 +27,9 @@ The form collects the following critical information: | **Region Radius** | A rough estimate (in km) of the area you intend to cover. | | **Region Boundary** | This is where you define your desired region boundary. We strongly encourage region admins to use geoJSON files and coordinate with neighboring regions when defining a region's boundaries. More information and geoJSON resources are available at [Region Boundaries](region_boundaries.md). | | **Email Address / Discord Notifications** | Enter your email address (required) and optionally - though encouraged - link your Discord account to receive notifications on the status of your application. | -| **Additional Notes** | Use this field to provide additional details or context about your application. If your desired region doesn't meet the [prerequisites](#Prerequisites) above and you believe an exception should be made, justify it in detail here. | +| **Additional Notes** | Use this field to provide additional details or context about your application. If your desired region doesn't meet the [prerequisites](#prerequisites) above and you believe an exception should be made, justify it in detail here. | | **Public Channels** | A list of public channels used in your mesh (e.g., `Chat`, `Emergency`). This helps the wardriving app correctly identify valid traffic. | -| **Volunteer as Administrator** | Optional but recommended. Tick this to volunteer as your region's administrator. Requires Discord to be linked. See [below](#volunteer-as-region-administrator) for details. | +| **Volunteer as Administrator** | Optional but recommended. Tick this to volunteer as your region's administrator. See [below](#volunteer-as-region-administrator) for details. | ## Volunteer as Region Administrator @@ -44,14 +44,12 @@ Enabling this option signals to the MeshMapper team that you are willing to take **Requirements:** - - You must **link your Discord account** before this option becomes available. The checkbox is disabled until Discord is connected. + - Provide an email address. Linking Discord is optional and lets you receive the invite by DM instead of email. - You must be genuinely active in your local mesh community. **What happens if you volunteer:** -When your region is approved and deployed, an administrator account will be automatically created for you. Your credentials (username and a generated key) will be sent to you via Discord DM. You should log in to your region's admin panel and change your key immediately after first login. - -*If you already have an administrator account on another MeshMapper region, access to the new region will simply be added to your existing account.* +When your region is approved, MeshMapper grants this region to your existing unified account or sends an invite bound to your email or linked Discord account. Open the invite, sign in or create your MeshMapper account, and accept it. The same account signs in to the portal and your region's admin panel. No generated admin key is sent. ## Defining the Boundary diff --git a/docs/portal.md b/docs/portal.md index fd54386..47be072 100644 --- a/docs/portal.md +++ b/docs/portal.md @@ -17,8 +17,8 @@ You can also reach it from any region map via the **About** menu → **My Portal Forgot your password? Use the **password reset** option on the login screen — a reset link is emailed to you (valid for 1 hour). -!!! info "Portal accounts vs admin accounts" - Portal accounts are for wardrivers and are separate from region **administrator** accounts (which are managed through the [Admin Portal](admins.md)). +!!! info "One account for the portal and admin panels" + A region administrator uses the same MeshMapper account for the portal and every [admin panel](admins.md) they can access. Accept an administrator invite or have access granted to your existing verified account. You do not need a separate admin login. --- diff --git a/docs/region_boundaries.md b/docs/region_boundaries.md index 3c39ac9..b7a5040 100644 --- a/docs/region_boundaries.md +++ b/docs/region_boundaries.md @@ -4,6 +4,12 @@ MeshMapper allows for different methods of defining a region's boundary using th All of the following methods are accessed via the admin panel for each region, under the `Settings` menu. Scroll to near the bottom of the page to reach the `Region Boundary` interface. +If a boundary change removed part of your area, open that editor and correct the polygon or re-import a saved GeoJSON file. The history records that a boundary changed, but it is not an undo button and does not keep a downloadable copy of the old shape. Ask a global administrator for help if you no longer have the original boundary. + +Use **Export GeoJSON** in the boundary editor to download the current shape. Save a copy before a large edit. + +Coordinate boundaries with neighboring region administrators. The onboarding form checks for substantial overlap, and the MeshMapper team reviews new requests before approval. + ## Radius Around a Point *Note: This method works best for isolated regions with no nearby neighbors, as adjacent neighboring regions will result in overlap or coverage gaps, resulting in potentially incorrect data inside overlaps or preventing seamless region transition for wardrivers crossing gaps.* diff --git a/docs/visuals.md b/docs/visuals.md index eaa3bf7..d38a990 100755 --- a/docs/visuals.md +++ b/docs/visuals.md @@ -59,6 +59,8 @@ One more square colour is not a ping type at all: ## Repeaters +**Ghost** means a ping identified a repeater by its full key, but that repeater has never been registered on this map, so MeshMapper does not know where to draw it. **Gone** means a repeater that was placed earlier can no longer be resolved for that ping. Neither label is a separate ping type. Ask a region admin to check the repeater's adverts and current record before changing coverage data. + ### Chip Anatomy A repeater is drawn as a small dark rounded chip carrying its hex ID: diff --git a/mkdocs.yml b/mkdocs.yml index 267e75e..3352dd0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -45,6 +45,7 @@ nav: - Administration: - Administrator List: administratorlist.md - Admin Portal: admins.md + - Region Boundaries: region_boundaries.md - Webhooks: webhooks.md - Coverage API: coverage-api.md - Zones API: zones-api.md