7.2 KiB
mc-webui
A lightweight web interface for meshcore-cli, providing browser-based access to MeshCore mesh network.
Overview
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 Heltec V4 device connected to a Debian VM.
Key Features
- 📱 View messages - Display chat history from Public channel with auto-refresh
- ✉️ Send messages - Publish to Public channel (200 char limit for LoRa)
- 💬 Reply to users - Quick reply with
@[UserName]format - 🧹 Clean contacts - Remove inactive contacts with configurable threshold
- 📦 Message archiving - Automatic daily archiving with browse-by-date selector
Tech Stack
- Backend: Python 3.11+, Flask
- Frontend: HTML5, Bootstrap 5, vanilla JavaScript
- Deployment: Docker / Docker Compose
- Communication: subprocess calls to
meshcli - Data source:
~/.config/meshcore/<device_name>.msgs(JSON Lines)
Quick Start
Prerequisites
- Docker and Docker Compose installed
- Heltec V4 device connected via USB
- meshcore-cli configured on host system
Installation
-
Clone the repository
git clone <repository-url> cd mc-webui -
Configure environment
cp .env.example .env # Edit .env with your settings nano .env -
Find your serial device
ls -l /dev/serial/by-id/Update
MC_SERIAL_PORTin.envwith your device path. -
Build and run
docker compose up -d --build -
Access the web interface Open your browser and navigate to:
http://localhost:5000Or from another device on your network:
http://<server-ip>:5000
Configuration
All configuration is done via environment variables in the .env file:
| Variable | Description | Default |
|---|---|---|
MC_SERIAL_PORT |
Path to serial device | /dev/ttyUSB0 |
MC_DEVICE_NAME |
Device name (for .msgs file) | MeshCore |
MC_CONFIG_DIR |
meshcore configuration directory | /root/.config/meshcore |
MC_REFRESH_INTERVAL |
Auto-refresh interval (seconds) | 60 |
MC_INACTIVE_HOURS |
Inactivity threshold for cleanup | 48 |
MC_ARCHIVE_DIR |
Archive directory path | /mnt/archive/meshcore |
MC_ARCHIVE_ENABLED |
Enable automatic archiving | true |
MC_ARCHIVE_RETENTION_DAYS |
Days to show in live view | 7 |
FLASK_HOST |
Listen address | 0.0.0.0 |
FLASK_PORT |
Application port | 5000 |
FLASK_DEBUG |
Debug mode | false |
See .env.example for a complete example.
Project Structure
mc-webui/
├── Dockerfile # Docker image definition
├── docker-compose.yml # Docker Compose configuration
├── app/
│ ├── __init__.py
│ ├── main.py # Flask entry point
│ ├── config.py # Configuration from env vars
│ ├── meshcore/
│ │ ├── __init__.py
│ │ ├── cli.py # meshcli wrapper (subprocess)
│ │ └── parser.py # .msgs file parser
│ ├── routes/
│ │ ├── __init__.py
│ │ ├── api.py # REST API endpoints
│ │ └── views.py # HTML views
│ ├── static/
│ │ ├── css/
│ │ │ └── style.css # Custom styles
│ │ └── js/
│ │ └── app.js # Frontend logic
│ └── templates/
│ ├── base.html # Base template
│ ├── index.html # Main chat view
│ └── components/ # Reusable components
├── requirements.txt # Python dependencies
├── .env.example # Example environment config
├── .gitignore
├── README.md # This file
└── PRD.md # Product Requirements Document
Development Status
🚧 Current Phase: 1 - Backend Basics ✅
Roadmap
- Phase 0: Environment Setup
- Phase 1: Backend Basics (REST API, message parsing, CLI wrapper)
- Phase 2: Frontend Chat View (Bootstrap UI, message display)
- Phase 3: Message Sending (Send form, reply functionality)
- Phase 4: Auto-refresh (60s polling, live updates)
- Phase 5: Contact Management (Cleanup modal)
- Phase 6: Polish & Documentation (Testing, optimization)
See PRD.md for detailed requirements and implementation plan.
Usage
Viewing Messages
The main page displays chat history from the Public channel (channel 0). Messages auto-refresh every 60 seconds by default.
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.
Viewing Message Archives
Access historical messages using the date selector in the navbar:
- Click the date dropdown in the navbar (next to Refresh button)
- Select a date to view archived messages for that day
- Select "Today (Live)" to return to live view
Archives are created automatically at midnight (00:00 UTC) each day. The live view always shows the most recent messages (last 7 days by default).
Sending Messages
- Type your message in the text field at the bottom
- Press Enter or click "Send"
- Your message will be published to the Public channel
Replying to Users
Click the reply button on any message to insert @[UserName] into the text field, then type your reply.
Managing Contacts
Access the settings panel to clean up inactive contacts:
- Click the settings icon
- Adjust the inactivity threshold (default: 48 hours)
- Click "Clean Inactive Contacts"
- Confirm the action
Docker Commands
# Start the application
docker compose up -d
# View logs
docker compose logs -f
# Stop the application
docker compose down
# Rebuild after code changes
docker compose up -d --build
# Check container status
docker compose ps
Troubleshooting
Device not found
# Check if device is connected
ls -l /dev/serial/by-id/
# Verify device permissions
sudo chmod 666 /dev/serial/by-id/usb-Espressif*
Container won't start
# Check logs
docker compose logs mc-webui
# Verify .env file exists
ls -la .env
# Check if port 5000 is available
sudo netstat -tulpn | grep 5000
Messages not updating
- Ensure meshcore-cli is properly configured
- Check that
.msgsfile exists inMC_CONFIG_DIR - Verify serial device is accessible from container
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
[License TBD]