PRE-RELEASE — v0.1.1 beta. Core functionality is working. Some features are incomplete and rough edges remain. Feedback and bug reports welcome via GitHub Issues.

MeshTTY is a terminal-based (TUI) client for Meshtastic LoRa mesh radio networks. It runs on a Raspberry Pi or any Linux/macOS system with a terminal. Built with the Textual framework, it connects to a Meshtastic node over USB/serial, TCP/WiFi, or Bluetooth (BLE) and renders a classic 80×24 box-drawing UI that works in any terminal — no desktop environment, GPU, or X server required.

1. Installation
   • 1.1 Raspberry Pi and DietPi
   • 1.2 macOS and Ubuntu
   • 1.3 Manual install
2. Updating
3. Running MeshTTY
4. Command-Line Flags
5. Connection Screen
6. Main Screen
   • 6.1 Messages Tab
   • 6.2 Channels Tab
   • 6.3 Nodes Tab
   • 6.4 Node Detail Modal
   • 6.5 Settings Tab
   • 6.6 DM Slash Commands
7. Keyboard Shortcuts
8. Configuration File
9. Message & Node Database
10. Themes
11. Debug Logging
12. Serial Port Permissions (Linux)
13. Known Issues & Missing Features
14. Troubleshooting
15. Headless / Kiosk Operation (Raspberry Pi)

git clone https://github.com/kendelmccarrey/MeshTTY.git
cd MeshTTY
bash install-pi.sh

Supported hardware:

The installer will:

• Install system packages (python3-full, python3-venv, bluez, fonts-terminus, etc.)
• Create a Python virtualenv at ~/.venv/meshtty (using --copies to avoid PEP 668 issues on Bookworm/Trixie)
• Handle ARMv6 pip failures gracefully (grpcio wheel incompatibility on Pi Zero W)
• Add your user to the dialout, bluetooth, and video groups
• Generate meshtty.sh and make launch-pi.sh executable
• Optionally configure tty1 auto-launch for kiosk operation
• Optionally enable loginctl enable-linger for user systemd services

Log out and back in after the install for group membership to take effect.

git clone https://github.com/kendelmccarrey/MeshTTY.git
cd MeshTTY
bash install.sh

macOS prerequisite: Homebrew must be installed first.

The installer handles system packages, virtualenv creation, and generates meshtty.sh.

python3 -m venv ~/.venv/meshtty
source ~/.venv/meshtty/bin/activate
pip install -e .

Dependencies installed automatically:

Python 3.11 or newer is required.

bash update.sh

update.sh will:

1. Warn if there are uncommitted local changes before pulling
2. Run git pull --ff-only
3. Print a changelog of commits since the last update
4. Re-run pip install only if requirements.txt changed
5. Re-install the local package to pick up source changes
6. Ensure all launch scripts are executable

./launch-pi.sh
./launch-pi.sh --bot --log    # pass flags through

launch-pi.sh detects whether it is running on the Linux framebuffer console ($TERM=linux, not SSH, not X). On the physical screen it reads the framebuffer resolution and loads the largest Terminus font that still fits at least 80 columns, so the UI fills whatever display is connected at a comfortable size. It then sets TERM=xterm-256color before launching MeshTTY.

./launch.sh                # thin wrapper around meshtty.sh
./meshtty.sh               # direct launcher
python -m meshtty.main     # using active virtualenv

The app starts on the Connection Screen. Once connected it switches automatically to the Main Screen.

Flags are persisted across reboots. The last set of flags is saved to ~/.config/meshtty/last_flags and replayed on the next launch unless new flags are passed explicitly or --noargs is used.

The first screen shown on launch. Choose how to connect to your radio node.

• The app scans for serial ports matching common Meshtastic USB chips and lists them in a table.
• Click a row or type the port path manually (e.g. /dev/ttyUSB0, /dev/ttyACM0).
• Press Enter or click CONNECT.

• Enter the hostname or IP address of the node and the port (default 4403).
• Press Enter or click CONNECT.

• Click SCAN FOR BLE DEVICES to perform a 5-second scan.
• Click a row or enter a MAC address manually.
• Click CONNECT.

The Remember this device switch (on by default) saves connection details so the same transport and address are pre-filled on the next launch.

If a device was remembered from a previous session, the connection screen starts a 5-second countdown and connects automatically. Press any key, switch tabs, or click a button to cancel.

Progress is shown in a status line: Connecting…, Connected — downloading nodes…, Download complete…, Connected! (N nodes loaded). Errors appear in red.

After a successful connection the app switches to the Main Screen, which has four tabs. The status bar at the top shows connection state and node count.

A unified, scrollable message history for all channels and direct messages, plus a compose bar at the bottom.

HH:MM ChannelName/SenderName: message text   ← channel broadcast
  HH:MM SenderName: message text             ← direct message (indented)

• Channel messages show ChannelName/SenderShortName as the prefix (e.g. Primary/HAK5).
• Direct messages show just the sender's short node name.
• Outgoing messages are indented two spaces and displayed in accent colour.
• Long lines wrap aligned under the message text.
• The 200 most recent messages are loaded from the local database on startup.
• Node short names are resolved from the local database so names appear correctly even after reconnect.

The bottom row is split into two focus areas:

[ Channel   ][ type your message here…               ][ SEND ]

