Meshyface

Meshyface es un panel de control de Meshtastic centrado en el chat que se ejecuta como un único servicio Python y sirve una interfaz web de una sola página a través de HTTP.

Superficie actual de la aplicación

La interfaz actual ofrece:

• Chat y conversaciones directas entre pares
• Espacio de trabajo de red para mapa, resumen, enlaces, rutas, sensores, rankings Top 10, detalles de nodo e historial bajo demanda
• Espacio de trabajo de consola para la salida en vivo de paquetes/registros
• Espacio de trabajo de aplicaciones con Juegos y una pestaña de Archivos cuando la transferencia de archivos está habilitada
• Espacio de trabajo de configuración con paneles de radio, dispositivo, conectividad, ubicación, canales, tickers, listas, apariencia y acerca de
• Historial respaldado por SQLite, búsqueda, rollups, persistencia de temas y persistencia de reglas de telemetría personalizadas

Espacio de trabajo de consola

El espacio de trabajo de consola es una superficie de control estilo terminal para el tráfico de paquetes, la búsqueda en el historial y los comandos de utilidad de la malla.

• Escribe un nombre de comando para abrir sugerencias de autocompletado. Usa Tab o Enter para aceptar, ArrowRight para aceptar el sufijo fantasma, y ArrowUp / ArrowDown para moverte por la ventana emergente.
• Los comandos que requieren un nodo de destino muestran sugerencias enriquecidas con nombre, ID, emoji, etiqueta, estado, saltos, GPS, estado de última escucha, puertos y número de nodo. El texto normal filtra por nombres y etiquetas de nodo; ! filtra por ID de nodo.
• live transmite el tráfico de paquetes hasta Ctrl+C o q. Usa live grep <text>, live rg <text>, live filter=<text> o simplemente live <text> para transmitir solo los grupos de paquetes en vivo que coincidan. Los filtros de capa y verbosidad siguen aplicándose, por ejemplo live rg TEXT_MESSAGE_APP -vv --layer=2.
• grep <text> y rg <text> buscan en el historial retenido de paquetes/chat con ventanas de contexto, límites, filtros de origen de paquetes/chat y filtros de alcance de resumen/paquetes.
• /search <text> filtra la salida visible de la consola desde el indicador sin iniciar una búsqueda en el historial retenido.

Capturas de pantalla

Mapa de red en vivo

Vista de mapa con ubicaciones de nodos, enlaces, rutas comunes, clústeres y mapa de calor de señal.

Resumen de red

Vista de historial para recuentos de nodos, estado en línea, nuevos nodos e informes de posición.

Topología de enlaces

Vista de topología que muestra los enlaces observados desde el nodo raíz seleccionado.

Trazado de ruta

Vista de trazado para un origen, un destino, enlaces cercanos y detalles de paquetes por salto.

Historial de sensores

Gráfico de telemetría que compara el historial de sensores entre varios nodos.

Tarjetas de estado

Tarjetas superiores para la actividad de radio, los recuentos de nodos, los paquetes, los enlaces, la batería y el uso de canales.

Personalización de temas

Los temas pueden reformar todo el panel con colores personalizados, degradados, transparencia, desenfoque, fuentes, partículas o un fondo de mapa en vivo. Estas paletas de ejemplo son temas personalizados; selecciona cualquier vista previa para abrir su captura de pantalla en resolución completa.

Signal Green	Neon Magenta	Aurora Relay

Apariencias de nodo compartidas

Los nodos de Meshyface pueden compartir paquetes de apariencia compactos que contienen una receta de tema de nodo y un fantasma o marca de agua opcional. Configura y previsualiza tu nodo en Settings > Appearance > Node Appearance, habilita Share node appearance, y luego usa Broadcast appearance para publicarlo.

• Los paquetes de apariencia usan el canal de envío de Perfiles configurado y heredan el ajuste de límite de saltos de la radio; Meshyface no impone un límite de saltos separado.
• Las apariencias recibidas pueden estilizar las identidades de nodo en el chat, las listas, los detalles de nodo, los mapas, las gráficas, los sensores y los tickers sin reemplazar el tema propio del panel receptor.
• Desactivar Share node appearance deshabilita ambos lados de la función. Detiene las transmisiones y evita la ruta de recepción de perfiles antes de que las cargas útiles de apariencia entrantes se decodifiquen, se almacenen en caché o se persistan; las apariencias compartidas en caché se borran y no se renderiza ninguna apariencia recibida.
• Cuando el historial está habilitado, los perfiles recibidos y la preferencia de uso compartido local se conservan en la base de datos SQLite del historial.
• Las apariencias compartidas son metadatos cosméticos. Una apariencia recibida no cambia los ajustes de radio, los canales ni el tema de paquete guardado del panel.

Arquitectura 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

Instalación

