This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

MeshCore User Guide (Ai Gen)

Introduction
Installation & Setup
System Overview
GUI Documentation
WebUI Documentation
Features & Capabilities
Device Compatibility
Advanced Usage
Troubleshooting
Best Practices

1. Introduction

1.1 What is MeshCore?

MeshCore is a lightweight, decentralised mesh communication system designed for LoRa packet radios. It enables multi-hop text messaging, sensor data exchange, and network administration across groups of small embedded devices — without any internet connection, cellular infrastructure, or central server.

Unlike conventional mesh radio systems that flood every packet to every node, MeshCore uses a hybrid routing model: it floods messages only when a direct route is unknown, and switches to targeted direct routing once a path to the destination has been established. This dramatically reduces channel congestion in larger networks.

The MeshCore companion firmware extends the base mesh stack with a full-featured, touch-first graphical interface (GUI) that runs directly on the radio hardware. It also provides a browser-accessible WebUI that mirrors the on-device interface when the device is connected to WiFi, giving users the option to manage their device from a laptop or phone without installing any software.

1.2 Use Cases

Scenario	Description
Off-grid communication	Stay in contact during hikes, camping trips, or expeditions without mobile coverage
Emergency & disaster response	Deploy an instant mesh network where infrastructure is unavailable
Community networks	Build low-power neighbourhood or event communication grids
Tactical operations	Encrypted group and direct messaging without internet dependency
Remote sensor monitoring	Collect temperature, humidity, CO₂, and other telemetry from remote nodes
General LoRa exploration	Experiment with mesh networking on affordable hardware

1.3 Supported Devices

MeshCore companion firmware runs on a range of LoRa-equipped devices. The following hardware is supported with the full graphical interface:

Device	Display	Input	Notable Features
LilyGO T-Deck Plus	320×240 colour TFT	QWERTY keyboard + trackball	Built-in GPS, microphone, speaker
LilyGO T-Deck (original)	320×240 colour TFT	QWERTY keyboard + trackball	No GPS module
Seeed Studio SenseCap Indicator	480×480 colour TFT	Touchscreen	Dual MCU, hardware buttons
Elecrow CrowPanel 3.5"	480×320 colour TFT	Touchscreen	SD card for map tiles
Elecrow CrowPanel Advanced 7"	1024×600 colour IPS	Touchscreen	ESP32-P4, WiFi via coprocessor
Heltec Vision Master V4 (TFT)	Colour TFT	Touchscreen	Compact form factor

Additionally, the companion radio firmware supports any device running in headless mode that accepts connections over BLE, USB, or WiFi from an external client application (see Section 3.3).

2. Installation & Setup

2.1 What You Need

To get started with MeshCore you need:

A supported hardware device — see the list in Section 1.3
A USB cable connecting the device to your computer
A modern web browser — Google Chrome or Microsoft Edge are recommended (Firefox does not support WebSerial)
A LoRa antenna — always attach the antenna before powering the device; transmitting without an antenna can damage the radio hardware

No software installation on your computer is required for basic flashing.

2.2 Flashing Firmware

The easiest way to install MeshCore is via the official web flasher.

Step-by-step:

Open https://flasher.meshcore.io in Chrome or Edge.
Select your device from the list.
Choose the firmware type:
- Companion Radio — full GUI with mesh radio capability (recommended for most users AND for MCTerm)
- Repeater — relay-only node with remote management, no GUI
- Room Server — shared group chat server node
For a first-time installation, click Erase All Flash before flashing. This removes any previous firmware and settings.
Click Flash and follow the on-screen prompts to connect your device via USB.
Wait for the flash to complete (typically 30–90 seconds).

Note: A full flash erase is only required for first-time installation or when switching firmware type. Routine updates — such as upgrading to a new version of the companion firmware — can be applied without erasing settings.

Note: After flashing, the first boot may take 1–2 minutes. The screen may flicker briefly while partitions and settings are initialised. This is normal.

DFU Mode (T-Deck)

Some T-Deck variants require manual entry into Device Firmware Update (DFU) mode before flashing:

Hold down the trackball button while connecting the USB cable.
The device should appear as a serial port to the web flasher.
Release the trackball and proceed with flashing normally.

SenseCap Indicator — RP2040 coprocessor (UF2)

The Seeed SenseCap Indicator has two MCUs:

MCU	Role	How to flash
ESP32-S3	Companion UI, LoRa, WiFi/BLE	Web flasher (steps above)
RP2040	microSD, sensors, buzzer, battery sense	UF2 file from GitHub Releases (not the web flasher)

The web flasher updates only the ESP32. On every release check if there is a NEW RP2040 image available , install the matching RP2040 image from the same release, OR the latest one. The build artifact is named like rp2040_indicator_<version>.uf2. An older RP2040 image with a newer ESP32 build can break SD-primary storage, map tiles, sensors, and the buzzer.

Flash the RP2040 (drag-and-drop UF2):

Download rp2040_indicator_<version>.uf2 from the project Releases page (same/latest version as your companion firmware).
Disconnect USB if the device is plugged in.
Locate the RP2040 BOOT button on the board (small internal button; Seeed documents using a paperclip or needle through the enclosure access).
Press and hold BOOT, connect the Indicator to your computer with USB-C, then release BOOT once the cable is connected.
The computer mounts a removable drive (RPI-RP2 on Windows/Linux; often RP2040 on macOS).
Copy the .uf2 file to the root of that drive (not into a subfolder). The drive ejects automatically when flashing finishes and the RP2040 reboots.
Disconnect USB or power-cycle, then start the device normally so the ESP32 companion firmware runs.

USB serial ports (two interfaces):

When both MCUs are running, two COM/serial devices may appear. Use the right one for each task:

Typical name	MCU	Use for
USB-SERIAL CH340 (Windows)	ESP32-S3	Web flasher, ESP32 serial log
USB Serial Device (Windows)	RP2040	Optional RP2040 serial monitor
usbmodem (macOS)	Often RP2040 when both are listed	UF2 drag-and-drop does not need a serial port

If the web flasher cannot find the device, connect only for ESP32 flashing (no BOOT held) and select the CH340 port. For RP2040 updates, always use the UF2 steps above.

After flashing:

Confirm Mgmt → Global → Admin → FW-MC matches your release.
Check SD-primary storage, map tiles, sensor readings, and buzzer behavior.
Mgmt → Global → Admin → Reboot RP2040 (HW) (double-tap to confirm) soft-resets the coprocessor without reflashing.

See also Seeed’s Indicator flashing guide for hardware photos.

2.3 First Boot

When the device starts for the first time after flashing:

A splash screen is displayed for approximately 2.5 seconds while hardware is initialised. On builds with the boot console enabled, a scrollable boot log may appear first (migration steps, SD sync, store selection). Swipe vertically to read it; it dismisses automatically after a short hold once startup finishes.
The GUI opens on the Contacts tab, which will be empty initially.
A default radio frequency and settings are applied. For EU/UK users this is 869.618 MHz, 62.5 kHz bandwidth, SF 8, CR 8, 22 dBm. For other regions, adjust these values in Management → Radio before transmitting.
A node name is automatically generated. It is recommended to set a meaningful name in Management → Global as soon as possible, since this is how other users will identify your device on the mesh.
The device immediately begins listening on the configured frequency and will add any nearby MeshCore nodes to the contacts list as it hears their advertisements.

Antenna reminder: Always ensure the LoRa antenna is properly attached before the first boot. Transmitting without an antenna can permanently damage the radio module.

3. System Overview

3.1 How MeshCore Works

MeshCore creates a network of independent radio nodes that communicate by passing packets over LoRa. There is no central infrastructure — each node participates autonomously.

When a node wants to send a message to another node, it first needs to know how to reach it. MeshCore discovers routes through a flooding mechanism: the first time a message is sent to an unknown destination, it is broadcast as a flood packet that propagates across the network until it reaches the target. Intermediate repeater nodes pass the packet along up to a configurable maximum number of hops.

Once a bidirectional exchange has occurred and a path is known, subsequent messages are sent as direct packets — targeted transmissions that follow the established route and are not rebroadcast by every node. This keeps network traffic low in established networks.

Because MeshCore companion nodes do not repeat or relay packets, the mesh relies on dedicated repeater nodes placed strategically in the network to extend range. Room servers similarly act as infrastructure nodes that handle group message storage and distribution.

All direct messages are end-to-end encrypted using the recipient's public key. Only the intended recipient can decrypt the contents. Channel (group) messages use a shared pre-shared key (PSK) known to all participants.

3.2 Communication Model

MeshCore uses two primary message types from a user perspective:

Direct Messages (DMs):

Sent to a specific contact
End-to-end encrypted
Delivery is tracked; the sender receives an acknowledgement when the message reaches the recipient
Route to the recipient is cached and reused; if the route becomes stale, a new one is discovered automatically

Channel Messages:

Sent to a named group channel
All members who share the channel's pre-shared key can receive and decrypt them
Always transmitted as flood packets so all participants can receive them
A default Public channel exists that any MeshCore node can join without a password

3.3 Node Roles

Role	Description
Companion Radio	A user-facing node with a GUI (or headless BLE/WiFi/USB endpoint). Sends and receives messages. Does not repeat packets — it participates only as an endpoint.
Repeater	A relay node with no user interface. Receives and retransmits mesh packets to extend network coverage. Most commonly deployed as a fixed, solar-powered installation. Can be managed remotely via the GUI on a companion device.
Room Server	A group chat server. Stores and distributes channel messages. Participants join the server with a password. Can be managed remotely in the same way as a repeater.
Sensor Node	A battery- or solar-powered node that periodically broadcasts sensor telemetry (temperature, humidity, CO₂, voltage, etc.) into the mesh.

4. GUI Documentation

4.1 Main Interface Overview

The GUI is organised around four main tabs shown in a permanent tab bar at the bottom of the screen. The tab bar is always visible regardless of what content is displayed above it.

Tab	Purpose
Contacts	Lists all known mesh nodes; provides access to direct messages and node details
Msgs	Group channel transcripts and direct message threads
Map	Interactive map showing GPS positions of nodes on the mesh
Mgmt	All device settings, diagnostics, and administration functions

The active tab is marked visually. Tap any tab icon to switch to it at any time.

4.2 Status Bar

The status bar runs across the top of the screen and is always visible.

Left Side

Node Name — your device's identity on the mesh, as seen by other nodes
Temporary Override Area — shows short-lived alert text such as "New message from Alice" when a message arrives; clears automatically after a few seconds

Right Side

The right side of the status bar shows one of two display modes, toggled by long-pressing the area:

Battery Mode (default) — shows the current battery voltage (e.g. 4.15 V) or percentage (e.g. 85 %). Long-press the indicator to toggle between volts and percentage.
Duty Cycle Mode — shows the current radio transmit duty cycle as a percentage in real time. Long-press again to return to battery display.

Status Icons

Icon	Meaning
WiFi symbol	WiFi interface state: off, connecting, connected (STA), or access-point (AP) mode
GPS dot	GPS state: searching for fix, or fix acquired
SD card symbol	An SD card is inserted and accessible
Radio activity dots	Left dot flashes on packet received (RX); right dot flashes on packet transmitted (TX). Each flash lasts 250 ms.

Touch Devices

Gesture	Effect
Tap	Select items, open detail views, press buttons, switch tabs
Long-press	Alternate actions — see the gesture reference in Section 4.11
Swipe / drag	Scroll lists; pan the map
Swipe left/right	Switch sub-pages in Management, Contact detail, and Channels
Double-tap word	Copy word to internal clipboard
Double-tap empty editor	Paste from internal clipboard

T-Deck Plus (Physical Keyboard + Trackball)

The T-Deck Plus has a full QWERTY keyboard and a physical trackball, providing hardware navigation across the entire interface.

Control	Effect
Trackball (roll)	Scroll lists; navigate in views
Trackball press	Select / confirm
QWERTY keyboard	Direct text input in any active text field
Arrow keys	Move cursor inside text editor fields; arrow escape bytes are automatically stripped to prevent accidental password damage

Elecrow CrowPanel & SenseCap Indicator

These devices are primarily touchscreen-driven. On the SenseCap Indicator, a hardware button on the top edge toggles the display on and off.

4.4 Contacts Tab

The Contacts tab is the primary hub for discovering nearby nodes and managing direct communication.

Contact List

The list shows all currently known mesh contacts. Each entry displays the node's name, type badge, and activity state.

Sorting and filtering:

