Meshyface

Meshyface est un tableau de bord Meshtastic centré sur le chat qui s'exécute comme un service Python unique et sert une interface web monopage via HTTP.

Surface applicative actuelle

L'interface actuelle expose :

• Chat ainsi que les conversations directes entre pairs
• Espace de travail Réseau pour la carte, l'aperçu, les liens, les itinéraires, les capteurs, les classements Top 10, les détails des nœuds et l'historique à la demande
• Espace de travail Console pour la sortie en direct des paquets/journaux
• Espace de travail Applications avec un onglet Jeux et un onglet Fichiers lorsque le transfert de fichiers est activé
• Espace de travail Paramètres avec les volets radio, appareil, connectivité, localisation, canaux, tickers, listes, apparence et à propos
• Historique, recherche, résumés, persistance du thème et persistance des règles de télémétrie personnalisées reposant sur SQLite

Espace de travail Console

L'espace de travail Console est une surface de contrôle de style terminal pour le trafic de paquets, la recherche dans l'historique et les commandes utilitaires mesh.

• Saisissez un nom de commande pour ouvrir les suggestions de saisie semi-automatique. Utilisez Tab ou Enter pour accepter, ArrowRight pour accepter le suffixe fantôme, et ArrowUp / ArrowDown pour parcourir la fenêtre contextuelle.
• Les commandes qui prennent une cible de nœud affichent des suggestions de nœuds riches avec nom, ID, emoji, tag, statut, sauts, GPS, état du dernier contact, ports et numéro de nœud. Le texte normal filtre par noms et tags de nœuds ; ! filtre par ID de nœud.
• live diffuse le trafic de paquets jusqu'à Ctrl+C ou q. Utilisez live grep <text>, live rg <text>, live filter=<text>, ou simplement live <text> pour diffuser uniquement les groupes de paquets en direct correspondants. Les filtres de couche et de verbosité s'appliquent toujours, par exemple live rg TEXT_MESSAGE_APP -vv --layer=2.
• grep <text> et rg <text> recherchent dans l'historique conservé des paquets/messages avec fenêtres de contexte, limites, filtres de source paquets/messages et filtres de portée résumé/paquets.
• /search <text> filtre la sortie console visible à partir de l'invite sans lancer de recherche dans l'historique conservé.

Captures d'écran

Carte réseau en direct

Vue cartographique avec emplacements des nœuds, liens, chemins courants, clusters et carte de chaleur du signal.

Aperçu du réseau

Vue historique pour les nombres de nœuds, le statut en ligne, les nouveaux nœuds et les rapports de position.

Topologie des liens

Vue topologique montrant les liens observés depuis le nœud racine sélectionné.

Trace d'itinéraire

Vue de trace pour une source, une destination, les liens voisins et les détails de paquets par saut.

Historique des capteurs

Graphique de télémétrie comparant l'historique des capteurs sur plusieurs nœuds.

Cartes de statut

Cartes supérieures pour l'activité radio, les nombres de nœuds, les paquets, les liens, la batterie et l'utilisation des canaux.

Personnalisation des thèmes

Les thèmes peuvent redessiner l'ensemble du tableau de bord avec des couleurs personnalisées, des dégradés, de la transparence, du flou, des polices, des particules ou un arrière-plan de carte en direct. Ces palettes d'exemple sont des thèmes personnalisés ; sélectionnez n'importe quel aperçu pour ouvrir sa capture d'écran en pleine résolution.

Signal Green	Neon Magenta	Aurora Relay

Apparences de nœuds partagées

Les nœuds Meshyface peuvent partager des paquets d'apparence compacts contenant une recette de thème de nœud et un fantôme ou filigrane facultatif. Configurez et prévisualisez votre nœud dans Settings > Appearance > Node Appearance, activez Share node appearance, puis utilisez Broadcast appearance pour le publier.

• Les paquets d'apparence utilisent le canal d'envoi des profils configuré et héritent du réglage de limite de sauts de la radio ; Meshyface n'impose pas de limite de sauts distincte.
• Les apparences reçues peuvent styliser les identités des nœuds dans le chat, les listes, les détails des nœuds, les cartes, les graphiques, les capteurs et les tickers sans remplacer le thème propre du tableau de bord récepteur.
• Désactiver Share node appearance désactive les deux volets de la fonctionnalité. Cela arrête les diffusions et contourne le chemin de réception des profils avant que les charges utiles d'apparence entrantes ne soient décodées, mises en cache ou persistées ; les apparences partagées en cache sont effacées et aucune apparence reçue n'est rendue.
• Lorsque l'historique est activé, les profils reçus et la préférence de partage locale sont persistés dans la base de données SQLite d'historique.
• Les apparences partagées sont des métadonnées cosmétiques. Une apparence reçue ne modifie pas les réglages radio, les canaux ni le thème de package enregistré du tableau de bord.

