mc-webui is a Flask-based web application that wraps meshcore-cli, eliminating the need for SSH/terminal access when using MeshCore chat on a LoRa device connected to a Debian VM via BLE or USB. Tested on Heltec V4.

Key Features

Mobile-first design - Responsive UI optimized for small screens
Channel management - Create, join, share (QR code), and switch between encrypted channels
Direct Messages (DM) - Private messaging with delivery status tracking
Smart notifications - Unread message counters per channel with cross-device sync
Contact management - Manual approval mode, filtering, cleanup tools
Contact map - View contacts with GPS coordinates on OpenStreetMap (Leaflet)
Message archives - Automatic daily archiving with browse-by-date selector
Interactive Console - Direct meshcli command execution via WebSocket
PWA support - Browser notifications and installable app (experimental)
Full offline support - Works without internet (local Bootstrap, icons, emoji picker)

For detailed feature documentation, see the User Guide.

Quick Start

Prerequisites

1. Meshcore Device (tested on Heltec V4)

Flash the device at https://flasher.meshcore.co.uk/. Choose the Companion USB role.
Configure the device with the Meshcore mobile app (from Google Play Store / App Store): Name, Location (optional), Preset

2. Linux Server

Git installed
Docker and Docker Compose installed (installation guide)

Important Notes:

No meshcore-cli installation required on host - automatically installed inside Docker container
No manual directory setup needed - all data stored in ./data/ inside the project directory
meshcore-cli version 1.3.12+ is automatically installed for proper DM functionality

Installation

Clone the repository

cd ~
git clone https://github.com/MarekWo/mc-webui
cd mc-webui

Create configuration file
```
cp .env.example .env
```
In most cases, no changes are needed! The defaults work automatically:
- MC_SERIAL_PORT=auto - auto-detects your USB device
- MC_DEVICE_NAME=auto - auto-detects device name from meshcli
Optionally edit .env to set your timezone: TZ=Europe/Warsaw
Troubleshooting: Multiple USB devices or detection fails

Check available serial devices:
```
ls /dev/serial/by-id/
```
If you see multiple devices, edit .env and set MC_SERIAL_PORT explicitly:
```
MC_SERIAL_PORT=/dev/serial/by-id/usb-Espressif_Systems_heltec_...
```

Verify Serial Device Permissions (if needed)

sudo usermod -aG dialout $USER
# Log out and log back in for changes to take effect

Build and run
```
python3 -m app.version freeze
docker compose up -d --build
```
This will:
- Download base images (Python, Alpine Linux)
- Install meshcore-cli inside containers
- Create ./data/ directory structure automatically
- Start both containers (meshcore-bridge and mc-webui)
Verify installation
```
docker compose ps
```
Both containers should show Up status. Check logs if needed:
```
docker compose logs -f
```
Access the web interface

Open your browser and navigate to:
```
http://<your-server-ip>:5000
```
To find your server IP: hostname -I | awk '{print $1}'
Initial Configuration (In Web UI)
- Main page loads with chat interface on "Public" channel
- Wait for initial sync (1-2 minutes)
- Optional: Enable manual contact approval in Contact Management

Basic Usage

View messages - Main page shows chat history with auto-refresh every 10 seconds
Send messages - Type in the text field and press Enter (140 byte limit)
Switch channels - Use the dropdown in navbar
Direct Messages - Access via menu (☰) → "Direct Messages"
Manage contacts - Access via menu (☰) → "Contact Management"
Console - Access via menu (☰) → "Console" for direct meshcli commands

For complete usage instructions, see the User Guide.

Updating

Using the update script (recommended)

The easiest way to update mc-webui:

cd ~/mc-webui
./scripts/update.sh

The script automatically pulls changes, freezes the version, and rebuilds containers.

Optional: Create a global alias for quick updates

Add to your ~/.bashrc or ~/.zshrc:

alias mcupdate='~/mc-webui/scripts/update.sh'

Then reload your shell (source ~/.bashrc) and update anytime with:

mcupdate

Manual update

If you prefer to run commands manually:

cd ~/mc-webui
git pull
python3 -m app.version freeze
docker compose up -d --build

The python3 -m app.version freeze command captures the current Git version (date + commit hash) for display in the app menu.

Testing experimental features

The dev branch contains new features that are still being tested:

cd ~/mc-webui
git checkout dev
./scripts/update.sh

To return to the stable version:

cd ~/mc-webui
git checkout main
./scripts/update.sh

Documentation

Document	Description
User Guide	Complete feature documentation
Architecture	Technical details, API reference
Troubleshooting	Common issues and solutions
Docker Installation	How to install Docker on Debian/Ubuntu

Development Status

Completed Features

Environment Setup & Docker Architecture
Backend Basics (REST API, message parsing, CLI wrapper)
Frontend Chat View (Bootstrap UI, message display)
Message Sending (Send form, reply functionality)
Intelligent Auto-refresh (10s checks, UI updates only when needed)
Contact Management (Cleanup modal with configurable threshold)
Channel Management (Create, join, share via QR, delete with auto-cleanup)
Public Channels (# prefix support, auto-key generation)
Message Archiving (Daily archiving with browse-by-date selector)
Smart Notifications (Unread counters per channel and total)
Direct Messages (DM) - Private messaging with delivery status tracking
Advanced Contact Management - Multi-page interface with sorting, filtering
Message Content Enhancements - Mention badges, clickable URLs, image previews
PWA Notifications (Experimental) - Browser notifications and app badge counters
Full Offline Support - Local Bootstrap libraries and Service Worker caching
Interactive Console - Direct meshcli access via WebSocket with command history
Contact Map - View contacts with GPS coordinates on OpenStreetMap (Leaflet)

Next Steps

Performance Optimization - Frontend and backend improvements
Enhanced Testing - Unit and integration tests
Documentation Polish - API docs and usage guides

Security Notes

Important: This application is designed for trusted local networks only and has no authentication. Do not expose it to the internet without implementing proper security measures.

Contributing

This is an open-source project. Contributions are welcome!

All code, comments, and documentation must be in English
Follow the existing code style
Test your changes with real hardware if possible

License

References

Contact

Languages

Python 46.7%

JavaScript 34.9%

HTML 12.2%

CSS 5.2%

Shell 0.9%