MeshTUI

MeshTUI: A Full-Featured MeshCore Client with Terminal UI

Description

MeshTUI is a comprehensive terminal user interface (TUI) client for MeshCore devices. Built with Textual, it provides a complete mesh networking experience with an intuitive, keyboard-driven interface for managing mesh networks, sending messages, administering nodes, and monitoring network status.

Unlike the command-line meshcore-cli, MeshTUI offers a rich visual interface with real-time updates, persistent message history, contact management, device configuration, and full node administration capabilities all in one terminal window.

Features

Real-time chat interface with contacts and channels
Message delivery tracking - ACK tracking, retry logic, and delivery status
Device management - scan, connect, and monitor MeshCore devices
Device identification - automatically detects and identifies MeshCore devices
Contact management - view, add, and manage mesh network contacts
Channel creation - create custom encrypted channels with auto-hash support
Node management - remote control of repeaters and room servers
Message history - browse and search through message history with delivery status
Async operations - built with asyncio for responsive UI
Multiple connection types - BLE, TCP, and Serial support
TCP Proxy (⚠️ Experimental) - Expose Serial/BLE devices over TCP for remote access
Command line options - specify connection method and device directly
Integrated logs - all logging output displayed in a dedicated Logs tab within the TUI
Configuration persistence - remembers device connections and settings
Automatic retry - messages automatically retry with flood routing fallback
F1 Help - comprehensive in-app help system

Message Delivery Tracking

MeshTUI provides comprehensive message delivery tracking for direct messages:

✓ Sent - Message successfully transmitted from your device
✓ Heard X repeats - Number of repeaters that acknowledged forwarding the message
✗ Delivery failed - No repeaters responded within timeout period
Automatic retry - Up to 3 send attempts with intelligent flood routing fallback
Database tracking - All delivery information stored for later analysis

Note: Channel broadcasts show "✓ Sent (broadcast)" and don't have ACK tracking (per MeshCore API design).

Channel replies and @mentions

Channel replies use the same text format as the official MeshCore apps:

@[Alice]: thanks, that path worked

