meshcore-gui/AGENTS.md

MeshCore GUI — Agent Notes

Purpose

MeshCore GUI is a NiceGUI-based desktop/headless web UI for MeshCore radios. It supports two transport modes:

• USB Serial via MeshCore.create_serial() — for wired connections
• Bluetooth LE via MeshCore.create_ble() — for wireless T1000e devices

The transport is auto-detected from the device argument.

Entry Points

• meshcore_gui.py (primary)
• python -m meshcore_gui (meshcore_gui/__main__.py)

Common Run

# Serial
./venv/bin/python meshcore_gui.py /dev/ttyACM0 --debug-on --baud=115200

# BLE
./venv/bin/python meshcore_gui.py literal:AA:BB:CC:DD:EE:FF --debug-on --ble-pin 123456

Architecture (High-Level)

• UI thread (NiceGUI): meshcore_gui/gui/*
• Worker thread (transport + asyncio): meshcore_gui/ble/worker.py
  • _BaseWorker — shared main loop, caching, data loading
  • SerialWorker — USB serial transport
  • BLEWorker — Bluetooth LE transport (PIN agent, bond management)
  • create_worker() — factory function for auto-detection
• Commands: meshcore_gui/ble/commands.py
• Events: meshcore_gui/ble/events.py
• Shared state: meshcore_gui/core/shared_data.py
• BLE PIN agent: meshcore_gui/ble/ble_agent.py (D-Bus, Linux only)
• BLE reconnect: meshcore_gui/ble/ble_reconnect.py (bond cleanup)

Transport Detection

config.is_ble_address(device_id) returns True when:

• Device ID starts with literal: prefix
• Device ID matches XX:XX:XX:XX:XX:XX MAC address pattern

Everything else is treated as a serial port path.

Config (meshcore_gui/config.py)

• TRANSPORT: "serial" or "ble" (set at startup)
• Serial: SERIAL_BAUDRATE, SERIAL_CX_DELAY, DEFAULT_TIMEOUT
• BLE: BLE_PIN, DEFAULT_TIMEOUT
• Shared: MESHCORE_LIB_DEBUG, RECONNECT_*, CONTACT_REFRESH_SECONDS

Dependencies

• Serial mode: meshcore, nicegui, meshcoredecoder
• BLE mode: additionally bleak, dbus_fast (Linux only)
• BLE dependencies are lazily imported — serial-only installs don't need them.

Device Name Behavior

• BOT toggle changes device name via set_device_name command.
• Warning labels are shown next to BOT toggles.
• Explicit device name can be set via the Actions panel input.

Map Centering

• Map is in meshcore_gui/gui/panels/map_panel.py.
• Centering happens on device updates or when the MAP panel is opened.
• There is a Center on Device button that uses the last known GPS.
• Leaflet size invalidation is called before centering to handle hidden panels.
• Map theme follows UI dark/light mode by default.
• Map theme can be overridden with the Theme toggle (Auto/Dark/Light).

Panel URLs

• Drawer and sidebar actions navigate to /?panel=<id>&channel=<optional> so browser back restores the last panel.
• On load, the dashboard reads the query params and shows the requested panel.

Route Viewer

• Clicking a message opens /route/{msg_key} in the same tab.
• The route page has Back to Dashboard and Back to Archive buttons.

Refresh Behavior

• GUI refresh queues a full device reload.
• Contacts fetch is bounded by a timeout to prevent hangs.

Persistent Data

Stored under ~/.meshcore-gui/:

• cache/, archive/, logs/, pins/, room_passwords/

Tests

• Tests live in tests/.
• pytest is not installed by default; use pip install pytest in the venv.

Installer Scripts

• install_serial.sh — systemd service for serial connections
• install_ble_stable.sh — systemd service for BLE connections