docs: sync README, user guide, and architecture with recent features

Catch up on ~36 commits since b60c99a. Document Device Settings tab (public info + radio) with map picker and regional presets, quick-access FAB cluster with drag/collapse/sizing, configurable route popup and toast timeout/position, multi-arch Docker images (amd64, arm64, arm/v7), and new endpoints /api/device/config and /api/ui/settings. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-05-02 03:22:40 +02:00 · 2026-04-15 16:14:57 +02:00
parent 8ccb3100c2
commit 0a08759065
3 changed files with 109 additions and 13 deletions
--- a/README.md
+++ b/README.md
@@ -24,8 +24,10 @@ A lightweight web interface providing browser-based access to MeshCore mesh netw
 - **Message archives** - Automatic daily archiving with browse-by-date selector
 - **Interactive Console** - Full MeshCore command suite via WebSocket — repeater, contact, device, and channel management
 - **Device dashboard** - Device info, statistics, and contact sharing (QR code / URI)
+- **Device configuration** - Edit device name, GPS coordinates (with map picker), advert location sharing, and LoRa radio parameters (frequency, bandwidth, SF, CR, TX power) directly from Settings
+- **Quick-access FAB buttons** - Draggable floating action buttons (Filter, Search, DM, Contacts, Settings) on main chat and DM pages, with collapsible visibility and customizable size/spacing
 - **Dark/Light theme** - Toggle between dark and light UI themes
- **Settings** - Configurable DM retry parameters, message retention, quote length, and theme
+- **Settings** - Configurable DM retry parameters, message retention, quote length, route popup timeout, toast notification position/timeout, and theme
 - **System Log** - Real-time log viewer with streaming
 - **Database backup** - Create, list, and download database backups from the UI
 - **@Mentions autocomplete** - Type @ to see contact suggestions with fuzzy search
@@ -43,12 +45,13 @@ For detailed feature documentation, see the [User Guide](docs/user-guide.md).
 ### Prerequisites

 **1. Meshcore Device (tested on Heltec V4)**
