A lightweight web interface for meshcore-cli, providing browser-based access to MeshCore mesh network.

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.

• 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.

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

1. Clone the repository

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

2. 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_...

3. Verify Serial Device Permissions (if needed)

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

4. 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)

5. Verify installation

   docker compose ps

   Both containers should show Up status. Check logs if needed:

   docker compose logs -f

6. 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}'

7. 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

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

For complete usage instructions, see the User Guide.

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

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.

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

• 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)

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

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.

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

• MeshCore Documentation
• meshcore-cli GitHub