- Introduced "Contacts" documentation detailing the contact management system, types, list, search, and tap actions. - Added "Map & Location" documentation covering map features, interactions, path tracing, and line-of-sight analysis. - Created "Navigation" documentation outlining app flow, QuickSwitchBar, and device screen interactions. - Developed "Notifications" documentation explaining notification types, in-app badges, settings, and rate limiting. - Established "Repeater Management" documentation for managing repeaters and room servers, including CLI access and telemetry. - Compiled "Scanner & Connection" documentation detailing BLE, USB, and TCP connection processes. - Formulated "Settings" documentation outlining access, layout, device info, app settings, node settings, actions, debug options, export features, and about section.chore/offband-rebrand
zjs81
4 months ago
parent
4ad4a93a20
commit
cb63b48b78
@ -0,0 +1,30 @@
|
|||||||
|
# MeshCore Open - Feature Documentation
|
||||||
|
|
||||||
|
MeshCore Open is an open-source Flutter client for MeshCore LoRa mesh networking devices. This documentation covers every user-facing feature, how to access it, and what it does.
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
1. [Scanner & Connection](scanner-and-connection.md) - BLE scanning, USB serial, and TCP connection
|
||||||
|
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
|
||||||
|
7. [Settings](settings.md) - Device settings, app settings, radio configuration, and exports
|
||||||
|
8. [Notifications](notifications.md) - System notifications, 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. [BLE Protocol & Data Layer](ble-protocol.md) - Technical reference for the communication protocol and data architecture
|
||||||
|
|
||||||
|
## App Overview
|
||||||
|
|
||||||
|
MeshCore Open connects to MeshCore LoRa mesh radios over BLE, USB, or TCP. Once connected, users can:
|
||||||
|
|
||||||
|
- **Chat** with other mesh nodes via encrypted direct messages
|
||||||
|
- **Broadcast** on shared channels (public, hashtag, private, or community-scoped)
|
||||||
|
- **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
|
||||||
|
- **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
|
||||||
@ -0,0 +1,87 @@
|
|||||||
|
# Navigation
|
||||||
|
|
||||||
|
## App Flow
|
||||||
|
|
||||||
|
The app follows this general flow:
|
||||||
|
|
||||||
|
```
|
||||||
|
Launch → Scanner Screen → [Connect via BLE/USB/TCP] → Contacts Screen
|
||||||
|
```
|
||||||
|
|
||||||
|
After connecting, the three main screens (Contacts, Channels, Map) are accessible via a persistent bottom navigation bar called the **QuickSwitchBar**.
|
||||||
|
|
||||||
|
## Quick Switch Bar
|
||||||
|
|
||||||
|
The QuickSwitchBar is a Material 3 `NavigationBar` with a frosted-glass visual treatment (blur backdrop, transparent theme, rounded corners). It appears at the bottom of all three main screens.
|
||||||
|
|
||||||
|
| Index | Icon | Label | Screen |
|
||||||
|
|---|---|---|---|
|
||||||
|
| 0 | People | Contacts | ContactsScreen |
|
||||||
|
| 1 | Tag | Channels | ChannelsScreen |
|
||||||
|
| 2 | Map | Map | MapScreen |
|
||||||
|
|
||||||
|
Tapping a tab replaces the current screen with a subtle fade + slight horizontal nudge transition (220ms forward, 200ms reverse). The back button is suppressed on all three main screens — navigation between them is flat, not stacked. All icons use outline variants (`people_outline`, `tag`, `map_outlined`) following Material 3 conventions.
|
||||||
|
|
||||||
|
## Device Screen
|
||||||
|
|
||||||
|
The Device Screen is a transitional hub that shows after connection. In practice, the app navigates directly to Contacts after connecting, but the Device Screen is reachable via the QuickSwitchBar.
|
||||||
|
|
||||||
|
### What the User Sees
|
||||||
|
|
||||||
|
**App Bar**:
|
||||||
|
- Left: Battery indicator chip (tappable — toggles between percentage and voltage display). Icon changes based on level: `battery_unknown` when data unavailable, `battery_alert` (orange) at 15% or below, `battery_full` otherwise
|
||||||
|
- Left-aligned title (`centerTitle: false`): Two-line layout — small grey "MeshCore" label above the device name in bold
|
||||||
|
- Right: Disconnect button (`bluetooth_disabled` crossed-out icon) and Settings button (tune icon)
|
||||||
|
|
||||||
|
**Body**:
|
||||||
|
- **Connection Card**: Device avatar, device name, device ID, "Connected" chip, and battery chip
|
||||||
|
- **Quick Switch** section: The QuickSwitchBar widget for navigating to Contacts/Channels/Map
|
||||||
|
|
||||||
|
### Disconnection
|
||||||
|
|
||||||
|
- The disconnect button shows a confirmation dialog before disconnecting
|
||||||
|
- If the device disconnects unexpectedly, the app automatically navigates back to the Scanner screen (fires after the current frame completes via a post-frame callback)
|
||||||
|
- This auto-navigation behavior (`DisconnectNavigationMixin`) is shared across all main screens
|
||||||
|
|
||||||
|
## Theme and Locale
|
||||||
|
|
||||||
|
- **Theme mode** is user-configurable in App Settings (System / Light / Dark) — not locked to system
|
||||||
|
- **Language** can be overridden to one of 15 supported languages, or follow the system locale
|
||||||
|
- On web, if a non-Chromium browser is detected, the app shows a `ChromeRequiredScreen` instead of the Scanner (Web Bluetooth requires Chromium)
|
||||||
|
|
||||||
|
## Full Navigation Graph
|
||||||
|
|
||||||
|
```
|
||||||
|
ScannerScreen (root, always on stack)
|
||||||
|
├─ [BLE connect] → push → ContactsScreen
|
||||||
|
├─ [TCP FAB] → push → TcpScreen
|
||||||
|
│ └─ [TCP connected] → pushReplacement → ContactsScreen
|
||||||
|
└─ [USB FAB] → push → UsbScreen
|
||||||
|
└─ [USB connected] → pushReplacement → ContactsScreen
|
||||||
|
|
||||||
|
ContactsScreen (selected=0)
|
||||||
|
├─ [quick-switch 1] → pushReplacement → ChannelsScreen
|
||||||
|
├─ [quick-switch 2] → pushReplacement → MapScreen
|
||||||
|
├─ [tap contact] → push → ChatScreen
|
||||||
|
├─ [overflow > Settings] → push → SettingsScreen
|
||||||
|
└─ [overflow > Discovered] → push → DiscoveryScreen
|
||||||
|
|
||||||
|
ChannelsScreen (selected=1)
|
||||||
|
├─ [quick-switch 0] → pushReplacement → ContactsScreen
|
||||||
|
├─ [quick-switch 2] → pushReplacement → MapScreen
|
||||||
|
├─ [tap channel] → push → ChannelChatScreen
|
||||||
|
└─ [overflow > Settings] → push → SettingsScreen
|
||||||
|
|
||||||
|
MapScreen (selected=2)
|
||||||
|
├─ [quick-switch 0] → pushReplacement → ContactsScreen
|
||||||
|
├─ [quick-switch 1] → pushReplacement → ChannelsScreen
|
||||||
|
├─ [radar button] → push → PathTraceMapScreen
|
||||||
|
├─ [terrain button] → push → LineOfSightMapScreen
|
||||||
|
└─ [long-press] → share marker / set location
|
||||||
|
|
||||||
|
Settings (push from any main screen)
|
||||||
|
└─ [App Settings] → push → AppSettingsScreen
|
||||||
|
└─ [Offline Map Cache] → push → MapCacheScreen
|
||||||
|
```
|
||||||
|
|
||||||
|
Any disconnection from any screen triggers `popUntil(route.isFirst)`, returning to the Scanner.
|
||||||
@ -0,0 +1,92 @@
|
|||||||
|
# Notifications
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
MeshCore Open provides both **system notifications** (push-style OS alerts) and **in-app unread badges** to inform users of new activity.
|
||||||
|
|
||||||
|
## Notification Types
|
||||||
|
|
||||||
|
### 1. Direct Message Notifications
|
||||||
|
- **Triggered when**: A new incoming message arrives from a Chat or Room contact
|
||||||
|
- **Title**: Contact's name
|
||||||
|
- **Body**: Message text (reactions show "Reacted [emoji]", GIFs show "Sent a GIF")
|
||||||
|
- **Priority**: High
|
||||||
|
- **Android channel**: `messages`
|
||||||
|
|
||||||
|
### 2. Channel Message Notifications
|
||||||
|
- **Triggered when**: A new message arrives on a non-muted channel
|
||||||
|
- **Title**: Channel name (or "Channel N" if unnamed)
|
||||||
|
- **Body**: `"<senderName>: <message text>"`
|
||||||
|
- **Priority**: High
|
||||||
|
- **Android channel**: `channel_messages`
|
||||||
|
|
||||||
|
### 3. Advertisement Notifications
|
||||||
|
- **Triggered when**: A new node is discovered on the mesh for the first time
|
||||||
|
- **Title**: "New [type] discovered" (e.g., "New chat node discovered")
|
||||||
|
- **Body**: Contact's name
|
||||||
|
- **Priority**: Default
|
||||||
|
- **Android channel**: `adverts`
|
||||||
|
|
||||||
|
### 4. Background Service Notification (Android Only)
|
||||||
|
- A persistent low-priority notification: "MeshCore running — Keeping BLE connected"
|
||||||
|
- Required by Android for foreground services to keep BLE alive in the background
|
||||||
|
- Tap to re-launch the app
|
||||||
|
- **Does not auto-start on reboot** — the user must re-open the app manually after a phone restart
|
||||||
|
|
||||||
|
### Notification Tap Behavior
|
||||||
|
|
||||||
|
Tapping a notification currently re-launches the app at the root route. It does **not** navigate directly to the relevant chat or channel.
|
||||||
|
|
||||||
|
## In-App Unread Badges
|
||||||
|
|
||||||
|
Red numeric badges appear throughout the UI:
|
||||||
|
- **Contacts list**: Each contact row shows a red pill badge (e.g., "3") for unread messages
|
||||||
|
- **Channels list**: Each channel row shows an unread badge
|
||||||
|
- **Chat screen subtitle**: Shows unread count inline
|
||||||
|
- Badges cap at "99+" for display
|
||||||
|
|
||||||
|
### How Unread Counts Work
|
||||||
|
|
||||||
|
- Stored per contact (by public key) and per channel, **scoped to the connected device's identity** (first 10 hex characters of its public key). Switching between different radios gives each its own independent unread state
|
||||||
|
- **Suppressed when viewing**: Opening a chat resets the count to 0 and cancels the OS notification
|
||||||
|
- **Ignored for**: Outgoing messages, CLI messages, and repeater contacts
|
||||||
|
- Debounced writes (500ms) to avoid excessive storage I/O during message bursts
|
||||||
|
|
||||||
|
## Notification Settings
|
||||||
|
|
||||||
|
Access via **App Settings → Notifications**:
|
||||||
|
|
||||||
|
| Setting | Default | Description |
|
||||||
|
|---|---|---|
|
||||||
|
| Enable Notifications | On | Master toggle; requests OS permission when turned on |
|
||||||
|
| Message Notifications | On | DM alerts (greyed out if master is off) |
|
||||||
|
| Channel Message Notifications | On | Channel alerts (greyed out if master is off) |
|
||||||
|
| Advertisement Notifications | On | New node alerts (greyed out if master is off) |
|
||||||
|
|
||||||
|
### Per-Channel Muting
|
||||||
|
|
||||||
|
Long-press a channel in the channels list → "Mute channel" / "Unmute channel". Muted channels do not generate OS notifications.
|
||||||
|
|
||||||
|
There is no per-contact muting.
|
||||||
|
|
||||||
|
## Rate Limiting
|
||||||
|
|
||||||
|
The notification system prevents notification storms:
|
||||||
|
- **Minimum interval**: 3 seconds between individual notifications
|
||||||
|
- **Batch window**: If multiple notifications arrive within 5 seconds, they are combined into a single summary notification on a fourth Android channel (`batch_summary`): "MeshCore Activity — 2 messages, 1 channel message, 3 new nodes". Note: batch summaries are Android-only; on Apple platforms individual notifications are shown
|
||||||
|
|
||||||
|
## Notification Clearing
|
||||||
|
|
||||||
|
- **Opening a contact chat**: Cancels the OS notification and resets unread count
|
||||||
|
- **Opening a channel**: Cancels the channel notification and resets unread count
|
||||||
|
- **Opening Contacts screen**: Cancels all advertisement notifications
|
||||||
|
|
||||||
|
## Platform Support
|
||||||
|
|
||||||
|
| Platform | Message Notifs | Badge | Background Service |
|
||||||
|
|---|---|---|---|
|
||||||
|
| Android | Yes | Via notification number | Yes (foreground service) |
|
||||||
|
| iOS | Yes | Yes (app badge) | No |
|
||||||
|
| macOS | Yes | Yes | No |
|
||||||
|
| Windows | Yes | No | No |
|
||||||
|
| Linux | Yes (if D-Bus available) | No | No |
|
||||||
@ -0,0 +1,124 @@
|
|||||||
|
# Scanner & Connection
|
||||||
|
|
||||||
|
## BLE Scanner (Home Screen)
|
||||||
|
|
||||||
|
The BLE Scanner is the app's home screen, displayed immediately on launch.
|
||||||
|
|
||||||
|
### How to Access
|
||||||
|
|
||||||
|
- Opens automatically when the app starts
|
||||||
|
- Returns here when disconnecting from any device
|
||||||
|
- Accessible by navigating back from a connected session
|
||||||
|
|
||||||
|
### What the User Sees
|
||||||
|
|
||||||
|
**App Bar**: Centered title "Scanner".
|
||||||
|
|
||||||
|
**Bluetooth-Off Warning Banner** (conditional): Appears when the Bluetooth adapter is off, showing a `bluetooth_disabled` icon, a warning message, and on Android, an "Enable Bluetooth" button.
|
||||||
|
|
||||||
|
**Status Bar**: A full-width colored strip reflecting the current connection state:
|
||||||
|
|
||||||
|
| State | Text | Color |
|
||||||
|
|---|---|---|
|
||||||
|
| Disconnected | "Not connected" | Grey |
|
||||||
|
| Scanning | "Scanning..." | Blue |
|
||||||
|
| Connecting | "Connecting..." | Orange |
|
||||||
|
| Connected | "Connected to \<device name\>" | Green |
|
||||||
|
| Disconnecting | "Disconnecting..." | Orange |
|
||||||
|
|
||||||
|
**Device List**: When no devices are found, shows a large Bluetooth icon with a prompt. The prompt text is dynamic: "Searching for devices..." while actively scanning, or "Tap Scan to search" when idle. When devices are found, shows a scrollable list of `DeviceTile` widgets.
|
||||||
|
|
||||||
|
**Bottom FAB Row**: Up to three floating action buttons:
|
||||||
|
- **USB** button - Opens USB connection screen (Android, Windows, Linux, macOS, Chrome web only)
|
||||||
|
- **TCP/IP** button - Opens TCP connection screen (all non-web platforms)
|
||||||
|
- **BLE Scan** button - Toggles BLE scanning on/off; shows a spinner when scanning. **Disabled** (greyed out, not tappable) when Bluetooth is off
|
||||||
|
|
||||||
|
### Device Tile
|
||||||
|
|
||||||
|
Each discovered device is displayed as a list tile showing:
|
||||||
|
- **Signal strength icon** (color-coded by RSSI):
|
||||||
|
- Green: >= -60 dBm (excellent)
|
||||||
|
- Light green: -60 to -70 dBm (good)
|
||||||
|
- Amber: -70 to -80 dBm (fair)
|
||||||
|
- Orange: -80 to -90 dBm (weak)
|
||||||
|
- Red: < -90 dBm (poor)
|
||||||
|
- **RSSI value** in dBm (e.g., "-72 dBm")
|
||||||
|
- **Device name** (falls back to "Unknown Device")
|
||||||
|
- **Device ID** (BLE MAC address on Android; a system-assigned UUID on iOS/macOS)
|
||||||
|
- **Connect button** (the entire tile row is also tappable — both trigger connection)
|
||||||
|
|
||||||
|
Note: The weak (-80 to -90 dBm) and poor (< -90 dBm) tiers share the same icon shape and are only differentiated by color (orange vs. red).
|
||||||
|
|
||||||
|
### How Scanning Works
|
||||||
|
|
||||||
|
- Filters for devices with names starting with `MeshCore-` or `Whisper-`
|
||||||
|
- Uses low-latency scan mode on Android
|
||||||
|
- Scans for 10 seconds then auto-stops
|
||||||
|
- On iOS/macOS, waits for BLE adapter initialization before starting
|
||||||
|
- If Bluetooth is turned off during a scan, scanning stops immediately
|
||||||
|
|
||||||
|
### Connecting to a Device
|
||||||
|
|
||||||
|
Tap a device tile or its Connect button:
|
||||||
|
1. The connector stops scanning and transitions to "connecting"
|
||||||
|
2. Connects to the device with a 15-second timeout
|
||||||
|
3. Requests MTU 185 bytes for optimal throughput
|
||||||
|
4. Discovers BLE services and locates the Nordic UART Service
|
||||||
|
5. Subscribes to TX notifications for receiving data
|
||||||
|
6. On success, automatically navigates to the Contacts screen
|
||||||
|
7. On failure, shows a red error snackbar
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## USB Connection
|
||||||
|
|
||||||
|
### How to Access
|
||||||
|
|
||||||
|
From the Scanner screen, tap the **USB** FAB button.
|
||||||
|
|
||||||
|
### What the User Sees
|
||||||
|
|
||||||
|
- A colored status bar at the top (same color scheme as BLE scanner)
|
||||||
|
- A list of detected USB serial ports, each showing:
|
||||||
|
- Friendly display name
|
||||||
|
- Raw port name (subtitle, only shown when it differs from the display name)
|
||||||
|
- "Connect" button
|
||||||
|
- FABs at the bottom to switch to BLE or TCP (these use `pushReplacement`, so back navigation returns to Scanner, not between USB/TCP)
|
||||||
|
|
||||||
|
### Key Interactions
|
||||||
|
|
||||||
|
- On desktop (Windows, Linux, macOS): ports are polled every 2 seconds for hot-plug detection (polling pauses while connecting/connected)
|
||||||
|
- On mobile: tap the "Scan" FAB to manually refresh
|
||||||
|
- Tap a port or its Connect button to connect
|
||||||
|
- On successful connection, navigates to Contacts screen
|
||||||
|
- On connection failure, the port list automatically refreshes
|
||||||
|
- Platform-specific error messages for common USB failures (permission denied, device missing, device detached, device busy, driver missing, port invalid, timeout, and more)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## TCP Connection
|
||||||
|
|
||||||
|
### How to Access
|
||||||
|
|
||||||
|
From the Scanner screen, tap the **TCP/IP** FAB button.
|
||||||
|
|
||||||
|
### What the User Sees
|
||||||
|
|
||||||
|
- A colored status bar at the top
|
||||||
|
- **Host address** text field
|
||||||
|
- **Port number** text field
|
||||||
|
- **Connect** button
|
||||||
|
- FABs at the bottom to switch to USB or BLE
|
||||||
|
|
||||||
|
### Key Interactions
|
||||||
|
|
||||||
|
- Last-used host and port are pre-populated from saved settings
|
||||||
|
- Tap Connect to validate inputs and connect
|
||||||
|
- Host must not be empty
|
||||||
|
- Port must be a number between 1 and 65535
|
||||||
|
- Validation errors are shown as red snackbars
|
||||||
|
- The Connect button shows a spinner and "Connecting..." label while in progress
|
||||||
|
- The status bar shows the specific host:port being connected to (e.g., "Connecting to 192.168.1.1:5000")
|
||||||
|
- On success, navigates to Contacts screen and saves the host/port to settings
|
||||||
|
- On connection, the status bar shows the active TCP endpoint (e.g., "Connected to 192.168.1.1:5000")
|
||||||
|
- Error messages for timeout, unsupported platform, and connection failures
|
||||||
Loading…
Reference in new issue