• Left area (12 chars) — shows the current channel name or DM node short name. Tab to focus it, then use Up/Down to cycle through conversations sorted by most recent message. Press Enter to advance to the message input.
• Right area — type your message and press Enter or click SEND.

Routing:

• If the selected prefix matches a channel name → broadcasts on that channel.
• If the selected prefix matches a node short name → sends as a direct message to that node.

• Up/Down — scroll one line when the message history or compose input has focus.
• PageUp/PageDown — scroll one screen from any focus.

Lists all channels configured on the radio. Updates when the connection is established.

Live table of all mesh nodes heard on the network.

Ctrl+R forces a refresh. Click any row to open the Node Detail Modal.

Shows node ID, short/long name, hardware model, last SNR, last heard, battery level, and GPS position. Close with CLOSE, Escape, or Q.

Configure transport, display, and messaging defaults. Shows current connection status and a Disconnect button. Press Tab / Shift+Tab to move between fields. Use Space, Enter, ←/→ on option fields to cycle through choices. Press Save to write changes to disk. The Theme setting takes effect immediately.

Enable with --bot. Incoming DMs starting with / trigger automatic replies:

Commands are case-insensitive. /JOKE requires meshtty/data/shortjokes.csv (not included — compatible file at Kaggle Short Jokes dataset).

Location: ~/.config/meshtty/config.json

Created automatically on first run.

{
  "default_transport": "serial",
  "last_serial_port": "/dev/ttyUSB0",
  "last_tcp_host": "",
  "last_tcp_port": 4403,
  "last_ble_address": "",
  "auto_connect": true,
  "log_level": "WARNING",
  "db_path": "~/.config/meshtty/messages.db",
  "default_channel": 0,
  "node_short_name_display": true,
  "theme": "crt-amber"
}

Location: ~/.config/meshtty/messages.db

SQLite database created automatically.

-- All messages, newest first
SELECT datetime(rx_time,'unixepoch','localtime') AS time, display_prefix, text
FROM messages ORDER BY rx_time DESC LIMIT 50;

-- All known nodes
SELECT node_id, short_name, long_name, battery, last_snr FROM nodes;

Three built-in themes selectable from Settings → Theme. Each uses a phosphor-inspired colour palette designed to look good in any terminal.

The Theme setting in the Settings tab takes effect immediately without restarting.

./launch-pi.sh --debug    # Pi
./launch.sh --debug       # macOS / Ubuntu
tail -f /tmp/meshtty.log

sudo usermod -aG dialout $USER

Log out and back in. Verify with groups — output should include dialout.

Both install.sh and install-pi.sh handle this automatically.

No group membership required. Serial devices appear as /dev/cu.usbserial-XXXX or /dev/cu.SLAB_USBtoUART. Run ls /dev/cu.* with the radio plugged in.

• Messages stored before the display_prefix column was added fall back to displaying the raw from_id node string.
• BLE transport is largely untested.

• Message acknowledgement display
• Persistent compose prefix across sessions
• Node position map view
• Channel creation / management
• Firmware version / radio config display
• New message notification on non-active tab

Run with --debug and watch the log. Timeouts like _waitConnected timed out but N nodes present are usually harmless — the transport forces a connection and node records continue arriving. If completely stuck, quit (Ctrl+Q) and reconnect.

1. Run with --debug, check /tmp/meshtty.log
2. Confirm dialout group membership (section 12)
3. Unplug and re-plug the USB cable
4. Test with the CLI: meshtastic --port /dev/ttyUSB0 --info

The scanner filters by USB vendor ID. Supported chips:

If your adapter uses a different chip, enter the port path manually.

The Pi Zero W's combined Wi-Fi/BT chip (CYW43438) can cause interference. If BLE scanning fails:

• Ensure BlueZ is version 5.55 or newer: bluetoothctl --version
• Try disabling Wi-Fi: rfkill block wifi
• Use serial or TCP transport instead — more reliable on Zero hardware.

Expected install time is 30–90 minutes. Do not interrupt pip once it starts.

If pip fails with a grpcio or "illegal instruction" error, install-pi.sh retries without grpcio automatically (meshtastic ≥ 2.5 no longer requires it).

dietpi-config → Performance Options → Swap

Set to 1024 MB for the install, then reduce back to 256 MB afterward.

python3 -m json.tool ~/.config/meshtty/config.json

If "theme" contains an unrecognised value, the app silently resets it to crt-amber.

MeshTTY runs as a full-screen terminal application on a headless Pi with a physical display — no desktop environment, X server, or GPU required.

1. Configure console auto-login:
   • Raspberry Pi OS: sudo raspi-config → System Options → Boot / Auto Login → Console Autologin
   • DietPi: dietpi-config → AutoStart Options → set to 0 (console autologin)
2. Run install-pi.sh and answer Y when asked about auto-launch on tty1.

The installer adds a block to ~/.bash_profile:

# MeshTTY auto-launch on tty1 (physical Pi screen)
if [[ "$(tty)" == "/dev/tty1" ]]; then
    while true; do
        /path/to/MeshTTY/launch-pi.sh
        sleep 2
    done
fi

launch-pi.sh skips the font load automatically when running over SSH or inside X/Wayland.

SSH in to investigate without disturbing the console:

ssh user@<pi-hostname>
tail -f /tmp/meshtty.log