diff --git a/README.md b/README.md index 7291a75..49fce1e 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ A lightweight web interface providing browser-based access to MeshCore mesh netw - **@Mentions autocomplete** - Type @ to see contact suggestions with fuzzy search - **Echo tracking** - "Heard X repeats" with repeater IDs for sent messages, all route paths for incoming messages with deterministic payload matching (persisted across restarts) - **MeshCore Analyzer** - View packet details on analyzer.letsmesh.net directly from channel messages -- **DM delivery tracking** - ACK-based delivery confirmation with SNR and route info +- **DM delivery tracking** - ACK-based delivery confirmation with SNR, route, and hop count details - **Multi-device support** - Database file named after device public key for easy multi-device setups - **PWA support** - Browser notifications and installable app (experimental) - **Full offline support** - Works without internet (local Bootstrap, icons, emoji picker) @@ -300,6 +300,8 @@ sudo ~/mc-webui/scripts/updater/install.sh --uninstall | [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions | | [Docker Installation](docs/docker-install.md) | How to install Docker on Debian/Ubuntu | | [Container Watchdog](docs/watchdog.md) | Auto-restart for unhealthy containers | +| [DM Delivery & Retry Logic](docs/dm-retry-logic.md) | How DM delivery confirmation and retry strategies work | +| [Bluetooth Pairing Guide](docs/meshcore_bluetooth_pairing.md) | How to pair MeshCore devices via BLE on Linux | --- diff --git a/docs/architecture.md b/docs/architecture.md index c9887c0..73f7bd2 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -37,7 +37,7 @@ mc-webui uses a **single-container architecture** for simplified deployment and │ │ mc-webui │ │ │ │ │ │ │ │ - Flask web app (Port 5000) │ │ -│ │ - DeviceManager (Direct USB/TCP access) │ │ +│ │ - DeviceManager (Direct USB/BLE/TCP access) │ │ │ │ - Database (SQLite) │ │ │ │ │ │ │ └─────────┬─────────────────────────────────────────────┘ │ @@ -46,11 +46,13 @@ mc-webui uses a **single-container architecture** for simplified deployment and │ ▼ ┌──────────────┐ - │ USB/TCP │ - │ Device │ + │ USB/BLE/TCP │ + │ Device │ └──────────────┘ ``` +Three transport options are supported with the following priority: **BLE > TCP > Serial (USB)**. Set the `MC_BLE_ADDRESS` or `MC_TCP_HOST` environment variable to activate BLE or TCP transport respectively; otherwise, USB serial is used by default. + This v2 architecture eliminates the need for a separate bridge container and relies on the native `meshcore` Python library for direct communication, ensuring lower latency and greater stability. --- @@ -111,9 +113,10 @@ Location: `./data/meshcore/.db` Key tables: - `messages` - All channel and direct messages (with FTS5 index for full-text search) -- `contacts` - Contact list with sync status, types, block/ignore flags +- `contacts` - Contact list with sync status, types, block/ignore flags, `no_auto_flood` flag - `channels` - Channel configuration and keys -- `echoes` - Sent message tracking and repeater paths +- `echoes` - Sent message tracking and repeater paths, `hash_size` for path_hash_mode +- `direct_messages` - DM messages with delivery tracking (`delivery_status`, `delivery_attempt`, `delivery_max_attempts`, `delivery_path`) - `acks` - DM delivery status - `settings` - Application settings (migrated from .webui_settings.json) @@ -198,7 +201,7 @@ The use of SQLite allows for fast queries, reliable data storage, full-text sear | Method | Endpoint | Description | |--------|----------|-------------| -| GET | `/api/status` | Connection status (device name, serial port) | +| GET | `/api/status` | Connection status (device name, transport type, serial port / BLE address) | | GET | `/api/device/info` | Device information | | GET | `/api/device/stats` | Device statistics | | GET | `/api/device/settings` | Get device settings | @@ -259,8 +262,12 @@ Real-time message delivery via Socket.IO. **Server → Client:** - `new_channel_message` - New channel message received - `new_dm_message` - New DM received -- `message_echo` - Echo/ACK update for sent message +- `message_echo` - Echo/ACK update for sent message (includes `hash_size`) - `dm_ack` - DM delivery confirmation +- `dm_retry_status` - Real-time retry progress (`dm_id`, `attempt`, `max_attempts`) +- `dm_retry_failed` - All retry attempts exhausted (`dm_id`) +- `dm_delivered_info` - Delivery details after ACK (`dm_id`, `attempt`, `max_attempts`, `path`, `hash_size`) +- `path_changed` - Contact path discovered/updated (`public_key`) ### Logs Namespace (`/logs`) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index f8d74ec..c5c4110 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -130,6 +130,16 @@ This can happen after a power failure during OTA update, flash memory corruption --- +### BLE Connection Issues + +If using Bluetooth Low Energy (BLE) transport, see the dedicated [Bluetooth Pairing Guide](meshcore_bluetooth_pairing.md) for setup and troubleshooting, including: +- Host preparation (BlueZ configuration, `ControllerMode = le`) +- Pairing with fixed PIN +- Trusting the device for automatic reconnection +- Diagnosing connection loops and stale BlueZ connections + +--- + ### Contact Management Issues **Check logs:** diff --git a/docs/user-guide.md b/docs/user-guide.md index 3bd03aa..51534b6 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -177,10 +177,15 @@ Access the Direct Messages feature: ### Message Status Indicators -- ✓ **Delivered** (green checkmark) - Recipient confirmed receipt (ACK). Tap/hover for SNR and route details +- ✓ **Delivered** (green checkmark) - Recipient confirmed receipt (ACK). Tap/hover for SNR, route, and hop count details +- ✗ **Failed** (red X) - All retry attempts exhausted with no ACK - ? **Unknown** (gray question mark) - No ACK received. Message may still have been delivered — ACK packets are often lost over multi-hop routes. Tap the icon for details - ⏳ **Pending** (clock icon, yellow) - Message sent, awaiting delivery confirmation +### Real-time Delivery Progress + +While a message is being retried, the UI shows a live counter below the message bubble (e.g., "Attempt 3/11"). When delivery is confirmed, the route used is displayed (e.g., `5E->05->58->D1`) and can be clicked to show a popup with full path details. + ### DM Notifications - The bell icon shows a secondary green badge for unread DMs @@ -505,11 +510,21 @@ Access the Settings modal to configure application behavior: ### DM Retry Settings -Configure how direct messages are retried when delivery is not confirmed: -- **Retry count** - Number of retry attempts (includes initial send) -- **Retry interval** - Seconds between retries -- **Flood fallback attempt** - After which attempt to switch from DIRECT to FLOOD routing -- **Grace period** - Seconds to wait for late ACKs after all retries complete +Configure how direct messages are retried when delivery is not confirmed. Settings are organized into two groups based on whether the contact has a known route: + +**When path is known:** +- **Direct retries** - How many times to resend via the current route before trying alternatives (default: 3) +- **Flood retries** - How many flood attempts after direct retries when no extra paths are configured (default: 1) +- **Interval (s)** - Minimum seconds between direct retry attempts (default: 30) + +**When no path:** +- **Max retries** - How many flood retry attempts (default: 3) +- **Interval (s)** - Minimum seconds between flood retry attempts (default: 60) + +**Other:** +- **Grace period (s)** - After all retries fail, keep listening for a late ACK this long before giving up (default: 60) + +The app automatically picks one of four retry strategies depending on the contact's route status and configured paths. For full details, see [DM Delivery & Retry Logic](dm-retry-logic.md). ### Quote Settings @@ -666,6 +681,8 @@ To get the full PWA experience with app badge counters: - **Full README:** [README.md](../README.md) - **Repeater Management:** [rpt-mgmt.md](rpt-mgmt.md) +- **DM Delivery & Retry Logic:** [dm-retry-logic.md](dm-retry-logic.md) +- **Bluetooth Pairing Guide:** [meshcore_bluetooth_pairing.md](meshcore_bluetooth_pairing.md) - **Troubleshooting:** [troubleshooting.md](troubleshooting.md) - **Architecture:** [architecture.md](architecture.md) - **Container Watchdog:** [watchdog.md](watchdog.md)