Architecture système

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

Commencez par les prérequis et dépendances, puis choisissez l'une des méthodes d'installation :

• Exécution manuelle au premier plan : clonez où vous voulez et exécutez le tableau de bord directement.
• Service systemd recommandé : clonez dans /opt/meshyface pour un hôte persistant mise à jour via GitHub.
• Docker : exécutez le même point d'entrée d'application dans un conteneur avec /data monté pour un état persistant.
• Déploiement par push depuis une station de travail : copiez une copie locale vers une cible via SSH.
• Topologie d'exécution Proxmox : choisissez le placement radio TCP ou USB pour une installation VM/LXC.
• Packs de cartes hors ligne : ajoutez des données cartographiques locales détaillées pour les tableaux de bord en environnement isolé ou à faible connectivité.

Données et stockage

Base de données d'historique partagée

--history-db est le nom de fichier SQLite final sur disque. Le tableau de bord n'ajoute plus de suffixe de radio connectée, donc toute radio branchée au tableau de bord contribue au même historique persistant de paquets, messages, nœuds et résumés.

Modes d'historique

• Le mode par défaut persiste les messages, paquets, événements de connexion, analyses de nœuds, enregistrements de texte malformé, métriques d'environnement et résumés consolidés dans SQLite.
• --no-history désactive le stockage persistant et ne conserve que les tampons mémoire en direct.
• Les résumés consolidés sont également échantillonnés en arrière-plan pendant que le tableau de bord est en cours d'exécution lorsque l'historique est activé.

Thème et paramètres locaux

• La sélection du préréglage de thème est persistée dans mesh_dashboard_theme_settings.json par défaut, ou dans le fichier fourni via --theme-settings-file.
• Les règles de télémétrie personnalisées sont stockées dans la base de données SQLite d'historique.

Commandes de maintenance

Les commandes opérationnelles qui inspectent ou réparent les données locales du tableau de bord sont documentées dans docs/maintenance.md.

Sémantique de la vue Liens

La sous-vue Links est une vue topologique, pas une relecture d'itinéraires de paquets.

• Le mode History s'appuie sur l'historique des liens stocké dans SQLite.
• Le mode Live s'appuie uniquement sur les observations de liens de la session en cours.
• Les anneaux numérotés montrent la distance de graphe la plus courte depuis la racine actuelle à l'aide d'une recherche en largeur sur le graphe de liens observé.
• Ces numéros d'anneaux ne sont pas des sauts de transfert Meshtastic réels et ne constituent pas une trace de paquets en temps réel.
• Les métadonnées de sauts de paquets, lorsqu'elles sont disponibles, sont toujours affichées séparément dans les détails des nœuds ou des arêtes comme valeurs de sauts de paquets.

La racine actuelle est le nœud autour duquel le graphe est centré. La sélection d'un autre nœud change la racine et recalcule les anneaux de distance numérotés à partir de ce nœud.

Référence de configuration

Connexion et transport

• --mesh-host <ip-or-dns> : hôte radio TCP
• --mesh-tcp-port <port> : port radio TCP, défaut 4403
• --mesh-port <path> : chemin du périphérique série
• --default-gateway-host <host> : hôte TCP de secours si --mesh-host n'est pas fourni et si le port série reste sur le chemin par défaut
• --default-gateway-port <port> : port TCP de secours pour --default-gateway-host
• --no-default-gateway : force le mode série, sauf si --mesh-host est explicitement défini

Variables d'environnement associées :

• MESH_GATEWAY_HOST
• MESH_GATEWAY_PORT
• MESH_DASH_MESH_PORT pour le chemin série par défaut

HTTP, interface et sécurité

• --http-host <host> : hôte de liaison, défaut 0.0.0.0
• --http-port <port> : port de liaison, défaut 8877
• --refresh-ms <ms> : intervalle d'interrogation du navigateur, défaut 3000
• --packet-limit <n> : taille du tampon des paquets en direct récents, défaut 250
• --reset-ticker-scale-on-restart / --no-reset-ticker-scale-on-restart
• --show-secrets : révéler les clés privées/mots de passe/PSK dans les panneaux JSON bruts
• --debug-mode / --no-debug-mode : exposer les surfaces du tableau de bord réservées au débogage, comme les diagnostics réseau avancés

Variables d'environnement associées :

• 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é d'exécution provient du commit git de 12 caractères, suivi éventuellement d'un numéro de pull request, par exemple abc123456789 · PR #43. Le panneau Software affiche cette révision unique au lieu d'une version de package. Les sujets de commits GitHub de merge/squash sont détectés automatiquement ; les déploiements d'aperçu non fusionnés peuvent définir MESH_DASH_PR_NUMBER explicitement.

