mirror of
https://github.com/zjs81/meshcore-open.git
synced 2026-06-14 22:55:12 +10:00
zjs81
ea657a964a
- Replaced sqflite with shared_preferences for local key-value storage in README.md - Updated gradle.properties to include builtInKotlin and newDsl flags - Enhanced translation feature documentation in additional-features.md - Modified BLE protocol documentation to include new command and response codes in ble-protocol.md - Clarified channel management details in channels.md - Improved chat and messaging documentation, including message path viewing and translation options in chat-and-messaging.md - Updated contacts management details in contacts.md - Revised map and location documentation for inferred locations and user interface changes in map-and-location.md - Adjusted navigation flow in navigation.md to reflect changes in screen transitions - Updated notification system details in notifications.md - Enhanced repeater management documentation in repeater-management.md - Clarified scanner and connection process in scanner-and-connection.md - Reorganized settings documentation for better clarity and added new node and location settings in settings.md
263 lines
10 KiB
Markdown
263 lines
10 KiB
Markdown
# Additional Features
|
||
|
||
## GIF Picker (Giphy Integration)
|
||
|
||
### How to Access
|
||
In any chat screen (direct or channel), tap the GIF button in the message input bar.
|
||
|
||
### What the User Sees
|
||
A bottom sheet with a search field and a grid of GIF thumbnails.
|
||
|
||
### Key Interactions
|
||
- On open, loads trending GIFs (G-rated, 25 results)
|
||
- Type to search and press the keyboard submit button (search triggers on submit, not on each keystroke). Clearing the search field reloads trending GIFs
|
||
- On network/API errors, a "Retry" button is shown in-place
|
||
- Tap a GIF to select it — the chat input shows an inline preview with an X button to dismiss
|
||
- Send the message to transmit the GIF reference (`g:<giphy-id>`)
|
||
- Recipients see the GIF rendered inline via Giphy CDN
|
||
- "Powered by Giphy" attribution is always shown at the bottom of the picker
|
||
- The bottom sheet occupies 70% of screen height
|
||
|
||
---
|
||
|
||
## Localization / Multi-Language Support
|
||
|
||
### How to Access
|
||
App Settings → Appearance → Language
|
||
|
||
### Supported Languages (18)
|
||
English, French, Spanish, German, Polish, Slovenian, Portuguese, Italian, Chinese, Swedish, Dutch, Slovak, Bulgarian, Russian, Ukrainian, Hungarian, Japanese, Korean
|
||
|
||
### How It Works
|
||
- All UI strings go through Flutter's ARB localization system
|
||
- Language can follow the system locale or be explicitly overridden
|
||
- Changes take effect immediately
|
||
|
||
---
|
||
|
||
## Discovered Contacts Screen
|
||
|
||
### How to Access
|
||
From Contacts screen → overflow menu → "Discovered Contacts"
|
||
|
||
### What the User Sees
|
||
A list of nodes heard passively over the air but not yet added as contacts. Each shows:
|
||
- Color-coded avatar (by type)
|
||
- Name
|
||
- Short public key
|
||
- Last-seen time
|
||
|
||
### Key Interactions
|
||
- Search bar with debounced filtering
|
||
- 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)
|
||
- Already-known contacts and your own node are filtered out
|
||
|
||
---
|
||
|
||
## SMAZ Compression
|
||
|
||
### What It Is
|
||
An optional per-contact and per-channel text compression feature using the SMAZ algorithm (optimized for short English text).
|
||
|
||
### How to Enable
|
||
- **Per contact**: Chat screen → info button → toggle "SMAZ compression"
|
||
- **Per channel**: Long-press channel → Edit → toggle "SMAZ compression"
|
||
|
||
### How It Works
|
||
- When enabled, compression is applied using a "compress only if smaller" strategy — the message is only transmitted compressed if the encoded result is actually shorter than the original. Otherwise, the original text is sent uncompressed
|
||
- Compressed messages are transmitted with a `s:` prefix followed by base64-encoded data
|
||
- Recipients using MeshCore Open will decompress automatically. **Recipients using other software** that is not SMAZ-aware will see garbled `s:...` text
|
||
- The codec operates on ASCII. Non-ASCII / non-English text generally does not benefit from compression and may even expand. Best suited for short English messages
|
||
- Disabled by default
|
||
|
||
---
|
||
|
||
## Community QR Scanner
|
||
|
||
### How to Access
|
||
From Channels screen → "+" FAB → "Scan Community QR"
|
||
|
||
### What the User Sees
|
||
A live QR scanner view with instruction text overlay.
|
||
|
||
### Key Interactions
|
||
- Scan a community QR code shared by another member
|
||
- On valid scan: confirmation dialog showing community name and ID
|
||
- Option to "Add public channel to device" on join
|
||
- If already a member: shows an "Already a member" dialog
|
||
- Invalid QR: shows an orange error snackbar
|
||
|
||
---
|
||
|
||
## Channel Message Path Viewing
|
||
|
||
### How to Access
|
||
In a channel chat, tap a message bubble (mobile) or use the "Path" action (desktop).
|
||
|
||
### What the User Sees
|
||
- Summary card: sender, time, repeat count, path type, observed hops
|
||
- "Other Observed Paths" section (if multiple paths detected)
|
||
- "Repeater Hops" section listing each hop with hex prefix, resolved name, and GPS coordinates
|
||
|
||
### Actions
|
||
- **Radar icon**: Opens path trace map for live trace
|
||
- **Map icon**: Opens a map with hop markers and polyline
|
||
- **Path dropdown**: Switch between observed path variants (if multiple)
|
||
|
||
---
|
||
|
||
## Debug Logging
|
||
|
||
### BLE Debug Log
|
||
**Access**: Settings → BLE Debug Log
|
||
|
||
Two views:
|
||
- **Frames**: Each BLE frame with direction, description, hex preview, timestamp. Long-press to copy hex.
|
||
- **Raw Log RX**: Decoded LoRa packets with route type, payload type, path bytes, and summary.
|
||
|
||
### App Debug Log
|
||
**Access**: Settings → App Debug Log (must be enabled first in App Settings → Debug)
|
||
|
||
Structured log entries with level (Info/Warning/Error), tag, message, and timestamp.
|
||
|
||
Both logs support copy-all and clear operations.
|
||
|
||
---
|
||
|
||
## Chrome Required Screen
|
||
|
||
### When It Appears
|
||
Automatically shown on web platforms when a non-Chromium browser is detected.
|
||
|
||
### What the User Sees
|
||
A full-screen informational page explaining that Web Bluetooth requires a Chromium-based browser. No interactive elements — purely informational.
|
||
|
||
---
|
||
|
||
## Path History Service
|
||
|
||
### What It Does (Background Service)
|
||
Maintains an in-memory LRU cache of up to 50 contacts, each with up to 100 route history entries, tracking:
|
||
- Hop count and trip time
|
||
- Success/failure counts and route weights
|
||
- Flood vs. direct discovery
|
||
|
||
### Path Scoring
|
||
Paths are scored using a weighted formula: reliability (45%), route weight (20%), latency (25%), and freshness (10%). These weights are internal and not user-configurable. Paths whose weight drops to zero or below are automatically deleted. Flood deliveries that receive an ACK give a weight boost (+0.5) to the specific return path.
|
||
|
||
Used internally for:
|
||
- **Auto route rotation**: Cycles through known paths using configurable weights on retries, with a diversity window to avoid re-using recently tried paths
|
||
- **Path selection**: Picks the best-scored path for each retry attempt
|
||
- **Flood statistics**: Tracks flood vs. direct discovery ratios
|
||
|
||
---
|
||
|
||
## Message Retry Service
|
||
|
||
### What It Does (Background Service)
|
||
Handles reliable delivery of outgoing direct messages:
|
||
1. Assigns a UUID and sends immediately. Only one message per contact can be in-flight at a time (avoids overflowing the firmware's 8-entry ACK table); subsequent messages are queued
|
||
2. Listens for ACK frames matched via SHA-256 hash of `[timestamp][attempt][text][sender_pubkey]`
|
||
3. On timeout, retries with exponential backoff: `1000 × 2^retryCount` ms (1s, 2s, 4s, 8s...)
|
||
4. Each retry may use a different path (via path history diversity window)
|
||
5. After max retries: marks failed but keeps a **30-second grace window** during which a late ACK can still resolve the message to "delivered". Optionally clears the contact's path
|
||
6. Reports RTT and path data for quality learning
|
||
7. Maintains an ACK hash history (last 50 entries) to handle duplicate ACKs
|
||
|
||
### Configurable Settings (App Settings → Messaging)
|
||
- Max retries (2–10, default 5)
|
||
- Clear path on max retry (on/off)
|
||
- Auto route rotation with weight parameters
|
||
|
||
---
|
||
|
||
## Timeout Prediction (ML)
|
||
|
||
### What It Does (Background Service)
|
||
An ML-based service that predicts expected delivery timeouts:
|
||
- Collects delivery observations (path length, message size, time since last RX, delivery time) in a sliding window of up to 100 observations (oldest evicted first)
|
||
- Requires **10 minimum observations** before first training. After that, retrains every 5 new observations
|
||
- Applies a **1.5x safety margin** to raw predictions (the actual timeout issued is 1.5× the model's predicted delivery time)
|
||
- Features with zero variance are automatically excluded from training
|
||
- Blends per-contact statistics with ML predictions
|
||
- Falls back to `3000 + 3000 × pathLength` ms when insufficient data
|
||
- Observations are persisted to storage via a 2-second debounced timer (observations within 2s of app termination may be lost)
|
||
|
||
---
|
||
|
||
## On-Device Message Translation
|
||
|
||
### What It Is
|
||
An optional on-device translation service powered by an embedded LLM (llamadart, running GGUF models). Translation runs entirely on-device — no data leaves the app.
|
||
|
||
### How to Access
|
||
Tap the translate button on any received message. On first use, the GGUF model file is downloaded and cached locally.
|
||
|
||
### How It Works
|
||
- Model files are managed by `TranslationFileStore`; download progress is shown in-place
|
||
- Before translating, the source language is automatically detected using the `flutter_langdetect` package. If the detected language already matches the target language, translation is skipped
|
||
- Translation runs via `TranslationService` using the llamadart CPU backend (arm64 and x64 on Android)
|
||
- Translated text is shown in `TranslatedMessageContent` as an inline overlay on the original message bubble
|
||
- Each translation is cached; re-tapping shows the cached result without re-running inference
|
||
|
||
---
|
||
|
||
## Emoji Reactions
|
||
|
||
### How to Access
|
||
Long-press a message bubble in any direct or channel chat, then select a reaction emoji.
|
||
|
||
### What the User Sees
|
||
An emoji picker inline with common reactions. Selected reactions appear below the message bubble with a count.
|
||
|
||
### How It Works
|
||
- Implemented via `emoji_picker.dart` and `reaction_helper.dart`
|
||
- Reactions are transmitted as a special message type visible to all participants with MeshCore Open
|
||
|
||
---
|
||
|
||
## Linkification
|
||
|
||
### What It Does
|
||
URLs and `meshcore://` URIs in received messages are automatically detected and rendered as tappable links.
|
||
|
||
### How It Works
|
||
- Powered by the `flutter_linkify` package via `link_handler.dart`
|
||
- Tapping a URL opens the system browser; tapping a `meshcore://` URI imports the contact
|
||
|
||
---
|
||
|
||
## GPX Export
|
||
|
||
### How to Access
|
||
Settings → Export section (three options: Export Repeaters, Export Contacts, Export All).
|
||
|
||
### What It Does
|
||
Exports contacts with GPS coordinates to a `.gpx` file via the OS share sheet. Not available on web.
|
||
|
||
---
|
||
|
||
## Pinch-to-Zoom Chat Text
|
||
|
||
### What It Does
|
||
Users can pinch to scale all chat text up or down within a session.
|
||
|
||
### How It Works
|
||
- Implemented via `ChatTextScaleService` and `ChatZoomWrapper`
|
||
- Scale range: 0.8× to 1.8×
|
||
- The chosen scale persists across the session via the service
|
||
|
||
---
|
||
|
||
## Background Service (Android)
|
||
|
||
### What It Does
|
||
On Android, a foreground service (`background_service.dart`) keeps the BLE connection and message handling alive when the app is in the background. On other platforms this is a no-op.
|
||
|
||
### User Impact
|
||
- A persistent notification appears while the service is running
|
||
- Messages are received and retry logic continues even when the app is not in the foreground
|