Meshyface

Meshyface è una dashboard Meshtastic incentrata sulla chat che gira come un singolo servizio Python e serve un'interfaccia web a pagina singola su HTTP.

Superficie attuale dell'app

L'interfaccia attuale espone:

• Chat e conversazioni dirette con i peer
• Workspace Network per mappa, panoramica, collegamenti, rotte, sensori, classifiche Top 10, dettagli dei nodi e cronologia on-demand
• Workspace Console per output live di pacchetti/log
• Workspace Apps con Giochi e una scheda File quando il trasferimento file è abilitato
• Workspace Impostazioni con riquadri per radio, dispositivo, connettività, posizione, canali, ticker, elenchi, aspetto e informazioni
• Cronologia basata su SQLite, ricerca, riepiloghi, persistenza del tema e persistenza di regole di telemetria personalizzate

Workspace Console

Il Workspace Console è una superficie di controllo in stile terminale per il traffico dei pacchetti, la ricerca nella cronologia e i comandi di utilità della mesh.

• Digita un nome di comando per aprire i suggerimenti di autocompletamento. Usa Tab o Enter per accettare, ArrowRight per accettare il suffisso fantasma e ArrowUp / ArrowDown per spostarti nel popup.
• I comandi che accettano un nodo come destinazione mostrano suggerimenti ricchi con nome, ID, emoji, tag, stato, hop, GPS, ultimo ascolto, porte e numero del nodo. Il testo normale restringe per nomi e tag dei nodi; ! restringe per ID del nodo.
• live trasmette il traffico dei pacchetti fino a Ctrl+C o q. Usa live grep <text>, live rg <text>, live filter=<text> o il semplice live <text> per trasmettere solo i gruppi di pacchetti live corrispondenti. I filtri di livello e verbosità vengono comunque applicati, ad esempio live rg TEXT_MESSAGE_APP -vv --layer=2.
• grep <text> e rg <text> cercano nella cronologia persistente di pacchetti/chat con finestre di contesto, limiti, filtri sulla fonte di pacchetti/chat e filtri di ambito riepilogo/pacchetto.
• /search <text> filtra l'output visibile della console dal prompt senza avviare una ricerca nella cronologia persistente.

Screenshot

Mappa di rete live

Vista mappa con posizioni dei nodi, collegamenti, percorsi comuni, cluster e mappa di calore del segnale.

Panoramica della rete

Vista cronologia per conteggio dei nodi, stato online, nuovi nodi e rapporti di posizione.

Topologia dei collegamenti

Vista topologia che mostra i collegamenti osservati dal nodo radice selezionato.

Tracciamento delle rotte

Vista tracciamento per una sorgente, una destinazione, i collegamenti vicini e i dettagli dei pacchetti hop-per-hop.

Cronologia dei sensori

Grafico di telemetria che confronta la cronologia dei sensori su più nodi.

Schede di stato

Schede principali per attività radio, conteggio dei nodi, pacchetti, collegamenti, batteria e uso dei canali.

Personalizzazione del tema

I temi possono rimodellare l'intera dashboard con colori personalizzati, gradienti, trasparenza, sfocatura, font, particelle o uno sfondo a mappa live. Queste palette di esempio sono temi personalizzati; seleziona una qualsiasi anteprima per aprire lo screenshot a piena risoluzione.

Signal Green	Neon Magenta	Aurora Relay

Aspetti condivisi dei nodi

I nodi Meshyface possono condividere pacchetti di aspetto compatti contenenti una ricetta per il tema del nodo e un eventuale ghost o filigrana. Configura e visualizza in anteprima il tuo nodo in Settings > Appearance > Node Appearance, abilita Condividi aspetto del nodo, quindi usa Trasmetti aspetto per pubblicarlo.

• I pacchetti di aspetto usano il canale di invio dei Profili configurato ed ereditano l'impostazione del limite di hop della radio; Meshyface non impone un limite di hop separato.
• Gli aspetti ricevuti possono stilizzare le identità dei nodi in chat, elenchi, dettagli dei nodi, mappe, grafici, sensori e ticker senza sostituire il tema della dashboard ricevente.
• Disattivare Condividi aspetto del nodo disabilita entrambi i lati della funzionalità. Interrompe le trasmissioni e bypassa il percorso di ricezione dei profili prima che i payload di aspetto in arrivo vengano decodificati, memorizzati nella cache o resi persistenti; gli aspetti condivisi in cache vengono cancellati e nessun aspetto ricevuto viene renderizzato.
• Quando la cronologia è abilitata, i profili ricevuti e la preferenza di condivisione locale persistono nel database SQLite della cronologia.
• Gli aspetti condivisi sono metadati cosmetici. Un aspetto ricevuto non modifica le impostazioni radio, i canali o il tema del pacchetto salvato della dashboard.