/api/revision est le point de terminaison d'identité canonique. Ses champs revision et build_ref indiquent la révision d'exécution, tandis que commit et pr_number restent disponibles comme champs structurés. /api/version reste un point de terminaison hérité, et son champ version conserve les métadonnées de release/package. MESH_DASH_VERSION est également réservé à l'empaquetage de version explicite et n'est pas affiché dans le tableau de bord.

Transfert de fichiers

• --file-transfer-enable : activer l'application Files ; nécessite --accept-file-transfer-traffic-disclaimer
• --file-transfer-auto-accept : accepter les transferts entrants directs sans confirmation du navigateur
• --file-transfer-max-bytes <bytes> : limite par fichier, défaut 65536 et contrainte à 1024-524288

Les transferts utilisent le protocole bêta MF_FILE_V2 sur le port privé 258 et ne sont pas compatibles avec l'ancien transport par messages texte. Lorsqu'une destination a un nombre de sauts détecté utilisable, Meshyface utilise ce nombre plus un, plafonné par la limite de sauts radio configurée. Les données de sauts datant de plus d'une heure retombent sur la limite configurée. L'application Files affiche la limite sélectionnée et sa source.

Variables d'environnement associées :

• MESH_DASH_FILE_TRANSFER_ENABLE
• MESH_DASH_FILE_TRANSFER_AUTO_ACCEPT
• MESH_DASH_FILE_TRANSFER_MAX_BYTES
• MESH_DASH_ACCEPT_FILE_TRANSFER_TRAFFIC_DISCLAIMER

Historique et analyses

• --history-db <path> : chemin de base de la base SQLite
• --history-max-rows <n> : défaut 200000
• --history-retention-days <days> : défaut 30, utiliser 0 pour désactiver l'élagage par âge
• --history-event-max-rows <n> : plafond des événements de paquets en ajout seul, défaut 200000
• --history-event-retention-days <days> : défaut 30
• --history-rollup-retention-days <days> : défaut 365
• --no-history : mode mémoire seule

Variables d'environnement associées :

• MESH_DASH_HISTORY_DB

Thèmes

• --theme-presets <json> : fichier optionnel de préréglages de thème personnalisés
• --theme-preset <name> : nom du préréglage sélectionné
• --theme-settings-file <json> : fichier persisté de sélection de thème à l'exécution

Préréglages intégrés :

• default (bleu Meshyface sûr, particules désactivées)
• custom (thème de démonstration avec particules et effets d'arrière-plan activés)

Les nouvelles installations utilisent default par défaut, sauf si un fichier de paramètres de thème persisté ou MESH_DASH_THEME_PRESET sélectionne un autre préréglage.

Variables d'environnement associées :

• MESH_DASH_THEME_PRESETS
• MESH_DASH_THEME_PRESET
• MESH_DASH_THEME_SETTINGS_FILE

Sécurité

• Ce tableau de bord est destiné à des environnements LAN/VPN de confiance.
• Ne l'exposez pas directement sur Internet public sans proxy inverse et contrôle d'accès.
• Utilisez --private-mode et/ou un jeton API pour un contrôle plus strict du chemin d'écriture.
• Préférez MESH_DASH_API_TOKEN à --api-token sur les hôtes partagés ou multi-utilisateurs. Un jeton passé en ligne de commande peut être visible dans les listes de processus et conservé dans l'historique du shell.
• Le préréglage de canal intégré Join Meshyface utilise un PSK Meshyface partagé délibérément public pour l'interopérabilité entre les utilisateurs de ce logiciel. N'utilisez pas ce canal public pour du trafic privé.
• --show-secrets expose des valeurs sensibles dans les panneaux JSON bruts ; ne l'activez pas à la légère sur des affichages partagés.
• Les téléchargements de la base de données de paquets bruts peuvent exposer le contenu des messages et de la télémétrie. Sur les hôtes partagés, exigez un jeton API et utilisez --no-allow-tokenless-raw-packet-download.
• Le transfert de fichiers peut consommer un temps d'antenne mesh important. Gardez-le désactivé à moins d'avoir explicitement accepté ce compromis.

Tests et couverture

Exécutez la suite de tests normale :

python -m pytest

Exécutez Ruff de la même manière que la CI :

scripts/run_ruff_local.sh

Exécutez le rapport de couverture consultatif de l'application :

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

Exécutez le contrôle de couverture local avec le minimum plus strict de 85 % :

scripts/run_coverage_local.sh

Exécutez le benchmark local de réactivité de l'interface graphique avant les PR :

scripts/run_gui_responsiveness_local.sh

La couverture exclut intentionnellement le package du moteur Zork porté du calcul, mais les tests Zork autonomes et de routage s'exécutent toujours. GitHub Actions publie le même rapport de couverture sous forme de commentaire et d'artefact consultatifs sur les PR. La CI échoue en dessous de 80 %. Le contrôle local reste 5 points de pourcentage au-dessus de la CI.