Meshyface

Meshyface ist ein Chat-zentriertes Meshtastic-Dashboard, das als einzelner Python-Dienst läuft und eine Single-Page-Web-UI über HTTP bereitstellt.

Aktuelle App-Oberfläche

Die aktuelle UI bietet:

• Chat sowie Direkt-Peer-Gespräche
• Netzwerkarbeitsbereich für Karte, Übersicht, Verbindungen, Routen, Sensoren, Top-10-Rankings, Knotendetails und On-Demand-Verlauf
• Konsolenarbeitsbereich für Live-Paket-/Log-Ausgabe
• Apps-Arbeitsbereich mit Spielen und einem Dateireiter, wenn Dateiübertragung aktiviert ist
• Einstellungsarbeitsbereich mit Funkgerät-, Geräte-, Konnektivitäts-, Standort-, Kanäle-, Ticker-, Listen-, Darstellungs- und Über-Panels
• SQLite-gestützter Verlauf, Suche, Rollups, Themenpersistenz und persistente benutzerdefinierte Telemetrieregeln

Konsolenarbeitsbereich

Der Konsolenarbeitsbereich ist eine terminalartige Steuerfläche für Paketverkehr, Verlaufssuche und Mesh-Dienstprogrammbefehle.

• Gib einen Befehlsnamen ein, um Autocomplete-Vorschläge zu öffnen. Verwende Tab oder Enter zum Annehmen, PfeilRechts zum Annehmen des ausgegrauten Suffixes und PfeilHoch / PfeilRunter zum Navigieren durch das Popup.
• Befehle mit einem Knotenziel zeigen umfangreiche Knotenvorschläge mit Name, ID, Emoji, Tag, Status, Hops, GPS, letztem Hören, Ports und Knotennummer an. Normaler Text filtert nach Knotennamen und Tags; ! filtert nach Knoten-ID.
• live streamt Paketverkehr bis Strg+C oder q. Verwende live grep <text>, live rg <text>, live filter=<text> oder einfach live <text>, um nur passende Live-Paketgruppen zu streamen. Ebenen- und Ausführlichkeitsfilter gelten weiterhin, z.B. live rg TEXT_MESSAGE_APP -vv --layer=2.
• grep <text> und rg <text> durchsuchen den gespeicherten Paket-/Chat-Verlauf mit Kontextfenstern, Begrenzungen, Paket-/Chat-Quellfiltern und Zusammenfassungs-/Paketbereichsfiltern.
• /search <text> filtert die sichtbare Konsolenausgabe von der Eingabeaufforderung, ohne eine gespeicherte Verlaufssuche zu starten.

Screenshots

Live-Netzwerkkarte

Kartenansicht mit Knotenpositionen, Verbindungen, gemeinsamen Pfaden, Clustern und Signal-Wärmekarte.

Netzwerkübersicht

Verlaufsansicht für Knotenanzahlen, Online-Status, neue Knoten und Positionsmeldungen.

Verbindungstopologie

Topologieansicht, die beobachtete Verbindungen vom ausgewählten Wurzelknoten zeigt.

Routenverfolgung

Trace-Ansicht für eine Quelle, ein Ziel, nahegelegene Verbindungen und paketgenaue Details pro Hop.

Sensorverlauf

Telemetriediagramm, das den Sensorverlauf über mehrere Knoten vergleicht.

Statuskarten

Oberste Karten für Funkaktivität, Knotenanzahlen, Pakete, Verbindungen, Akku und Kanalnutzung.

Design-Anpassung

Designs können das gesamte Dashboard mit benutzerdefinierten Farben, Farbverläufen, Transparenz, Unschärfe, Schriftarten, Partikeln oder einem Live-Karten-Hintergrund umgestalten. Diese Beispielpaletten sind benutzerdefinierte Designs; wähle eine Vorschau aus, um ihren Screenshot in voller Auflösung zu öffnen.

Signal Grün	Neon Magenta	Aurora Relay

Gemeinsame Knotendarstellungen

Meshyface-Knoten können kompakte Darstellungspakete teilen, die ein Knoten-Design-Rezept und einen optionalen Geist oder ein Wasserzeichen enthalten. Konfiguriere und zeige eine Vorschau deines Knotens unter Einstellungen > Darstellung > Knotendarstellung, aktiviere Knotendarstellung teilen und verwende dann Darstellung senden, um sie zu veröffentlichen.