Tap the CONTACTS header to cycle through display modes:

Mode	Description
A-Z	Alphabetical by name
Last Heard	Most recently active nodes first
Last Message	Contacts with the most recent incoming message first
Favs Only	Show only starred (favourite) contacts

Colour coding:

Bright / white — recently active node
Dim / grey — node not heard recently
Consistent colour — each node has a unique persistent colour derived from its identity; this colour is reused consistently across contacts, transcripts, the log, and map markers

Type badges:

Badge	Colour	Node Type
`USR`	Blue	Chat user / companion radio
`RPT`	Orange	Repeater
`SVR`	Purple	Room server
`SNS`	Green	Sensor node

Favourite badge: ⭐ shown on favourited contacts.

Discovered Nodes View:

Long-press the CONTACTS header to toggle between the normal contact list and the Discovered Nodes view. This secondary view shows recently overheard advertisement frames — useful for finding nearby repeaters or nodes that have not yet been added as contacts.

Contact Detail View

Tap any contact to open its detail panel. The panel has up to two swipeable sub-pages.

Page 0 — Contact Info

Field	Description
Name + hash	Node identity; the first byte of the public key is shown in parentheses for disambiguation
Public Key	Truncated hex; tap VIEW to display the full 32-byte key with a scannable QR code
Type / Firmware level	Node type and reported firmware capability level
Last heard	Relative age of the most recent packet from this node (e.g. `5 m ago`, `2 h ago`)
SNR / RSSI	Signal quality from the most recently received packet
Battery	Reported battery voltage or percentage (if broadcast by the node)
GPS	Last reported coordinates, if the node broadcasts its location
Telemetry	Latest temperature, humidity, CO₂, and TVOC values (if telemetry is shared)
Path	Current routing path with intermediate hop identifiers

If a contact was removed while you had its detail open (for example after auto-add / purge ran on another tab), the detail view shows Contact missing with a visible Back button and returns to the list when you tap Back or anywhere on the header row.

Action buttons on Page 0:

Button	Action
Back	Return to the contact list
MSG	Open a direct-message composer to this contact
PATH	View the current routing path; tap again to force a path reset
FAV	Toggle the favourite star
DEL	Remove this contact from the list
TPERM	Toggle permission for this contact to share telemetry (location and environment data) with you
PING	Send a ping packet; the round-trip time is displayed inline after the response arrives
MAP	Switch to the Map tab and centre it on this contact's GPS position

Page 1 — Admin / Session (swipe left; only available for repeaters and room servers)

See Remote Repeater Administration and Room Server Session later in this section.

Sending a Direct Message

Open any contact in the Contacts tab and tap MSG.
The text editor opens with the recipient's name shown as the title.
Type your message (up to 125 characters) and tap OK — or press Enter on a hardware keyboard.
The message is dispatched and appears in the Msgs → Users tab under the conversation thread for that contact.
A delivery state badge is shown next to the message:

Badge	Meaning
⏳	Pending — message sent; awaiting acknowledgement
✓	Delivered — acknowledgement received
✗	Not delivered — no acknowledgement received within the timeout

Repeater Administration

When a contact is a repeater (RPT) and you have the admin password, Page 1 on the contact detail panel provides a full remote-management console.

Stage 0 — Login

