diff --git a/README.md b/README.md index 68b015a6..92d60fe4 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Open-source Flutter client for MeshCore LoRa mesh networking devices. MeshCore Open is a cross-platform application for communicating with MeshCore LoRa mesh radios over Bluetooth Low Energy (BLE), USB serial, or TCP. The app enables long-range, off-grid communication through peer-to-peer messaging, public channels, and mesh networking capabilities. -**Website:** [meshcoreopen.org](https://meshcoreopen.org/) +**Website:** [meshcoreopen.org](https://meshcoreopen.org/) · **Network map:** [map.meshcoreopen.org](https://map.meshcoreopen.org/) Get it on Obtainium diff --git a/docs/PRIVACY_POLICY.md b/docs/PRIVACY_POLICY.md index 6737012e..bd7bf6de 100644 --- a/docs/PRIVACY_POLICY.md +++ b/docs/PRIVACY_POLICY.md @@ -1,6 +1,6 @@ # Privacy Policy for MeshCore Open -**Last Updated:** September 27, 2026 +**Last Updated:** October 11, 2026 ## Introduction @@ -11,7 +11,7 @@ MeshCore Open ("the App") is an open-source Flutter application for communicatin ### Data We Do NOT Collect MeshCore Open does **not**: -- Collect personal information for the developer +- Collect personal information for the developer. The optional network map upload described below sends anonymized radio data only if you turn it on - Track your usage or behavior - Use analytics services - Require account creation @@ -54,7 +54,7 @@ Required by Android for BLE scanning on Android 11 and below. MeshCore Open does ### Internet Permission - **INTERNET** -Used for features that access third-party internet services, including map tiles, Line-of-Sight elevation lookups, optional model downloads, GIF search/display, and optional URL image previews. +Used for features that access third-party internet services, including map tiles, the MeshCore Open network map, Line-of-Sight elevation lookups, optional model downloads, GIF search/display, and optional URL image previews. ### Notification Permission - **POST_NOTIFICATIONS** (Android 13+) @@ -70,6 +70,39 @@ Used to maintain BLE connection with your MeshCore device while the app is in th Camera access is used for contact and community QR scanning. Photo-library access is used when you select a photo for mesh image messaging. Selected photos are encoded locally for transmission over the mesh; the App does not upload them to a model service for inference. +## MeshCore Open Network Map + +The MeshCore Open project runs a public network map at [map.meshcoreopen.org](https://map.meshcoreopen.org). It shows MeshCore repeaters, room servers, the links between them, traffic and measured coverage. + +### Viewing the map +When you use the Online or Both view on the App's map, the App requests map data for the area on screen from `map.meshcoreopen.org`. These requests include the visible map area and expose your device's IP address to the server as part of normal internet communication. Viewing the map never uploads anything. + +### Sharing data (opt-in) +Uploading is **off by default**. The first time a radio connects, the App asks once whether you want to share; you can also turn it on or off at any time in **Settings → App settings → Network map**. Turning it off stops uploads immediately and discards anything waiting to be sent. + +While sharing is on and a radio is connected, the App sends the following about once a minute: + +- **Packet headers** for packets your radio hears: payload type, route type, the repeater path hashes, hop count, signal strength (SNR/RSSI), size rounded to 16 bytes, a one-way packet fingerprint used to count duplicates, and the time rounded to the minute. +- **Repeater and room server adverts** with a valid signature: public key, name, node type and advertised location. +- **Your radio's position and settings**, if the radio has a position: rounded to a grid of about 2 km, plus its frequency, bandwidth, spreading factor and coding rate. +- **A random install ID** that changes every 24 hours. + +All locations are rounded to the ~2 km grid on your phone before upload, and the map shows them only as hexagons. + +The App never uploads message text or payloads, channel or community names, keys or hashes, direct-message sender or recipient hashes, region transport codes, exact coordinates, your contact list, or information about chat or sensor nodes beyond the header-only packet records above. + +### How the server handles uploads +- **IP addresses are not stored or logged.** The server uses your IP address in memory to rate-limit uploads and to check whether a request comes from a hosting provider. To count how many independent people reported something, it keeps a keyed hash of your network prefix (the /24 IPv4 or /48 IPv6 block) until the end of the day. The key changes daily and is discarded, after which these hashes cannot be linked to an address; they are then deleted. +- **Retention:** individual packet and advert records are deleted after 7 days. Hourly and daily totals (for example, the number of packets a link carried in a day) are kept longer to draw 30-day views. +- **Public data:** repeater names, rough locations, links, traffic totals and coverage are shown publicly on the map and in the App. + +Uploaded records are not linked to an account, name or device identity, so the project cannot find or delete a particular person's records; they expire on the schedule above. + +### Hiding a repeater +Repeater and room server owners can remove their node from the map by putting the 🚫 emoji anywhere in its name and sending a flood advert. Its name and location are then removed from the map, and the packet viewer shows it only as an anonymous repeater with its public key. Location traces tied to it, such as which areas heard it, are deleted too. To show it again, remove the emoji; it reappears with its first advert after 7 days without one. + +See the map's [privacy page](https://map.meshcoreopen.org/privacy) for more detail. + ## Third-Party Services ### Map Tiles @@ -99,6 +132,9 @@ The App includes a GIF picker feature powered by Giphy. When you use the GIF sea GIF search is optional and activated through the picker. Displaying a GIF reference received in a chat also requests image content from Giphy’s CDN, even if you did not perform a search. See [Giphy's Privacy Policy](https://support.giphy.com/hc/en-us/articles/360032872931-GIPHY-Privacy-Policy) for more information about how they handle data. +### Device Purchase Link (Seeed Studio) +The connection screen shows a link to buy a MeshCore device from Seeed Studio. The link contains a MeshCore Open affiliate code, so the project may earn a commission on purchases made through it, at no extra cost to you. The App sends nothing to Seeed Studio unless you tap the link; tapping it opens Seeed Studio's website in your browser, where Seeed Studio's own privacy policy applies. + ### URL Image Previews and Custom Model URLs When URL images are enabled for a contact or channel, supported links in messages can cause requests to the referenced image host, sharing-page provider, or IPFS gateway. These services receive the requested URL and normal connection information, including your IP address. Requests may occur when chat content is displayed rather than only after tapping the link. Disable URL images in the contact/channel settings to disable this preview feature. @@ -131,4 +167,4 @@ If you have questions about this Privacy Policy or the App's privacy practices, --- -**Summary**: MeshCore Open does not use the phone's GPS for location, does not include analytics, and does not collect personal information for the developer. Some optional features communicate with third-party services, including map tile providers, Open-Meteo for LOS elevation lookups, Hugging Face for model downloads, Giphy for GIF search/display, and image hosts/gateways for enabled URL previews. +**Summary**: MeshCore Open does not use the phone's GPS for location, does not include analytics, and does not collect personal information for the developer. If you opt in, the App uploads anonymized packet headers, repeater adverts and ~2 km rounded locations to the MeshCore Open network map; the server does not store IP addresses and deletes raw records after 7 days. Some optional features communicate with third-party services, including map tile providers, Open-Meteo for LOS elevation lookups, Hugging Face for model downloads, Giphy for GIF search/display, and image hosts/gateways for enabled URL previews. diff --git a/documentation/README.md b/documentation/README.md index af6c73bb..9053cf05 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -1,6 +1,6 @@ # MeshCore Open - Feature Documentation -MeshCore Open is an open-source Flutter client for MeshCore LoRa mesh networking devices. These guides describe current user-facing features and their requirements. Reviewed against app `9.5.0+16`, including region-display merge `5eca459e`, on September 27, 2026. Hardware behavior still depends on platform, radio, and firmware. +MeshCore Open is an open-source Flutter client for MeshCore LoRa mesh networking devices. These guides describe current user-facing features and their requirements. Reviewed against app `9.5.0+18` on October 11, 2026. Hardware behavior still depends on platform, radio, and firmware. ## Start here @@ -11,22 +11,24 @@ MeshCore Open is an open-source Flutter client for MeshCore LoRa mesh networking ## Table of Contents -1. [Scanner & Connection](scanner-and-connection.md) - BLE scanning, USB serial, and TCP connection +1. [Scanner & Connection](scanner-and-connection.md) - BLE scanning, USB serial, and TCP connection with automatic reconnect 2. [Navigation](navigation.md) - App flow, device screen, and quick-switch navigation -3. [Contacts](contacts.md) - Contact management, groups, discovery, and sharing -4. [Chat & Messaging](chat-and-messaging.md) - Direct messages, message status, reactions, and retries -5. [Channels](channels.md) - Broadcast channels, communities, and channel chat -6. [Map & Location](map-and-location.md) - Node map, path tracing, line-of-sight, and offline caching +3. [Contacts](contacts.md) - Contact management, groups, discovery, nearby-node scan, discovered-contact import/export, and sharing +4. [Chat & Messaging](chat-and-messaging.md) - Direct messages, location sharing, message status, reactions, and retries +5. [Channels](channels.md) - Broadcast channels, communities, channel chat, and auto-resend +6. [Map & Location](map-and-location.md) - Node map, shared pins, path tracing, line-of-sight, and offline caching 7. [Settings](settings.md) - Device settings, app settings, radio configuration, and exports 8. [Notifications](notifications.md) - System notifications, replies from watches and Android Auto, unread badges, and notification preferences 9. [Repeater Management](repeater-management.md) - Repeater hub, status, CLI, telemetry, and neighbors 10. [Additional Features](additional-features.md) - GIF picker, localization, debug logs, SMAZ compression, and more 11. [Routing Paths](routing-paths.md) - Path encoding, validation, device capability detection, and storage 12. [BLE Protocol & Data Layer](ble-protocol.md) - Technical reference for the communication protocol and data architecture -13. [Regions](regions.md) - Default/override scopes, message labels, and reply regions +13. [Regions](regions.md) - App and radio default regions, unscoped sends, message labels, and reply regions 14. [Image Messages](image-messages.md) - Model setup, mesh image sending, recovery, and reconstruction 15. [Companion Radio Statistics](radio-statistics.md) - Noise, signal metrics, and airtime 16. [Troubleshooting](troubleshooting.md) - BLE, USB, browser, and firmware issues +17. [Review Mode](review-mode.md) - Simulated radio and reviewer instructions for Google Play and App Store review +18. [Network Map](network-map.md) - Online repeater map, adding and managing repeaters from it, opt-in uploads, and hiding a repeater ## App Overview @@ -37,6 +39,8 @@ MeshCore Open connects to MeshCore LoRa mesh radios over BLE, USB, or TCP. Once - **View nodes on a map** with GPS locations, predicted positions, and path traces - **Manage repeaters** with CLI access, telemetry, neighbor info, and settings - **Share contacts** via `meshcore://` URIs and QR codes +- **Share locations** as map pins from chat or the map +- **Scan for nearby nodes** and import/export discovered contacts - **Configure radio settings** including frequency, power, bandwidth, and spreading factor - **Cache offline maps** for use without internet connectivity - **Analyze line-of-sight** between nodes with terrain elevation profiles @@ -52,6 +56,7 @@ MeshCore Open connects to MeshCore LoRa mesh radios over BLE, USB, or TCP. Once | Model downloads | Internet required | | GIF search/display and URL image previews | Internet required to retrieve content | | Map display | Cached tiles work offline; uncached tiles need internet | +| Online network map and opt-in uploads | Internet required | | Terrain LOS analysis | Elevation lookup needs internet unless the required data is already cached | ## Keeping documentation current diff --git a/documentation/additional-features.md b/documentation/additional-features.md index c1e2fe76..9a110020 100644 --- a/documentation/additional-features.md +++ b/documentation/additional-features.md @@ -52,7 +52,8 @@ A list of nodes heard passively over the air but not yet added as contacts. Each - Sort by last seen or name; filter by type - **Tap**: Import the contact (adds to your contact list) - **Long-press**: Add Contact, Copy `meshcore://` URI to clipboard, or Delete -- Overflow menu → "Delete All" (with confirmation) +- Overflow menu → "Export discovered contacts", "Import discovered contacts", or "Delete All" (with confirmation). See [Contacts](contacts.md#export-and-import-discovered-contacts) +- Radar icon → **Scan for nearby nodes** (firmware version code 8+). See [Contacts](contacts.md#scan-for-nearby-nodes) - Already-known contacts and your own node are filtered out --- diff --git a/documentation/ble-protocol.md b/documentation/ble-protocol.md index a8a67bf3..88f83dc3 100644 --- a/documentation/ble-protocol.md +++ b/documentation/ble-protocol.md @@ -112,7 +112,7 @@ On unexpected disconnection, auto-reconnect with exponential backoff: | 40 | CMD_GET_CUSTOM_VAR | Get custom variables | | 41 | CMD_SET_CUSTOM_VAR | Set a custom variable | | 50 | CMD_SEND_BINARY_REQ | Send binary request | -| 54 | CMD_SET_FLOOD_SCOPE_KEY | Set flood routing scope (v8+; `cmdSetFloodScope` in the app) | +| 54 | CMD_SET_FLOOD_SCOPE_KEY | Set flood routing scope (v8+; `cmdSetFloodScope` in the app). `[54,0,key16]` sets, `[54,0]` clears the override (radio default scope then applies), `[54,1]` sends unscoped (firmware code 12+) | | 55 | CMD_SEND_CONTROL_DATA | Send control data (e.g. zero-hop discovery, v8+) | | 56 | CMD_GET_STATS | Request companion radio stats | | 57 | CMD_SEND_ANON_REQ | Send anonymous request | @@ -120,6 +120,8 @@ On unexpected disconnection, auto-reconnect with exponential backoff: | 59 | CMD_GET_AUTO_ADD_CONFIG | Get auto-add configuration | | 61 | CMD_SET_PATH_HASH_MODE | Set path hash width (bytes per hop) | | 62 | CMD_SEND_CHANNEL_DATA | Send GRP_DATA image chunks (firmware code 11+) | +| 63 | CMD_SET_DEFAULT_FLOOD_SCOPE | Store the radio's default flood scope: `[63][name 31, NUL padded][key 16]`, or `[63]` to clear (firmware code 11+) | +| 64 | CMD_GET_DEFAULT_FLOOD_SCOPE | Read the radio's default flood scope (firmware code 11+) | ## Response / Push Codes (Device → App) @@ -146,6 +148,7 @@ On unexpected disconnection, auto-reconnect with exponential backoff: | 24 | RESP_CODE_STATS | Companion radio stats | | 25 | RESP_CODE_AUTO_ADD_CONFIG | Auto-add flags | | 27 | RESP_CODE_CHANNEL_DATA_RECV | Received GRP_DATA image chunk | +| 28 | RESP_CODE_DEFAULT_FLOOD_SCOPE | `[28][name 31][key 16]`, or `[28]` alone when no default is set | | 0x80 | PUSH_CODE_ADVERT | Known contact re-seen | | 0x81 | PUSH_CODE_PATH_UPDATED | Better path found; carries the 32-byte public key of the updated contact | | 0x82 | PUSH_CODE_SEND_CONFIRMED | Delivery ACK from remote; carries ACK hash (4 bytes) + trip time (4 bytes) | @@ -195,13 +198,17 @@ UUID, name, 32-byte secret, hashtag channel list. Shared via QR code. Message/contact metadata and preferences use `SharedPreferences` (JSON-serialized); there is no SQLite database. Model bundles, received image bitstreams/reconstructions, and map caches use files. Region metadata is persisted with channel messages; older records without it load with a null region. +Per-channel data is keyed by a channel ID, not the radio slot: `` is the first 8 bytes of SHA-256(`"meshcore-channel:"` + PSK) as 16 hex characters, so a reused slot starts clean and a re-added channel gets its history back. Each channel sync saves the slot-to-ID map (`channel_slot_ids_`) and reloads any slot whose channel changed since the last connection; queued channel messages are not fetched until that map is confirmed. Older slot-keyed data is moved once per radio (`channel_storage_v2_`) using the cached channel list; slots with no cached PSK keep their old keys unread. + | Data | Storage Key Pattern | Scope | |---|---|---| | Contacts | `contacts` | Per device identity | | Messages | `messages_` | Per device + contact | -| Channel Messages | `channel_messages_` | Per device + channel | +| Channel Messages | `channel_messages__` | Per device + channel | | Channels | `channels` | Per device identity | -| Channel Order | `channel_order_` | Per device identity | +| Channel Order | `channel_order_` (list of channel IDs) | Per device identity | +| Channel Slot Map | `channel_slot_ids_` | Per device identity | +| Channel Settings | `channel_{smaz,cyr2lat,url_images}__`, `channel_cyr2lat__profile_` | Per device + channel | | Contact Groups | `contact_groups` | Per device identity | | Communities | `communities_v1` | Per device identity | | Unread Counts | `contact_unread_count` | Per device identity | @@ -209,7 +216,7 @@ Message/contact metadata and preferences use `SharedPreferences` (JSON-serialize | App Settings | `app_settings` | Global | | Path History | `path_history_` | Per contact | | Region Names | `regions` | Global | -| Channel Region | `channel_region_` | Per device + channel | +| Channel Region | `channel_region__` | Per device + channel | | Default Region | `default_region_` | Per device identity | ## Auto-Add Configuration Bitmask @@ -272,6 +279,6 @@ Reactions use `r::`. Channel replies ## Regions and image data -Transport-routed raw packets include four transport-code bytes before packed path metadata. For transport floods, the app matches the first two code bytes against locally known region candidates using HMAC-SHA256 over `[payloadType][payload]`. Region scope keys are the first 16 bytes of SHA256 of `#`. The name itself is not carried as plain text. Unknown or ambiguous matches remain null; see [regions](regions.md). +Transport-routed raw packets include four transport-code bytes before packed path metadata. For transport floods, the app matches the first two code bytes against locally known region candidates using HMAC-SHA256 over `[payloadType][payload]`. Region scope keys are the first 16 bytes of SHA256 of `#`. The radio's default flood scope is also a candidate, matched on the key the radio reports (it may have been set by another client). The name itself is not carried as plain text. Unknown or ambiguous matches remain null; see [regions](regions.md). Image chunks use `CMD_SEND_CHANNEL_DATA` (62), `RESP_CODE_CHANNEL_DATA_RECV` (27), and application data type `0xAE1C`. The framing, capacities, metadata byte, and XOR recovery algorithm are defined in [image_chunk_transport.dart](../lib/services/image_chunk_transport.dart), which is the source of truth. See [image messages](image-messages.md) for user requirements and limitations. diff --git a/documentation/channels.md b/documentation/channels.md index d3c68a1f..2f4e55fa 100644 --- a/documentation/channels.md +++ b/documentation/channels.md @@ -48,20 +48,24 @@ Pull-to-refresh (swipe down) forces a re-fetch of channels from the device firmw Tap the "+" FAB to open a dialog with six options: -1. **Create Private Channel** — Enter a name (max 31 characters); a random PSK is generated +1. **Create Private Channel** — Enter a name (max 31 bytes of UTF-8, so fewer characters for accented letters, Cyrillic, or emoji); a random PSK is generated 2. **Join Private Channel** — Enter a name and a 32-hex PSK (non-hex characters like spaces and dashes are silently stripped, so pasted keys with formatting are accepted) 3. **Join Public Channel** — One tap; uses the well-known public PSK (only shown if no public channel exists) 4. **Join Hashtag Channel** — Enter a hashtag name; PSK is derived from the name. If communities exist, choose between regular hashtag (SHA-256) or community hashtag (HMAC) 5. **Scan Community QR** — Opens QR scanner to join a community 6. **Create Community** — Enter a name; generates a random 32-byte secret; optionally adds a community public channel; shows QR code for sharing +Name limits count the `#` and any community prefix, so the name stored on the radio matches what you typed and others derive the same key. Adding a channel is blocked until the channel list has finished syncing from the radio (a snackbar says the channels are still loading), and the free slot is picked when you confirm, so an existing channel is never overwritten. + ## Channel Actions (Long-Press / Right-Click) | Action | Description | |---|---| | Edit | Change name, PSK (with a dice icon to generate a random PSK), SMAZ compression toggle (compresses outgoing messages to allow longer text within the byte limit), Cyr2Lat encoding toggle (transliterates Cyrillic to Latin for compatibility), or "Enable URL images" toggle (previews image links; requires internet) | | Mute / Unmute | Toggle push notification suppression for this channel | -| Delete | Remove the channel from the device (confirmation required) | +| Delete | Remove the channel from the device and delete its messages, settings, region and images (confirmation required) | + +Channel history and settings belong to the channel's key, not its slot on the radio. A slot reused for another channel (here or in another app) starts empty, editing a channel's PSK starts a fresh history, and adding a channel again with its old PSK brings its history back. ## Channel Chat @@ -85,7 +89,7 @@ Tap a channel card to open the channel chat screen. - **Pinch-to-zoom**: Two-finger zoom (0.8x–1.8x) and double-tap to reset text size - **Message tracing mode** (when enabled in App Settings): Each bubble additionally shows path prefix bytes (`via XX,YY,...`), a timestamp, and a repeat count icon -Messages also show a region label when known, independently of message tracing. The [message-region guide](regions.md#regions-displayed-on-messages) explains why some incoming messages have no label. +Messages also show a region label when known, independently of message tracing. By default the region chip sits below the hop count; turn on **Region next to hop count** in App Settings → Messaging to show both on one line. The [message-region guide](regions.md#regions-displayed-on-messages) explains why some incoming messages have no label. ### Message Types in Chat @@ -110,6 +114,12 @@ Messages also show a region label when known, independently of message tracing. - **All platforms**: Long-press (or right-click on desktop) a message bubble → "Path" - Opens the Channel Message Path Screen (see [Additional Features](additional-features.md)) +### Channel Auto-Resend + +With **Resend channel messages until they travel far enough** on (App Settings → Messaging), the app waits after each channel send and checks how far the message was heard repeated. If no repeat reached the required hop count, it sends the message again, up to the configured number of times. + +Where your radio only hears nearby repeaters, turn on **Also count different nearby repeaters**: the message then also counts as sent once the required number of *different* first-hop repeaters have repeated it, across all attempts. Your own radio's echo and zero-hop echoes don't count. + ### Context Actions (Long-Press / Right-Click) | Action | Availability | Description | diff --git a/documentation/chat-and-messaging.md b/documentation/chat-and-messaging.md index b70ee99b..6cc3af0c 100644 --- a/documentation/chat-and-messaging.md +++ b/documentation/chat-and-messaging.md @@ -28,13 +28,16 @@ From the Contacts screen, tap any Chat-type contact to open the ChatScreen. - **Incoming messages**: Left-aligned, grey background with a colored avatar (initial letter or first emoji of sender name; color is deterministic from a hash of the sender name) - Bubble width capped at 72% of screen width - Hyperlinks rendered as tappable green underlined text +- Message text follows the system font size (Android/iOS accessibility text size); pinch-to-zoom scales on top of it - **Pinch-to-zoom**: Two-finger zoom (0.8x–1.8x) and double-tap to reset - **Jump to bottom**: Floating button appears when scrolled away from the bottom -- **Lazy loading**: Scrolling to top loads older messages from storage +- **Lazy loading**: Scrolling to top loads older messages from storage. The newest 200 messages are kept in memory; up to 1000 per conversation are kept in storage +- **Arrival order**: Messages are ordered by when they arrived on this device, not by the sender's clock. If a message's time is more than 5 minutes in the future, a small clock-warning icon appears next to its time (the sender's clock is probably wrong); tap it for an explanation ### Input Bar -- **GIF button** (left): Opens GIF picker bottom sheet +- **Send action button** (left, ⊕ icon): Opens a menu with **Send GIF** (GIF picker bottom sheet) and **Share my location** +- **Share my location**: Sends your radio's current position (from the radio, not the phone's GPS) as a location pin. You're asked for a label (default: your node name) before sending; the keyboard's Send key confirms. If the radio reports no usable position (none set, or 0,0), the item is hidden and a snackbar says "Your radio has no location set". Location shares follow the same send cooldown as typed messages and are never sent as a reply. In channel chat the menu also holds **Send low-res image over radio** when image messages are set up - **Translation button** (optional, between GIF and text field): Shown only when translation is enabled in App Settings. Tap to configure outgoing-message translation language and on/off toggle. - **Text field** (center): Auto-capitalization, enforces UTF-8 byte limit in real-time - **Send button** (right): Submits the message @@ -85,7 +88,7 @@ Only one message per contact can be in-flight at a time (to avoid overflowing th When a direct message is sent: 1. The app computes an expected ACK hash: `SHA256([timestamp][attempt][text][selfPubKey])[0:4]` — matching the firmware's hash calculation. If SMAZ compression is enabled, the compressed text (not the original) is hashed -2. On device acknowledgment (`RESP_CODE_SENT`), the message transitions to "sent" and a timeout timer starts +2. On device acknowledgment (`RESP_CODE_SENT`), the message transitions to "sent" and a timeout timer starts. If that acknowledgment never arrives (for example a dropped BLE notification), a backup timer (the delivery timeout plus 5 seconds) runs the normal retry path instead of leaving the message pending; a late ACK still marks it delivered 3. **Timeout duration**: Preferably from the ML timeout prediction service; otherwise from the device's own `est_timeout` in `RESP_CODE_SENT` (clamped to the physics range); otherwise calculated from LoRa airtime physics: `500 + (airtime × 6 + 250) × (pathLength + 1)` ms for direct paths, `500 + 16 × airtime` ms for flood (airtime is estimated from the radio's current spreading factor, bandwidth, and coding rate). The result is capped at 45 seconds. 4. On timeout, the message is retried with **exponential backoff**: `1000 × 2^retryCount` ms (1s, 2s, 4s, 8s, 16s...) 5. **Max retries**: Configurable (default 5, range 2–10) diff --git a/documentation/contacts.md b/documentation/contacts.md index eb736247..27eace4a 100644 --- a/documentation/contacts.md +++ b/documentation/contacts.md @@ -107,7 +107,24 @@ When the radio hears an advertisement, the contact appears automatically if auto Overflow menu (or the FAB shortcut) → "Add Contact from Clipboard". Reads a `meshcore://` URI from clipboard and imports it to the device. ### Import from Discovered Contacts -Overflow menu → "Discovered Contacts". Shows nodes heard passively that haven't been added yet. Tap to immediately import (no confirmation dialog), or long-press for more options (Copy URI, Delete). The Discovery screen has its own search bar, type filters (Users, Repeaters, Rooms), and sort options (Last Seen, A-Z). An overflow "Delete All" option clears all discovered contacts. +Overflow menu → "Discovered Contacts". Shows nodes heard passively that haven't been added yet. Tap to immediately import (no confirmation dialog), or long-press for more options (Copy URI, Delete). The Discovery screen has its own search bar, type filters (Users, Repeaters, Rooms), and sort options (Last Seen, A-Z). Its overflow menu has **Export discovered contacts**, **Import discovered contacts**, and "Delete All". + +### Scan for Nearby Nodes + +On the Discovered Contacts screen, tap the radar icon (**Scan for nearby nodes**) to ask nodes within direct radio range to identify themselves, instead of waiting for their next advert. The button appears only while connected to firmware with version code 8 or newer. + +- Repeaters and sensors answer. Room servers and companions usually don't. +- Results appear live for about 12 seconds, sorted by signal. Each shows the node type, signal strength, how well the node heard you ("they heard us at … dB"), and either **Already in contacts** or an add button. +- A node you haven't heard an advert from yet is added with a placeholder name; its real name appears after its next advert. +- Repeaters limit how often they reply. If nothing answers, wait a minute and tap **Scan again**. + +### Export and Import Discovered Contacts + +Use the Discovered Contacts overflow menu to move the list of heard-but-not-added nodes between devices or radios. + +- **Export discovered contacts** writes `meshcore_discovered_contacts.json`. On desktop a save dialog opens; on mobile the OS share sheet opens. The file holds each node's public key, name, type, flags, GPS position, timestamps, and its last advert packet. It contains no private keys and no routing paths (a path is only valid from the radio that learned it). On web the file is shared or downloaded through the browser. +- **Import discovered contacts** opens a file picker for a `.json` export (up to 2 MB) and requires a connected radio; imports go to that radio's discovered list. Nodes already in your contact list or discovered list, duplicates within the file, and your own node are skipped. Entries that can't be read (for example a public key that isn't 32 bytes) are skipped individually instead of failing the whole file. Imported nodes get no routing path, and future timestamps are clamped to now. When discovered-contact eviction is on, the list is trimmed back to its limit afterwards. A snackbar reports how many were imported, skipped, and unreadable, or that the file isn't a discovered-contacts export. +- Imported nodes go into the discovered list of the radio you're connected to. When eviction of discovered contacts is on, the list is trimmed back to the 500 most recently seen nodes the next time it loads. ### Import from a QR Code diff --git a/documentation/image-messages.md b/documentation/image-messages.md index c834c26a..2cda8bf8 100644 --- a/documentation/image-messages.md +++ b/documentation/image-messages.md @@ -29,7 +29,7 @@ Chunks are reassembled into an image entry in channel chat. A partially received With Process images automatically enabled, complete images are queued for local reconstruction. Automatic decoding runs only while the app is in the foreground, one image at a time, with at most 3 images queued; when more arrive, the newest 3 are kept and the rest wait for a tap. Otherwise, tap an image entry to process it. Download/enable the model if prompted. A failed reconstruction can be retried; missing chunks and inference errors are different failures. -Tap a reconstructed image to inspect it. Long-press or right-click its chat bubble for Packet info, Delete, and Save (available once decoded). Deletion is local. Encoded streams and reconstructed images are persisted in application storage, capped at 200 images, 64 MB, and 30 days. When the cap is reached, the oldest reconstructed images are evicted first and show "Image no longer stored"; they can be decoded again while their small encoded stream remains. Past 30 days the stream is removed too. +Tap a reconstructed image to inspect it. Long-press or right-click its chat bubble for Packet info, Delete, and Save (available once decoded). Deletion is local. Encoded streams and reconstructed images are persisted in application storage, capped at 200 images, 64 MB, and 30 days, plus a limit of 400 image entries (including ones waiting to be decoded and your own sent images once their data has expired). When the cap is reached, the oldest reconstructed images are evicted first and show "Image no longer stored"; they can be decoded again while their small encoded stream remains. Past 30 days the stream is removed too. ## Other image features diff --git a/documentation/map-and-location.md b/documentation/map-and-location.md index 28a09bd1..3cfa7a6f 100644 --- a/documentation/map-and-location.md +++ b/documentation/map-and-location.md @@ -35,6 +35,8 @@ Location pins shared in chat messages are displayed as flags: Tap a pin to see its info. Options to "Hide" (session only) or "Remove" (persistent). +Pins from the same sender in the same chat or channel with the same label (case-insensitive) are treated as one marker: a newer message moves it and keeps the earlier positions as its track. To update a pin you shared before, share again with the same label. + ### Predicted / Guessed Locations Many contacts on the mesh don't have GPS hardware, so the map has no explicit coordinates for them. Instead of leaving these contacts invisible, the app **infers an approximate position** by analyzing the repeater path the contact's messages travel through. These inferred positions are displayed as markers with a `not_listed_location` icon and a muted grey or colored border, visually distinct from confirmed-location markers. @@ -84,7 +86,7 @@ Opens a dialog showing: type, path (hop chain), coordinates, last-seen time, and ### Long-Press on Empty Map Area Shows a bottom sheet with: -- **Share marker here**: Prompts for a label, then pick a DM contact or channel to send the location to. Wire format: `m:,|