Meshyface

Meshyface é um painel (dashboard) focado em chat para Meshtastic que funciona como um único serviço Python e serve uma interface web de página única via HTTP.

Superfície Atual do Aplicativo

A UI atual expõe:

• Chat mais conversas diretas entre pares
• Workspace de rede para mapa, visão geral, links, rotas, sensores, rankings Top 10, detalhes de nós e histórico sob demanda
• Workspace de console para saída ao vivo de pacotes/logs
• Workspace de aplicativos com uma aba Jogos e uma aba Arquivos quando a transferência de arquivos está ativada
• Workspace de configurações com painéis de rádio, dispositivo, conectividade, localização, canais, tickers, listas, aparência e sobre
• Histórico baseado em SQLite, busca, rollups, persistência de tema e persistência de regras de telemetria personalizadas

Workspace de Console

O workspace de console é uma superfície de controle estilo terminal para tráfego de pacotes, busca de histórico e comandos utilitários da malha.

• Digite um nome de comando para abrir sugestões de autocomplete. Use Tab ou Enter para aceitar, ArrowRight para aceitar o sufixo fantasma, e ArrowUp / ArrowDown para navegar no popup.
• Comandos que aceitam um nó alvo mostram sugestões de nós completas com nome, ID, emoji, tag, status, hops, GPS, último estado ouvido, portas e número do nó. Texto normal filtra por nomes e tags de nós; ! filtra por ID do nó.
• live transmite o tráfego de pacotes até Ctrl+C ou q. Use live grep <texto>, live rg <texto>, live filter=<texto>, ou apenas live <texto> para transmitir apenas grupos de pacotes ao vivo correspondentes. Filtros de camada e verbosidade ainda se aplicam, por exemplo live rg TEXT_MESSAGE_APP -vv --layer=2.
• grep <texto> e rg <texto> buscam no histórico retido de pacotes/chat com janelas de contexto, limites, filtros de fonte de pacote/chat e filtros de escopo de resumo/pacote.
• /search <texto> filtra a saída visível do console a partir do prompt sem iniciar uma busca no histórico retido.

Screenshots (Capturas de Tela)

Mapa de rede ao vivo

Visualização do mapa com localizações de nós, links, caminhos comuns, clusters e mapa de calor de sinal.

Visão geral da rede

Visualização do histórico para contagens de nós, status online, novos nós e relatórios de posição.

Topologia de links

Visualização da topologia mostrando links observados a partir do nó raiz selecionado.

Rastreio de rota

Visualização de rastreio para uma origem, destino, links próximos e detalhes de pacote por hop.

Histórico de sensores

Gráfico de telemetria comparando o histórico de sensores entre múltiplos nós.

Cartões de status

Cartões principais para atividade de rádio, contagens de nós, pacotes, links, bateria e uso de canal.

Personalização de tema

Os temas podem remodelar o painel completo com cores personalizadas, gradientes, transparência, desfoque, fontes, partículas ou um fundo de mapa ao vivo. Estas paletas de exemplo são temas personalizados; selecione qualquer pré-visualização para abrir sua captura de tela em resolução total.

Signal Green	Neon Magenta	Aurora Relay

Aparências compartilhadas de nós

Nós Meshyface podem compartilhar pacotes de aparência compactos contendo uma receita de tema de nó e um fantasma ou marca d'água opcional. Configure e visualize seu nó em Settings > Appearance > Node Appearance, ative Share node appearance, e depois use Broadcast appearance para publicá-lo.

• Pacotes de aparência usam o canal de envio do perfil configurado e herdam a configuração de hop-limit do rádio; Meshyface não impõe um limite de hop separado.
• Aparências recebidas podem estilizar identidades de nós no chat, listas, detalhes de nós, mapas, gráficos, sensores e tickers sem substituir o tema do próprio painel receptor.
• Desativar Share node appearance desabilita ambos os lados da funcionalidade. Interrompe transmissões e desvia o caminho de recepção do perfil antes que cargas de aparência recebidas sejam decodificadas, armazenadas em cache ou persistidas; aparências compartilhadas em cache são limpas e nenhuma aparência recebida é renderizada.
• Quando o histórico está ativado, os perfis recebidos e a preferência de compartilhamento local persistem no banco de dados SQLite de histórico.
• Aparências compartilhadas são metadados cosméticos. Uma aparência recebida não altera as configurações de rádio, canais ou o tema do pacote salvo do painel.

Arquitetura do 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