Architettura del sistema

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

Installazione

Inizia con prerequisiti e dipendenze, poi scegli un percorso di installazione:

• Esecuzione manuale in primo piano: clona ovunque ed esegui direttamente la dashboard.
• Servizio systemd consigliato: clona in /opt/meshyface per un host persistente aggiornabile via GitHub.
• Docker: esegui lo stesso entrypoint dell'app in un contenitore con /data montato per lo stato persistente.
• Distribuzione push da workstation: copia un checkout locale su una destinazione via SSH.
• Topologia di runtime Proxmox: scegli il posizionamento della radio TCP o USB per un'installazione VM/LXC.
• Pacchetti di mappe offline: aggiungi dati cartografici locali dettagliati per dashboard air-gapped o a bassa connettività.

Dati e archiviazione

Database di cronologia condiviso

--history-db è il nome del file SQLite finale su disco. La dashboard non aggiunge più un suffisso per la radio collegata, quindi qualsiasi radio collegata alla dashboard contribuisce alla stessa cronologia persistente di pacchetti, chat, nodi e riepiloghi.

Modalità di cronologia

• La modalità predefinita rende persistenti in SQLite chat, pacchetti, eventi di connessione, analisi dei nodi, record di testo malformato, metriche ambientali e riepiloghi.
• --no-history disabilita l'archivio persistente e mantiene solo i buffer in memoria live.
• I riepiloghi vengono anche campionati in background mentre la dashboard è in esecuzione, quando la cronologia è abilitata.

Tema e impostazioni locali

• La selezione del preset del tema viene resa persistente in mesh_dashboard_theme_settings.json per impostazione predefinita, o nel file fornito tramite --theme-settings-file.
• Le regole di telemetria personalizzate vengono archiviate nel database SQLite della cronologia.

Comandi di manutenzione

I comandi operativi che ispezionano o riparano i dati locali della dashboard sono documentati in docs/maintenance.md.

Semantica della vista Collegamenti

La sottovista Links è una vista di topologia, non una riproduzione del percorso dei pacchetti.

• La modalità History attinge dalla cronologia dei collegamenti salvata in SQLite.
• La modalità Live attinge solo dalle osservazioni dei collegamenti della sessione corrente.
• Gli anelli numerati mostrano la distanza minima nel grafo dalla radice corrente usando una ricerca in ampiezza sul grafo dei collegamenti osservati.
• Quei numeri di anello non sono hop di inoltro Meshtastic letterali e non sono una traccia dei pacchetti in tempo reale.
• I metadati hop-per-pacchetto, quando disponibili, vengono comunque mostrati separatamente nei dettagli di nodo o arco come valori di hop del pacchetto.

La radice corrente è il nodo attorno al quale è centrato il grafo. Selezionare un nodo diverso cambia la radice e ricalcola gli anelli di distanza numerati a partire da quel nodo.

Riferimento di configurazione

Connessione e trasporto

• --mesh-host <ip-or-dns>: host TCP della radio
• --mesh-tcp-port <port>: porta TCP della radio, predefinita 4403
• --mesh-port <path>: percorso del dispositivo seriale
• --default-gateway-host <host>: host TCP di fallback se --mesh-host non viene fornito e la seriale si trova ancora sul percorso predefinito
• --default-gateway-port <port>: porta TCP di fallback per --default-gateway-host
• --no-default-gateway: forza l'uso della seriale a meno che --mesh-host non venga impostato esplicitamente

Variabili d'ambiente correlate:

• MESH_GATEWAY_HOST
• MESH_GATEWAY_PORT
• MESH_DASH_MESH_PORT per il percorso seriale predefinito

HTTP, interfaccia e sicurezza

• --http-host <host>: host di bind, predefinito 0.0.0.0
• --http-port <port>: porta di bind, predefinita 8877
• --refresh-ms <ms>: intervallo di polling del browser, predefinito 3000
• --packet-limit <n>: dimensione del buffer dei pacchetti live recenti, predefinita 250
• --reset-ticker-scale-on-restart / --no-reset-ticker-scale-on-restart
• --show-secrets: rivela chiavi private/password/PSK nei pannelli JSON grezzi
• --debug-mode / --no-debug-mode: espone superfici della dashboard esclusive del debug, come la diagnostica di rete avanzata

Variabili d'ambiente correlate:

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

L'identità di runtime deriva dal commit git di 12 caratteri, seguito da un numero opzionale di pull request, ad esempio abc123456789 · PR #43. Il pannello Software mostra questa singola revisione invece di una versione di pacchetto. I soggetti dei commit di merge/squash su GitHub vengono rilevati automaticamente; le distribuzioni di anteprima non unite possono impostare MESH_DASH_PR_NUMBER esplicitamente.