Comienza con prerrequisitos y dependencias, y luego elige una ruta de instalación:

• Ejecución manual en primer plano: clona en cualquier lugar y ejecuta el panel directamente.
• Servicio systemd recomendado: clona en /opt/meshyface para un host persistente actualizable desde GitHub.
• Docker: ejecuta el mismo punto de entrada de la aplicación en un contenedor con /data montado para el estado persistente.
• Implementación push desde estación de trabajo: copia un checkout local a un destino a través de SSH.
• Topología de ejecución Proxmox: elige la ubicación de la radio TCP o USB para una instalación en VM/LXC.
• Paquetes de mapas sin conexión: añade datos de mapas locales detallados para paneles aislados o con baja conectividad.

Datos y almacenamiento

Base de datos de historial compartida

--history-db es el nombre final del archivo SQLite en disco. El panel ya no añade un sufijo de radio conectada, por lo que cualquier radio conectada al panel contribuye al mismo historial persistido de paquetes, chat, nodos y rollups.

Modos de historial

• El modo predeterminado persiste en SQLite el chat, los paquetes, los eventos de conexión, los análisis de nodos, los registros de texto malformado, las métricas de entorno y los rollups de resumen.
• --no-history deshabilita el almacenamiento persistente y conserva solo los búferes en memoria en vivo.
• Los rollups de resumen también se muestrean en segundo plano mientras el panel está en ejecución cuando el historial está habilitado.

Tema y ajustes locales

• La selección de tema preestablecido se persiste en mesh_dashboard_theme_settings.json de forma predeterminada, o en el archivo proporcionado mediante --theme-settings-file.
• Las reglas de telemetría personalizadas se almacenan en la base de datos SQLite del historial.

Comandos de mantenimiento

Los comandos operativos que inspeccionan o reparan los datos locales del panel están documentados en docs/maintenance.md.

Semántica de la vista de enlaces

La subvista Links es una vista de topología, no una reproducción de ruta de paquetes.

• El modo History se basa en el historial de enlaces almacenado en SQLite.
• El modo Live se basa únicamente en las observaciones de enlaces de la sesión actual.
• Los anillos numerados muestran la distancia de grafo más corta desde la raíz actual mediante una búsqueda en anchura sobre el grafo de enlaces observado.
• Esos números de anillo no son saltos de reenvío Meshtastic literales ni un rastreo de paquetes en tiempo real.
• Los metadatos de saltos de paquetes, cuando están disponibles, se muestran por separado en los detalles de nodo o arista como valores de saltos de paquetes.

La raíz actual es el nodo alrededor del cual se centra el grafo. Seleccionar un nodo distinto cambia la raíz y vuelve a calcular los anillos de distancia numerados desde ese nodo.

Referencia de configuración

Conexión y transporte

• --mesh-host <ip-or-dns>: host de radio TCP
• --mesh-tcp-port <port>: puerto de radio TCP, predeterminado 4403
• --mesh-port <path>: ruta del dispositivo serie
• --default-gateway-host <host>: host TCP de respaldo si no se proporciona --mesh-host y el serie sigue en la ruta predeterminada
• --default-gateway-port <port>: puerto TCP de respaldo para --default-gateway-host
• --no-default-gateway: fuerza el serie a menos que --mesh-host se establezca explícitamente

Variables de entorno relacionadas:

• MESH_GATEWAY_HOST
• MESH_GATEWAY_PORT
• MESH_DASH_MESH_PORT para la ruta serie predeterminada

HTTP, interfaz y seguridad

• --http-host <host>: host de enlace, predeterminado 0.0.0.0
• --http-port <port>: puerto de enlace, predeterminado 8877
• --refresh-ms <ms>: intervalo de sondeo del navegador, predeterminado 3000
• --packet-limit <n>: tamaño del búfer de paquetes en vivo recientes, predeterminado 250
• --reset-ticker-scale-on-restart / --no-reset-ticker-scale-on-restart
• --show-secrets: revela claves/contraseñas/PSK privadas en los paneles JSON sin procesar
• --debug-mode / --no-debug-mode: expone superficies del panel solo de depuración, como los diagnósticos de red avanzados

Variables de entorno relacionadas:

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

La identidad en tiempo de ejecución proviene del commit de git de 12 caracteres, seguido de un número de pull request opcional, por ejemplo abc123456789 · PR #43. El panel de Software muestra esta única revisión en lugar de una versión de paquete. Los asuntos de commits de fusión/squash de GitHub se detectan automáticamente; las implementaciones de vista previa sin fusionar pueden establecer MESH_DASH_PR_NUMBER explícitamente.