In a channel, type @ or @[ plus a few letters of a nickname and press Tab (or Right) to complete it. Candidates are people who have spoken in that channel, then your contacts. F4 prefills a reply to the last incoming sender. Messages that mention your name are highlighted.

Delivery Status Database

All messages are tracked in the database with delivery information:

ack_code - Unique acknowledgment code for tracking
delivery_status - Current status: 'sent', 'repeated', 'failed', or 'broadcast'
repeat_count - Number of repeater acknowledgments received
last_ack_time - Timestamp of most recent acknowledgment

This allows you to review message delivery history and identify network issues.

Installation

MeshTUI depends on the python meshcore package.

PyPI Installation

You can install it via pipx or uv:

pipx install meshtui
# or
uv tool install meshtui

This will install the meshtui command globally and isolate its dependencies.

Desktop notifications are optional and Linux-only (pipx install 'meshtui[notifications]'). They are not required to run the TUI. See Linux system packages if that extra fails to build.

Optional: TCP Proxy Component

⚠️ EXPERIMENTAL: The TCP proxy is a new feature in active development.

To install with the TCP proxy component (allows exposing Serial/BLE devices over TCP):

pipx install meshtui[proxy]
# or
uv tool install meshtui[proxy]

This installs the meshcore-tcp-proxy command in addition to meshtui. See the TCP Proxy section below for usage.

Arch Linux

For Arch Linux users, PKGBUILD files are available in the arch/ directory:

Stable version (from PyPI):

cd arch/meshtui
makepkg -si

Development version (from git):

cd arch/meshtui-git
makepkg -si

The -git version builds directly from the latest GitHub repository and conflicts with the stable package.

Development Installation

For development, use uv or standard pip:

git clone <your-repo-url>
cd meshtui
uv pip install -e .
# or with pip in a virtual environment:
# python -m venv .venv && source .venv/bin/activate && pip install -e .

Linux system packages (optional)

Desktop notifications use D-Bus (notify2 / dbus-python). They are not required to run MeshTUI.

Core install (recommended, works on Linux, macOS, and Windows):

pipx install meshtui
# or
uv tool install meshtui

Desktop notifications (Linux with D-Bus only):

# Debian / Ubuntu (including Debian 13 Trixie LXC)
sudo apt install pkg-config libdbus-1-dev libglib2.0-dev

# Fedora
sudo dnf install pkgconf-pkg-config dbus-devel glib2-devel

# then
pipx install 'meshtui[notifications]'
# or
uv tool install 'meshtui[notifications]'

On a minimal Debian/Ubuntu container, the pkg-config / libdbus-1-dev / libglib2.0-dev packages are only needed if you install the notifications extra.

macOS: D-Bus notifications are not used. Install with uv tool install meshtui or pipx install meshtui. Do not install the notifications extra unless you have dbus available (for example via brew install dbus).

Windows: dbus-python does not build on native Windows. Install with pipx install meshtui or uv tool install meshtui. WSL works the same as Linux.

Requirements

Python >= 3.10
A MeshCore-compatible radio device
BLE support (if using Bluetooth connectivity)

Usage

Launch MeshTUI with:

meshtui

Command Line Options

MeshTUI supports various connection methods via command line arguments:

# Connect via serial (USB)
meshtui --serial /dev/ttyUSB0

# Connect via serial with custom baudrate
meshtui --serial /dev/ttyACM0 --baudrate 9600

# Connect via TCP/IP
meshtui --tcp 192.168.1.100 --port 5000

# Connect via BLE address
meshtui --address C2:2B:A1:D5:3E:B6

# Compact layout for small displays (PicoCalc, 320x320, etc.)
meshtui --compact

# Show help
meshtui --help

Available options:

-s, --serial SERIAL: Connect via serial port (e.g., /dev/ttyUSB0)
-b, --baudrate BAUDRATE: Serial baudrate (default: 115200)
-t, --tcp TCP: Connect via TCP/IP hostname
-p, --port PORT: TCP port (default: 5000)
-a, --address ADDRESS: Connect via BLE address or name
--compact: Start in compact mode with the sidebar hidden
--low-power: Lighter UI and no radio polling (auto-enabled on original Raspberry Pi-class hosts)
--debug: Write DEBUG logs to ~/.config/meshtui/meshtui.log

Device Identification

MeshTUI automatically identifies MeshCore devices:

BLE devices: Scans for devices with names starting with "MeshCore-"
Serial devices: Tests each serial port to identify MeshCore-compatible devices
Automatic prioritization: Prefers /dev/ttyUSB0 if available, then other serial devices, then BLE devices

When scanning, MeshTUI will show which devices are confirmed MeshCore devices with device information like model and firmware version.

Interface Layout

MeshTUI features a two-panel layout with tabbed content:

Left Sidebar: Shows available mesh network contacts and channels
Main Content (Tabbed): Contains Chat, Device Settings, Node Management, and Logs tabs

Node Management

MeshTUI includes comprehensive remote node management capabilities for repeaters and room servers:

Node Management Tab Features:

Node Discovery: Automatically discovers available nodes in the mesh network
Node Login/Logout: Authenticate with repeaters and room servers
Command Execution: Send commands to remote nodes (no acknowledgment)
Status Monitoring: Request and display node status information
Real-time Feedback: All operations logged in the Logs tab

Node Management Workflow:

Refresh Nodes: Click "Refresh Nodes" to scan for available nodes
Login: Enter node name and password, then click "Login"
Send Commands: Use the command input to send instructions to logged-in nodes
Check Status: Click "Get Status" to retrieve node information
Logout: Use the logout command when finished

Supported Node Types:

Repeaters: Extend network coverage by relaying messages
Room Servers: Provide shared messaging spaces (BBS-style)
Other Nodes: Any meshcore-compatible remote device

Creating Custom Channels

MeshTUI allows you to create encrypted channels for group communication:

How to Create a Channel:

Click the "+" button next to the "Channels" header in the sidebar
Enter a channel slot (1-7, slot 0 is reserved for Public channel)
Enter a channel name:
- Use # prefix (e.g., #mychannel) for auto-generated hash-based secret
- Or enter a custom name without # for manual secret management
Click "Create" to create the channel
The new channel appears in your channels list

Joining an existing channel (you already have the key):

Click the "+" button next to the "Channels" header
Pick a free channel slot (1-7)
Enter the channel name exactly as the other devices use it (do not add a # prefix if you are supplying the key)
Paste the 16-byte secret as 32 hex characters (colons, spaces, dashes, or a 0x prefix are accepted)
Click "Create" — this writes the name and secret into that slot on the radio

The # prefix always derives the secret from the name and ignores any key you type. Use #name only when every device joins that way.

Channel Security:

Channels with # prefix automatically generate a 16-byte secret from the hash of the channel name
Other devices can join by using the same channel name with # prefix
Custom channels require the same 16-byte secret on every device
All channel messages are encrypted using the channel secret

Example:

Creating a channel named #team will:

Generate a consistent secret from hash("#team")
Allow anyone with #team to decrypt messages
Secure from others who don't know the channel name

Small screens

On terminals under 80×24 (for example a PicoCalc 320×320 display), MeshTUI switches to compact chrome automatically and hides the contacts sidebar under 60 columns so the chat can use the full width.

F2 — show or hide the contacts/channels sidebar
F3 — force compact mode on or off
meshtui --compact — start with compact chrome and the sidebar hidden
Choice is saved in ~/.config/meshtui/ui.json

When the sidebar is hidden, a Show contacts (F2) bar appears above the chat, and the header subtitle shows the active conversation.

Key Bindings

Ctrl+C - Quit the application
Ctrl+R - Refresh current view
F1 - Show help
F2 - Toggle contacts sidebar
F3 - Toggle compact mode
F4 - Reply to the last person who spoke in the current channel
Tab - Complete an @ mention in the message box (or move focus)
Enter - Send message or activate button

First Time Setup

Auto-connect: MeshTUI attempts to connect automatically on startup
Manual scan: Click "Scan Devices" to manually search for devices
Command line: Specify device directly with command line options
Start chatting: Use the input field to send messages or commands

Connection Process

When you specify a serial device (e.g., --serial /dev/ttyUSB0), MeshTUI:

Opens the serial connection at the specified baudrate (default: 115200)
Sends a device query to verify the device is a MeshCore-compatible radio
Retrieves device information (model, firmware version, capabilities)
Sets up event handlers for real-time contact and message updates
Refreshes the contact list from the device's memory

Why Contacts Don't Appear

Empty contact list is normal for several reasons:

Single device setup: If you're testing with only one MeshCore device, there are no other devices to communicate with
Fresh device: New or factory-reset devices have no saved contacts
Network isolation: Devices must be within radio range and on the same frequency/channel
No prior communication: Contacts are only created after successful message exchanges

How to Populate Contacts

To see contacts in the list:

Add multiple devices to your mesh network
Send messages between devices - this automatically creates contact entries
Use the same frequency/channel settings across devices
Ensure devices are powered on and within communication range
Wait for advertisements - devices periodically announce themselves

Device Status Indicators

Connection successful: Device info appears in logs (model, firmware, etc.)
Zero contacts: Normal for single-device or new network setups
Communication working: Messages sent/received successfully

Troubleshooting

Serial Port Permissions (Linux/macOS)

If you get permission errors when connecting via serial port, you need to add your user to the appropriate group:

Linux:

# Add your user to the dialout group
sudo usermod -a -G dialout $USER

# Log out and log back in for changes to take effect
# Or use: newgrp dialout

macOS:

# macOS typically doesn't require special permissions
# If you encounter issues, check /dev/tty.* or /dev/cu.* devices
ls -l /dev/tty.* /dev/cu.*

Verify access:

# Check group membership
groups

# Test device access (replace with your device path)
ls -l /dev/ttyUSB0

Common error messages indicating permission issues:

"Permission denied" when opening serial port
"Could not open port /dev/ttyUSB0"
"Access denied"

Log Files for Debugging

All application logs are automatically saved to a log file for postmortem analysis:

Location: $HOME/.config/meshtui/meshtui.log
Content: Includes DEBUG level logs with detailed connection and event information
Rotation: Automatically rotates when reaching 5MB (keeps 3 backup files)
Usage: Check this file when the application behaves unexpectedly or for detailed debugging

Example log entries:

2024-01-15 10:30:15 - meshtui - INFO - MeshTUI started - logging to ~/.config/meshtui/meshtui.log
2024-01-15 10:30:16 - meshtui.connection - INFO - Connected to Heltec V3 via serial. Found 2 contacts
2024-01-15 10:30:17 - meshtui.connection - DEBUG - 📡 EVENT: New contact detected: {'name': 'Device2', 'id': 123}

Common Issues

Serial port permission denied: Add your user to the dialout group (Linux) - see above
No contacts appearing: See "Why Contacts Don't Appear" above
Connection fails: Check serial port permissions and device power
Device not found: Ensure the device is connected and appears in /dev/ttyUSB* or /dev/ttyACM*
Logs not updating: Switch to the Logs tab to view application logs
Performance issues: Check log file size and rotate if necessary
Very slow on a Raspberry Pi B / Zero: MeshTUI auto-enables --low-power on armv6 and other single-core ≤512MB hosts. Force it with meshtui --low-power. Use meshtui --debug only when diagnosing (DEBUG logs on an SD card are expensive).

Configuration

Configuration files are stored in $HOME/.config/meshtui/

Per-Device Databases

MeshTUI creates a separate database for each connected device to prevent data collision:

Location: $HOME/.config/meshtui/devices/{device_pubkey}.db
Automatic: Database is created on first connection to each device
Isolated: Each device has its own messages, contacts, and settings
Seamless: Switching devices automatically uses the correct database

When you connect to a device for the first time, a new database is created using the device's unique public key. This ensures that messages and contacts from one device don't mix with another device's data.

Other Configuration Files

Device connections: Preferences and last-used BLE address are saved
Message history: All conversations persist between sessions
Log files: All application logs are saved to meshtui.log for postmortem analysis
- Location: $HOME/.config/meshtui/meshtui.log
- Includes DEBUG level logs for detailed troubleshooting
- Automatically rotates when reaching 5MB (keeps 3 backup files)
- Use for debugging issues after the application closes

Connection Types

MeshTUI supports the same connection methods as meshcore-cli:

BLE (Bluetooth Low Energy): Default for most companion radios
TCP/IP: For network-connected devices
Serial: For direct serial connections

Commands and Features

MeshTUI provides access to all MeshCore functionality through an intuitive interface:

Messaging: Send direct messages or broadcast to channels
Contacts: Manage your mesh network contacts
Device Info: View device status, telemetry, and configuration
Channels: Join and participate in mesh channels
Repeaters: Connect through mesh repeaters
Administration: Device management and configuration

Development

To contribute or modify MeshTUI:

Clone the repository
Create a virtual environment: python -m venv .venv or uv venv
Activate: source .venv/bin/activate (Linux/Mac) or .venv\Scripts\activate (Windows)
Install dependencies: pip install -e . or uv pip install -e .
Run: python -m meshtui

Project Structure

src/meshtui/
├── app.py           # Main Textual application (UI layer)
├── app.css          # UI styling
├── connection.py    # Connection orchestration and lifecycle
├── transport.py     # BLE, Serial, TCP transport layers
├── contact.py       # Contact/node management
├── channel.py       # Channel operations
├── room.py          # Room server handling
├── database.py      # SQLite message and contact persistence
├── __init__.py      # Package initialization
└── __main__.py      # Entry point

docs/
└── meshcore-api/    # MeshCore API reference (copied from installed package)
    ├── README.md    # API documentation and examples
    ├── commands/    # Command modules (messaging, contacts, device)
    └── *.py         # Core API files

API Reference

For MeshCore API reference, see docs/meshcore-api/README.md. This includes:

Complete API documentation
Command examples for messaging, contacts, and device management
Event types and handling
Room server administration
Contact type definitions

TCP Proxy (EXPERIMENTAL)

⚠️ Status: Experimental feature in active development (Phase 1 MVP complete)

The MeshCore TCP Proxy allows you to expose USB Serial or BLE-connected MeshCore devices over TCP/IP, enabling remote network access and TCP mode testing without WiFi firmware.

Features

Companion framing - Host→device 0x3C, device→host 0x3E (same as MeshCore serial/BLE/TCP)
Multi-client support - Multiple meshtui instances can connect simultaneously
Remote access - Access locally-connected devices over network
TCP testing - Test TCP connectivity without WiFi firmware

Installation

# Install meshtui with proxy support
pipx install meshtui[proxy]

Usage

Start the proxy (exposes serial device on TCP port 5000):

meshcore-tcp-proxy --serial /dev/ttyUSB0

Connect meshtui via TCP:

meshtui --tcp localhost --port 5000

Advanced Options

# Custom port
meshcore-tcp-proxy --serial /dev/ttyUSB0 --port 6000

# Debug mode with frame logging
meshcore-tcp-proxy --serial /dev/ttyUSB0 --debug --log-frames

# Use config file
meshcore-tcp-proxy --config /path/to/config.yaml

# Remote access (listen on all interfaces)
meshcore-tcp-proxy --serial /dev/ttyUSB0 --host 0.0.0.0

Configuration File

Example configuration (config.yaml):

proxy:
  listen_host: 0.0.0.0
  listen_port: 5000

backend:
  type: serial
  serial_port: /dev/ttyUSB0
  baudrate: 115200
  auto_reconnect: true

logging:
  level: INFO
  log_frames: false

See config/proxy/config.yaml.example for full configuration options.

Architecture

The proxy consists of:

Serial Backend - Connects to USB serial devices (Phase 1 ✅)
TCP Server - Accepts multiple client connections
Frame Router - Bidirectional forwarding (no protocol translation)
BLE Backend - Bluetooth LE support (Phase 3, planned)

Documentation

Complete design documentation: docs/MESHCORE_TCP_PROXY_DESIGN.md

Limitations (Phase 1)

Serial backend only (BLE support planned for Phase 3)
No authentication/encryption (use SSH tunnel or VPN for remote access)
Experimental status - may have bugs or breaking changes

Roadmap

Phase 1 (✅ Complete): Serial backend, basic TCP server
Phase 2 (Planned): Multi-client enhancements, session management
Phase 3 (Planned): BLE backend support
Phase 4 (Planned): Auto-reconnect, health monitoring, robustness
Phase 5 (Planned): Systemd service, packaging, deployment tools

License

MIT License - see LICENSE file for details

Contributing

Contributions welcome! Please feel free to submit issues and pull requests.

Related Projects

meshcore-cli - Command-line interface
meshcore_py - Python library for MeshCore
Textual - TUI framework used by MeshTUI </edit_description>

Name		Name	Last commit message	Last commit date
.github		.github
arch		arch
config/proxy		config/proxy
docs		docs
src/meshtui		src/meshtui
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CHANGES.md		CHANGES.md
CLAUDE.md		CLAUDE.md
FIXED_ISSUES.md		FIXED_ISSUES.md
LICENSE		LICENSE
README.md		README.md
TESTING.md		TESTING.md
pyproject.toml		pyproject.toml
sys		sys
test_connection.py		test_connection.py
test_quick.py		test_quick.py
upload_to_pypi.sh		upload_to_pypi.sh

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

MeshTUI

Description

Features

Message Delivery Tracking

Channel replies and @mentions

Delivery Status Database

Installation

PyPI Installation

Optional: TCP Proxy Component

Arch Linux

Development Installation

Linux system packages (optional)

Requirements

Usage

Command Line Options

Device Identification

Interface Layout

Node Management

Node Management Tab Features:

Node Management Workflow:

Supported Node Types:

Creating Custom Channels

How to Create a Channel:

Joining an existing channel (you already have the key):

Channel Security:

Example:

Small screens

Key Bindings

First Time Setup

Connection Process

Why Contacts Don't Appear

How to Populate Contacts

Device Status Indicators

Troubleshooting

Serial Port Permissions (Linux/macOS)

Log Files for Debugging

Common Issues

Configuration

Per-Device Databases

Other Configuration Files

Connection Types

Commands and Features

Development

Project Structure

API Reference

TCP Proxy (EXPERIMENTAL)

Features

Installation

Usage

Advanced Options

Configuration File

Architecture

Documentation

Limitations (Phase 1)

Roadmap

License

Contributing

Related Projects

About

Resources

Stars

Watchers

Forks

Releases

Sponsor this project

Packages

Contributors

Languages