openelab.de
openelab.com
What is Meshtastic UI?
Meshtastic UI (MUI) is an independent and comprehensive user interface designed specifically for Meshtastic devices. Its primary purpose is to allow users to interact directly with their mesh network without relying on a companion phone application for most everyday configurations. This makes it possible to manage and monitor devices in a more autonomous way. Initially, MUI was created for standalone touchscreen devices, but over time it has been expanded to support Linux-native systems, making it a versatile solution across a wide variety of hardware platforms. While many essential settings can be adjusted directly through MUI, certain advanced features may still require pairing with another device, such as a smartphone, to unlock full functionality.
The development of MUI began in early 2024. After more than a year of active work, the first preview release was made available in early 2025. By that time, the project had grown significantly, encompassing approximately 12,000 lines of handwritten code and 50,000 lines of generated code. It had been successfully ported to 10 different devices and translated into 18 languages, demonstrating its broad applicability and international reach. MUI continues to evolve, with ongoing updates aimed at introducing new features, optimizing performance, and expanding compatibility with additional hardware platforms.
Supported Devices
MUI is compatible with a diverse range of devices, including but not limited to:
-
Standalone LoRa devices with ESP32-S3 and TFT displays:
-
LilyGo T-Deck
-
Seeed SenseCAP Indicator
-
unPhone
-
PICOmputer
-
-
CYD-style devices with ESP32-S3 connected via serial to LoRa modules:
-
T-HMI
-
Mesh-Tab "Replicator" (ESP-4848S040)
-
Makerfabs 4"
-
-
Embedded Linux devices with SPI/I2C and GPIO support:
-
Raspberry Pi
-
Milk-V
-
LuckFox with TFT SPI and LoRa hat
-
-
Linux-native setups:
-
PC with Meshstick or SIMRadio simulation using X11 MUI
-
Installation
For most standalone devices, MUI can be installed using the Meshtastic Web Flasher. Users should look for the MUI logo on supported hardware, select firmware version 2.6 or higher, and enable the Meshtastic UI option during the flashing process.
Some devices are not supported by the web flasher but have prebuilt firmware binaries available. These firmware files can be identified by the “-tft” suffix in their filenames. Prebuilt firmware can be downloaded from the official downloads page.
For certain supported devices that do not have automatic firmware builds or web flasher support, manual compilation and flashing are required. Detailed instructions for building firmware manually can be found in the developer documentation.
Usage
SD Card Support
Devices equipped with SD card slots must ensure the card is properly formatted before use. The recommended partition scheme is MBR. MUI supports both FAT32 and exFAT file systems, with exFAT being the preferred option due to its improved performance and compatibility.
Initial Setup
When booting MUI for the first time, or after performing a factory reset, the device will display a quick configuration screen. This screen allows users to set the device’s region, long name, and short name simultaneously. By consolidating these steps, only one reboot is required, streamlining the setup process compared to configuring each setting separately.
Home Dashboard
Once the initial setup is complete, the Home Dashboard becomes the default screen displayed at each boot. It provides a concise overview of the device’s status and offers fast navigation to key areas or settings. Many dashboard elements support both short and long press actions, enabling additional functionality and customization. For a detailed breakdown of available controls and their functions, users can refer to the Dashboard Infographic.
On standalone devices, an SD Card icon is also visible. This icon shows the detected SD card’s size, format, and usage statistics in both gigabytes and percentage. Tapping the icon refreshes the SD card status, which is particularly useful if the card has been hot-swapped. During this refresh, the firmware may briefly pause.
Nodes List
The Nodes List provides a comprehensive view of all nodes within the mesh network. Users can view, filter, and highlight nodes based on selected criteria. A single tap on the Node icon opens the full list of active nodes, while a long press opens Node Options, where filters and highlights can be applied to emphasize specific nodes.
Channels
The Channels screen displays all configured channels for the device, with icons indicating their encryption status:
-
Yellow key: Channel is using a default Pre-Shared Key (PSK).
-
Green lock: Channel is using a custom-configured PSK.
-
Red lock: Channel has no PSK configured.
Tapping on a configured channel opens a chat window for that channel.
Chats
The Chats screen lists all available conversations, including shared channels and direct messages. The chat list can be accessed by tapping the chat icon. Long pressing a chat reveals a delete option, while unread messages are highlighted in orange. Within a chat, messages are threaded: incoming messages appear on the left, and outgoing messages from the local device appear on the right. Message outlines change color based on acknowledgment status, providing immediate feedback on delivery success.
Map
The Map screen displays map tiles stored on the device’s SD card. No tiles are included by default and must be manually added. Tiles should be 256x256 PNG images, ideally with an 8-bit color depth and a 256-color palette. A starter set of tiles covering zoom levels 1–6 of the Earth is available here. Map controls include arrow icons for panning, magnifying glass icons for zooming, a GPS icon to center on the device’s current location, and crosshairs to recenter on the home position. Long pressing the crosshairs allows users to set a new home position. If no location data is available, the map defaults to Big Ben in London, UK.
Settings & Tools
The Settings & Tools screen provides access to device configuration and diagnostic utilities. It is divided into two tabs:
-
Settings: Allows users to configure various aspects of the device directly within MUI.
-
Tools: Provides utilities for network diagnostics and monitoring, including Mesh Detector, Signal Scanner, Trace Route, Statistics, and Packet Log.
Accessing this screen is straightforward: a single tap on the settings icon opens it, while a long press either locks the screen (if the lock screen feature is enabled) or puts the device to sleep (if disabled).
Client API Access
MUI operates as a client, similar to the Android and iOS applications. It runs on one core of the MCU, while the standard Meshtastic firmware runs on the other. Communication between MUI and the firmware is handled through the Client API, which supports only one active connection at a time. This means that other clients cannot be used simultaneously while MUI is running. Since not all settings can be configured within MUI, users may need to switch to Bluetooth Programming Mode or BaseUI to free up the API for other clients.
Bluetooth Programming Mode
Bluetooth Programming Mode can be enabled in two ways: by pressing and holding the Meshtastic logo during boot, or by selecting the Bluetooth icon in the shutdown/reset menu within settings. When activated, the device reboots into Bluetooth Programming Mode and displays a randomly generated PIN, which must be entered when connecting via Bluetooth on the client app. To exit this mode, press and hold the Bluetooth icon again, and the device will reboot back into MUI.
BaseUI Mode
Since the introduction of Unified Firmware for TFT devices in version 2.7, switching between Meshtastic UI (MUI) and BaseUI has become seamless. Users no longer need to reinstall firmware to change interfaces. Booting into BaseUI frees up the Client API connection, allowing other clients such as mobile apps or serial tools to connect and configure advanced settings.
To enter BaseUI from Bluetooth Programming Mode, press and hold the Bluetooth icon until the system reboots. Once in BaseUI, users gain access to a more traditional interface that prioritizes compatibility with external clients. This mode is particularly useful when you need to perform configurations not available directly in MUI.
Returning to MUI is straightforward: navigate to the System Window within BaseUI, then long-press until the System Action dialog appears. From there, select Reboot/Shutdown and choose Switch to MUI. The device will restart and load back into the Meshtastic UI environment.
Summary
Meshtastic UI provides a powerful, flexible, and user-friendly interface for managing mesh networks across a wide range of devices. With support for standalone LoRa hardware, embedded Linux systems, and native PC setups, MUI offers direct control without requiring a phone app for most tasks. Features such as the Home Dashboard, Nodes List, Channels, Chats, Map integration, and diagnostic tools make it a comprehensive solution for both beginners and advanced users.
Installation options are varied, from simple web flashing to manual compilation, ensuring accessibility across supported hardware. The inclusion of SD card support, quick setup screens, and intuitive navigation further enhance usability. For advanced configurations, users can switch between MUI, Bluetooth Programming Mode, and BaseUI, providing flexibility depending on their needs.
As development continues, MUI will expand with new features, optimizations, and broader hardware support, solidifying its role as a key interface for the Meshtastic ecosystem.