Enter the admin password in the password field.
Optionally tick Save credential to store it encrypted on the device (tied to the repeater's public key).
Tap LOGIN. The result — OK, Fail, Timeout, or Send Fail — is shown inline.

Stage 1 — Overview (after a successful login)

Eight quick-action tiles give fast access to common operations:

Tile	Function
Status	Fetch live statistics: battery, noise floor, RSSI, packet counters, uptime
ACL	View and edit the repeater's access control list
Neighbours	Scan for adjacent repeater nodes
CLI	Open a raw command-line terminal to the repeater
Device	Read and write device name, radio parameters, and TX power
Advert	Configure advertisement intervals
Clock	Read (and optionally set) the repeater's clock
Telemetry	View live environment sensor data from the repeater
Passwords	Remote password management
Reboot	Remotely reboot the repeater (requires a second confirmation tap)

Stage 2 — Overlay views

Each tile opens a detailed overlay. Key views:

Status — shows packet receive/send counts, flood and direct subsets, duplicate counts, total air time, noise floor, last RSSI, last SNR, error events, and uptime.

Access Control List (ACL) — displays up to 112 bytes of ACL data parsed into individual entries. Each entry shows a 6-byte key prefix and the assigned role. Actions:

REMOVE — delete the selected entry
ADD — enter a full 32-byte public key and select a role (Read-Only, Read-Write, or Admin)

Device — reads and allows editing of: device name, radio frequency, bandwidth, spreading factor, coding rate, TX power. Tap SAVE to commit changes.

Advert — configures the direct (zero-hop) advertisement interval in minutes and the flood advertisement interval in hours. Tap SET to apply.

Clock — displays the repeater's current time. A SET button appears when the local device has a valid NTP-synchronised time, allowing the repeater's clock to be updated remotely.

CLI — a full terminal with scrollback. Type commands using the on-screen or hardware keyboard. Command history is navigable with the up/down arrow keys.

Room Server Session

When the contact is a room server (SVR), Page 1 provides a session console:

Enter the room password and tap LOGIN.
On success, the session view shows the room transcript, a message compose field, your permission level, and an ACL button to view who has access.

4.5 Channels Tab (Msgs)

The Msgs tab contains two sub-views, accessible by swiping left/right or tapping the frame indicator dots at the bottom of the view.

Sub-page 0 — Channels (Group Messages)

Displays all joined channels, each showing:

Channel name
A preview of the most recent message
An unread message badge

Opening a channel: tap its row to open the full transcript.

Joining a new channel: tap the + button and:

For a public-name channel: enter the channel name (e.g. hiking)
For a hashtag channel: type #channelname — the GUI automatically parses the name
For a channel with a pre-shared key (PSK): enter the channel name and its base64-encoded key

Inside a transcript:

The header row (channel and DM threads) provides:

Button	Action
Back	Return to the channel or user list
Read	Mark every message in this thread as read (clears unread badges)
Newest	Jump scroll to the latest message at the bottom
Custom (or Qck on narrow screens)	Send Custom QuickSend text immediately (no editor)
Send	Open the message composer

Per-message quick replies (Q1 / Q2):

WebUI: each message row has Q1 and Q2 buttons (channel and DM). They fill the composer with Custom QuickR1 / Custom QuickR2 from Mgmt → Messages, expanded with route data from that message (see Quick Send and quick replies below).
Device (channels): tap a message → Reply in the detail header → the composer shows QuickR1 and QuickR2 below the text field (same templates as Q1/Q2). DM threads on the device use Custom / Qck for QuickSend only; use the WebUI for per-message Q1/Q2 in DMs.
Messages are displayed in IRC-style with sender names coloured consistently by node identity
#hashtag references in messages are highlighted; tap one to get a prompt to join that channel
Tap any message to view the full text along with path information, SNR/RSSI, the sender's timestamp, and the list of overheard repeaters for that packet
Long-press the Back arrow in the header to clear the entire channel transcript (confirmation required)
Long-press the channel name in the header to delete the channel from your device (confirmation required)

Phone / WebUI companion: While Wi‑Fi or BLE companion transport is connected, new messages received on the device are stored as already read, so the on-device unread count stays lower after you read traffic on the phone app. Messages you read only on the phone before disconnecting are not synced as read — use Read on the device thread if badges remain.

Note: The Public channel is the default open channel shared by all MeshCore nodes. It is automatically restored if deleted.

Sub-page 1 — Users (Direct Message Threads)

Lists all direct message conversations sorted by most recent activity. Each row shows:

Contact name and identity colour
Most recent message preview
Unread message count

Opening a thread: tap it to view the full conversation history.

Deleting a thread: long-press the row and confirm. Threads with no remaining messages are pruned automatically.

4.6 Map Tab

The Map tab shows an interactive geographic view of all GPS-enabled mesh nodes.

Map Display

Element	Meaning
Blue circle with dot	Your current location ("ME")
Coloured node marker	A mesh contact with a known GPS position; colour matches the contact's identity colour; `[hash]` badge shows that node's path-hash prefix (1–3 bytes per Path Hash Mode / advert metadata)
Orange/yellow border on marker	Currently selected contact
Altitude bar (top-left, vertical green bar)	Your current altitude (can be toggled)
Zoom level indicator (top-centre)	Current zoom level; auto-hides after 3 seconds
Red "No SD" banner	SD card is absent; offline map tiles cannot be loaded
Yellow "No GPS fix" banner	GPS module is searching for a satellite fix

Map Controls

Touch / on-screen buttons:

Control	Action
Drag	Pan the map in any direction
+ / − buttons	Zoom in / zoom out (can be hidden in settings)
D-pad arrows	Coarse directional pan (can be hidden in settings)
ME button	Jump to your current GPS location and re-centre the view
Tap a node marker	Select the contact
Double-tap a node marker	Open the full contact detail view
Long-press a node marker	Select the contact (alternative to single-tap)

T-Deck Plus keyboard shortcuts while in the Map tab:

Key	Action
`W`	Pan up
`A`	Pan left
`S`	Pan down
`D`	Pan right
`I`	Zoom in
`O`	Zoom out
`R`	Re-centre on your location
`T`	Toggle the altitude bar

Route overlay (message path)

From a DM or channel message detail view, tap the Path: line to open the Map tab with that message's hop path drawn. While the overlay is active:

Hop repeaters are highlighted with numbered markers and connecting lines.
Only contacts on that path remain visible on the map.

To return to the normal map (all GPS contacts), leave the Map tab (switch to Contacts, Messages, etc.). The overlay clears automatically when you re-enter Map.

Map Tiles

The map renders from two sources:

SD card — slippy-tile image files stored in the standard {z}/{x}/{y}.png directory hierarchy. The root tiles directory is configurable in Mgmt → Map → Tiles Folder. The GUI caches up to 32 tiles in device RAM (LRU eviction) to minimise repeated SD card reads during panning.
Network — tiles downloaded from OpenStreetMap over WiFi when Network Tiles is enabled and WiFi is connected. Missing tiles are fetched on demand and, when Local Tiles is also enabled, saved under Tiles Folder on the storage selected by Primary Disk (internal flash or SD card).

On devices without an SD card and without WiFi connectivity, the map will display a grid background without imagery, but node positions are still plotted correctly.

Tiles Directory Picker

Navigate to Mgmt → Map → Tiles Folder → Open to choose which folder on the SD card contains the tile images. A folder browser opens showing the SD card root. Tap a directory name to enter it, tap .. to go up, and tap Use to confirm (or Cancel to leave the path unchanged).

4.7 Management Tab

The Management tab provides access to all device settings and administrative functions. Swipe left or right on the overview grid, or use the ◀ ▶ header arrows on a settings page, to navigate. There are 20 settings pages (plus a three-page overview grid). Tap a tile on the overview to open that page.

Overview Grid

The overview has three pages (dots under the header). Swipe horizontally on the grid, or use the header arrows while the overview is showing.

Overview page	Main tiles (tap to open)	Corner shortcut
0	Pages 0–7: Global, WiFi, BLE, UI, Light, Lock, Map, Sound	CLI (page 18)
1	Pages 8–15: GPS, Radio, Advert, Messages, Stats, Log, Tele, Contacts	Backup (page 19; SD-capable builds only)
2	Channels (16), Date/Time (17)	—

Page Index

#	Page Name	Contents
0	Global	Identity, Admin, storage, reboot/OTA, C6/RP2040 coprocessor actions (board-specific)
1	WiFi	Mode (AP/STA), credentials per mode, IP mode (STA), saved profiles, WebUI, transport switch
2	BLE	Bluetooth PIN, BLE address, transport switch
3	UI	Brightness slider, Disp. Timeout, UI Zoom
4	Light	Keyboard Light (T-Deck+), keyboard/display blink, Blink Bright slider, Color Scheme
5	Lock	Autolock, lock background (PNG), lock text colour, timer
6	Map	Navigation Btn, zoom buttons, Def. Follow Me, Tiles Folder, local/network tiles
7	Sound	All Sounds, When Connected, volume, boot/DM/channel/ack sounds
8	GPS	GPS function, pins, AutoBaud, manual location, Tracking (F-Advert), capture/clear
9	Radio	Frequency, bandwidth, spreading factor, coding rate, TX power
10	Advert	Auto advert intervals, advert location, Path Hash Mode, manual advert + Rpts scan
11	Messages	Custom QuickSend/QuickR1/QuickR2, clear RAM messages, retry/ack options
12	Stats	Packet counters, RSSI/SNR/link-margin live graphs, airtime metrics
13	Log	Scrollable receive log with per-packet detail
14	Tele	Self-telemetry readings and live sensor graphs
15	Contacts	Auto-add, types, max hops, manual add, Purge actions
16	Channels	Add/join, scopes, per-channel Scope/Share/Del
17	Date/Time	Manual time entry, GPS time sync, NTP configuration
18	CLI	Local command-line shell for the node
19	Backup	SD backup slots: New, Refresh, Restore, Delete (device only; not in WebUI)

Page 0 — Global

Identity

Row / control	Action
Name	Tap Edit to rename the node (advertised on the mesh).
Device ID	Read-only short hex prefix of your public key (width follows Mgmt → Advert → Path Hash Mode: 2 / 4 / 6 characters). Long-press the row to copy `Device ID: …` to the clipboard.
Public Key	Tap the row or View to open the Identity detail (scrollable): name, grouped public key, private key (if export is enabled), SD key file path, and SD bundle path (`/meshcore_identity.json`). Long-press a section in the detail view to copy that block (public key as raw hex, etc.).
Save key to SD	Tap the path area to edit the SD key file path; tap Save to write identity to SD (also writes the bundle JSON).
Load key from SD	Tap the path area to edit; tap Load to import identity from SD.
Set private key	Tap Set to paste a 128-character hex private key (replaces the node identity; advanced).

Admin (read-only, refreshes about every 500 ms while visible)

Field	Meaning
Uptime	Time since boot
FW-MC / FW-MOD	Main companion firmware version and build modifier string
Heap	Free internal RAM (and minimum seen)
PSRAM	External RAM free/total (or `none`)
Flash	Flash chip size
Sketch	Firmware partition used/free
CPU	CPU frequency
Chip	ESP32 variant, revision, core count
Reset	Last reset reason (e.g. PowerOn, SW, Panic, Brownout)

Actions

Row / button	Action
Storage	Summary of primary data stores (internal vs SD usage).
FW upgrade	Hint only on device: upload a `.bin` from the WebUI Global page in the browser (not from the touchscreen).
Primary Disk	(SD-capable builds) Toggle Internal vs SD Card for the authoritative binary prefs blob. `/MCTerm/prefs.txt` on SD stays in sync when a card is present (§8.1). Switching copies all managed settings; wait for progress to finish before removing the card.
Reboot RP2040 (HW)	(SenseCap Indicator only) Double-tap to reset the RP2040 coprocessor via the board reset line.
Reboot	Restarts the ESP32 companion (confirm where prompted).
OTA Update	(When built with auto-update and WiFi is up with STA password set) Validates the manifest, sets the update flag, and reboots into the WiFi updater. Greyed out if WiFi has no IP or password.
Update ESP32-C6	(Elecrow CrowPanel 7" with hosted C6) Double-tap to flash the WiFi/BLE coprocessor from the embedded image on next boot. If C6 firmware is outdated, a red banner warns that WiFi is blocked until updated.

On CrowPanel 7, identity save/load/view/set actions are disabled while C6 firmware is outdated (update C6 first).

Contact purge is on Mgmt → Contacts, not Global.

Page 1 — WiFi

WiFi settings are stored in saved profiles. The main screen edits the active profile; use Pick to switch profiles (each profile has its own mode and credentials). See §8.3 WiFi Profile Management.

Control	Description
Profile	Active profile name. Tap Pick to open the profile list (each row shows AP or STA). Tap Select to activate a profile and apply its settings; tap Del to delete (with confirmation).
New Profile	Tap Add, enter a name, and create a profile seeded from the current active settings.
Mode	Access Point or Station. Toggle applies to the active profile.
AP SSID	(AP mode) Network name clients connect to. Default: device node name (sanitized). Empty stored value uses the node name at runtime.
AP Password	(AP mode) WPA2 password (8–63 characters). Default when unset: BLE PIN as six digits plus `00` (e.g. PIN `123456` → `12345600`).
AP Clients	(AP mode) Up to 3 devices may associate. DHCP is provided by the device at 192.168.4.1/24.
SSID	(Station mode) Tap Edit to enter the upstream WiFi network name.
Password	(Station mode) Tap Edit to enter the network password.
IP Mode	(Station mode) DHCP or Static; when Static, edit IP, subnet, gateway, and DNS fields below.
WebUI	Enable or disable the WebUI feature (persisted). Does not bind port 80 by itself.
WebUI Server	Read-only: Running = HTTP/WebSocket listener active; Stopped = disabled, not on WiFi, or no IP yet.
Live status	Role, link state, IP, and mode-specific fields (AP: stations count; STA: RSSI) when WiFi transport is active on this boot.

Access Point mode: The device hosts its own WiFi network. Connect a phone or PC to the AP SSID, then open the WebUI at http://192.168.4.1 (when WebUI is enabled). The same URL works whenever the status line shows the AP address.

Station mode: The device joins an existing router or hotspot. Use the IP shown under IP for the WebUI (e.g. http://192.168.1.45).

The WebUI WiFi page mirrors these fields (Mode, AP SSID/password, STA SSID/password, static IP options) with per-row Save buttons.

Page 2 — BLE

Control	Description
BLE PIN	The 6-digit fixed PIN used when pairing a BLE client. Enter it on the connecting device when prompted.
BLE Address	The device's Bluetooth hardware address; displayed once the BLE stack is initialised
Transport Switch	Switch to WiFi or disable the connection transport

Page 3 — UI

Setting	Options	Description
Brightness	0–100 % slider	Display backlight only; drag horizontally on the slider track (vertical scrolling on the page does not change the value). Keyboard backlight is on Light (T-Deck Plus).
Disp. Timeout	Tap Set	Screen soft-off delay after inactivity; any touch wakes the display
UI Zoom	^ / v buttons	Scales the entire interface on supported displays

Page 4 — Light

Setting	Description
Keyboard Light	T-Deck Plus only. Steady keyboard backlight (0–100 % slider); default 50 %. Independent of display brightness.
Keyboard Blink	Enable/disable keyboard blink on new messages (T-Deck Plus)
KB Blink Dur	Keyboard blink duration in milliseconds
KB Timeout	Turn keyboard backlight off after inactivity (Set to choose duration)
Display Blink	Momentarily raise display brightness when a new message arrives
Blink Bright	Peak brightness during display blink (0–100 % slider)
Disp Blink Dur	Display blink duration in milliseconds
Color Scheme	Dark or Light UI theme

Page 5 — Lock

All lock options are under the LOCK section on this page (not on Mgmt → UI).

Setting	Options	Description
Autolock	Enabled / Disabled	After inactivity, the UI enters the lock overlay (mesh receive/store continues). Toggling on resets the idle timer briefly so it does not lock immediately.
Lock Background	None / Picture	None: solid black lock screen. Picture: draw a PNG from Picture PNG behind the clock (scaled to the display).
Picture PNG	Path (default `/MCTerm/lockscreen.png`)	Tap Set to edit the path (must be absolute, `.png` suffix). Tap ? for limits: PNG only, max 480×480, max 512 KiB. File must exist on SD or internal storage. WebUI: upload via Global or lock settings (`/api/lockscreen/upload`).
Lock Text Color	White, Blue, Green, Yellow, Orange, Red	Colour for the clock, Locked label, and unlock hints on the overlay.
Autolock Timer	5–3600 seconds	Tap Set and enter seconds (shown as `…s` on the row). Default 30 s if unset.

Lock overlay behaviour (see also §4.10): shows local time (or --:--:-- if unset), Locked, optional Tracking badge when Mgmt → GPS → F-Advert Tracking is on, and unlock instructions. With Lock Background → Picture, the PNG is drawn full-screen; on touch/key activity the clock and hints appear over it.

Page 6 — Map

Setting	Description
Navigation Btn	Show or hide on-screen D-pad and ME buttons on the Map tab
Zoom Btn	Show or hide +/− zoom buttons on the Map tab
Def. Follow Me	Re-centre on your position when a new GPS fix arrives (if follow mode is active)
Tiles Folder	Current SD tiles root; tap Open for the folder browser (Use / Cancel)
Local Tiles	Read tiles from Tiles Folder; also required to save network downloads into that cache
Network Tiles	Download missing tiles from OpenStreetMap over WiFi when connected

Altitude bar: On the Map tab, press T (T-Deck Plus keyboard) to toggle the altitude bar. The WebUI exposes the same as Alt Info Bar under Mgmt → Map.

Route overlay: Same behaviour as on the Map tab — see §4.6 Route overlay. In the WebUI, open a message detail and use Show Path On Map; clear with Clear Path or Alt+C — see §5.3.1.

Page 7 — Sound

Setting	Options	Description
All Sounds	On / Off	Master mute for notification audio
When Connected	On / Off	Play a tone when a BLE or WiFi client connects
Volume	Low / Med / High	Tap Set to cycle level
Boot Sound	On / Off (+ Play preview)	Startup chime
New DM	On / Off (+ Play)	Direct message received
New Channel	On / Off (+ Play)	Channel message received
Ack	On / Off (+ Play)	Outgoing DM acknowledged

Page 8 — GPS

Setting	Description
GPS function	Enable or disable the GPS module
RX Pin / TX Pin	UART pins; tap Edit to change
AutoBaud	Automatic baud detection; when enabled, Baud shows Auto
Baud	Manual baud rate when AutoBaud is off
Defaults	Reset factory GPS pin and baud defaults
Restart GPS	Go — restart the GPS driver without rebooting the device
Manual Lat	Manually set latitude in decimal degrees (`-90` to `90`)
Manual Lon	Manually set longitude in decimal degrees (`-180` to `180`)
Manual Alt	Manually set altitude in meters (`-500` to `12000`)
Capture GPS Fix	Copy the current live GPS fix into Manual Lat/Lon/Alt
Clear Location	Reset manual location values to `0,0,0`

Tracking (movement-based flood adverts):

Setting	Description
F-Advert Tracking	Enabled / Disabled — when enabled, the node sends an extra flood advert after you move farther than the distance threshold (requires a valid GPS fix)
Send tracking advert every	Movement threshold in metres (`1`–`999`, default 15 m). Tap Edit to change

When tracking is active, an orange tracking icon appears beside the WiFi/BLE badges in the status bar. Tracking is independent of Advert Location and Auto Advert Flood schedules; it only fires on movement. If GPS is off or has no fix, tracking pauses until a fix returns.

GPS coordinates are automatically saved to storage approximately every 5 minutes when a valid fix is maintained. After a reboot, the map opens at the last saved GPS position even before a new fix is acquired.

To set a manual location directly on the device:

Open Mgmt -> GPS.
In Manual Location, tap Edit for Manual Lat, enter latitude, then confirm.
Tap Edit for Manual Lon, enter longitude, then confirm.
Tap Edit for Manual Alt, enter altitude (meters), then confirm.
Set Advert Location to Manual so advertisements use your manual coordinates.

Advert Location modes on-device are:

Off: do not include coordinates in adverts.
GPS: advertise coordinates from the active GPS fix.
Manual: advertise the saved Manual Lat/Lon/Alt values.

Page 9 — Radio

Parameter	Unit	Typical Values
Frequency	MHz	869.x (EU), 915.x (US), 433.x (Asia), etc.
Bandwidth	kHz	62.5 / 125 / 250 / 500
Spreading Factor	—	7 (fastest, shortest range) to 12 (slowest, longest range)
Coding Rate	—	5 to 8 (denominator; 5 = lowest overhead, 8 = most redundancy)
TX Power	dBm	Legal limit varies by region and antenna; check local regulations

Tap the RADIO action button to commit all changes. A device restart may be required for some changes to take full effect. All nodes on the same mesh must use identical radio settings to hear each other.

Regulatory note: Always operate within the legal transmit power limits and frequency allocations for your country. Unlicensed operation on LoRa frequencies is subject to duty-cycle restrictions in most regions.

Advertisements are periodic broadcast packets that announce your node's presence on the mesh. Other nodes use these to discover you and add you to their contact list.

Setting	Description
Auto Advert 0-Hop	Automatic zero-hop advert interval in hours (Disabled or e.g. `4h`)
Auto Advert Flood	Automatic flood advert interval in hours (Disabled or e.g. `24h`)
Advert Location	Off, GPS, or Manual — whether coordinates are included in adverts
Path Hash Mode	1-Byte / 2-Byte / 3-Byte — on-air path hash size; sets Device ID width and map badge sizes
Advert 0-Hop / Advert Flood / Scan Rpts	Manual actions: send adverts now, or open the overheard-repeater list (Rpts) with RSSI/SNR

Reducing advertisement frequency (longer intervals) decreases channel usage. Advertising more frequently increases how quickly new nodes discover you.

Page 11 — Messages

Setting	Description
Custom QuickSend	Fixed phrase for one-tap send: long-press status-bar centre, or Custom / Qck in a thread header
Custom QuickR1	Template for Q1 / QuickR1 (per-message quick reply); tap Edit
Custom QuickR2	Template for Q2 / QuickR2; tap Edit
Clear All Msgs	Empty — clears channel + DM messages from RAM only (not SD history)
Auto Retry	Resend DMs when no ACK within timeout
Auto Reset Path	With Auto Retry, failed delivery clears the cached route before retry
Direct Message Acks	Tap Set to choose how many ACKs are required (0 = off)
Mark Delivered Faster	Mark sent DMs delivered without waiting for ACK
Replace HashCodes	Enabled / Disabled — show contact names instead of raw `[XX]` path-hash codes in transcripts (display only; default Enabled)

Quick-reply templates may include placeholders expanded from the message you are replying to: (HP) / [HP] (path hashes), (HC) / [HC] (hop count), (SNR) / [SNR], (RSSI) / [RSSI]. Example: Heard you on (HC) at (SNR). See Replace HashCodes for how [XX] tokens in message text relate to path hashes.

Page 12 — Stats

Provides live and historical radio performance data.

Packet Counters

Counter	Description
`n_recv`	Total packets received
`n_sent`	Total packets transmitted
`n_recv_flood` / `n_sent_flood`	Flood-routed packet subset
`n_recv_direct` / `n_sent_direct`	Direct-routed packet subset
`n_flood_dups` / `n_direct_dups`	Duplicate packets discarded
`err_events`	Radio error events
`total_air_time_secs`	Total cumulative transmit air time in seconds
`total_rx_air_time_secs`	Total cumulative receive air time in seconds

Radio Section

Displays the current noise floor, last received RSSI, and last received SNR.

Airtime Section

Shows the current transmit duty cycle, and cumulative TX and RX air time. Note that regulatory duty-cycle limits (e.g. 1 % in EU SRD bands) apply to transmit time. Monitor this counter to ensure compliance.

Live Graphs

Tap any of the RSSI, SNR, or Link Margin rows to open a scrolling live graph. The graph displays the last 96 received samples, updating in real time. Use this to assess link quality over time, identify interference windows, or compare antenna positions.

Page 13 — Log

A scrollable receive log showing the most recent 48 received packets. Each row displays:

Relative timestamp (e.g. 5 m ago)
SNR and RSSI values
Route type (Flood or Direct)
Payload type and version
Sender identity (resolved to name if the contact is known)
Destination hash (if present)
Path length (number of hops)

Each entry uses the consistent identity colour for the sender, making it easy to track a specific node's packets in the log.

The log automatically scrolls to show the newest entries. Scrolling up pauses auto-follow; the log resumes auto-follow when you scroll back to the bottom.

Tap any log row to open a full-detail overlay showing the complete raw frame data including the decoded routing path.

Page 14 — Tele (Telemetry)

Displays sensor readings reported by the local node (readings are only available if the hardware includes the relevant sensor):

Reading	Unit
Battery voltage	V
Temperature	°C
Relative humidity	%
CO₂ concentration	ppm
TVOC index	—

Tap any sensor row to open a scrolling live graph of the last 96 samples for that sensor channel. These graphs update in real time and are independent of radio activity — they reflect the device's own onboard sensors.

Page 15 — Contacts

Setting	Description
Auto Add Contacts	When enabled, overheard adverts can add contacts (Note: adds from adverts)
Manual add contact	Tap Add to enter a public key and name without hearing an advert
Auto Add Types	Tap Set (when auto-add is on) to toggle USR, RPT, SRV, SNS, and OW (Overwrite oldest)
AutoAdd Max Hops	Edit — limit path length for auto-add (`No Limit`, `Direct (0)`, or N hops)
ACT/MAX Contacts	Current contact count vs device maximum
Purge Contacts	Remove all contacts (confirmation required)
Purge w/o favs	Remove all non-favourite contacts

Manual add is useful for pre-loading a known public key before nodes are in range, or after scanning a QR code from another device.

Page 16 — Channels

Control	Description
Add channel	Create a new channel
Join channel	Join by name/PSK; Public restores the default public channel if missing
Scopes	Edit region-scope definitions used for geo-filtered channels
Default Scope	Default scope applied to new channels
Per-channel row	Scope, Share (QR), Del — delete requires confirmation; Public channel can be re-added with Public

Page 17 — Date/Time

Setting	Description
Device Time	Manual time entry in ISO date-time format; tap SET to apply
GPS Time	Synchronise the device clock from a currently active GPS fix
NTP Enabled	Enable automatic time synchronisation over WiFi
NTP Timezone	Short form (`CET`, `UTC+2`, `UTC-5`, `GMT`, `BST`) or full POSIX TZ string. MeshCoreTerm converts short forms automatically.
NTP Server	NTP server hostname; default is `pool.ntp.org`

NTP Timezone examples:

What you type	Meaning
`UTC` or `GMT`	UTC, no DST
`UTC+2`	Fixed UTC+2 (no DST)
`UTC-5`	Fixed UTC−5 (no DST)
`CET`	Central Europe with DST (CET/CEST)
`BST` or `UK`	UK with DST (GMT/BST)
`EST`	US Eastern with DST

Advanced (POSIX — optional):

Region	POSIX string
UK (GMT + BST)	`GMT0BST,M3.5.0/1,M10.5.0/2`
Central Europe (CET + CEST)	`CET-1CEST,M3.5.0,M10.5.0/3`
US Eastern	`EST5EDT,M3.2.0,M11.1.0`

Do not use IANA names like Europe/London or Europe/Vienna — they are not supported on ESP32.

The device stores UTC internally. Status bar, message timestamps, and Device Time display apply your TZ string as local time. Device Time → Set expects local date/time (YYYY-MM-DD HH:MM:SS), not UTC.

NTP synchronisation occurs automatically at boot when WiFi is connected, and is repeated approximately every hour. A Force Sync action is also available for immediate manual synchronisation.

Accurate time is important for message timestamps and for ensuring the routing path cache behaves correctly. GPS time sync provides an alternative to NTP in environments without internet access.

Page 18 — CLI

A full local command-line interface for sending raw mesh commands to the connected node. The CLI overlays a scrollable terminal with history, identical in appearance and behaviour to the remote repeater CLI in the contact admin view. Use the hardware keyboard (T-Deck Plus) or the on-screen keyboard to type commands. Navigate history with the up/down arrow keys.

The CLI is primarily an advanced diagnostic and configuration tool.

Page 19 — Backup (device only)

Available on builds with SD backup support (overview page 1 corner tile, or page 19 in the page index). The WebUI Debug page occupies the same index in the browser UI; backup is on-device only.

The page title Backup is centred in the header between the pager arrows (same layout as the Log page).

Control	Description
New (bottom row)	Create a new backup slot on SD (progress spinner with file counts)
Refresh (bottom row)	Rescan backup slot list
Slot list	Tap a slot to select it
Restore / Delete / Deselect (bottom row)	Active when a slot is selected; Restore or Delete opens a confirm step
Confirm step	Bottom row shows only Restore! or Delete! plus Cancel until you proceed or cancel; restore reboots the device

Backup slots are full SPIFFS-style snapshots. They are not the same as day-to-day settings sync via /MCTerm/prefs.txt (see §8.1). Use Backup for periodic full restores; copy prefs.txt alone for a lightweight settings export.

4.8 Text Editor & On-Screen Keyboard

The text editor overlay appears whenever the interface requires text input — for messages, settings, passwords, channel names, and search fields. On hardware keyboard devices (T-Deck Plus), physical key input is active in all text fields without needing to open the on-screen keyboard explicitly.

Layout

┌────────────────────────────────────┐
│ Field title            [counter]   │
│ ┌──────────────────────────────┐   │
│ │ typed text with cursor █     │   │
│ └──────────────────────────────┘   │
│ ┌──────────────────────────────┐   │
│ │ Q W E R T Y U I O P         │   │
│ │  A S D F G H J K L          │   │
│ │   Z X C V B N M  ←   ↵      │   │
│ │ ⇧   123    [space]  . OK  × │   │
│ └──────────────────────────────┘   │
└────────────────────────────────────┘

Keyboard Modes

Mode	How to activate
UPPERCASE	Default mode on open
lowercase	Tap the shift key (⇧)
Symbol set 1 (SYM1)	Tap `123`
Symbol set 2 (SYM2)	Tap `#+=` from SYM1

Input Actions

Action	Touch	Hardware keyboard
Insert character	Tap key	Type key
Delete character	Tap ←	Backspace
Confirm / Send	Tap OK	Enter
Cancel	Tap ×	Esc
Move cursor left/right	Tap in text area	← → arrow keys
Copy a word	Double-tap the word	—
Paste from clipboard	Double-tap in empty area	—

Internal Clipboard

The GUI maintains a private clipboard (up to 256 characters) for copy and paste within the device.

Copy a word: double-tap any word in a message detail view. A brief notification shows the copied text.
Copy public key: from Mgmt → Global → View → Copy or from the QR view.
Paste: double-tap in an empty text input area. A character counter in the title shows remaining space.
The clipboard is saved to the SD card as /clipboard.txt and is restored on reboot.

Password Fields

Fields designated as passwords — BLE PIN, WiFi password, repeater admin passwords — display characters as • dots. The actual value is withheld from the display but can be copied from a clipboard operation in specific flows (e.g. copying a displayed credential for transfer).

Character Counter

For fields with a maximum length (channel messages are limited to 125 characters), a counter is shown in the top-right corner of the input box. The counter turns red as the limit approaches.

4.9 Confirm Dialogs

Destructive or irreversible actions always present a confirmation dialog before executing, showing a title and description of the action with OK and Cancel buttons.

A 150 ms suppression window is applied after the dialog opens. This prevents the finger-up event of the opening tap from immediately and accidentally dismissing the dialog.

Action	Location
Delete channel	Long-press channel name in transcript header
Delete DM thread	Long-press thread row in Users list
Join hashtag channel	Tapping a `#tag` in a message
Switch transport	Mgmt → WiFi/BLE → Transport Switch
Share channel (copy/QR confirm)	Mgmt → Channels → Share
Purge all contacts	Mgmt → Contacts → Purge Contacts
Purge contacts (keep favourites)	Mgmt → Contacts → Purge w/o favs
Disable all flood adverts	Mgmt → Advert
Disable all direct adverts	Mgmt → Advert
Delete WiFi profile	Mgmt → WiFi → Profiles

4.10 Lock Screen & Autolock

Enabling Autolock

Go to Mgmt → Lock.
Set Autolock to Enabled.
Tap Set on Autolock Timer and enter idle seconds (5–3600).
Optional: set Lock Background to Picture, place a PNG at Picture PNG (or upload from WebUI), and pick Lock Text Color.

The timer resets on every touch, keypress, or navigation event. The lock does not engage during the boot splash screen.

Behaviour While Locked

When locked, normal UI input is blocked and a full-screen overlay is drawn:

Lock Background → None: black screen (display may soft-off until you touch; see below).
Lock Background → Picture: your PNG fills the screen; touch or a key press turns the panel on and shows the time and hints on top.
Shows HH:MM:SS (device local time), Locked, and — if F-Advert Tracking is enabled — an orange Tracking badge.
Mesh receive, message storage, and radio activity continue; only the interactive UI is suspended.

Configure appearance under Mgmt → Lock (Page 5).

Unlocking

On touch devices:

Long-press anywhere for 2 seconds. A progress bar and Hold: X.Xs countdown appear.
Release early and the attempt resets; hold until the bar completes.

On keyboard devices (e.g. T-Deck):

Press Alt+L to toggle lock, or use the same 2 s long-press where touch is available.

After unlocking:

A short grace period (~1.5–3 s) prevents the unlock gesture from immediately activating a control underneath.

Soft-Off (Display Sleep)

Mgmt → UI → Disp. Timeout dims the backlight after inactivity; a tap wakes brightness. This is independent of autolock — both can be active. Entering lock while soft-off forces the panel on so the lock screen remains visible when Lock Background → Picture is used.

4.11 Touch Gestures Reference

Gesture	Effect
Single tap	Select, open, activate
Tap battery indicator	Cycle status label: Percent → Volts → duty cycle
Long-press CONTACTS header	Toggle Discovered Nodes view
Long-press Back arrow in transcript	Clear transcript (with confirmation)
Long-press channel name in header	Delete channel (with confirmation)
Long-press DM thread row	Delete thread (with confirmation)
Long-press map node marker	Select contact
Long-press lock screen	Unlock (2-second hold)
Long-press status bar centre	Quick Send
Double-tap word in detail view	Copy word to clipboard
Double-tap empty editor area	Paste from clipboard
Swipe up/down	Scroll any list or log
Swipe left/right	Switch sub-pages (Mgmt, Contact detail, Channels)
Drag on map	Pan map

Scroll Gating

Fixed headers, title bars, and action bars do not initiate drag-scroll when a touch begins in their region. Only the scrollable content area below responds to vertical drag. This prevents unintentional scrolling when tapping buttons in headers.

Touch Dropout Protection

A 150 ms grace window joins brief touch-panel dropout events into the preceding gesture, so that a momentary lift during a slow drag does not break the scroll. The suppression window after dialogs and editor overlays also prevents ghost taps from the closing interaction.

4.12 Keyboard Shortcuts (T-Deck Plus)

Map Tab

Key	Action
`W`	Pan up
`A`	Pan left
`S`	Pan down
`D`	Pan right
`I`	Zoom in
`O`	Zoom out
`R`	Re-centre on your location
`T`	Toggle altitude bar

Text Editor

Key	Action
Printable characters	Insert at cursor position
Backspace	Delete character before cursor
← / →	Move cursor left/right
Enter	Confirm and send
Esc	Cancel and close editor

Repeater / Local CLI

Key	Action
Printable characters	Add to command input
Enter	Send command
↑ / ↓	Navigate command history
Backspace	Delete last character

5. WebUI Documentation

5.1 Relationship to the GUI

The WebUI is a browser-based interface that mirrors the on-device GUI in structure, appearance, and functionality. It is served directly from the device itself over WiFi — no external server or cloud service is involved. When the device is connected to a WiFi network (or acting as a WiFi access point), any device on the same network can open the WebUI in a web browser.

The WebUI offers the same five main sections as the on-device GUI: Contacts, Channels, DMs, Map, and Management. All data visible in the WebUI comes from the device in real time via a WebSocket connection; changes made in the WebUI are immediately reflected on the device and vice versa.

5.2 Accessing the WebUI

The on-device HTTP/WebSocket server (port 80) starts only when both are true:

WebUI is Enabled (Mgmt → WiFi → WebUI — default is often disabled on first boot).
WiFi is the active transport (not BLE or Off) and the link has a usable IP (Station associated or Access Point running, e.g. 192.168.4.1).

Enabling WebUI while the device is on BLE turns the setting on but does not start the server. After you switch transport to WiFi and the link has an IP, the server starts automatically. Mgmt → WiFi → WebUI Server shows Running only when the listener is actually bound; Enabled with Stopped means waiting for WiFi or an IP.

Anyone who can reach the device IP on the LAN can open the login page; you must sign in before data or settings are available.

Prerequisites

WiFi transport selected and up (Station or AP) — see §8.3.
WebUI: Enabled on the device.
The device's BLE PIN (Mgmt → BLE → BLE PIN, or Mgmt → Global). This is the WebUI password.

When connected to an existing WiFi network (Station mode):

Connect the device to your WiFi (active WiFi profile, Station mode).
On the device, note the IP in Mgmt → WiFi (e.g. 192.168.1.45) or use the address your router assigned.
On a phone or PC on the same network, open a browser: http://<device-ip> (example: http://192.168.1.45).

When using the device as a WiFi access point:

Use a WiFi profile in Access Point mode; connect clients to the AP SSID (see §8.3).
Open http://192.168.4.1 in the browser (typical AP address when the status line shows the AP is up).

Login (required)

The first screen is the MeshCore WebUI login overlay:

Field	Value
User	`admin` (fixed; shown on the form)
Password	The device's 6-digit BLE PIN (same PIN used for BLE pairing)

Tap Login. On success, the overlay closes and the WebUI loads contacts, channels, map, and management pages. A session token is stored in the browser (localStorage); the next visit on the same browser may skip the login step until that token expires or is cleared.

Wrong credentials show Login failed; API and WebSocket requests without a valid token return 401 Unauthorized.

After login

The browser opens a WebSocket to the device for live data (messages, contacts, GPS, debug tiles).
If the connection drops, the client retries with backoff (about 1.5 s up to ~12 s). If the session is no longer valid, you are returned to the login screen.
Logging out or clearing site data removes the saved token; you must log in again.
Keyboard shortcuts use Alt + a letter (e.g. Alt+S opens map search on the Map tab). These are browser shortcuts in the WebUI, not the T-Deck Map pan keys (W/A/S/D). Full list: §5.3.2.

Security: The WebUI has no separate account password — knowledge of the BLE PIN (and network access to the device IP) is enough to sign in. Do not expose the WebUI to the public internet without a VPN or tunnel; see §5.4.

5.3 Feature Overview

The WebUI provides full access to device state and configuration:

Section	Features
Contacts	View all contacts with type, signal quality, GPS coordinates, battery level, and telemetry. Send pings, view public keys, and open direct message threads.
Channels	View all joined channels and their transcripts. Send channel messages, scroll history, and view per-message metadata (path, RSSI, SNR). Add channels with name + PSK; keys may be base64, hex (32 or 64 characters), or `psk:`-prefixed — the device normalises them before save.
DMs	View and send direct messages. Delivery status is tracked and displayed in real time. Opening a thread marks its messages read (same idea as the on-device Read button).
Map	Interactive map; Alt+S opens search (§5.3.2). Layer switch, path overlay, Clear Path — §5.3.1. Tiles from device (SD / network).
Management	Same 20 logical pages as the device (Global through CLI, plus Debug instead of Backup). Settings use per-row Save where shown. Light page: keyboard light, display blink, blink brightness. Map page includes Alt Info Bar and default zoom (device toggles altitude with `T` on the Map tab).

The WebUI supports large contact lists through paginated delivery — contacts are loaded in batches to avoid overloading the connection. All updates from the mesh (new messages, new contacts, GPS movements, signal changes) are pushed to the browser automatically without requiring a page refresh.

Debug page (Mgmt index 19 in the browser): Live diagnostics pushed over WebSocket — CPU/heap/PSRAM, UI state (display, soft-off, lock, tab), timers, battery, WebSocket client counts, message-store sizes, SD queue, and mesh/radio JSON stats. Tap a card to expand detail. Use Copy Debug Snapshot (Help) when reporting issues. There is no WebUI backup UI; use the device Backup page when SD backup is supported.

5.3.1 WebUI Map Tab

The browser Map tab uses Leaflet with tiles loaded from the device (same sources as the on-device map: local cache and/or network fetch via the radio).

Control	Action
+ (top-right)	Open map search panel — filter by name, hash, or type; tap a result to centre the map and open that marker's popup. Same as Alt+S when the Map tab is active (§5.3.2).
Layer buttons (Dark / Light / Topo)	Switch basemap style (stored in the browser for the session). Same as Alt+D / Alt+L / Alt+T.
Clear Path (bottom-left)	Visible only while a message path overlay is active — removes hop lines and shows all contacts again (zoom/pan unchanged)
Marker popup	Coordinates, distance, Open Contact Detail; repeaters can be added to a manual path when Build Path on Map is active from contact detail

Message path overlay

In Channels or DMs, open a message that has path metadata.
In message detail, tap Show Path On Map.
The Map tab opens with numbered hop markers, route polylines, and only contacts on that path visible (same filtering idea as the device GUI overlay in §4.6).
To exit overlay mode and restore the full contact map, tap Clear Path (bottom-left) or press Alt+C while the Map tab is focused.

Note: Clear Path clears the view overlay only. It does not change stored routing paths on contacts or messages. Build Path on Map (contact detail) is a separate flow for editing a contact's outbound path; cancel that with Alt+P or the path-picker Cancel button.

Live marker updates while you stay on the Map tab (WebSocket pushes) refresh positions without reloading the page; path overlay geometry is updated incrementally when overlay mode is active.

Map Alt+ shortcuts are listed in §5.3.2. In the WebUI help overlay (Map tab → ? or Alt+H), the same shortcuts appear under Map Shortcuts.

5.3.2 WebUI Keyboard Shortcuts

The WebUI is used in a desktop or mobile browser. Shortcuts are Alt + letter (hold Alt, tap the letter). They are not the on-device T-Deck Map keys (W / A / S / D pan the hardware map; Alt+S in the browser opens search on the WebUI map).

Tip: On macOS, Option is the same modifier as Alt for these shortcuts.

Map tab shortcuts

Works when the WebUI Map tab is selected (focus is in the page). Alt+M switches to Map from any other tab.

Shortcut	Action
Alt+S	Map search — open the top-right search panel, focus the search field, and show matching contacts (name, pubkey, type, hash). Enter selects the first result; Escape closes search.
Alt+M	Switch to the Map tab
Alt+F	Centre map on this device (self GPS)
Alt+D	Basemap: Dark
Alt+L	Basemap: Light
Alt+T	Basemap: Topo
Alt+C	Clear Path — exit message path overlay; show all contacts again
Alt+P	Cancel Build Path on Map picker (if active)
Alt+H	Open Map Shortcuts help (marker legend + shortcut list)

Map search workflow (Alt+S or + button):

Open the Map tab (or press Alt+M).
Press Alt+S (or tap + at the top-right of the map).
Type in the search field — results update as you type (up to 24 matches).
Click a result (or press Enter with the field focused) to pan/zoom to that node and open its popup.
Press Escape or tap × on + to close the search panel.

5.4 Remote Usage

The WebUI is designed for local network use. It is not intended to be exposed directly to the internet. For remote access over the internet, use a VPN or a secure tunnel.

Practical limitations:

The WebUI requires the device to be on WiFi or acting as an AP. It is not available when the device is in BLE-only mode.
Map tiles in the WebUI come from the same source as the on-device GUI. Network tile downloads (from OpenStreetMap) pass through the device — if the device has internet access, the map will auto-load tiles; if not, only pre-loaded SD card tiles are available.
Very large contact lists (hundreds of contacts) load progressively; the initial page may show a partial list for a few seconds on first connection.

6. Features & Capabilities

6.1 Messaging

MeshCore supports two types of text messaging: direct messages (one-to-one, end-to-end encrypted) and channel messages (group, PSK-encrypted).

Direct Messages

Maximum message length: 125 characters
Encryption: end-to-end using the recipient's public key
Delivery tracking: each sent message is assigned a pending state; it transitions to delivered (✓) when an acknowledgement is received, or undelivered (✗) if no acknowledgement arrives within the timeout
Route caching: the path to the recipient is cached after the first successful exchange. Subsequent messages reuse this path without flooding. If delivery fails, a path reset and re-flood are triggered automatically (if Auto Retry is enabled)
Message history is stored on the device and persists across reboots

Channel Messages

Maximum message length: 125 characters
Encryption: all participants share a pre-shared key (PSK); messages are decryptable by anyone with the key
All channel messages use flood routing, so they propagate across the entire reachable mesh
Message history per channel is stored on the device and persists across reboots
Up to the device storage limit, multiple channels can be joined simultaneously

Quick Send and quick replies

MeshCore provides three configurable message shortcuts in Mgmt → Messages:

Setting	UI label	What it does
Custom QuickSend	Custom / Qck (thread header); status-bar long-press	Sends the phrase immediately to the open channel or DM — no composer
Custom QuickR1	Q1 (WebUI); QuickR1 (device composer)	Inserts expanded template text into the composer for a reply to a specific message
Custom QuickR2	Q2 (WebUI); QuickR2 (device composer)	Second quick-reply template (same behaviour as Q1)

Quick Send (Custom QuickSend):

Long-press the centre of the status bar (shows the phrase briefly), or tap Custom / Qck in the channel or DM transcript header.
Sends at once; useful for canned status lines such as OK or Heading back.

Quick replies Q1 / Q2 (Custom QuickR1 / QuickR2):

Configure both strings under Mgmt → Messages (up to 128 characters each).
WebUI: in an open channel or DM thread, tap Q1 or Q2 on a message row. The composer is prefilled with the template after placeholder expansion; for incoming channel traffic the WebUI may add an @[sender] prefix.
Device: in a channel thread, tap a message → Reply → tap QuickR1 or QuickR2 in the editor. Placeholders (HP), [HP], (HC), [HC], (SNR), [SNR], (RSSI), [RSSI] are filled from that message’s route/SNR/RSSI data. Edit if needed, then confirm OK to send.
If a template is empty, the device shows QuickR1 not set / QuickR2 not set; the WebUI shows a similar notice.

Quick Send and Q1/Q2 are separate: Quick Send transmits directly; Q1/Q2 only prepare (or prefill) a reply tied to a chosen message.

Replace HashCodes

MeshCore routes packets using shortened path hashes — the first 1, 2, or 3 bytes of each node’s public key (see Mgmt → Advert → Path Hash Mode and your Device ID on Mgmt → Global). On the air and in stored message text, those hops often appear as bracketed hex:

Pattern	Path hash size	Example
`[XX]`	1 byte	`[A3]`
`[XXXX]`	2 bytes	`[A3F2]`
`[XXXXXX]`	3 bytes	`[A3F2C1]`

Bots, repeaters, and users may embed these tokens in channel or DM text (for example route reports, diagnostics, or templates that expand (HP) / [HP] to a hop list).

Replace HashCodes (Mgmt → Messages, default Enabled) controls display only:

Enabled: in channel/DM transcripts and message detail, each matching [XX] / [XXXX] / [XXXXXX] token is shown as [ContactName] when that prefix matches a node in your Contacts list (same lookup as the map hash badge and route overlay).
Disabled: messages show the literal hex tokens as received — useful for debugging, support logs, or copying exact on-air path data.

This does not change what was transmitted or what is saved on SD; it only changes how the device UI and WebUI render message bodies. Unknown hashes (no matching contact) stay as [A3] etc. The WebUI setting is the same (Replace HashCodes under node/message settings); unresolved hashes are shown in monospace grey, resolved ones as a name badge plus the hash.

When to use it:

Leave Enabled for day-to-day reading — channel traffic and quick-reply expansions are easier to follow when hop codes become repeater or user names you already know.
Turn Disabled if you need the exact hash bytes (troubleshooting routes, comparing with a packet log, or matching Path Hash Mode on another node).

Ensure repeaters and peers you care about are in Contacts (auto-add or manual); replacement only works for public-key prefixes you have stored locally.

Unread state and marking read

Unread badges appear on the Msgs tab, channel rows, and DM rows when messages have not been marked read on the device.
Open a thread and scroll to the bottom to mark visible traffic read automatically, or tap Read in the transcript header to mark the whole thread at once.
Tap Newest to jump to the latest message without scrolling manually.
While a phone or browser companion session is connected over Wi‑Fi/BLE, newly arriving messages are ingested as read on the device; use Read after disconnect if you cleared unread state only on the companion app.

6.2 Channels & Group Communication

Joining Channels

Channels can be joined in two ways:

By name: open the Msgs tab, tap +, and enter a channel name. A channel with no PSK is effectively a public channel — anyone using the same name on the same radio frequency can participate.
By name + PSK: tap +, enter the name, and enter the pre-shared key (base64 is usual; the WebUI also accepts hex or a psk: prefix). Only devices with the matching key can decrypt messages.
By hashtag link: tapping a #channelname reference in any received message immediately prompts you to join that channel.
Mgmt → Channels: use Add channel or Join channel — same channel list as the Msgs tab; changes are saved immediately.

Joined channels are written to the same store as contacts. With Primary Disk → SD Card, channel data is saved on the SD card (not only internal flash), so new channels survive reboot when the card is present.

The Public Channel

A default Public channel exists that is pre-configured on all MeshCore nodes. It has a known public key, so any node on the same frequency can participate. The Public channel is restored automatically if deleted.

Channel Management

Delete a channel: long-press the channel name in the transcript header, or use Mgmt → Channels → Delete.
Clear transcript: long-press the Back arrow inside a channel transcript.
Share a channel: Mgmt → Channels → Share shows a QR code. The QR encodes both the channel name and PSK.

6.3 Contact Management

Auto-Population

New nodes are discovered from their advertisement packets. When Auto Add Contacts is enabled, the GUI automatically adds incoming advertisements to the contact list based on:

Type filter — only the selected node types (USR, RPT, SVR, SNS) are added
Hop limit — only nodes reachable within the configured maximum number of hops are added

Manual Import

If you know a node's public key but it is not in radio range, you can add it manually:

Go to Mgmt → Contacts → Manual Add.
Enter the full 32-byte hexadecimal public key.
Enter a display name.
Tap Add.

The contact appears in the list immediately and will be available for messaging.

Favourites

Star any contact by tapping FAV in the contact detail view. Favourite contacts:

Are always shown regardless of the Favs Only filter
Are preserved when Purge Contacts (keep favourites) is used
Display a ⭐ badge in the contact list

Telemetry Permissions

By default, contacts do not automatically share their GPS coordinates and sensor readings with you unless you grant them permission. Tap TPERM in the contact detail view to toggle this. When permission is granted, the contact's telemetry fields are populated in the detail view as the node broadcasts data.

6.4 Map & GPS

GPS Acquisition

On first boot or after enabling the GPS module, allow up to 5 minutes for an initial satellite fix, especially indoors or in built-up areas. The GPS status icon in the status bar shows whether the module is searching or has a valid fix. Once a fix is acquired, the map automatically places the "ME" marker at your location.

For best results, position the device with a clear view of the sky. Some device variants (e.g. T-Deck Plus) have specific antenna placement requirements — consult your device's documentation for the optimal antenna orientation.

When Advert Location is enabled (Mgmt → Advert), your GPS coordinates are included in advertisement packets. Other nodes receive these coordinates and can plot your position on their maps. Disable Advert Location if you do not want to share your position.

GPS coordinates are saved to persistent storage every 5 minutes while a fix is active. After a reboot, the last saved position is shown on the map immediately.

Movement tracking (Tracker)

Mgmt → GPS → Tracking controls automatic flood adverts when your position changes:

Set F-Advert Tracking to Enabled.
Set Send tracking advert every to the distance in metres you must move before another tracking advert is sent (default 15 m).
Ensure GPS function is on and the module has a valid fix (Advert Location → GPS if you want coordinates in those adverts).

Each time you move at least that far from the last tracking anchor, the device issues a flood advert (rate-limited to about one attempt every 1.5 s). Other nodes can discover your updated position without waiting for the normal auto-advert schedule. An orange tracking icon in the status bar indicates tracking is enabled.

On the WebUI, the same options appear under node settings as Tracking and Track Dist m.

Offline Mapping

For offline map tiles, use the slippy-tile format ({z}/{x}/{y}.png) under Mgmt → Map → Tiles Folder, on internal flash or microSD depending on Mgmt → Global → Primary Disk. You can copy tiles from a PC (MOBAC, MAPC2MAPC, etc., zoom 8–16) or let the device download them when Network Tiles and Local Tiles are enabled and WiFi is connected (see §8.2).

The device also keeps 32 map tiles in RAM to reduce storage reads while panning.

Message path on the map

On the device, tap Path: in message detail to show the hop route on the Map tab (§4.6). In the WebUI, use Show Path On Map and Clear Path / Alt+C (§5.3.1).

6.5 Telemetry & Sensors

If the device has onboard sensors, the Tele page (Mgmt → Tele) shows live readings for:

Battery voltage
Temperature
Relative humidity
CO₂ concentration
TVOC (Total Volatile Organic Compounds) index

Each sensor channel has a live graph showing the last 96 readings. Telemetry from the local device is independent of radio communication — it reads the hardware sensors directly.

Remote telemetry from other node types (sensor nodes, repeaters) is visible in the contact detail view under the Telemetry field. The contact must have TPERM granted and must broadcast its sensor data in advertisements.

6.6 Radio Configuration

MeshCore uses LoRa radio modulation. The key configurable parameters are:

Frequency: The centre frequency in MHz. All nodes on the same mesh must use the same frequency. Consult your regional radio regulations for authorised ISM-band frequencies (e.g. 868 MHz in Europe, 915 MHz in North America).

Bandwidth (BW): The LoRa channel width. Narrower bandwidth gives better sensitivity and longer range but lower data rates and slower messaging. Wider bandwidth allows faster communication at shorter range. Common values: 62.5 kHz (maximum range), 125 kHz (balanced), 250/500 kHz (high throughput, shorter range).

Spreading Factor (SF): Controls the encoding spread. Higher SF = greater range and interference resilience, lower data rate, longer airtime. Lower SF = shorter range, faster messages. SF 7–8 is typical for shorter distances; SF 11–12 for maximum range on very sparse networks.

Coding Rate (CR): Forward error correction overhead. CR 5 (4/5 encoding) has less overhead; CR 8 (4/8 encoding) is more robust in noisy environments. Typically left at 5 unless experiencing high packet error rates.

TX Power: Output power in dBm. Higher power extends range but increases current draw and may exceed regulatory limits. Always verify the legal limit for your region and frequency band before increasing power.

All nodes communicating on the same mesh must have identical frequency, bandwidth, spreading factor, and coding rate settings. If any parameter differs, two nodes will not hear each other.

6.7 Time Synchronisation

Accurate time is used for message timestamps and routing cache management. Three synchronisation methods are available:

Manual entry (Mgmt → Date/Time → Device Time) — enter the current date and time manually and tap SET.
GPS sync (Mgmt → Date/Time → GPS Time) — read the current time from a GPS fix. Requires a valid GPS lock.
NTP (Mgmt → Date/Time → NTP Enabled) — automatically synchronise over WiFi to an internet NTP server. NTP syncs at boot and every hour thereafter. The firmware validates received timestamps and rejects values outside a plausible range to prevent rogue time sources from disrupting the device clock.

The NTP server hostname and timezone string are configurable. Use short forms like CET or UTC+2, or a full POSIX string (see Page 17 — Date/Time table) so displayed timestamps match local civil time including DST.

Quick check: after saving the timezone, the status-bar clock should match local UK/EU/US time before NTP sync (TZ alone shifts display). With NTP Enabled and WiFi connected, wait until NTP Status shows Synced.

6.8 Connectivity Transports

The companion firmware can connect to external client applications (mobile apps, WebUI, Python/JavaScript tools) via three transports:

Transport	Description
BLE	Bluetooth Low Energy. Suitable for short-range connections to a paired phone or tablet. Uses a fixed 6-digit PIN for pairing.
WiFi	Connects to an existing WiFi access point (STA mode) or creates its own network (AP mode). Enables the WebUI and remote access.
USB	Serial-over-USB. Used for direct connection to a computer running a compatible client. No wireless configuration required.

Only one primary transport (BLE or WiFi) is active at a time on most devices. Switching between BLE and WiFi is performed in Mgmt → WiFi or Mgmt → BLE using the Transport Switch control. On some devices the switch takes effect immediately; on others a reboot is required.

Access Point vs Station: Each saved WiFi profile stores whether it uses AP or STA mode plus the credentials for that mode. Switching profiles is the recommended way to move between a field hotspot, home router, and office WLAN (see §8.3). New devices default to AP when no Station SSID is configured.

Access Point mode: The device creates its own WiFi network (SSID/password from the active profile), assigns clients an address via DHCP (192.168.4.1/24 on the device), and allows up to three associated clients. The WebUI is reachable at http://192.168.4.1 when WebUI is enabled.

6.9 Firmware Updates

Firmware updates can be performed:

Via the web flasher — connect the device via USB and use https://flasher.meshcore.io as described in Section 2.2. Settings are preserved unless a full erase is performed.
Over-the-air (OTA) — when the build includes auto-update and WiFi is connected (with password set where required), use OTA Update on Mgmt → Global. Some boards also offer Update ESP32-C6 for coprocessor firmware. OTA downloads firmware over WiFi; a reboot follows.

SenseCap Indicator: OTA updates the ESP32 companion only. After any companion update, flash the matching RP2040 .uf2 from Releases as described in SenseCap Indicator — RP2040 coprocessor.

After any firmware update, verify that your radio settings (frequency, bandwidth, etc.) are still correct before transmitting.

6.10 Power Management

MeshCore is designed with power efficiency in mind.

Display sleep: The display enters soft-off (zero brightness) after Disp. Timeout (Mgmt → UI) elapses. The touch panel remains powered, so a touch wakes the display without a hardware button. This is the largest single contributor to battery life improvement.

Brightness: Lower Mgmt → UI → Brightness to reduce backlight current. On T-Deck Plus, Keyboard Light on Mgmt → Light is separate from the display.

GPS: The GPS module is a significant power consumer. Disable it (Mgmt → GPS → GPS function) when location is not required.

Radio: The LoRa radio is active continuously for reception. Reducing TX power and decreasing advertisement frequency reduce transmit power consumption.

Sounds: Active buzzers draw current when producing sound. Disabling notifications reduces idle power draw on devices with always-on buzzer hardware.

Autolock: Use autolock with a short timer (30–60 seconds) to ensure the display enters soft-off promptly after the device is set down. This prevents the display from remaining bright in a pocket or bag.

6.11 Audio Notifications

Devices with onboard audio hardware (buzzer or speaker) can play notification sounds for various events. All audio settings are in Mgmt → Sound:

All Sounds — master enable for notification audio
When Connected — tone when a BLE or WiFi client connects
Boot Sound, New DM, New Channel, Ack — per-event tones (each has a Play preview on device)

Volume can be set to Low, Medium, or High. Disabling individual notification sounds does not affect the other sounds.

Note: Audio is only available on devices with dedicated audio hardware. On the Heltec V4, audio support depends on hardware configuration; sound may be compiled as a no-operation on units without a confirmed buzzer connection.

7. Device Compatibility

7.1 Supported Hardware

Device	Processor	Display	GPS	Audio	SD Card	BLE	WiFi
LilyGO T-Deck Plus	ESP32-S3	320×240 TFT	✓	Speaker	✓	✓	✓
LilyGO T-Deck (OG)	ESP32-S3	320×240 TFT	—	—	✓	✓	✓
Seeed SenseCap Indicator	ESP32-S3 + RP2040	480×480 TFT	—	—	—	✓	✓
Elecrow CrowPanel 3.5"	ESP32-S3	480×320 TFT	—	—	✓	✓	✓
Elecrow CrowPanel Advanced 7"	ESP32-P4	1024×600 IPS	—	—	✓	✓ (via C6)	✓ (via C6)
Heltec V4 (extended)	ESP32-S3	TFT	—	Optional buzzer	—	✓	✓

7.2 Device-Specific Features & Limitations

LilyGO T-Deck Plus

Physical QWERTY keyboard and trackball provide the most complete input experience
Keyboard backlight blink notification is available on this device only
GPS module requires correct UART baud rate (38400) and antenna orientation; external antenna strongly recommended for reliable fix acquisition
Up to 32 GB SD cards supported; FAT32 format required
Screenshots can be captured from within the device (consult the FAQ for the key combination)

LilyGO T-Deck (Original)

No GPS module; GPS-related settings and map ME / follow-me behaviour are limited
No speaker; Mgmt → Sound rows may show as unavailable
Physical QWERTY keyboard and trackball; no Keyboard Light / keyboard-blink rows (those are T-Deck Plus only)
Map tab still supports keyboard pan/zoom (W/A/S/D, I/O, R, T for altitude bar)
Same core messaging, channels, and management pages otherwise

Seeed Studio SenseCap Indicator

Touchscreen only; no physical keyboard or trackball
Hardware button on the top edge toggles the display on/off
No built-in GPS; GPS features unavailable
Dual-MCU architecture (ESP32-S3 + RP2040): ESP32 runs the companion; RP2040 owns the onboard microSD, sensors, buzzer, and battery measurement — flash both on every release (§2.2 RP2040 UF2)
Map tiles and primary data can use the RP2040-attached SD when Mgmt → Global → Primary Disk is set to SD Card; network download remains available when SD is empty

Elecrow CrowPanel 3.5"

Capacitive touchscreen only
SD card slot available for map tiles
No built-in GPS

Elecrow CrowPanel Advanced 7" (ESP32-P4)

Largest supported display: 1024×600 MIPI-DSI IPS
WiFi and Bluetooth provided through an integrated ESP32-C6 coprocessor
Switching from BLE to WiFi involves the coprocessor and requires slightly longer transition delays than native ESP32 devices
GPS not built in; no audio hardware
Requires USB-C power delivery capable of 8–10 W for the display and coprocessor; underpowered USB ports may cause display instability

Heltec Vision Master V4

Touch TFT variant only (non-TFT variants use e-paper and are not covered by this GUI guide)
Audio support depends on hardware variant; buzzer notifications may be inactive on some units
No GPS, no SD card in the standard configuration

7.3 Default Radio Settings

The following defaults are applied on first boot when no saved settings exist (tuned for EU/UK ISM bands):

Parameter	Default Value
Frequency	869.618 MHz
Bandwidth	62.5 kHz
Spreading Factor	8
Coding Rate	8
TX Power	22 dBm

For other regions, adjust these settings immediately after first boot via Mgmt → Radio before transmitting. Example settings for other regions:

Region	Typical Frequency	Notes
Europe (EU863-870)	869.525 MHz or 869.618 MHz	1 % duty cycle applies
North America (US915)	915.0 MHz	Check local SUB-GHz regulations
Australia (AU915)	915.0–928.0 MHz	Channel plan varies
Asia (AS920-923)	923.0 MHz	Varies by country

8. Advanced Usage

8.1 Settings Persistence & Sync

Settings use two layers:

Binary prefs blob — the authoritative NodePrefs store (radio, telemetry, GPS, message options, scopes, etc.) plus manual position, written by savePrefs() to internal flash or SD depending on Primary Disk.
/MCTerm/prefs.txt — a portable INI-style sidecar (key=value, one per line) on the SD card when SD is available.

On boot, the firmware compares sync_version in internal storage and in prefs.txt and reconciles UI-oriented fields from the newer copy. The binary blob path follows Primary Disk (below).

What is in `prefs.txt`

Besides sync_version and UI keys (timeouts, map toggles, region scopes, sound, WebUI flags, zoom/brightness, and similar), the file includes every field written by the binary prefs save — for example:

Category	Example keys
Identity / node	`node_name`, `ble_pin`
Radio	`freq`, `bw`, `sf`, `cr`, `tx_power_dbm`, `airtime_factor`, `multi_acks`, `rx_delay_base`, `rx_boosted_gain`, `client_repeat`, `path_hash_mode`
Telemetry / advert	`telemetry_mode_base`, `telemetry_mode_loc`, `telemetry_mode_env`, `advert_loc_policy`, `auto_advert_zerohop_hours`, `auto_advert_flood_hours`
GPS / position	`gps_enabled`, `gps_interval`, `manual_lat`, `manual_lon`, `manual_alt`
Contacts / messaging	`manual_add_contacts`, `autoadd_config`, `autoadd_max_hops`, `quick_send_text`, `quick_reply1_text`, `quick_reply2_text`, `msg_auto_retry`, `msg_auto_reset_path`, `msg_mark_delivered_fast`, `msg_replace_hashes`
Map / tracking	`map_network_tiles_enabled`, `tracking_enabled`, `tracking_distance_m`
Scope defaults	`default_scope_name`, `default_scope_key`
Other	`buzzer_quiet`, identity key lines when exported, region scope rows (`ui_rgn…`), etc.

Whenever settings change in firmware (Mgmt edits, WebUI Save, GPS interval updates, and any other path that calls the internal prefs save), the sidecar is scheduled for rewrite (~120 ms debounce). After editing, wait briefly before removing the SD card, or leave Mgmt / let autolock run to force an immediate flush.

Primary Disk (Mgmt → Global → Actions) selects which store is authoritative for the binary prefs blob when SD is available:

Primary	Behaviour
Internal	Internal storage is source of truth; SD file is updated from internal when synced
SD Card	SD prefs file is source of truth when the card is present; switching may copy the blob between stores (watch boot log / progress UI)

What Primary Disk switch copies

Before the switch finishes, firmware flushes every pending save, then copies the complete managed state — not just radio fields:

Layer	Included
Node / radio	Full `NodePrefs` binary blob (`new_prefs`), including GPS interval, manual position, quick-send/reply text, map tiles flag, tracking, scopes, and message options
UI settings	All Mgmt/WebUI options in internal storage (timeouts, autolock, map, sound, NTP, WebUI, zoom/brightness, identity key path, etc.)
Region scopes	Region definitions and per-channel scope assignments (internal + `prefs.txt`)
Mesh data	Contacts, channels, main identity, advert path blobs, WiFi profiles
Internal namespace	Entire `meshcore` internal export (transport, GPS pin/baud overrides, boot transport, OTA flags, and other dynamic keys)
Sidecars	`/MCTerm/prefs.txt` (full key set above), advert-path sidecar, clipboard (per primary mode)

When SD Card is primary, day-to-day saves for contacts and channels go to the SD mirror paths (for example channels2.bin under /MCTerm/primary_state_v2/). Adding or joining a channel from the Msgs tab, Mgmt → Channels, or the WebUI persists there; you do not need a separate “apply” step beyond confirming the add/join dialog.

Progress is shown on device (Storage switch). Wait until it completes before removing the SD card.

prefs.txt is also updated from current in-memory settings whenever SD is mounted (see debounce note above). Moving an SD card between devices can transfer settings if the sync version on the card is newer. The internal clipboard is stored separately at /clipboard.txt on SD and is restored on boot when present.

SD Backup (Mgmt page 19) snapshots SPIFFS-style data to named slots on the card; it is separate from day-to-day prefs.txt sync (see page 19 notes above).

8.2 Map Tiles Setup

Map imagery uses the standard slippy-tile layout: each file is {z}/{x}/{y}.png (e.g. 12/2048/1365.png). The root directory is set in Mgmt → Map → Tiles Folder (default is often /tiles).

You can load tiles in two ways: copy them onto the device in advance, or let the firmware download them over WiFi when Network Tiles is enabled.

Where tiles are stored (Primary Disk)

The local tile cache — both pre-copied tiles and tiles saved after a network download — is written to:

Mgmt → Global → Primary Disk	Tile cache backend
Internal (default on many boards)	Device internal flash (SPIFFS), under the path from Tiles Folder
SD Card	microSD card, under Tiles Folder on that card

Switching Primary Disk changes where new network downloads are saved and where Local Tiles reads from. Use Mgmt → Map → Tiles Folder → Open to pick the subdirectory (e.g. /tiles) on whichever backend is active.

On boards that use a remote SD (e.g. some SenseCAP setups), SD Card primary may store tiles on the companion SD module; behaviour matches Primary Disk = SD Card in the UI.

Preparing tiles manually (offline copy)

Use a tile tool such as MOBAC (Mobile Atlas Creator), MAPC2MAPC, or a wget-style slippy downloader
Select OpenStreetMap or another compatible source and your area of interest
Export zoom levels 8–16 (or fewer on small cards; zoom 16 grows quickly)
Copy the {z}/{x}/{y}.png tree onto the chosen storage:
- Internal primary: copy into the SPIFFS path that matches Tiles Folder (via USB mass storage, backup restore, or another supported transfer path for your board)
- SD Card primary: copy onto the microSD, then set Tiles Folder to that directory

On-device folder selection:

Set Primary Disk if you want internal flash vs SD card as the tile store
Mgmt → Map → Tiles Folder → Open — browse the active backend and tap Use on the folder that contains the zoom-level directories
Enable Mgmt → Map → Local Tiles

The map reads from that cache. A 32-tile LRU RAM cache avoids re-reading storage on every pan frame.

Network tile download (WiFi)

When the device is on WiFi with internet access:

Enable Mgmt → Map → Network Tiles (and WebUI → Map → Network Tiles if you use the browser UI)
Enable Mgmt → Map → Local Tiles — required if downloads should be saved for later offline use. With Local Tiles off and Network Tiles on, tiles are shown from the network but not written to storage (RAM-only for that session).
Pan the map to areas that are not yet cached; missing tiles are fetched from OpenStreetMap, displayed immediately, and written under Tiles Folder on internal flash or SD card, according to Primary Disk

Firmware checks the local cache first, then the network. After a successful download, the PNG is stored at {Tiles Folder}/{z}/{x}/{y}.png on the selected backend so later sessions (or Local Tiles only, without WiFi) can reuse it.

Typical combinations:

Local Tiles	Network Tiles	WiFi	Result
On	On	Connected	Cache first, then download and save missing tiles
On	Off	—	Offline cache only
Off	On	Connected	Online view only; no persistence to storage
Off	Off	—	No map imagery (grid/positions may still show)

Attribution: When using OpenStreetMap tiles, display of attribution ("© OpenStreetMap contributors") is required by the OpenStreetMap licence. The device itself does not display attribution text on the map view; if you publish screenshots or use the map data in a public context, ensure compliance with the OSM tile usage policy.

8.3 WiFi Profile Management

WiFi profiles are the primary way to manage connectivity. Each profile is a complete WiFi configuration, not just an SSID/password pair:

Stored per profile	Description
Mode	Access Point (device is the hotspot) or Station (device joins another network)
STA SSID / password	Used in Station mode
AP SSID / password	Used in Access Point mode

Examples: a profile Field AP (AP mode, custom SSID for deployment), a profile Home (STA mode, home router credentials), and a profile Office (STA mode, office WLAN). Tap Pick → Select to activate a profile; the device applies mode and credentials and restarts WiFi when WiFi transport is already running.

Defaults (new or empty fields)

Setting	Default
Mode (new device, no STA SSID yet)	Access Point
Mode (upgraded device with STA SSID already saved)	Station (preserves existing behaviour)
AP SSID	Device node name (invalid characters stripped; max 32 characters)
AP password	BLE PIN formatted as six digits plus `00` (8 characters for WPA2, e.g. PIN `123456` → password `12345600`)
AP DHCP	192.168.4.1/24 on the device; up to 3 clients

Station IP Mode (DHCP vs static IP) is shared across profiles — it is not stored inside each profile file.

Creating a profile

Set Mode, credentials, and any other fields on Mgmt → WiFi (or WebUI → WiFi with Save per row).
Tap New Profile → Add, enter a name, and confirm.
The new profile is saved with a copy of the current active settings. The active profile does not change unless you select the new one.

The first time you edit WiFi without any profile, firmware creates a Default profile automatically.

Switching profiles

Mgmt → WiFi → Profile → Pick
Each row shows the profile name and AP or STA
Tap Select on the desired profile
The main WiFi screen updates; if WiFi transport is active, settings are applied without a full device reboot when possible

Editing the active profile

Changes on Mgmt → WiFi (Mode, AP SSID, AP password, STA SSID, password) are written to the active profile immediately. No separate “save profile” step is required.

Deleting a profile

Open the profile picker (Pick)
Tap Del on the profile row
Confirm deletion

If you delete the active profile, firmware selects another saved profile or clears the active name if none remain.

Legacy STA-only profiles

Older firmware stored only Station SSID and password per profile. On first boot with newer firmware, those files are upgraded automatically (MWP1 → MWP2): Station fields are kept; mode is Station if an SSID was set, otherwise Access Point. One-time global AP settings from older internal keys, if present, are merged into the active profile and removed from internal storage.

Profile persistence

Profiles are stored in SPIFFS at /state_v2/wifi_profiles.dat (format MWP2). They survive reboots and firmware updates. They are not part of prefs.txt, but they are included when you switch Primary Disk to copy full device state to or from SD (see §8.1), and may be mirrored to SD backup paths when SD mirroring is enabled. Swapping SD cards between devices can transfer profiles only when that full state copy or backup restore includes the WiFi profile file.

8.4 Repeater & Room Server Administration

Remote administration is accessible from the contact detail view when the target contact is a repeater or room server and you have the admin credentials.

Key workflows covered in Section 4.4:

Viewing live status and statistics
Managing the access control list (ACL)
Editing device name and radio parameters
Setting advertisement intervals
Reading and correcting the remote device clock
Running raw CLI commands for advanced configuration

Password security notes:

Admin passwords are stored per-public-key in device flash. The stored form is hashed, so the cleartext password is never persisted.
If you forget the admin password, physical access to the repeater is required to reset it via USB.
ACL entries limit who can access the repeater at each permission level (RO, RW, Admin). A repeater with an empty ACL accepts connections from any node.

8.5 Manual Contact Import

When you need to message a specific node but cannot wait for its advertisement packet — for example, before deploying two devices in different locations — use the manual contact import:

Obtain the target node's full 32-byte hexadecimal public key (Mgmt → Global → View → Copy on the target device, then transfer by any means)
On your device, go to Mgmt → Contacts → Manual Add
Paste or type the public key hex string
Enter a display name
Tap Add

The contact is immediately added to your list. Sending a message to this contact before an advertisement has been received will use flood routing to reach the destination, since the routing path is not yet known.

8.6 Optimisation Tips

Maximising Range

Use a lower bandwidth (62.5 kHz) and higher spreading factor (SF 11–12) for maximum link budget. Be aware this significantly slows message delivery and increases airtime.
Position repeaters at elevated locations — hilltops, rooftops, towers — with unobstructed line of sight.
Use a quality external antenna with a gain appropriate for your deployment distance. Replace the stock antenna on devices where the connector is accessible.
Lower coding rate (CR 5) is faster but less resilient to interference. In noisy RF environments, try CR 7 or 8.

Reducing Channel Congestion

Increase advertisement intervals (Mgmt → Advert). In an established network with stable membership, advertising every 30 minutes is sufficient.
Limit auto-add by setting Max Hops to 0 or 1 in Mgmt → Contacts. This prevents distant nodes — whose messages are unlikely to reach you directly — from flooding your contact list.
A mesh with many nodes all using SF 12 and frequent advertisements can quickly saturate the channel. Consider multiple frequency groups or reduce advertisement density.

Battery Life

Set Disp. Timeout to 10–30 s and enable Autolock with a 60 s timer
Set brightness to Low
Disable GPS when not needed
Disable sounds on devices with active buzzers
Increase advertisement intervals to reduce TX events
Use SF 7–8 (shorter messages = shorter airtime = less TX current)

Messaging Reliability

Enable Auto Retry and Auto Reset Path together: failed messages will trigger a full path re-discovery and retry automatically
Use Ping (contact detail → PING) to verify reachability before sending long messages
If a contact is consistently unreachable, use Mgmt → Advert → Scan Rpts to list overheard repeaters and their signal quality
Check Stats (Mgmt → Stats) for error events and duplicate counts. High traffic noise-floor degradation is visible in the noise floor reading on the Stats page.

9. Troubleshooting

Symptom	Most Likely Cause	Recommended Action
Screen stays dark on boot	Inadequate USB power (especially CrowPanel 7")	Use a USB power supply rated for at least 10 W; try a powered USB hub
No contacts appearing	No nearby nodes or wrong radio settings	Verify frequency, bandwidth, SF, CR in Mgmt → Radio; check that at least one other node is powered and on the same settings
Map tiles not displaying	Cache empty, wrong folder, Local Tiles off, or bad files	Check Primary Disk (SD inserted if SD primary); Tiles Folder must contain zoom folders; enable Local Tiles for cache reads; for network fill, also enable Network Tiles + WiFi
Map shows "No GPS fix"	GPS module searching; no satellite signal	Move to an open area with clear sky view; allow 3–5 minutes for cold start; verify GPS is enabled in Mgmt → GPS
Map tiles load from network but are slow	WiFi connected via coprocessor with limited RPC bandwidth	Normal behaviour on CrowPanel 7"; tiles load in the background — panning speed improves as the RAM cache fills
Touch not responding	Autolock is active	Long-press anywhere on the screen for 2 seconds to unlock
WiFi won't connect	Wrong SSID or password	Re-enter credentials in Mgmt → WiFi; check that the access point is reachable and using a 2.4 GHz band (5 GHz not supported)
Messages show ✗ (undelivered)	Destination out of range, stale path, or no repeater coverage	Tap the contact → PATH → Reset; enable Auto Retry; verify the destination node is online with a Ping
Repeater login fails	Wrong admin password or insufficient ACL role	Verify the password; if forgotten, reset the repeater via USB
NTP not syncing	No WiFi connectivity or NTP server unreachable	Check WiFi status; verify the NTP server in Mgmt → Date/Time; for offline networks use GPS or manual time entry
Clock wrong by ~1 h (e.g. UK BST)	Wrong timezone or missing DST rules	Use `BST` or `UK` for UK (with DST), `CET` for Central Europe, or `UTC+2` for fixed offset; not IANA names like `Europe/London`; save TZ then confirm status bar; enable NTP + WiFi for sync
System clock shows wrong year	Bad GPS time or rogue NTP source	The firmware validates time against a 2020–2050 plausibility range; if GPS is providing a wildly wrong date, try disabling GPS time sync and using NTP only
Stats graphs appear empty	No radio packets yet received	Wait for radio events; graphs populate on each received and transmitted packet
Device reboots during WiFi/BLE switch	Insufficient FreeRTOS scheduler time during radio transition	This is mitigated in recent firmware; if recurring, try switching transports with the device stationary and fewer background operations active
WebUI does not load	Device not on WiFi or wrong IP address	Check WiFi status (Mgmt → WiFi); confirm the IP address displayed under WiFi Status and navigate to `http://<IP>` in the browser
WebUI shows stale data after reconnecting	Browser WebSocket reconnecting	The browser reconnects automatically; wait 1–3 seconds after the page indicates "Connected" for all data to repopulate
BLE pairing fails	Wrong PIN entered on the connecting device	The PIN is the 6-digit value shown in Mgmt → BLE → BLE PIN; delete the existing pairing on the phone and pair again with the correct PIN
SD card not detected	Card not fully seated or incompatible format	Reseat the card; ensure it is formatted as FAT32; cards larger than 32 GB may need to be reformatted
Duplicate contacts appearing	Two nearby nodes generating identical public key prefix bytes	Use Manual Add to clarify identities; this is rare but can occur with large meshes
Joined channel missing after reboot (SD primary)	Channel list saved to internal flash while firmware loaded channels from SD	Fixed in v0.9.12.2+ — update firmware; re-add the channel once if needed, then reboot to verify
Backup page title not visible	Header New / Refresh overlapped centred title on some screen widths	Fixed in v0.9.12.2+ — title is drawn in the free space to the right of Refresh
Contact detail blank after contact removed	Detail stayed open with no Back control	Fixed in v0.9.12.2+ — Contact missing + Back; detail auto-closes when returning to the list
Unread badges after reading on phone only	Read state is not synced from the companion app after disconnect	Tap Read in the thread header, or open the thread on device; new traffic while companion is connected is marked read automatically

10. Best Practices

Network Deployment

Place repeaters high. The single most effective way to extend a MeshCore mesh is putting at least one repeater at elevation (a rooftop, hill, or tower) with clear line of sight to as many participants as possible.
One frequency, one mesh. All nodes in a communicating group must use identical radio settings. Document the agreed settings before deploying devices in the field.
Use dedicated repeater hardware. Running a companion-radio device as a relay is not recommended; it does not forward packets. Use repeater firmware on dedicated hardware for infrastructure nodes.
Plan your hop budget. Each additional hop adds latency and consumes channel bandwidth. Design the network so that most nodes need at most 2–3 hops to reach any destination.

Security

Set a strong admin password on all repeater and room server nodes before deployment. An empty or default admin password allows anyone on the mesh to reconfigure or reboot the hardware.
Use PSK-protected channels for any communication that should not be readable by all participants. The Public channel is visible to every node on the frequency.
Do not share admin credentials over mesh messages. The admin password should be distributed out-of-band (in person or via encrypted link).
Disable telemetry sharing (TPERM) for contacts you do not trust with your location data.
Rotate PSKs for private channels periodically, especially after a member leaves the group.

Everyday Operation

Name your device clearly. Use a name that uniquely identifies you within your group (e.g. your callsign or first name + last initial). Generic names cause confusion on the contact list.
Use Favourites. Star the contacts you communicate with most often and activate the Favs Only filter for a clean, focused contact view during an event.
Keep SD tiles updated. Before a field event, download fresh map tiles for the target area and copy them to the SD card. OSM data improves continually — tiles from 6+ months ago may be noticeably outdated in actively mapped regions.
Check Stats before an event. Review Mgmt → Stats → noise floor and last RSSI/SNR after deploying to verify you are on a clean frequency with adequate signal margins.
Use Ping to verify routes. Before relying on a contact for communications, send a Ping from the contact detail view. The measured round-trip time gives a realistic indication of whether messages will get through reliably.
Back up your settings. Periodically copy /MCTerm/prefs.txt to a safe location. It lists UI preferences plus the full radio/node field set (see §8.1). For a full device image including contacts and message stores, use Mgmt → Backup slots in addition to keeping prefs.txt.

MeshCore is open-source software released under the MIT licence. Contributions, bug reports, and device support requests are welcome via the project repository.