- Flash the device at [https://flasher.meshcore.co.uk/](https://flasher.meshcore.co.uk/). Choose the `Companion USB` role.
+- Flash the device at [https://flasher.meshcore.co.uk/](https://flasher.meshcore.co.uk/). Choose the `Companion USB` role (or `Companion BLE` if you plan to use Bluetooth).
 - Configure the device with the Meshcore mobile app (from Google Play Store / App Store): Name, Location (optional), Preset

-**2. Linux Server**
+**2. Linux Server (or Raspberry Pi)**
 - Docker and Docker Compose installed ([installation guide](docs/docker-install.md))
 - Git installed (only needed for Option B: From Source)
+- Supported architectures: `linux/amd64`, `linux/arm64`, `linux/arm/v7` (Raspberry Pi 2/3/4/5 all work)

 **Important Notes:**
 - Powered by direct meshcore library integration (v2 architecture)
@@ -474,12 +477,15 @@ sudo ~/mc-webui/scripts/updater/install.sh --uninstall
 - [x] MeshCore Analyzer - Packet analysis links on channel messages (analyzer.letsmesh.net)
 - [x] DM Delivery Tracking - ACK-based delivery checkmarks with SNR/route details
 - [x] Device Dashboard - Device info, statistics, and contact sharing (QR/URI)
- [x] Settings Modal - DM retry parameters, message retention, and dark/light theme
+- [x] Device Configuration - Edit device name, coordinates (map picker), radio parameters from Settings
+- [x] Settings Modal - DM retry parameters, message retention, route popup / toast customization, and dark/light theme
+- [x] Quick-Access FAB Buttons - Draggable floating buttons with collapse toggle and size/spacing controls
 - [x] System Log - Real-time log viewer with streaming
 - [x] Database Backup - Create, list, and download backups from the UI
 - [x] Desktop Sidebar - Channel/contact sidebar for wide screens (tablet/desktop)
 - [x] Dark/Light Theme - Toggle between dark and light UI themes
 - [x] Multi-device Support - Database file named after device public key
+- [x] Multi-arch Docker Images - amd64, arm64, arm/v7 (Raspberry Pi supported)

 ### Next Steps

--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -55,6 +55,14 @@ Three transport options are supported with the following priority: **BLE > TCP >

 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.

+### Docker Entrypoint (BLE cleanup)
+
+`scripts/docker-entrypoint.sh` runs before the Flask app starts. When `MC_BLE_ADDRESS` is set, it uses D-Bus to check if BlueZ has an active session to the device and disconnects it. BlueZ auto-reconnects trusted devices, which leaves stale GATT notification handles that block `bleak` from establishing a new session. A clean disconnect at startup ensures the app starts with a fresh BLE state.
+
+### Multi-architecture Images
+
+Official images are built via GitHub Actions for `linux/amd64`, `linux/arm64`, and `linux/arm/v7` (Raspberry Pi 2/3/4/5 supported). Build dependencies (`gcc`, `python3-dev`, `libjpeg-dev`, `zlib1g-dev`) are installed and then purged to keep the final image size small while still compiling `Pillow` and `pycryptodome` from source when wheels are unavailable (notably on `arm/v7`). GHA layer cache (`cache-from` / `cache-to`) speeds up subsequent rebuilds. Images are pushed to both Docker Hub (`mawoj/mc-webui`) and GitHub Container Registry (`ghcr.io/marekwo/mc-webui`), with `latest` tag on `main` and `dev` tag on the `dev` branch.
+
 ---

 ## DeviceManager Architecture
@@ -67,6 +75,8 @@ The `DeviceManager` handles the connection to the MeshCore device via a direct s
 - **Real-time messages** - Instant message processing via callback events without polling
 - **Thread-safe queue** - Commands are serialized to prevent device lockups
 - **Auto-restart watchdog** - Monitors connection health and restarts the session on crash
+- **BLE keepalive & reconnect** - When using Bluetooth transport, a 60s keepalive loop detects "zombie" connections (reads still succeed but writes silently fail). On disconnect or keepalive failure, the manager marks the session as permanently failed and the `/health` endpoint returns 503, letting the Docker healthcheck trigger a fast container restart (~5s) to get a clean BLE state rather than attempting unreliable in-process reconnects
+- **Echo correlation** - Sent channel messages pre-compute their expected `pkt_payload` using the channel secret and send timestamp (±3s for clock drift), so incoming echoes are matched exactly instead of only by 1-byte channel hash (prevents misattribution when two messages go out simultaneously on the same channel)

 ---

@@ -97,9 +107,14 @@ mc-webui/
 │   │   ├── api.py                  # REST API endpoints
 │   │   └── views.py                # HTML views
 │   ├── static/                     # Frontend assets (CSS, JS, images, vendors)
+│   │   └── js/fab-utils.js         # Floating-button drag/collapse/sizing helpers
 │   └── templates/                  # HTML templates
 ├── docs/                           # Documentation
-├── scripts/                        # Utility scripts (update, watchdog, updater)
+├── scripts/
+│   ├── update.sh                   # Automated update script
+│   ├── docker-entrypoint.sh        # Container startup (BLE cleanup)
+│   ├── updater/                    # Remote update webhook service
+│   └── watchdog/                   # Container health monitor
 └── README.md
 ```

@@ -206,10 +221,14 @@ The use of SQLite allows for fast queries, reliable data storage, full-text sear
 | GET | `/api/device/stats` | Device statistics |
 | GET | `/api/device/settings` | Get device settings |
 | POST | `/api/device/settings` | Update device settings |
+| GET | `/api/device/config` | Get device configuration (name, coords, advert_loc_policy, radio params, tx_power) |
+| POST | `/api/device/config` | Update device configuration from Settings > Device tab |
 | POST | `/api/device/command` | Execute command (advert, floodadv) |
 | GET | `/api/device/commands` | List available special commands |
-| GET | `/api/chat/settings` | Get chat settings (quote length) |
+| GET | `/api/chat/settings` | Get chat settings (quote length, route popup timeout/no-autoclose) |
 | POST | `/api/chat/settings` | Update chat settings |
+| GET | `/api/ui/settings` | Get UI settings (toast timeout, no-autoclose, position) |
+| POST | `/api/ui/settings` | Update UI settings |
 | GET | `/api/retention-settings` | Get message retention settings |
 | POST | `/api/retention-settings` | Update retention settings |

--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -16,6 +16,7 @@ This guide covers all features and functionality of mc-webui. For installation i
 - [DM Path Management](#dm-path-management)
 - [Interactive Console](#interactive-console)
 - [Device Dashboard](#device-dashboard)
+- [Quick-Access FAB Buttons](#quick-access-fab-buttons)
 - [Settings](#settings)
 - [System Log](#system-log)
 - [Database Backup](#database-backup)
@@ -184,7 +185,9 @@ Access the Direct Messages feature:

 ### 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.
+While a message is being retried, the UI shows a live counter below the message bubble (e.g., "Attempt 3/11") starting from "Attempt 1/..." immediately after sending. When delivery is confirmed (or fails), delivery details (attempt, route used) appear instantly without needing to close and reopen the conversation.
+
+The route used (e.g., `5E->05->58->D1`) can be clicked to show a popup with full path details. Tapping individual route entries in the popup copies the path to the clipboard in comma-separated format (e.g. `5E,32,0D,8C`).

 ### DM Notifications

@@ -501,14 +504,64 @@ Share your device contact with others:

 ---

+## Quick-Access FAB Buttons
+
+A set of Floating Action Buttons (FAB) is pinned to the main chat and DM pages for one-tap access to common features:
+
+- **Filter** (funnel icon) - Open the message filter bar
+- **Search** (magnifier icon) - Open global full-text search (main chat only)
+- **Direct Messages** (envelope icon) - Jump to the DM page (main chat only)
+- **Contact Management** (person icon) - Open the Contact Management page (main chat only)
+- **Settings** (gear icon) - Open the Settings modal
+
+### Drag to Reposition
+
+Press and hold the small toggle button (chevron) and drag the FAB cluster to any corner of the screen. The position is saved to browser local storage per page (main chat and DM each have their own).
+
+### Collapse / Expand
+
+Tap the toggle button (short click, no drag) to hide or show the rest of the FAB cluster. Only the toggle remains visible when collapsed. The collapsed state is shared between main chat and DM views and persists across page loads.
+
+### Customization
+
+Open Settings → **Appearance** tab to adjust:
+- **Button size** - 28 to 72 pixels (default: 56)
+- **Spacing** - 2 to 24 pixels between buttons (default: 12)
+- **Reset position** - Reset both main chat and DM FAB positions to their defaults
+
+Size and spacing are applied live as you move the sliders.
+
+---
+
 ## Settings

 Access the Settings modal to configure application behavior:

-1. Click the menu icon (☰) in the navbar
+1. Click the menu icon (☰) in the navbar (or tap the gear FAB button)
 2. Select "Settings" from the menu

-### DM Retry Settings
+The modal is organized into tabs: **Device**, **Messages**, **Group Chat**, **Interface**, and **Appearance**.
+
+### Device Tab
+
+Configure your MeshCore device directly from the web UI. Split into two sub-tabs:
+
+**Public Info:**
+- **Name** - Device name (up to 32 characters)
+- **Latitude / Longitude** - GPS coordinates. Click the map pin button to open a map picker and click anywhere on the map to select coordinates
+- **Share position in advert** - Toggle whether GPS coordinates are broadcast in advertisement frames (maps to `advert_loc_policy`)
+
+**Radio Settings:**
+- **Load preset** - Apply a regional preset (Australia, EU/UK, USA/Canada, New Zealand, Switzerland, Vietnam, and more). Selecting a preset fills in frequency, bandwidth, spreading factor, and coding rate
+- **Frequency (MHz)** - LoRa carrier frequency
+- **Bandwidth (kHz)** - 7.8 / 10.4 / 15.6 / 20.8 / 31.25 / 41.7 / 62.5 / 125 / 250 / 500
+- **Spreading Factor** - 5-12
+- **Coding Rate** - 5-8
+- **TX Power (dBm)** - 0-30
+
+Changes are written to the device (via the `set` command internally) and are persisted on the device.
+
+### Messages Tab — DM Retry Settings

 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:

@@ -526,18 +579,36 @@ Configure how direct messages are retried when delivery is not confirmed. Settin

 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
+### Group Chat Tab

+**Quote Settings:**
 - **Max quote length** - Maximum number of bytes to include when quoting a message

-### Message Retention
-
+**Message Retention:**
 - **Live view days** - Number of days of messages shown in the live view (older messages are archived)

-### Theme
+**Route popup** (applies to both channel messages and DMs):
+- **Auto-close after (s)** - Seconds before the route popup (shown when tapping "SNR | Hops" under a message) closes automatically (default: 8)
+- **Don't close automatically** - Popup stays open until you tap outside it

+### Interface Tab
+
+Controls small notification toasts shown after actions (e.g. "Advert Sent", errors).
+
+- **Auto-close after (s)** - Seconds before a notification closes (default: 2.0)
+- **Don't close automatically** - Toasts stay visible until dismissed via their close button
+- **Position on screen** - Top-left / Top-right / Bottom-left / Bottom-right / Center
+
+### Appearance Tab
+
+**Theme:**
 - **Dark / Light** - Toggle between dark and light UI themes. The preference is saved in local browser storage

+**Quick Access Buttons:**
+- **Button size (px)** - Adjust the size of FAB buttons (default: 56)
+- **Spacing (px)** - Space between FAB buttons (default: 12)
+- **Position** - Reset FAB position to default (top-right)
+
 ---

 ## System Log