diff --git a/documentation/README.md b/documentation/README.md index 6778e97d..5198c08f 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,19 +11,19 @@ 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 @@ -38,6 +38,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 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/channels.md b/documentation/channels.md index d3c68a1f..b569f54b 100644 --- a/documentation/channels.md +++ b/documentation/channels.md @@ -48,13 +48,15 @@ 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 | @@ -85,7 +87,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 +112,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:,|