adam/mc-webui
1
0
Fork 0
mirror of https://github.com/MarekWo/mc-webui.git synced 2026-08-08 09:42:55 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: comprehensive documentation update for v2 features

Browse Source 
Update all documentation to reflect features added since last doc update:
- README: new features list, gallery screenshots, development status
- User Guide: global search, console commands, device dashboard, settings,
  system log, backup, updated DM and contact management sections
- Architecture: complete API reference, WebSocket namespaces, updated
  project structure and database tables
- Troubleshooting: remove v1 bridge references, add UI-based backup,
  system log references
- Gallery: add 4 new screenshots (search, filtering, settings, system log),
  update 12 existing screenshots

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
MarekWo
2026-03-21 16:26:52 +01:00
parent ce8227247f
commit 66ada3d03c
20 changed files with 348 additions and 168 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture.md
+126 -17
View File
@@ -10,6 +10,7 @@ Technical documentation for mc-webui, covering system architecture, project stru
- [Project Structure](#project-structure)
- [Database Architecture](#database-architecture)
- [API Reference](#api-reference)
- [WebSocket API](#websocket-api)
- [Offline Support](#offline-support)
---
@@ -75,11 +76,13 @@ mc-webui/
├── docker-compose.yml # Single-container orchestration
├── app/
│ ├── __init__.py
│ ├── main.py # Flask entry point + Socket.IO
│ ├── main.py # Flask entry point + Socket.IO handlers
│ ├── 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
│ ├── version.py # Git-based version management
│ ├── migrate_v1.py # Migration script from v1 flat files to v2 SQLite
│ ├── meshcore/
│ │ ├── __init__.py
@@ -94,7 +97,7 @@ mc-webui/
│ ├── static/ # Frontend assets (CSS, JS, images, vendors)
│ └── templates/ # HTML templates
├── docs/ # Documentation
├── scripts/ # Utility scripts (update, watchdog, etc.)
├── scripts/ # Utility scripts (update, watchdog, updater)
└── README.md
```
@@ -107,45 +110,151 @@ mc-webui v2 uses a robust **SQLite Database** with WAL (Write-Ahead Logging) ena
Location: `./data/meshcore/<device_name>.db`
Key tables:
- `messages` - All channel and direct messages
- `messages` - All channel and direct messages (with FTS5 index for full-text search)
- `contacts` - Contact list with sync status, types, block/ignore flags
- `channels` - Channel configuration and keys
- `echoes` - Sent message tracking and repeater paths
- `acks` - DM delivery status
- `settings` - Application settings (migrated from .webui_settings.json)
The use of SQLite allows for fast queries, reliable data storage, and complex filtering (such as contact ignoring/blocking) without the risk of file corruption inherent to flat JSON files.
The use of SQLite allows for fast queries, reliable data storage, full-text search, and complex filtering (such as contact ignoring/blocking) without the risk of file corruption inherent to flat JSON files.
---
## API Reference
### Main Web UI Endpoints
### Messages
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/messages` | List messages (supports `?archive_date`, `?days`, `?channel_idx`) |
| GET | `/api/messages` | List messages (`?archive_date`, `?days`, `?channel_idx`) |
| POST | `/api/messages` | Send message (`{text, channel_idx, reply_to?}`) |
| GET | `/api/messages/updates` | Check for new messages (smart refresh) |
| GET | `/api/status` | Connection status |
| GET | `/api/messages/<id>/meta` | Get message metadata (echoes, paths) |
| GET | `/api/messages/search` | Full-text search (`?q=`, `?channel_idx=`, `?limit=`) |
### Contacts
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/contacts` | List contacts |
| GET | `/api/contacts/detailed` | Full contact data |
| POST | `/api/contacts/delete` | Soft-delete contact by name |
| POST | `/api/contacts/update` | Update contact properties (ignore, block) |
| GET | `/api/contacts/detailed` | Full contact data (includes protection, ignore, block flags) |
| GET | `/api/contacts/cached` | Get cached contacts (superset of device contacts) |
| POST | `/api/contacts/delete` | Soft-delete contact (`{selector}`) |
| POST | `/api/contacts/cached/delete` | Delete cached contact |
| GET | `/api/contacts/protected` | List protected public keys |
| POST | `/api/contacts/<key>/protect` | Toggle contact protection |
| POST | `/api/contacts/<key>/ignore` | Toggle contact ignore |
| POST | `/api/contacts/<key>/block` | Toggle contact block |
| GET | `/api/contacts/blocked-names` | Get blocked names count |
| POST | `/api/contacts/block-name` | Block a name pattern |
| GET | `/api/contacts/blocked-names-list` | List blocked name patterns |
| POST | `/api/contacts/preview-cleanup` | Preview cleanup criteria |
| POST | `/api/contacts/cleanup` | Remove contacts by filter |
| GET | `/api/contacts/cleanup-settings` | Get auto-cleanup settings |
| POST | `/api/contacts/cleanup-settings` | Update auto-cleanup settings |
| GET | `/api/contacts/pending` | Pending contacts (`?types=1&types=2`) |
| 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 |
### Channels
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/channels` | List all channels |
| POST | `/api/channels` | Create new channel |
| POST | `/api/channels/join` | Join existing channel |
| DELETE | `/api/channels/<index>` | Remove channel |
| GET | `/api/dm/conversations` | List DM conversations |
| GET | `/api/dm/messages` | Get messages for conversation |
| POST | `/api/dm/messages` | Send DM |
| GET | `/api/device/info` | Device information |
| GET | `/api/read_status` | Get server-side read status |
| GET | `/api/channels/<index>/qr` | QR code (`?format=json\|png`) |
| GET | `/api/channels/muted` | Get muted channels |
| POST | `/api/channels/<index>/mute` | Toggle channel mute |
### WebSocket API (Console)
### Direct Messages
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/dm/conversations` | List DM conversations |
| GET | `/api/dm/messages` | Get messages (`?conversation_id=`, `?limit=`) |
| POST | `/api/dm/messages` | Send DM (`{recipient, text}`) |
| GET | `/api/dm/updates` | Check for new DMs |
| GET | `/api/dm/auto_retry` | Get DM retry configuration |
| POST | `/api/dm/auto_retry` | Update DM retry configuration |
### Device & Settings
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/status` | Connection status (device name, serial port) |
| GET | `/api/device/info` | Device information |
| GET | `/api/device/stats` | Device statistics |
| GET | `/api/device/settings` | Get device settings |
| POST | `/api/device/settings` | Update device settings |
| 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) |
| POST | `/api/chat/settings` | Update chat settings |
| GET | `/api/retention-settings` | Get message retention settings |
| POST | `/api/retention-settings` | Update retention settings |
### Archives & Backup
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/archives` | List archives |
| POST | `/api/archive/trigger` | Manual archive |
| GET | `/api/backup/list` | List database backups |
| POST | `/api/backup/create` | Create database backup |
| GET | `/api/backup/download` | Download backup file |
### Other
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/read_status` | Get server-side read status |
| POST | `/api/read_status/mark_read` | Mark messages as read |
| POST | `/api/read_status/mark_all_read` | Mark all messages as read |
| GET | `/api/version` | Get app version |
| GET | `/api/check-update` | Check for available updates |
| GET | `/api/updater/status` | Get updater service status |
| POST | `/api/updater/trigger` | Trigger remote update |
| GET | `/api/advertisements` | Get recent advertisements |
| GET | `/api/console/history` | Get console command history |
| POST | `/api/console/history` | Save console command |
| DELETE | `/api/console/history` | Clear console history |
| GET | `/api/logs` | Get application logs |
---
## WebSocket API
### Console Namespace (`/console`)
Interactive console via Socket.IO WebSocket connection.
**Namespace:** `/console`
**Client → Server:**
- `send_command` - Execute command (`{command: "infos"}`)
**Server → Client:**
- `console_status` - Connection status
- `command_response` - Command result (`{success, command, output}`)
### Chat Namespace (`/chat`)
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
- `dm_ack` - DM delivery confirmation
### Logs Namespace (`/logs`)
Real-time log streaming via Socket.IO.
**Server → Client:**
- `log_line` - New log line
---
docs/troubleshooting.md
+28 -127
View File
@@ -5,9 +5,8 @@ Common issues and solutions for mc-webui.
## Table of Contents
- [Common Issues](#common-issues)
- [Device Not Responding](#device-not-responding-bridge-crash-loop)
- [Device Not Responding](#device-not-responding)
- [Docker Commands](#docker-commands)
- [Testing Bridge API](#testing-bridge-api)
- [Backup and Restore](#backup-and-restore)
- [Next Steps](#next-steps)
- [Getting Help](#getting-help)
@@ -20,8 +19,7 @@ Common issues and solutions for mc-webui.
**Check logs:**
```bash
docker compose logs meshcore-bridge
docker compose logs mc-webui
docker compose logs -f mc-webui
```
**Common causes:**
@@ -53,18 +51,19 @@ docker compose ps
### No messages appearing
**Verify meshcli is working:**
**Check device connection:**
```bash
# Test meshcli directly in bridge container
docker compose exec meshcore-bridge meshcli -s /dev/ttyUSB0 infos
# Check container logs for device communication
docker compose logs -f mc-webui
```
**Check .msgs file:**
**Check database:**
```bash
docker compose exec mc-webui cat /root/.config/meshcore/YourDeviceName.msgs
# Verify the database file exists
ls -la data/meshcore/*.db
```
Replace `YourDeviceName` with your `MC_DEVICE_NAME`.
**Check System Log in the web UI** (Menu → System Log) for real-time device event information.
---
@@ -87,9 +86,9 @@ sudo chmod 666 /dev/serial/by-id/usb-Espressif*
ls -l /dev/serial/by-id/
```
**Restart bridge container:**
**Restart container:**
```bash
docker compose restart meshcore-bridge
docker compose restart mc-webui
```
**Check device permissions:**
@@ -101,32 +100,15 @@ Should show `crw-rw----` with group `dialout`.
---
### USB Communication Issues
The 2-container architecture resolves common USB timeout/deadlock problems:
- **meshcore-bridge** has exclusive USB access
- **mc-webui** uses HTTP (no direct device access)
- Restarting `mc-webui` **does not** affect USB connection
- If bridge has USB issues, restart only that service:
```bash
docker compose restart meshcore-bridge
```
---
### Device not responding (bridge crash-loop)
### Device not responding
**Symptoms:**
- `meshcore-bridge` container shows `unhealthy` status
- Bridge logs show repeated `no_event_received` errors and restarts:
- Container logs show repeated `no_event_received` errors and restarts:
```
ERROR:meshcore:Error while querying device: Event(type=<EventType.ERROR: 'command_error'>, payload={'reason': 'no_event_received'})
meshcli process died (exit code: 0)
Attempting to restart meshcli session...
```
- Device name not detected, falls back to `auto.msgs` (file not found)
- All commands (`infos`, `contacts`, etc.) time out
- Device name not detected (auto-detection fails)
- All commands timeout in the Console
**What this means:**
@@ -148,44 +130,15 @@ This can happen after a power failure during OTA update, flash memory corruption
---
### Bridge connection errors
```bash
# Check bridge health
docker compose exec mc-webui curl http://meshcore-bridge:5001/health
# Bridge logs
docker compose logs -f meshcore-bridge
# Test meshcli directly in bridge container
docker compose exec meshcore-bridge meshcli -s /dev/ttyUSB0 infos
```
---
### Messages not updating
- Check that `.msgs` file exists in `MC_CONFIG_DIR`
- Verify bridge service is healthy: `docker compose ps`
- Check bridge logs for command errors
---
### Contact Management Issues
**Check logs:**
```bash
# mc-webui container logs
docker compose logs -f mc-webui
# meshcore-bridge container logs (where settings are applied)
docker compose logs -f meshcore-bridge
```
**Look for:**
- "Loaded webui settings" - confirms settings file is being read
- "manual_add_contacts set to on/off" - confirms setting is applied to meshcli session
- "Saved manual_add_contacts=..." - confirms setting is persisted to file
You can also check the System Log in the web UI (Menu → System Log) for real-time information about contact events and settings changes.
---
@@ -194,17 +147,13 @@ docker compose logs -f meshcore-bridge
### View logs
```bash
docker compose logs -f # All services
docker compose logs -f mc-webui # Main app only
docker compose logs -f meshcore-bridge # Bridge only
docker compose logs -f mc-webui
```
### Restart services
### Restart
```bash
docker compose restart # Restart both
docker compose restart mc-webui # Restart main app only
docker compose restart meshcore-bridge # Restart bridge only
docker compose restart mc-webui
```
### Start / Stop
@@ -230,69 +179,22 @@ docker compose ps
```bash
docker compose exec mc-webui sh
docker compose exec meshcore-bridge sh
```
---
## Testing Bridge API
The `meshcore-bridge` container exposes HTTP endpoints for diagnostics.
### Test endpoints
```bash
# List pending contacts (from inside mc-webui container or server)
curl -s http://meshcore-bridge:5001/pending_contacts | jq
# Add a pending contact
curl -s -X POST http://meshcore-bridge:5001/add_pending \
-H 'Content-Type: application/json' \
-d '{"selector":"Skyllancer"}' | jq
# Check bridge health
docker compose exec mc-webui curl http://meshcore-bridge:5001/health
```
### Example responses
**GET /pending_contacts:**
```json
{
"success": true,
"pending": [
{
"name": "Skyllancer",
"public_key": "f9ef..."
},
{
"name": "KRA Reksio mob2🐕",
"public_key": "41d5..."
}
],
"raw_stdout": "Skyllancer: f9ef...\nKRA Reksio mob2🐕: 41d5..."
}
```
**POST /add_pending:**
```json
{
"success": true,
"stdout": "Contact added successfully",
"stderr": "",
"returncode": 0
}
```
**Note:** These endpoints require `manual_add_contacts` mode to be enabled.
---
## Backup and Restore
**All important data is in the `data/` directory.**
### Create backup
### UI Backup (recommended)
You can create and download database backups directly from the web UI:
1. Click the menu icon (☰) → "Backup"
2. Click "Create Backup" to create a timestamped backup
3. Click "Download" to save a backup to your local machine
### Manual backup (CLI)
```bash
cd ~/mc-webui
@@ -343,9 +245,8 @@ After successful installation:
- [Architecture](architecture.md) - Technical documentation
- [README](../README.md) - Installation guide
- MeshCore docs: https://meshcore.org
- meshcore-cli docs: https://github.com/meshcore-dev/meshcore-cli
**Issues:**
- GitHub Issues: https://github.com/MarekWo/mc-webui/issues
- Check existing issues before creating new ones
- Include logs when reporting problems
- Include logs when reporting problems (use Menu → System Log for easy access)
docs/user-guide.md
+158 -6
View File
@@ -10,7 +10,13 @@ This guide covers all features and functionality of mc-webui. For installation i
- [Sending Messages](#sending-messages)
- [Message Content Features](#message-content-features)
- [Direct Messages (DM)](#direct-messages-dm)
- [Global Search](#global-search)
- [Contact Management](#contact-management)
- [Interactive Console](#interactive-console)
- [Device Dashboard](#device-dashboard)
- [Settings](#settings)
- [System Log](#system-log)
- [Database Backup](#database-backup)
- [Network Commands](#network-commands)
- [PWA Notifications](#pwa-notifications)
@@ -146,11 +152,12 @@ Access the Direct Messages feature:
### Using the DM Page
1. **Select a recipient** from the dropdown at the top:
1. **Select a recipient** using the searchable contact selector at the top:
- Type to search contacts by name (fuzzy matching)
- **Existing conversations** are shown first (with message history)
- Separator: "--- Available contacts ---"
- **All companion contacts** from your device (only COM type, no repeaters/rooms)
- You can start a new conversation with anyone in your contacts list
- Click the info icon next to a contact to view their details (public key, type, location)
- Use the (x) button to clear the search and select a different contact
2. Type your message in the input field (max 140 bytes, same as channels)
3. Use the emoji picker button to insert emojis
4. Press Enter or click Send
@@ -162,7 +169,7 @@ Access the Direct Messages feature:
- When you return to the DM page, it automatically opens the last conversation you were viewing
- This works similarly to how the main page remembers your selected channel
**Note:** Only companion contacts (COM) are shown in the dropdown. Repeaters (REP), rooms (ROOM), and sensors (SENS) are automatically filtered out.
**Note:** Only companion contacts (COM) are shown in the selector. Repeaters (REP), rooms (ROOM), and sensors (SENS) are automatically filtered out.
### Message Status Indicators
@@ -178,6 +185,23 @@ Access the Direct Messages feature:
---
## Global Search
Search across all your messages (channels and DMs) using full-text search:
1. Click the menu icon (☰) in the navbar
2. Select "Search" from the menu
3. Type your search query and press Enter or click the search button
**Features:**
- **Full-text search** powered by SQLite FTS5 for fast results
- **FTS5 syntax support** - Use quotes for exact phrases (`"hello world"`), prefix matching (`mesh*`), boolean operators (`hello AND world`)
- Results show message content, sender, channel/conversation, and timestamp
- Click a result to navigate to that channel or DM conversation
- Syntax help available via the (?) icon next to the search field
---
## Contact Management
Access the Contact Management feature to control who can connect to your node:
@@ -225,8 +249,12 @@ When manual approval is enabled, new contacts appear in the Pending Contacts lis
- Confirmation modal shows list of contacts to be approved
- Progress indicator during batch approval
**Ignore contacts:**
- **Batch ignore:** Click "Ignore Filtered" to ignore all filtered contacts at once
- **Single ignore:** Click "Ignore" on individual contacts
**Other actions:**
- Click "Map" button to view contact location on Google Maps (when GPS data available)
- Click "Map" button to view contact location on the map (when GPS data available)
- Click "Copy Key" to copy full public key to clipboard
- Click "Refresh" to reload pending contacts list
@@ -317,6 +345,130 @@ You can schedule automatic cleanup to run daily at a specified hour:
---
## Interactive Console
Access the interactive console for direct MeshCore command execution:
1. Click the menu icon (☰) in the navbar
2. Select "Console" from the menu
3. Opens in a fullscreen modal with a command prompt
### Available Command Categories
The console supports a comprehensive set of MeshCore commands organized into categories:
**Repeater Management:**
- `req_owner <name>` - Request repeater owner info
- `req_regions <name>` - Request repeater regions
- `req_clock <name>` - Request repeater clock
- `req_neighbours <name>` - Request repeater neighbors list
- `set_owner <name> <value>` - Set repeater owner
- `set_regions <name> <value>` - Set repeater regions
- `set_clock <name>` - Sync repeater clock
**Contact Management:**
- `contacts` - List all device contacts
- `.contacts` - List contacts (JSON format)
- `.pending_contacts` - List pending contacts
- `add_pending <key>` - Approve pending contact
- `remove_contact <name>` - Remove contact
**Device & Channel Management:**
- `infos` / `ver` - Device info / firmware version
- `stats` - Device statistics
- `self_telemetry` - Own device telemetry
- `get_channels` - List channels
- `get <param>` / `set <param> <value>` - Get/set device parameters
- `trace <name>` - Trace route to contact
- `neighbours` - Request neighbor list from device
### Console Features
- **Command history** - Navigate with up/down arrows, or use the history dropdown
- **Persistent history** - Saved on server, accessible across sessions
- **Auto-reconnect** - WebSocket reconnects automatically on disconnect
- **Status indicator** - Green/yellow/red dot shows connection status
- **Human-readable output** - Clock times, statistics, and telemetry formatted for readability
---
## Device Dashboard
Access device information and statistics:
1. Click the menu icon (☰) in the navbar
2. Select "Device Info" from the menu
### Info Tab
Displays device parameters in a readable table:
- Device name, type, public key
- Location coordinates with map button
- Radio parameters (frequency, bandwidth, spreading factor, coding rate)
- TX power, multi-acks, location sharing settings
### Stats Tab
Shows live device statistics:
- Uptime, free memory, battery voltage
- Message counters (sent, received, forwarded)
- Current airtime usage
---
## Settings
Access the Settings modal to configure application behavior:
1. Click the menu icon (☰) in the navbar
2. Select "Settings" from the menu
### 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
### Quote Settings
- **Max quote length** - Maximum number of bytes to include when quoting a message
### Message Retention
- **Live view days** - Number of days of messages shown in the live view (older messages are archived)
---
## System Log
View real-time application logs:
1. Click the menu icon (☰) in the navbar
2. Select "System Log" from the menu
3. Opens in a fullscreen modal with streaming log output
The log viewer shows the most recent application log entries and streams new entries in real-time. Useful for monitoring device events, debugging issues, and verifying message delivery.
---
## Database Backup
Create and manage database backups:
1. Click the menu icon (☰) in the navbar
2. Select "Backup" from the menu
**Features:**
- **Create backup** - Creates a timestamped copy of the current database
- **List backups** - View all available backups with timestamps and file sizes
- **Download** - Download any backup file to your local machine
Backups are stored in the `./data/` directory alongside the main database.
---
## Network Commands
Access network commands from the slide-out menu under "Network Commands" section:
@@ -432,6 +584,6 @@ To get the full PWA experience with app badge counters:
- **Repeater Management:** [rpt-mgmt.md](rpt-mgmt.md)
- **Troubleshooting:** [troubleshooting.md](troubleshooting.md)
- **Architecture:** [architecture.md](architecture.md)
- **Container Watchdog:** [watchdog.md](watchdog.md)
- **MeshCore docs:** https://meshcore.org
- **meshcore-cli docs:** https://github.com/meshcore-dev/meshcore-cli
- **GitHub Issues:** https://github.com/MarekWo/mc-webui/issues