From 054b80926de63ca4b21df09ff299bdc6499cf707 Mon Sep 17 00:00:00 2001 From: MarekWo Date: Thu, 26 Mar 2026 18:08:58 +0100 Subject: [PATCH] docs: update documentation for path management, add contact, theme, sidebar - README: add multi-path routing, add contact via URI/QR, dark/light theme, desktop sidebar, device share tab, pubkey-based DB naming - User Guide: add sections for Adding Contacts (URI/QR/manual), DM Path Management (multi-path, repeater picker, map picker, keep path toggle), Device Share tab, theme setting, desktop sidebar notes - Architecture: add path management API endpoints (CRUD, reorder, reset, no_auto_flood), manual-add, push-to-device, move-to-cache endpoints, update DB naming to pubkey prefix Co-Authored-By: Claude Opus 4.6 --- README.md | 27 +++++++------- docs/architecture.md | 21 ++++++++--- docs/user-guide.md | 84 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 116 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index bb1aece..7291a75 100644 --- a/README.md +++ b/README.md @@ -13,25 +13,26 @@ A lightweight web interface providing browser-based access to MeshCore mesh netw ## Key Features -- **Mobile-first design** - Responsive UI optimized for small screens +- **Mobile-first design** - Responsive UI optimized for small screens, with desktop sidebar for wide screens - **Channel management** - Create, join, share (QR code), and switch between encrypted channels -- **Direct Messages (DM)** - Private messaging with searchable contact selector, delivery tracking, and configurable retry strategy +- **Direct Messages (DM)** - Private messaging with searchable contact selector, delivery tracking, configurable retry strategy, and multi-path routing - **Smart notifications** - Unread message counters per channel with cross-device sync -- **Contact management** - Manual approval mode, filtering, protection, ignoring, blocking, batch operations, and cleanup tools +- **Contact management** - Manual approval, add via URI/QR, filtering, protection, ignoring, blocking, batch operations, and cleanup tools - **Global search** - Full-text search across all messages (channels and DMs) with FTS5 backend - **Database** - Fast and reliable SQLite storage for messages, contacts, and configurations - **Contact map** - View contacts and own device on OpenStreetMap (Leaflet) with last seen info - **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 and statistics with firmware details -- **Settings** - Configurable DM retry parameters, message retention, and quote length +- **Device dashboard** - Device info, statistics, and contact sharing (QR code / URI) +- **Dark/Light theme** - Toggle between dark and light UI themes +- **Settings** - Configurable DM retry parameters, message retention, quote length, 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 - **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 -- **Multi-device support** - Database file named after device for easy multi-device setups +- **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) @@ -311,12 +312,12 @@ sudo ~/mc-webui/scripts/updater/install.sh --uninstall - [x] Frontend Chat View (Bootstrap UI, message display, quote/reply) - [x] Message Sending (Send form, reply, quote with configurable length) - [x] Intelligent Auto-refresh (10s checks, UI updates only when needed) -- [x] Contact Management (Approval, filtering, protection, ignore/block, batch operations, cleanup) +- [x] Contact Management (Approval, add via URI/QR, filtering, protection, ignore/block, batch operations, cleanup) - [x] Channel Management (Create, join, share via QR, delete with auto-cleanup) - [x] Public Channels (# prefix support, auto-key generation) - [x] Message Archiving (Daily archiving with browse-by-date selector) - [x] Smart Notifications (Unread counters per channel and total) -- [x] Direct Messages (DM) - Searchable contact selector, delivery tracking, configurable retry +- [x] Direct Messages (DM) - Searchable contact selector, delivery tracking, configurable retry, multi-path routing - [x] Global Message Search - Full-text search across channels and DMs (FTS5) - [x] Message Content Enhancements - Mention badges, clickable URLs, image previews - [x] @Mentions Autocomplete - Type @ to get contact suggestions with fuzzy search @@ -327,11 +328,13 @@ sudo ~/mc-webui/scripts/updater/install.sh --uninstall - [x] Echo Tracking - "Heard X repeats" badge for sent channel messages - [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 and statistics with firmware details -- [x] Settings Modal - Configurable DM retry parameters and message retention +- [x] Device Dashboard - Device info, statistics, and contact sharing (QR/URI) +- [x] Settings Modal - DM retry parameters, message retention, and dark/light theme - [x] System Log - Real-time log viewer with streaming - [x] Database Backup - Create, list, and download backups from the UI -- [x] Multi-device Support - Database file named after device name +- [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 ### Next Steps @@ -365,7 +368,7 @@ This is an open-source project. Contributions are welcome! ## References - [MeshCore Documentation](https://meshcore.org) -- [meshcore-cli GitHub](https://github.com/meshcore-dev/meshcore-cli) +- [meshcore Python library](https://pypi.org/project/meshcore/) --- diff --git a/docs/architecture.md b/docs/architecture.md index c46b084..c9887c0 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -21,7 +21,7 @@ Technical documentation for mc-webui, covering system architecture, project stru - **Frontend:** HTML5, Bootstrap 5, vanilla JavaScript, Socket.IO client - **Deployment:** Docker / Docker Compose (Single-container architecture) - **Communication:** Direct hardware access (USB, BLE, or TCP) via `meshcore` library -- **Data source:** SQLite Database (`./data/meshcore/.db`) +- **Data source:** SQLite Database (`./data/meshcore/.db`) --- @@ -80,8 +80,8 @@ mc-webui/ │ ├── config.py # Configuration from env vars │ ├── database.py # SQLite database models and CRUD operations │ ├── device_manager.py # Core logic for meshcore communication -│ ├── contacts_cache.py # Persistent contacts cache -│ ├── read_status.py # Server-side read status manager +│ ├── contacts_cache.py # Persistent contacts cache (DB-backed) +│ ├── read_status.py # Server-side read status manager (DB-backed) │ ├── version.py # Git-based version management │ ├── migrate_v1.py # Migration script from v1 flat files to v2 SQLite │ ├── meshcore/ @@ -107,7 +107,7 @@ mc-webui/ mc-webui v2 uses a robust **SQLite Database** with WAL (Write-Ahead Logging) enabled. -Location: `./data/meshcore/.db` +Location: `./data/meshcore/.db` Key tables: - `messages` - All channel and direct messages (with FTS5 index for full-text search) @@ -157,6 +157,19 @@ The use of SQLite allows for fast queries, reliable data storage, full-text sear | POST | `/api/contacts/pending/approve` | Approve pending contact | | POST | `/api/contacts/pending/reject` | Reject pending contact | | POST | `/api/contacts/pending/clear` | Clear all pending contacts | +| POST | `/api/contacts/manual-add` | Add contact from URI or params | +| POST | `/api/contacts//push-to-device` | Push cached contact to device | +| POST | `/api/contacts//move-to-cache` | Move device contact to cache | +| GET | `/api/contacts/repeaters` | List repeater contacts (for path picker) | +| GET | `/api/contacts//paths` | Get contact paths | +| POST | `/api/contacts//paths` | Add path to contact | +| PUT | `/api/contacts//paths/` | Update path (star, label) | +| DELETE | `/api/contacts//paths/` | Delete path | +| POST | `/api/contacts//paths/reorder` | Reorder paths | +| POST | `/api/contacts//paths/reset_flood` | Reset to FLOOD routing | +| POST | `/api/contacts//paths/clear` | Clear all paths | +| GET | `/api/contacts//no_auto_flood` | Get "Keep path" flag | +| PUT | `/api/contacts//no_auto_flood` | Set "Keep path" flag | ### Channels diff --git a/docs/user-guide.md b/docs/user-guide.md index 560e38c..3bd03aa 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -12,6 +12,8 @@ This guide covers all features and functionality of mc-webui. For installation i - [Direct Messages (DM)](#direct-messages-dm) - [Global Search](#global-search) - [Contact Management](#contact-management) +- [Adding Contacts](#adding-contacts) +- [DM Path Management](#dm-path-management) - [Interactive Console](#interactive-console) - [Device Dashboard](#device-dashboard) - [Settings](#settings) @@ -35,6 +37,8 @@ The main page displays chat history from the currently selected channel. The app By default, the live view shows messages from the last 7 days. Older messages are automatically archived and can be accessed via the date selector. +On wide screens (tablets/desktops), a sidebar shows the channel list on the left side for quick switching. + --- ## Managing Channels @@ -183,6 +187,10 @@ Access the Direct Messages feature: - Each conversation shows unread indicator (*) in the dropdown - DM badge in the menu shows total unread DM count +### Desktop Sidebar + +On wide screens (tablets/desktops), the DM page shows a sidebar with the contact list on the left side, making it easy to switch between conversations without using the dropdown selector. + --- ## Global Search @@ -345,6 +353,72 @@ You can schedule automatic cleanup to run daily at a specified hour: --- +## Adding Contacts + +Add new contacts to your device from the Contact Management page: + +1. Click the "Add Contact" button at the top of the Contact Management page +2. Opens a dedicated page with three methods: + +### Paste URI + +1. Paste a MeshCore contact URI (`meshcore://...`) into the text field +2. The contact details (name, public key, type) are automatically parsed and previewed +3. Click "Add to Device" to add the contact + +### Scan QR Code + +1. Click "Scan QR" to open the camera +2. Point at a MeshCore QR code (from another user's Share tab) +3. The URI is decoded and contact details are previewed +4. Click "Add to Device" to add the contact + +### Manual Entry + +1. Enter the contact's public key (64 hex characters) +2. Optionally enter name, type (COM/REP/ROOM/SENS), and location +3. Click "Add to Device" + +### Cache vs Device Contacts + +- **Device contacts** are stored on the MeshCore hardware (limit: 350) +- **Cache contacts** are stored only in the database (unlimited) +- Use "Push to Device" to promote a cache contact to the device +- Use "Move to Cache" to free a device slot while keeping the contact in the database + +--- + +## DM Path Management + +Configure message routing paths for individual contacts: + +1. Open a DM conversation +2. Click the contact info icon next to the contact name +3. In the Contact Info modal, navigate to the "Paths" section + +### Path Configuration + +- **Add Path** - Add a repeater to the routing path using: + - **Repeater picker** - Browse available repeaters by name or ID + - **Map picker** - Select repeaters from a map view showing their GPS locations + - **Import current path** - Import the path currently stored on the device +- **Reorder** - Drag paths to change priority (starred path is used first) +- **Star** - Mark a preferred primary path (used first in retry rotation) +- **Delete** - Remove individual paths + +### Keep Path Toggle + +- Enable "Keep path" to prevent the device from automatically switching to FLOOD routing +- When enabled, the device will always use the configured DIRECT path(s) +- Useful when you know the optimal route and don't want the device to override it + +### Path Operations + +- **Reset to FLOOD** - Clear all paths and switch to FLOOD routing +- **Clear Paths** - Remove all configured paths without changing routing mode + +--- + ## Interactive Console Access the interactive console for direct MeshCore command execution: @@ -414,6 +488,12 @@ Shows live device statistics: - Message counters (sent, received, forwarded) - Current airtime usage +### Share Tab + +Share your device contact with others: +- **QR Code** - Scannable QR code containing your contact URI +- **URI** - Copyable `meshcore://` URI that others can paste into their Add Contact page + --- ## Settings @@ -439,6 +519,10 @@ Configure how direct messages are retried when delivery is not confirmed: - **Live view days** - Number of days of messages shown in the live view (older messages are archived) +### Theme + +- **Dark / Light** - Toggle between dark and light UI themes. The preference is saved in local browser storage + --- ## System Log