• Darstellungspakete verwenden den konfigurierten Profile-Sendekanal und übernehmen die Hop-Limit-Einstellung des Funkgeräts; Meshyface legt kein separates Hop-Limit fest.
• Empfangene Darstellungen können Knotenidentitäten in Chat, Listen, Knotendetails, Karten, Graphen, Sensoren und Tickern gestalten, ohne das Design des empfangenden Dashboards zu ersetzen.
• Das Deaktivieren von Knotendarstellung teilen deaktiviert beide Seiten der Funktion. Es stoppt Sendungen und umgeht den Profile-Empfangspfad, bevor eingehende Darstellungsdaten dekodiert, zwischengespeichert oder gespeichert werden; zwischengespeicherte gemeinsame Darstellungen werden gelöscht und keine empfangene Darstellung wird gerendert.
• Wenn der Verlauf aktiviert ist, bleiben empfangene Profile und die lokale Freigabeeinstellung in der SQLite-Verlaufsdatenbank erhalten.
• Gemeinsame Darstellungen sind kosmetische Metadaten. Eine empfangene Darstellung ändert keine Funkeinstellungen, Kanäle oder das gespeicherte Paketdesign des Dashboards.

Systemarchitektur

flowchart LR
  Browser["Browser<br/>single-page UI"]
  CDN["Vendored browser assets<br/>Leaflet + leaflet.heat + particles.js"]
  Tiles["Basemap provider<br/>OpenStreetMap tile service"]
  Server["ThreadingHTTPServer<br/>HTML shell + JSON API"]
  Assets["Python template assembly<br/>meshdash/html* + meshdash/assets/*"]
  State["State loaders<br/>live snapshot + history readers"]
  Services["Write services<br/>chat, settings, tools, games, optional files"]
  Tracker["DashboardTracker<br/>live receive path + in-memory buffers"]
  History["HistoryStore / SQLite (WAL)<br/>chat, packets, rollups, settings"]
  Radio["Meshtastic interface<br/>serial or TCP"]
  Mesh["Meshtastic radio / mesh"]
  Atlas["Bundled offline atlas<br/>reference basemap fallback"]

  Browser -->|GET /| Server
  Browser -->|GET /api/*| Server
  Browser -->|POST write APIs| Server
  Browser --> CDN
  Browser --> Tiles
  Browser -->|fallback basemap data| Atlas
  Server --> Assets
  Server --> State
  Server --> Services
  State <--> Tracker
  State <--> History
  Services <--> History
  Services <--> Radio
  Radio <--> Mesh
  Radio -->|receive callbacks| Tracker

Installation

Beginne mit Voraussetzungen und Abhängigkeiten, wähle dann einen Installationspfad:

• Manueller Vordergrundbetrieb: Klone überall und führe das Dashboard direkt aus.
• Empfohlener systemd-Dienst: Klone nach /opt/meshyface für einen persistenten, über GitHub aktualisierbaren Host.
• Docker: Führe denselben App-Einstiegspunkt in einem Container mit gemountetem /data für persistenten Zustand aus.
• Workstation-Push-Bereitstellung: Kopiere ein lokales Checkout per SSH auf ein Zielsystem.
• Proxmox-Laufzeit-Topologie: Wähle TCP- oder USB-Funkplatzierung für eine VM/LXC-Installation.
• Offline-Kartenpakete: Füge detaillierte lokale Kartendaten für air-gapped oder schlecht angebundene Dashboards hinzu.

Daten und Speicherung

Gemeinsame Verlaufsdatenbank

--history-db ist der endgültige SQLite-Dateiname auf der Platte. Das Dashboard fügt kein Suffix mehr für das angeschlossene Funkgerät hinzu, sodass jedes am Dashboard angeschlossene Funkgerät zur selben gespeicherten Paket-, Chat-, Knoten- und Rollup-Verlauf beiträgt.

Verlauf-Modi

• Standardmodus speichert Chat, Pakete, Verbindungsereignisse, Knotenanalysen, fehlerhafte Textdatensätze, Umgebungsmetriken und Zusammenfassungs-Rollups in SQLite.
• --no-history deaktiviert den persistenten Speicher und behält nur Live-Puffer im Arbeitsspeicher.
• Zusammenfassungs-Rollups werden im Hintergrund abgetastet, während das Dashboard läuft, wenn der Verlauf aktiviert ist.

Design und lokale Einstellungen

• Die Designvorauswahl wird standardmäßig in mesh_dashboard_theme_settings.json oder der über --theme-settings-file angegebenen Datei gespeichert.
• Benutzerdefinierte Telemetrieregeln werden in der SQLite-Verlaufsdatenbank gespeichert.

Wartungsbefehle

Betriebsbefehle, die lokale Dashboard-Daten überprüfen oder reparieren, sind in docs/maintenance.md dokumentiert.

Semantik der Verbindungsansicht

Die Verbindungen-Teilansicht ist eine Topologieansicht, keine Paketrouten-Wiedergabe.

• Der Verlauf-Modus zeichnet aus der in SQLite gespeicherten Verbindungshistorie.
• Der Live-Modus zeichnet nur aus aktuellen Sitzungsverbindungsbeobachtungen.
• Die nummerierten Ringe zeigen den kürzesten Graphabstand vom aktuellen Wurzelknoten mittels einer Breitensuche über den beobachteten Verbindungsgraphen.
• Diese Ringnummern sind keine wörtlichen Meshtastic-Weiterleitungshops und keine Echtzeit-Paketverfolgung.
• Paket-Hop-Metadaten werden, falls verfügbar, weiterhin separat in Knoten- oder Kantendetails als Paket-Hop-Werte angezeigt.

Der aktuelle Wurzelknoten ist der Knoten, um den der Graph zentriert ist. Das Auswählen eines anderen Knotens ändert die Wurzel und berechnet die nummerierten Entfernungsringe ausgehend von diesem Knoten neu.

Konfigurationsreferenz

Verbindung und Transport

• --mesh-host <ip-or-dns>: TCP-Funk-Host
• --mesh-tcp-port <port>: TCP-Funk-Port, Standard 4403
• --mesh-port <path>: Seriellgerätepfad
• --default-gateway-host <host>: Fallback-TCP-Host, falls --mesh-host nicht angegeben ist und seriell noch auf dem Standardpfad liegt
• --default-gateway-port <port>: Fallback-TCP-Port für --default-gateway-host
• --no-default-gateway: Erzwinge seriell, es sei denn, --mesh-host ist explizit gesetzt

Zugehörige Umgebungsvariablen:

• MESH_GATEWAY_HOST
• MESH_GATEWAY_PORT
• MESH_DASH_MESH_PORT für den Standard-Seriellpfad

HTTP, UI und Sicherheit

• --http-host <host>: Bind-Host, Standard 0.0.0.0
• --http-port <port>: Bind-Port, Standard 8877
• --refresh-ms <ms>: Browser-Poll-Intervall, Standard 3000
• --packet-limit <n>: Puffergröße für kürzliche Live-Pakete, Standard 250
• --reset-ticker-scale-on-restart / --no-reset-ticker-scale-on-restart
• --show-secrets: Zeige private Schlüssel/Passwörter/PSKs in rohen JSON-Panels
• --debug-mode / --no-debug-mode: Lege nur für das Debugging bestimmte Dashboard-Oberflächen frei, z.B. erweiterte Netzwerkdiagnose

Zugehörige Umgebungsvariablen:

• MESH_DASH_PRIVATE_MODE
• MESH_DASH_API_TOKEN
• MESH_DASH_GAMES_ENABLE
• MESH_DASH_VERSION
• MESH_DASH_GIT_COMMIT
• MESH_DASH_PR_NUMBER

Die Laufzeitidentität stammt aus dem 12-stelligen Git-Commit, gefolgt von einer optionalen Pull-Request-Nummer, z.B. abc123456789 · PR #43. Das Software-Panel zeigt diese einzelne Revision anstelle einer Paketversion. GitHub-Merge/Squash-Commit-Betreffe werden automatisch erkannt; unmergeierte Vorschau-Bereitstellungen können MESH_DASH_PR_NUMBER explizit setzen.

/api/revision ist der kanonische Identitätsendpunkt. Seine Felder revision und build_ref melden die Laufzeitrevision, während commit und pr_number als strukturierte Felder verfügbar bleiben. /api/version bleibt als Legacy-Endpunkt erhalten, und sein Feld version behält Release-/Paket-Metadaten. MESH_DASH_VERSION ist ebenfalls für explizite Release-Paketierung reserviert und wird nicht im Dashboard angezeigt.

Dateiübertragung

• --file-transfer-enable: Aktiviere die Dateien-App; erfordert --accept-file-transfer-traffic-disclaimer
• --file-transfer-auto-accept: Akzeptiere eingehende Direktübertragungen ohne Browser-Bestätigung
• --file-transfer-max-bytes <bytes>: Limit pro Datei, Standard 65536 und begrenzt auf 1024-524288

Übertragungen verwenden das Beta-Protokoll MF_FILE_V2 auf privatem Port 258 und sind nicht mit dem früheren Textnachrichten-Transport kompatibel. Wenn ein Ziel eine nutzbare erkannte Hop-Anzahl hat, verwendet Meshyface diese Anzahl plus eins, begrenzt durch das konfigurierte Funk-Hop-Limit. Hop-Daten, die älter als eine Stunde sind, fallen auf das konfigurierte Limit zurück. Die Dateien-App zeigt das ausgewählte Limit und seine Quelle an.

Zugehörige Umgebungsvariablen:

• MESH_DASH_FILE_TRANSFER_ENABLE
• MESH_DASH_FILE_TRANSFER_AUTO_ACCEPT
• MESH_DASH_FILE_TRANSFER_MAX_BYTES
• MESH_DASH_ACCEPT_FILE_TRANSFER_TRAFFIC_DISCLAIMER

Verlauf und Analyse

• --history-db <path>: Basis-SQLite-DB-Pfad
• --history-max-rows <n>: Standard 200000
• --history-retention-days <days>: Standard 30, verwende 0 zum Deaktivieren der Altersbereinigung
• --history-event-max-rows <n>: Append-only-Paketereignisgrenze, Standard 200000
• --history-event-retention-days <days>: Standard 30
• --history-rollup-retention-days <days>: Standard 365
• --no-history: Nur-Arbeitsspeicher-Modus

Zugehörige Umgebungsvariablen:

• MESH_DASH_HISTORY_DB

Designs

• --theme-presets <json>: Optionale benutzerdefinierte Designvorlagendatei
• --theme-preset <name>: Ausgewählter Vorlagenname
• --theme-settings-file <json>: Persistente Laufzeit-Designauswahldatei

Integrierte Vorlagen:

• default (sicheres Meshyface-Blau, Partikel deaktiviert)
• custom (Showcase-Design mit Partikeln und Hintergrundeffekten aktiviert)

Frische Installationen verwenden standardmäßig default, es sei denn, eine persistierte Designeinstellungsdatei oder MESH_DASH_THEME_PRESET wählt eine andere Vorlage aus.

Zugehörige Umgebungsvariablen:

• MESH_DASH_THEME_PRESETS
• MESH_DASH_THEME_PRESET
• MESH_DASH_THEME_SETTINGS_FILE

Sicherheit

• Dieses Dashboard ist für vertrauenswürdige LAN/VPN-Umgebungen vorgesehen.
• Setze es nicht direkt dem öffentlichen Internet aus, ohne einen Reverse-Proxy und Zugriffskontrolle.
• Verwende --private-mode und/oder einen API-Token für strengere Schreibpfadkontrolle.
• Bevorzuge MESH_DASH_API_TOKEN gegenüber --api-token auf gemeinsam genutzten oder Mehrbenutzer-Hosts. Ein Befehlszeilen-Token kann in Prozesslisten sichtbar sein und in der Shell-Historie gespeichert bleiben.
• Die integrierte Join Meshyface-Kanalvorlage verwendet einen absichtlich öffentlich geteilten Meshyface-PSK für die Interoperabilität zwischen Benutzern dieser Software. Verwende diesen öffentlichen Kanal nicht für privaten Datenverkehr.
• --show-secrets legt sensible Werte in rohen JSON-Panels offen; aktiviere es nicht leichtfertig auf gemeinsam genutzten Bildschirmen.
• Raw-Packet-Datenbank-Downloads können Nachrichten- und Telemetrieinhalte offenlegen. Auf gemeinsam genutzten Hosts erfordere einen API-Token und verwende --no-allow-tokenless-raw-packet-download.
• Dateiübertragung kann erhebliche Mesh-Sendezeit verbrauchen. Lasse sie deaktiviert, es sei denn, du hast diesen Kompromiss ausdrücklich akzeptiert.

Tests und Abdeckung

Führe die normale Testsuite aus:

python -m pytest

Führe Ruff genauso aus wie CI:

scripts/run_ruff_local.sh

Führe den Advisory-App-Coverage-Bericht aus:

python -m pytest \
  --cov=meshdash \
  --cov=mesh_dashboard \
  --cov=mesh_connection \
  --cov-report=term

Führe das lokale Coverage-Gate mit dem strengeren Minimum von 85 % aus:

scripts/run_coverage_local.sh

Führe vor PRs den lokalen GUI-Reaktivitäts-Benchmark aus:

scripts/run_gui_responsiveness_local.sh

Coverage schließt das portierte Zork-Engine-Paket absichtlich von der Bewertung aus, aber eigenständige Zork- und Routing-Tests laufen weiter. GitHub Actions veröffentlicht denselben Coverage-Bericht als Advisory-PR-Kommentar und Artefakt. CI schlägt unter 80 % fehl. Das lokale Gate liegt 5 Prozentpunkte über dem CI-Wert.