diff --git a/docs/app_how_it_works.md b/docs/app_how_it_works.md index 93a3173..0d69225 100644 --- a/docs/app_how_it_works.md +++ b/docs/app_how_it_works.md @@ -39,21 +39,21 @@ When you send a TX ping (manually or via auto-ping), you are sending a **channel 1. **Message composition**: GPS coordinates + TX power level 2. **Encryption**: AES-ECB with the #wardriving channel key (SHA-256 hash of "#wardriving"). ECB mode is mandated by the MeshCore protocol. 3. **Broadcast and flooding**: The encrypted message is sent via BLE as a GROUP_TEXT packet. It **floods the entire mesh** by default (every repeater relays it). If a **flood scope** is configured by the regional admin, only repeaters within the scope relay it. -4. **Echo listening (5-second window)**: After sending, the app opens a 5-second listening window. Every incoming packet is checked against these criteria: - - GROUP_TEXT type - - RSSI below -30 dBm (not a carpeater) - - Channel hash matches #wardriving - - Decrypted content matches what you sent - - Path length > 0 (traveled through at least one repeater) -5. **Deduplication**: Same repeater echoing multiple times? Only the best SNR is kept. -6. **Queuing**: After the 5-second window closes, the TX ping and its echo results are added to the **upload queue**. A 5-second flush timer starts. When it fires, the queue uploads. +4. **Echo listening (5-second window)**: After sending, the app opens a 5-second listening window. Every incoming packet is checked against these criteria, proceeding to step 5 if all of the following conditions are met: + - Packet is of the GROUP_TEXT type + - RSSI is NOT stronger (closer to zero) than -30 dBm (likely a vehicle-mounted "carpeater" if so). This can be overridden by the user in the MeshMapper app settings. + - Channel hash matches that of #wardriving + - Decrypted content matches that of the ping just sent + - Path length is > 0 (the packet has traveled through at least one repeater) +5. **Deduplication**: If the same packet is heard from the same repeater more than once, only the one with the best SNR value is kept. +6. **Queuing**: After the 5-second window closes, the TX ping and its echo results are added to the **upload queue**. A 5-second flush timer starts. When the timer expires, the queue uploads. ### TX vs RX Queuing TX pings are queued differently from RX observations: - **TX/DISC/Trace** go directly into the upload queue as a single item (the ping + its results from the listening window). A **5-second flush timer** triggers an upload shortly after. -- **RX observations** go through a **two-stage pipeline**: first the RX Logger batches by repeater (best SNR, 25m/30s flush), then the API queue buffers up to **4 RX entries per repeater** before flushing to the main queue. +- **RX observations** go through a **two-stage pipeline**: first the RX Logger batches by repeater (best SNR, 25 meter/30 second flush), then the API queue buffers up to **4 RX entries per repeater** before flushing to the main queue. --- @@ -71,29 +71,29 @@ RX packets aren't uploaded individually. Instead, they are **grouped by repeater **How it works:** -1. A packet arrives from repeater `A3B2FF` at your current GPS location +1. A packet arrives from a repeater at your current GPS location 2. The app creates a **batch** for that repeater, recording your GPS position and the packet's SNR/RSSI -3. More packets arrive from the same repeater. If a new packet has a **better SNR**, it replaces the previous one in the batch. Worse SNR packets are discarded. +3. More packets arrive from the same repeater. If a new packet has a **better SNR**, it replaces the previous one in the batch. Worse SNR packets are discarded, leaving only the **best SNR observation** to be sent to the API. 4. The batch keeps the **original GPS location** where you first heard that repeater (the map pin doesn't follow you as you move) -**The batch flushes (uploads) when either condition is met:** +**The batch flushes (uploads) when either condition below is met:** -- You move **25m** from where you first heard the repeater, OR +- You move **25 meters** from where you first heard the repeater, OR - **30 seconds** pass since the first observation -Whichever happens first. On flush, only the **best SNR observation** per repeater is sent to the API. After flushing, if you hear the same repeater again, a new batch starts at your new location. +After flushing, if you hear the same repeater again, a new batch starts at your new location. -**On disconnect or stopping auto-ping**, all active batches are flushed immediately so no data is lost. +**On disconnect or stopping auto-ping**, all active batches are flushed immediately, so no data is lost. --- ## How Discovery Pings Work -Discovery pings use a fundamentally different mechanism than TX channel messages. Instead of flooding the mesh, discovery sends a **direct control data request** to nearby repeaters. They do not propagate. +Discovery pings use a fundamentally different mechanism than TX channel messages. Instead of flooding the mesh, discovery sends a **direct control data request** (zero-hop) to nearby repeaters. Note: Only repeaters and room servers with firmware 1.10.0 or newer support and will respond to discovery pings. 1. **Request**: ControlData command (0x37) with DISCOVER_REQ flag, requesting responses from repeaters and rooms in direct range. Includes a random 4-byte tag for matching. 2. **Response**: Repeaters respond with node type, public key, and their assessment of signal quality from their end (remote SNR). -3. **Tracking**: Discovery Tracker collects responses during a 5-second window, deduplicates by public key, and filters carpeaters. Gives you **bidirectional** signal quality (how you hear them + how they hear you). +3. **Tracking**: Discovery Tracker collects responses during a 5-second window, deduplicates by public key, and filters carpeaters. Gives you **bidirectional** signal quality (how you hear them & how they hear you). 4. **Upload**: "DISC" type data with repeater public key, node type, and bidirectional signal quality. --- @@ -117,18 +117,18 @@ Every packet goes through a strict validation pipeline before being accepted. If - Packet must have traveled through **at least one repeater** (path length > 0) - Direct transmissions from nearby devices are not repeater coverage data -### 2 CARpeater ID check (optional) +### 2 Vehicle-mounted "CARpeater" ID check (optional) -- If you have configured a CARpeater filter with a repeater hex ID: +- If you have configured a CARpeater filter with a repeater hex ID in the MeshMapper app settings: - **Single hop** from your CARpeater → **dropped** (this is just your own repeater relaying back to you, no real coverage info) - **Multiple hops** with CARpeater as last hop → CARpeater hop is **stripped**, second-to-last hop used as the real repeater (the packet traveled through a distant repeater first, then your CARpeater delivered it to you. The distant repeater is the real coverage data, your CARpeater just happened to be the final relay. SNR/RSSI are set to null since they reflect your CARpeater's signal, not the distant repeater's.) ### 3 RSSI check (CARpeater failsafe) -- Signal must be **weaker than -30 dBm** -- Anything stronger = device is right next to you (carpeater) +- Signal must be **weaker (farther from zero) than -30 dBm** +- Anything stronger implies the relaying node is right next to you (likely a carpeater) - Acts as a safety net even without the CARpeater ID filter -- Skipped if RSSI filter is disabled in Settings or CARpeater hop was already stripped +- Skipped if the Disable RSSI Filter option is ENABLED in app Settings or if CARpeater hop was already stripped ### 4 Packet type check @@ -160,7 +160,7 @@ Every packet goes through a strict validation pipeline before being accepted. If Without this pipeline, the coverage map would be polluted with: -- **False coverage data** from CARpeaters (your own co-located repeater always reporting perfect signal) +- **False coverage data** from CARpeaters (your own vehicle-mounted repeater always reporting perfect signal) - **False repeater IDs** from corrupt or non-conforming packets that partially decode, causing phantom repeaters to appear in the path with garbage data ### After validation @@ -169,7 +169,7 @@ Validated packets enter the RX batching pipeline (see [How RX Observations Work] 1. **Grouped by repeater ID** (last hop in path, the repeater that delivered the packet to you) 2. **Best SNR kept** per repeater. If multiple packets arrive from the same repeater, only the one with the strongest SNR is retained. GPS location is pinned to where you **first** heard that repeater. -3. **Flushed to upload queue** when you move **25m** from the first observation OR **30 seconds** pass, whichever comes first +3. **Flushed to upload queue** when you move **25 meters** from the first observation OR **30 seconds** pass, whichever comes first 4. The upload queue then buffers up to **4 RX entries per repeater** before adding them to the main batch for API upload --- @@ -182,6 +182,7 @@ The noise floor is the ambient radio energy when no intentional signals are pres - Included with every data point uploaded (TX, RX, DISC, Trace) - Helps the community understand the radio environment at each coverage point - The noise floor graph overlays ping events on the timeline for visual correlation +- Values are reported as dBm departure from a device's 10th percentile baseline to account for variances between hardware types. See [How Calibration Works](https://wiki.meshmapper.net/layers/#how-calibration-works). --- @@ -200,11 +201,11 @@ All wardriving data (TX, RX, DISC, Trace) flows through a single persistent uplo ## Carpeater Filtering -"Carpeater" (car + repeater) = a repeater mounted in/on your vehicle. Always has a very strong signal, does not provide useful coverage data. +A "carpeater" (car + repeater) is a repeater mounted in/on your vehicle. It will always have a very strong signal and does not provide useful coverage data. **Two filter methods:** -1. **RSSI threshold**: RSSI ≥ -30 dBm → automatically dropped (device is right next to you) +1. **RSSI threshold**: RSSI equal to or stronger (closer to 0) than -30 dBm → automatically dropped (device is right next to you) 2. **User-configured repeater ID**: Specify your repeater's hex ID in Settings > Filtering > CARpeater Filter. Echoes from that repeater are stripped before upload. Both can be adjusted or disabled in Settings for testing. @@ -223,7 +224,7 @@ Each packet carries a "path" showing which repeaters it traveled through, with e - Configurable in Settings > Radio > TX Bytes (firmware 1.14+ required) - RX auto-detects path size regardless of your TX setting -- Some regions enforce a specific path size via the regional admin +- Regional administrators can require a specific TX path setting in the admin panel --- diff --git a/docs/app_settings_reference.md b/docs/app_settings_reference.md index a4808a0..ece59fd 100644 --- a/docs/app_settings_reference.md +++ b/docs/app_settings_reference.md @@ -37,7 +37,7 @@ Complete reference for every setting in MeshMapper, organized by section. ### Anonymous Mode -- Renames your companion device to **"Anonymous"** on the mesh +- Renames your companion device to **"Anonymous"** on the mesh (requires a clean disconnect to reset your node name) - Changing while connected triggers a brief reconnection - Confirmation dialog when enabling or disabling while connected - Cannot change while auto-ping is running @@ -116,7 +116,7 @@ If you're wardriving with a repeater mounted in your vehicle or nearby ("CARpeat ### Disable RSSI Filter -By default, the app drops any packet with RSSI ≥ -30 dBm because a signal that strong almost certainly came from a co-located repeater, not meaningful coverage. Only disable this if you are certain no co-located repeater is within range. If disabled while a CARpeater is present, your device will report false coverage data to the MeshMapper community map, degrading accuracy for everyone. +By default, the app drops any packet with RSSI equal to or stronger (closer to 0) than -30 dBm because a signal that strong almost certainly came from a co-located repeater and is not meaningful coverage data. Only disable this if you are certain no co-located repeater is within range. If disabled while a CARpeater is present, your device will report false coverage data to the MeshMapper community map, degrading accuracy for everyone. - Default: Drops packets with RSSI ≥ -30 dBm (carpeater threshold) - Enabling allows **all signal strengths** through diff --git a/docs/app_wardriving_modes.md b/docs/app_wardriving_modes.md index bc8f874..a5edff5 100644 --- a/docs/app_wardriving_modes.md +++ b/docs/app_wardriving_modes.md @@ -61,7 +61,7 @@ No channel messages (no mesh flooding at all). Sends **discovery requests** ever 1. Every 30 seconds, sends a zero-hop discovery request (direct query, not a broadcast) 2. Repeaters/rooms respond with node type, public key, and signal quality (local + remote SNR/RSSI) -3. Discovery Tracker collects responses during a 5-second window, deduplicates by public key, and filters carpeaters +3. Discovery Tracker collects responses during a 5-second window, deduplicates by public key, and filters carpeaters (RSSI stronger than -30 or by user-configured prefix value) 4. Unified RX Handler monitors for mesh traffic on subscribed channels 5. All discovery responses and RX observations queued for upload diff --git a/docs/awards.md b/docs/awards.md index d6e3856..b4e2ff5 100644 --- a/docs/awards.md +++ b/docs/awards.md @@ -40,7 +40,7 @@ These are granted automatically by the system based on wardriving milestones: ### Manual Awards -Administrators can grant custom awards for special achievements, events, contest wins, donating to MeshMapper, or community contributions. +Master/Global Administrators can grant custom awards for special achievements, events, contest wins, donating to MeshMapper, or community contributions. ## Available Awards diff --git a/docs/duplicaterepeaterid.md b/docs/duplicaterepeaterid.md index 5c5df10..701dade 100755 --- a/docs/duplicaterepeaterid.md +++ b/docs/duplicaterepeaterid.md @@ -76,7 +76,7 @@ When a new repeater appears on the network with an ID that is indistinguishable The most effective solution is to upgrade your region's repeaters to firmware that supports **2-byte or 3-byte hops**. Once upgraded, update the **Hop Bytes** setting in your region's admin panel to match. As repeaters are heard with longer IDs, MeshMapper will automatically update their hop byte tracking and resolve false collisions. ### Hybrid Wardriving Mode -Wardrivers can choose to collect data in **Hybrid** mode, which utilizes **Discovery**, or **DISC**, packets. You can think of these packets as broadcasting "Hello, who's out there?", and any repeater within hearing distance (and with compatible firmware) will respond with their full Public ID. As we're not relying on only the short hop ID to make the association to the repeater, associations can be made even if the short ID of that particular repeater is in collision with another. +Wardrivers are encouraged to collect data in **Hybrid** mode, which utilizes **Discovery**, or **DISC**, packets. You can think of these packets as broadcasting "Hello, who's out there?", and any repeater within hearing distance (and with compatible firmware - 1.10+) will respond with their full Public ID. As we're not relying on only the short hop ID to make the association to the repeater, associations can be made even if the short ID of that particular repeater is in collision with another. !!! tip "Enforce Hybrid Mode" If a region is large and contains many duplicate ID's, region administrators can choose to "Enforce Hybrid Mode" for their region. This will prevent any **Active** wardriving from occuring in the region by automatically enabling Hybrid mode for wardrivers. The option is available in the regional admin panel. @@ -120,4 +120,4 @@ MeshCore now supports multi-byte repeater hop identification, available in **fir | --- | --- | --- | | **1 byte** | ~254 | Small regions with few repeaters | | **2 bytes** | ~65,536 | Most regions | -| **3 bytes** | ~16,777,216 | Very large deployments | \ No newline at end of file +| **3 bytes** | ~16,777,216 | Very large deployments | diff --git a/docs/index.md b/docs/index.md index fb7c7fc..6b8bead 100755 --- a/docs/index.md +++ b/docs/index.md @@ -26,7 +26,7 @@ MeshMapper was desiged to provide realistically reliable data without making ass - **Association:** For every data point, repeaters involved in its transmission are associated based on their GPS coordinates. **If a repeater is ever relocated, all links to its coverage data are broken** to ensure actual coverage is not skewed. - **Authentication:** Every wardriving session is validated against known mesh nodes. -MeshMapper believes in the ownership and control of how a regions data is presented lies with the region itself. If a region chooses to bypass logic to limit false or misleading data, that is their choice, and visitors to their map will be warned as such. +MeshMapper believes in the ownership and control of how a regions data is presented lies with the region itself. If a region chooses to bypass logic designed to limit false or misleading data, that is their choice, and visitors to their map will be warned as such. Repeater owners can easily [opt out of being publicly listed](https://wiki.meshmapper.net/layers/#private-repeaters) on the map. ## The Wardriving App @@ -60,4 +60,4 @@ The map provides objective data on hardware performance. You can see exactly how MeshMapper is developed by **MrAlders0n** and **CSP-Tom** of the Greater Ottawa Mesh Radio Enthusiasts. While MeshMapper is 100% free to use, your support helps us cover the backend resources and development time needed to keep up with the rapid global growth. If MeshMapper has helped you, [feel free to buy us a coffee](https://buymeacoffee.com/meshmapper)! ## And More! -There's much more to learn and explore. Click the links to the left to navigate to different articles. \ No newline at end of file +There's much more to learn and explore. Click the links to the left to navigate to different articles. diff --git a/docs/layers.md b/docs/layers.md index ed7b9c0..1665189 100755 --- a/docs/layers.md +++ b/docs/layers.md @@ -50,12 +50,12 @@ These layers display the actual mesh network data. You can toggle them on or off | Layer Name | Description | | --- | --- | -| **BIDIR** | **Green** grid squares showing confirmed two-way coverage. | -| **TX** | **Orange** grid squares where packets were sent but no confirmation was received. | -| **RX** | **Purple** grid squares where packets were heard but no transmission occurred. | +| **BIDIR** | **Green** grid squares showing confirmed two-way coverage (the sender heard a repeat AND the packet was also heard by at least one observer after being repeated). | +| **TX** | **Orange** grid squares where packets were sent but no confirmation was received (no repeat heard by the sender but the packet was repeated and heard by at least one observer). | +| **RX** | **Purple** grid squares where other repeated mesh traffic was heard by the meshmapper companion. | | **DISC / TRACE** | **Cyan** grid squares showing Node Discovery and Trace packets. | -| **DEAD** | **Grey** grid squares where a repeater heard the ping, but it didn't route further. | -| **DROP** | **Red** grid squares showing failed pings (no route, no repeats). | +| **DEAD** | **Grey** grid squares where a repeater heard the ping, but it didn't route further (sender heard a repeat but no observer did). | +| **DROP** | **Red** grid squares showing failed pings (neither the sender nor any observers heard repeats of the packet). | | **Repeaters** | The icons representing repeater nodes. | | **Repeater Coverage** | When a repeater is clicked, this layer draws dashed blue lines to all locations where that repeater was heard. Useful for visualizing the effective footprint of a specific repeater. | | **Adv. Repeater Coverage** | Similar to standard Repeater Coverage, but colour-codes the lines and grid squares based on the connection type (Green=BIDIR, Orange=TX, etc.) instead of using a uniform blue. Lines are labelled as **In** or **Out** to indicate whether the ping originated inside or outside the region boundary. | @@ -76,18 +76,18 @@ The **Noise Heatmap** is an optional overlay that visualizes the RF noise enviro Every companion reports a **noise floor** reading (in dBm) with each ping it submits. The noise floor represents the level of background RF interference the radio is experiencing at that location. A reading closer to 0 dBm is "loud" (lots of interference), while a very negative value like -120 dBm is "quiet." -Because different radios and antennas report different absolute noise values, MeshMapper doesn't display the raw readings directly. Instead, it calculates a **noise delta** — how much louder or quieter a location is compared to that user's personal baseline. +Because different radios and antennas report different absolute noise values, MeshMapper doesn't display the raw readings directly. Instead, it calculates a **noise delta** — how much louder or quieter a location is compared to that device's baseline. #### How Calibration Works MeshMapper automatically calibrates each companion's baseline: 1. After enough data has been collected (at least 5 readings), MeshMapper calculates the companions's **10th percentile** noise floor — essentially the quietest conditions that companion typically experiences. -2. This becomes the companions's personal **baseline**. +2. This becomes the companions's **baseline**. 3. Every data point is then scored as a **delta** (difference) from that baseline. -4. Every day a new calibration is done to update that companions noise delta. +4. Every day a new calibration is done to update that companion's noise delta. -For example, if your companion's baseline is **-110 dBm** and you submit a reading of **-90 dBm**, the delta is **+20** — meaning that location is 20 dB noisier than your typical quiet conditions. +For example, if your companion's baseline is **-110 dBm** and you submit a reading of **-90 dBm**, the delta is **+20** — meaning that location is 20 dB (100X) noisier than your device sees under typical quiet conditions. This per-companion calibration ensures that readings from different hardware/setups are comparable on the same map. All readings for a single location are averaged and displayed accordingly. @@ -163,4 +163,4 @@ Operators can opt-out of location sharing by appending the "no entry" emoji ( - **Map**: The Name, Location, and ID are removed from the map and the **Repeaters** layer. - **Pings**: Coverage pings are kept and visible in the grid layers, but the repeater details are masked. - - **Leaderboards**: The name is replaced with "(private repeater)", but stats are still calculated. \ No newline at end of file + - **Leaderboards**: The name is replaced with "(private repeater)", but stats are still calculated. diff --git a/docs/onboarding.md b/docs/onboarding.md index b526004..5f3c7f6 100755 --- a/docs/onboarding.md +++ b/docs/onboarding.md @@ -53,7 +53,7 @@ When your region is approved and deployed, an administrator account will be auto One of the most important steps is defining the geographic boundary of your region. - **The Map Tool**: The form includes an interactive map with drawing tools. - - **Draw Polygon**: You must use the **Polygon Tool** (pentagon icon) to draw a precise shape around your coverage area. + - **Draw Polygon**: Use the **Polygon Tool** (pentagon icon) to draw a precise shape around your mesh's coverage area if a circle doesn't accurately describe it. - **Import GeoJSON**: Alternatively, click the **Import GeoJSON** button to paste GeoJSON data directly. This is useful if you already have a boundary defined in another tool (e.g., [geojson.io](https://geojson.io)). Supported formats include `Polygon`, `MultiPolygon`, `Feature`, and `FeatureCollection`. - **Region Center**: The center pin automatically moves to the center of the polygon when one is drawn or imported. You can also drag the pin manually if needed. This determines where your region appears on the global map. - **Purpose**: This polygon is used to: @@ -78,4 +78,4 @@ If you associated your Discord account during the onboarding process, you will r ## Legacy Data -If you have historical coverage data from other systems, it can be imported into MeshMapper. This data will appear on a separate layer and is not included in leaderboard statistics. See [Data Upload](https://wiki.meshmapper.net/dataupload/) for format requirements. \ No newline at end of file +If you have historical coverage data from other systems, it can be imported into MeshMapper. This data will appear on a separate layer and is not included in leaderboard statistics. See [Data Upload](https://wiki.meshmapper.net/dataupload/) for format requirements.