/api/revision es el endpoint canónico de identidad. Sus campos revision y build_ref informan la revisión en tiempo de ejecución, mientras que commit y pr_number permanecen disponibles como campos estructurados. /api/version permanece como endpoint heredado, y su campo version conserva los metadatos de versión/paquete. MESH_DASH_VERSION está igualmente reservado para el empaquetado explícito de versiones y no se muestra en el panel.

Transferencia de archivos

• --file-transfer-enable: habilita la aplicación Archivos; requiere --accept-file-transfer-traffic-disclaimer
• --file-transfer-auto-accept: acepta transferencias entrantes directas sin confirmación del navegador
• --file-transfer-max-bytes <bytes>: límite por archivo, predeterminado 65536 y limitado a 1024-524288

Las transferencias usan el protocolo beta MF_FILE_V2 en el puerto privado 258 y no son compatibles con el transporte anterior de mensajes de texto. Cuando un destino tiene un recuento de saltos detectado utilizable, Meshyface usa ese recuento más uno, limitado por el límite de saltos de radio configurado. Los datos de saltos con más de una hora de antigüedad recurren al límite configurado. La aplicación Archivos muestra el límite seleccionado y su origen.

Variables de entorno relacionadas:

• MESH_DASH_FILE_TRANSFER_ENABLE
• MESH_DASH_FILE_TRANSFER_AUTO_ACCEPT
• MESH_DASH_FILE_TRANSFER_MAX_BYTES
• MESH_DASH_ACCEPT_FILE_TRANSFER_TRAFFIC_DISCLAIMER

Historial y analíticas

• --history-db <path>: ruta base de la base de datos SQLite
• --history-max-rows <n>: predeterminado 200000
• --history-retention-days <days>: predeterminado 30, usa 0 para deshabilitar la poda por antigüedad
• --history-event-max-rows <n>: tope de solo agregación de eventos de paquetes, predeterminado 200000
• --history-event-retention-days <days>: predeterminado 30
• --history-rollup-retention-days <days>: predeterminado 365
• --no-history: modo solo memoria

Variables de entorno relacionadas:

• MESH_DASH_HISTORY_DB

Temas

• --theme-presets <json>: archivo opcional de preestablecidos de temas personalizados
• --theme-preset <name>: nombre del preestablecido seleccionado
• --theme-settings-file <json>: archivo persistido de selección de tema en tiempo de ejecución

Preestablecidos integrados:

• default (azul Meshyface seguro, partículas deshabilitadas)
• custom (tema de exhibición con partículas y efectos de fondo habilitados)

Las instalaciones nuevas usan default como predeterminado, a menos que un archivo persistido de ajustes de tema o MESH_DASH_THEME_PRESET seleccione otro preestablecido.

Variables de entorno relacionadas:

• MESH_DASH_THEME_PRESETS
• MESH_DASH_THEME_PRESET
• MESH_DASH_THEME_SETTINGS_FILE

Seguridad

• Este panel está pensado para entornos LAN/VPN de confianza.
• No lo expongas directamente a la internet pública sin un proxy inverso y control de acceso.
• Usa --private-mode y/o un token de API para un control más estricto de la ruta de escritura.
• Prefiere MESH_DASH_API_TOKEN sobre --api-token en hosts compartidos o multiusuario. Un token de línea de comandos puede ser visible en los listados de procesos y conservarse en el historial del shell.
• El preestablecido de canal Join Meshyface integrado usa una PSK Meshyface compartida intencionadamente pública para la interoperabilidad entre usuarios de este software. No uses ese canal público para tráfico privado.
• --show-secrets expone valores sensibles en los paneles JSON sin procesar; no lo habilites sin cuidado en pantallas compartidas.
• Las descargas de la base de datos de paquetes sin procesar pueden exponer el contenido de mensajes y telemetría. En hosts compartidos, exige un token de API y usa --no-allow-tokenless-raw-packet-download.
• La transferencia de archivos puede consumir una cantidad significativa de tiempo de transmisión de la malla. Mantenla deshabilitada a menos que hayas aceptado explícitamente esa compensación.

Pruebas y cobertura

Ejecuta el conjunto de pruebas normal:

python -m pytest

Ejecuta Ruff de la misma manera que lo hace CI:

scripts/run_ruff_local.sh

Ejecuta el informe de cobertura informativo de la aplicación:

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

Ejecuta el umbral de cobertura local con el mínimo más estricto del 85%:

scripts/run_coverage_local.sh

Ejecuta el punto de referencia local de capacidad de respuesta de la GUI antes de los PR:

scripts/run_gui_responsiveness_local.sh

La cobertura excluye intencionadamente el paquete del motor Zork portado del cálculo, pero las pruebas de Zork independiente y de enrutamiento siguen ejecutándose. GitHub Actions publica el mismo informe de cobertura como comentario y artefacto informativos del PR. CI falla por debajo del 80%. El umbral local se mantiene 5 puntos porcentuales por encima de CI.