Instalação

Comece com pré-requisitos e dependências, depois escolha um caminho de instalação:

• Execução manual em primeiro plano: clone em qualquer lugar e execute o painel diretamente.
• Serviço systemd recomendado: clone em /opt/meshyface para um host persistente atualizável via GitHub.
• Docker: execute o mesmo ponto de entrada do aplicativo em um contêiner com /data montado para estado persistente.
• Implantação por push de estação de trabalho: copie um checkout local para um destino via SSH.
• Topologia de runtime Proxmox: escolha posicionamento de rádio TCP ou USB para uma instalação VM/LXC.
• Pacotes de mapa offline: adicione dados de mapa local detalhados para painéis sem conexão ou com baixa conectividade.

Dados e Armazenamento

Banco de dados de histórico compartilhado

--history-db é o nome final do arquivo SQLite em disco. O painel não adiciona mais um sufixo de rádio conectado, então qualquer rádio conectado ao painel contribui para o mesmo histórico persistente de pacotes, chat, nós e rollups.

Modos de histórico

• O modo padrão persiste chat, pacotes, eventos de conexão, análises de nós, registros de texto malformado, métricas de ambiente e rollups de resumo em SQLite.
• --no-history desabilita o armazenamento persistente e mantém apenas buffers em memória ao vivo.
• Os rollups de resumo também são amostrados em segundo plano enquanto o painel está em execução, quando o histórico está ativado.

Tema e configurações locais

• A seleção de predefinição de tema persiste em mesh_dashboard_theme_settings.json por padrão, ou no arquivo fornecido via --theme-settings-file.
• Regras de telemetria personalizadas são armazenadas no banco de dados SQLite de histórico.

Comandos de manutenção

Comandos operacionais que inspecionam ou reparam dados locais do painel estão documentados em docs/maintenance.md.

Semântica da Visualização de Links

A subvisão Links é uma visualização de topologia, não uma reprodução de rota de pacote.

• O modo History (Histórico) desenha a partir do histórico de links armazenado no SQLite.
• O modo Live (Ao Vivo) desenha apenas a partir de observações de links da sessão atual.
• Os anéis numerados mostram a distância mais curta no grafo a partir do nó raiz atual, usando uma busca em largura sobre o grafo de links observados.
• Esses números de anel não são hops de encaminhamento Meshtastic literais e não são um rastreio de pacote em tempo real.
• Metadados de hop de pacote, quando disponíveis, ainda são mostrados separadamente nos detalhes do nó ou aresta como valores de hop de pacote.

O nó raiz atual é o nó em torno do qual o grafo é centralizado. Selecionar um nó diferente altera a raiz e recalcula os anéis de distância numerados a partir desse nó.

Referência de Configuração

Conexão e transporte

• --mesh-host <ip-or-dns>: host do rádio TCP
• --mesh-tcp-port <porta>: porta do rádio TCP, padrão 4403
• --mesh-port <caminho>: caminho do dispositivo serial
• --default-gateway-host <host>: host TCP de fallback se --mesh-host não for fornecido e serial ainda estiver no caminho padrão
• --default-gateway-port <porta>: porta TCP de fallback para --default-gateway-host
• --no-default-gateway: forçar serial a menos que --mesh-host seja explicitamente definido

Variáveis de ambiente relacionadas:

• MESH_GATEWAY_HOST
• MESH_GATEWAY_PORT
• MESH_DASH_MESH_PORT para o caminho serial padrão

HTTP, UI e segurança

• --http-host <host>: host de bind, padrão 0.0.0.0
• --http-port <porta>: porta de bind, padrão 8877
• --refresh-ms <ms>: intervalo de polling do navegador, padrão 3000
• --packet-limit <n>: tamanho do buffer de pacotes ao vivo recentes, padrão 250
• --reset-ticker-scale-on-restart / --no-reset-ticker-scale-on-restart
• --show-secrets: revelar chaves privadas/senhas/PSKs em painéis JSON brutos
• --debug-mode / --no-debug-mode: expor superfícies do painel apenas para depuração, como diagnósticos de rede avançados

Variáveis de ambiente relacionadas:

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

A identidade de runtime vem do git commit de 12 caracteres, seguido por um número opcional de pull request, por exemplo abc123456789 · PR #43. O painel de Software exibe esta revisão única em vez de uma versão de pacote. Assuntos de commit de merge/squash do GitHub são detectados automaticamente; implantações de pré-visualização não mescladas podem definir MESH_DASH_PR_NUMBER explicitamente.