/api/revision è l'endpoint di identità canonico. I suoi campi revision e build_ref riportano la revisione di runtime, mentre commit e pr_number restano disponibili come campi strutturati. /api/version rimane come endpoint legacy e il suo campo version conserva i metadati di release/pacchetto. MESH_DASH_VERSION è allo stesso modo riservata al packaging di release esplicito e non viene mostrata nella dashboard.

Trasferimento file

• --file-transfer-enable: abilita l'app File; richiede --accept-file-transfer-traffic-disclaimer
• --file-transfer-auto-accept: accetta i trasferimenti in entrata diretti senza conferma nel browser
• --file-transfer-max-bytes <bytes>: limite per file, predefinito 65536 e limitato a 1024-524288

I trasferimenti usano il protocollo beta MF_FILE_V2 sulla porta privata 258 e non sono compatibili con il precedente trasporto a messaggi di testo. Quando una destinazione ha un conteggio di hop rilevato e utilizzabile, Meshyface usa quel conteggio più uno, limitato dal limite di hop radio configurato. I dati di hop più vecchi di un'ora ricadono sul limite configurato. L'app File mostra il limite selezionato e la sua origine.

Variabili d'ambiente correlate:

• MESH_DASH_FILE_TRANSFER_ENABLE
• MESH_DASH_FILE_TRANSFER_AUTO_ACCEPT
• MESH_DASH_FILE_TRANSFER_MAX_BYTES
• MESH_DASH_ACCEPT_FILE_TRANSFER_TRAFFIC_DISCLAIMER

Cronologia e analisi

• --history-db <path>: percorso base del DB SQLite
• --history-max-rows <n>: predefinito 200000
• --history-retention-days <days>: predefinito 30, usa 0 per disabilitare la potatura per età
• --history-event-max-rows <n>: limite massimo degli eventi di pacchetto append-only, predefinito 200000
• --history-event-retention-days <days>: predefinito 30
• --history-rollup-retention-days <days>: predefinito 365
• --no-history: modalità solo memoria

Variabili d'ambiente correlate:

• MESH_DASH_HISTORY_DB

Temi

• --theme-presets <json>: file opzionale di preset di temi personalizzati
• --theme-preset <name>: nome del preset selezionato
• --theme-settings-file <json>: file persistente di selezione del tema a runtime

Preset integrati:

• default (blu Meshyface sicuro, particelle disabilitate)
• custom (tema dimostrativo con particelle ed effetti di sfondo abilitati)

Le nuove installazioni usano default a meno che un file persistente di impostazioni del tema o MESH_DASH_THEME_PRESET selezioni un altro preset.

Variabili d'ambiente correlate:

• MESH_DASH_THEME_PRESETS
• MESH_DASH_THEME_PRESET
• MESH_DASH_THEME_SETTINGS_FILE

Sicurezza

• Questa dashboard è pensata per ambienti LAN/VPN fidati.
• Non esporla direttamente a internet pubblico senza un reverse proxy e un controllo degli accessi.
• Usa --private-mode e/o un token API per un controllo più rigoroso del percorso di scrittura.
• Preferisci MESH_DASH_API_TOKEN rispetto a --api-token su host condivisi o multiutente. Un token passato da riga di comando può essere visibile negli elenchi dei processi e conservato nella cronologia della shell.
• Il preset di canale integrato Join Meshyface usa un PSK Meshyface condiviso intenzionalmente pubblico per l'interoperabilità tra gli utenti di questo software. Non usare quel canale pubblico per traffico privato.
• --show-secrets espone valori sensibili nei pannelli JSON grezzi; non abilitarlo con leggerezza su display condivisi.
• I download grezzi del database dei pacchetti possono esporre contenuti di messaggi e telemetria. Su host condivisi, richiedi un token API e usa --no-allow-tokenless-raw-packet-download.
• Il trasferimento file può consumare una quantità significativa di tempo radio della mesh. Tienilo disabilitato a meno che tu non abbia accettato esplicitamente questo compromesso.

Test e copertura

Esegui la suite di test normale:

python -m pytest

Esegui Ruff come fa la CI:

scripts/run_ruff_local.sh

Esegui il report di copertura dell'app:

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

Esegui la soglia di copertura locale con il minimo più severo dell'85%:

scripts/run_coverage_local.sh

Esegui il benchmark locale di reattività della GUI prima delle PR:

scripts/run_gui_responsiveness_local.sh

La copertura esclude intenzionalmente il pacchetto del motore Zork portato dallo scoring, ma i test autonomi di Zork e di routing vengono comunque eseguiti. GitHub Actions pubblica lo stesso report di copertura come commento consultivo di PR e artefatto. La CI fallisce sotto l'80%. La soglia locale resta 5 punti percentuali più alta della CI.