/api/revision é o endpoint de identidade canônico. Seus campos revision e build_ref reportam a revisão de runtime, enquanto commit e pr_number permanecem disponíveis como campos estruturados. /api/version permanece como um endpoint legado, e seu campo version retém metadados de versão/empacotamento. MESH_DASH_VERSION também é reservado para empacotamento explícito de versão e não é exibido no painel.

Transferência de arquivos

• --file-transfer-enable: ativar o aplicativo de Arquivos; requer --accept-file-transfer-traffic-disclaimer
• --file-transfer-auto-accept: aceitar transferências de entrada diretas sem confirmação do navegador
• --file-transfer-max-bytes <bytes>: limite por arquivo, padrão 65536 e restrito a 1024-524288

As transferências usam o protocolo beta MF_FILE_V2 na porta privada 258 e não são compatíveis com o transporte anterior de mensagens de texto. Quando um destino tem uma contagem de hops detectada utilizável, Meshyface usa essa contagem mais um, limitada pelo limite de hops do rádio configurado. Dados de hop com mais de uma hora recaem para o limite configurado. O aplicativo de Arquivos exibe o limite selecionado e sua origem.

Variáveis de ambiente 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

Histórico e análises

• --history-db <caminho>: caminho base do banco de dados SQLite
• --history-max-rows <n>: padrão 200000
• --history-retention-days <dias>: padrão 30, use 0 para desabilitar a poda por idade
• --history-event-max-rows <n>: teto de eventos de pacote somente anexação, padrão 200000
• --history-event-retention-days <dias>: padrão 30
• --history-rollup-retention-days <dias>: padrão 365
• --no-history: modo apenas memória

Variáveis de ambiente relacionadas:

• MESH_DASH_HISTORY_DB

Temas

• --theme-presets <json>: arquivo opcional de predefinições de tema personalizado
• --theme-preset <nome>: nome da predefinição selecionada
• --theme-settings-file <json>: arquivo de seleção de tema em runtime persistido

Predefinições incorporadas:

• default (azul Meshyface seguro, partículas desativadas)
• custom (tema de demonstração com partículas e efeitos de fundo ativados)

Instalações novas usam default por padrão, a menos que um arquivo de configurações de tema persistido ou MESH_DASH_THEME_PRESET selecione outra predefinição.

Variáveis de ambiente relacionadas:

• MESH_DASH_THEME_PRESETS
• MESH_DASH_THEME_PRESET
• MESH_DASH_THEME_SETTINGS_FILE

Segurança

• Este painel é destinado a ambientes LAN/VPN confiáveis.
• Não o exponha diretamente à internet pública sem um proxy reverso e controle de acesso.
• Use --private-mode e/ou um token de API para controle de caminho de escrita mais rigoroso.
• Prefira MESH_DASH_API_TOKEN em vez de --api-token em hosts compartilhados ou multiusuário. Um token de linha de comando pode ser visível em listagens de processos e retido no histórico do shell.
• A predefinição de canal Join Meshyface usa um PSK Meshyface compartilhado intencionalmente público para interoperabilidade entre usuários deste software. Não use esse canal público para tráfego privado.
• --show-secrets expõe valores sensíveis em painéis JSON brutos; não o ative casualmente em displays compartilhados.
• Downloads brutos de banco de dados de pacotes podem expor conteúdos de mensagens e telemetria. Em hosts compartilhados, exija um token de API e use --no-allow-tokenless-raw-packet-download.
• A transferência de arquivos pode consumir tempo de antena significativo da malha. Mantenha-a desativada a menos que você tenha aceitado explicitamente essa troca.

Testes e Cobertura

Execute o conjunto de testes normal:

python -m pytest

Execute o Ruff da mesma forma que o CI:

scripts/run_ruff_local.sh

Execute o relatório de cobertura do aplicativo:

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

Execute a verificação de cobertura local com o mínimo mais rigoroso de 85%:

scripts/run_coverage_local.sh

Execute o benchmark de responsividade da GUI local antes de PRs:

scripts/run_gui_responsiveness_local.sh

A cobertura exclui intencionalmente o pacote do motor Zork adaptado da pontuação, mas os testes independentes do Zork e de roteamento ainda são executados. O GitHub Actions publica o mesmo relatório de cobertura como comentário de PR e artefato. O CI falha abaixo de 80%. A verificação local fica 5 pontos percentuais acima do CI.