Como corrigir erros de conexão WebSocket do Moonraker no Printer Tools
Solução de problemas do WebSocket do Moonraker
A resposta rápida
O Printer Tools mantém uma conexão WebSocket ativa com o Moonraker em ws(s)://<host>/websocket e reconecta automaticamente a cada 5 segundos caso ela caia. A maioria dos erros de conexão vem de um host inacessível, um endereço IP alterado ou o Klippy ainda não estar pronto, não do próprio aplicativo. Verificar essas três coisas primeiro resolve a maioria dos casos.
O que você precisa
- O endereço IP local exato ou o nome de host usado atualmente pela impressora que executa o Moonraker
- Confirmação de que o Klippy mostra Ready, e não Error ou Shutdown
- A mesma rede acessível tanto pelo celular ou computador quanto pelo host da impressora
- O endereço completo, incluindo esquema e porta, se sua configuração usar HTTPS ou um proxy reverso
- Qualquer API key do Moonraker, token Bearer ou credenciais de Basic Auth exigidos pela sua instalação
Diagnosticar um erro de WebSocket do Moonraker
- 1
Confirme se o Klippy está realmente pronto
Abra o mesmo host em um navegador ou no Mainsail ou Fluidd, se você os tiver instalados. Se o Klippy mostrar Error ou Shutdown ali também, o problema está no Klipper ou no seu printer.cfg, não no Printer Tools, e reconectar o aplicativo não vai ajudar até o próprio Klippy se recuperar.
- 2
Verifique novamente o endereço do host
Os roteadores costumam atribuir um novo endereço IP local depois de uma reinicialização. Confirme o endereço atual da máquina que executa o Moonraker e atualize-o no Printer Tools caso tenha mudado. Reservar um endereço estático para esse dispositivo no seu roteador evita que isso volte a acontecer.
- 3
Digite o endereço completo em configurações personalizadas
Se o Moonraker estiver atrás de HTTPS, uma porta não padrão ou um proxy reverso, digite o endereço completo exatamente como você faria em um navegador. O Printer Tools monta a URL do WebSocket a partir do que você fornece, então um endereço parcial ou incorreto falha antes mesmo de o Moonraker ser alcançado.
- 4
Confira a autenticação exigida pela sua instalação
Se o Moonraker exigir uma API key, token Bearer ou Basic Auth, as mesmas credenciais precisam ser inseridas no Printer Tools. Uma incompatibilidade fecha o WebSocket imediatamente depois de aberto, em vez de bloquear a tentativa inicial de conexão.
- 5
Force uma reconexão limpa
Remova e adicione novamente a impressora, ou desative e ative a conexão, para reiniciar o soquete do zero em vez de esperar pela nova tentativa automática. Isso também limpa qualquer solicitação pendente deixada pela tentativa de conexão anterior.
- 6
Descarte o caminho de rede
Wi-Fi de convidados, isolamento de clientes, regras de firewall de VLAN ou um perfil de VPN ativo podem impedir que o celular alcance o host da impressora mesmo quando ambos os dispositivos mostram acesso à internet. Teste a partir do mesmo segmento de rede antes de supor que o problema está no próprio Moonraker.
Status do Moonraker dentro do Printer Tools
O painel do Klipper reflete o estado ao vivo do WebSocket e é atualizado automaticamente assim que o Moonraker volta a ficar acessível.
O que a conexão WebSocket viabiliza
- Estado de impressão, progresso, temperaturas e objetos padrão do Klipper enviados em tempo real
- Reconexão automática a cada 5 segundos sem precisar reabrir o aplicativo
- Um heartbeat que mantém a conexão ativa durante o uso normal em segundo plano
- Uma verificação do status do Klippy realizada imediatamente após cada conexão bem-sucedida
- Suporte a API key, token Bearer ou Basic Auth quando sua configuração do Moonraker exigir um deles
O que isso não consegue resolver
- Um erro ou estado de desligamento do Klippy precisa ser resolvido no próprio Klipper, não pelo Printer Tools
- O Printer Tools não consegue alcançar um host que mudou de endereço sem atualizar o IP salvo da impressora
- O isolamento de rede entre o celular e o host da impressora bloqueia o WebSocket independentemente das configurações do aplicativo
- Uma impressão já em andamento continua na impressora mesmo enquanto o aplicativo mostra desconectado
Erros comuns de WebSocket
O Printer Tools fica conectando indefinidamente
Confirme se o endereço do host está atual e acessível, e se o próprio Moonraker está em execução. Se o mesmo endereço também falhar em um navegador, o problema está no host da impressora, não no aplicativo.
A conexão abre e depois cai repetidamente
Verifique se há uma rede que desconecta clientes ociosos, como alguns recursos de economia de energia de Wi-Fi de roteadores, ou um loop de reinicialização do Moonraker causado por um erro de configuração. Revise o log do Moonraker no host da impressora em busca de entradas repetidas de desconexão.
O Mainsail ou o Fluidd conectam, mas o Printer Tools não
Use exatamente o mesmo endereço, incluindo esquema e porta, que funciona no navegador. Um proxy reverso ou certificado HTTPS que um navegador aceita silenciosamente ainda pode exigir que o endereço completo seja digitado manualmente no Printer Tools.
O Klippy mostra um erro imediatamente após conectar
Isso significa que o próprio WebSocket teve sucesso e o problema está na configuração do Klipper. Corrija o erro relatado no printer.cfg e reinicie o Klipper pelo Moonraker antes de esperar que o Printer Tools mostre um painel normal.
A conexão funciona em casa, mas falha fora da rede local
Um WebSocket direto do Moonraker só funciona na mesma rede local. Use uma VPN de volta à sua rede doméstica ou adicione a impressora pelas opções de acesso remoto OctoEverywhere ou Obico no Printer Tools, em vez de expor o Moonraker diretamente.
Reconectando de fora da sua rede
O WebSocket direto só funciona enquanto o celular e o host da impressora compartilham uma rede acessível. Para acesso remoto, use uma VPN de volta a essa rede ou conecte a mesma impressora Klipper pelo OctoEverywhere ou Obico no Printer Tools. Não redirecione a porta do Moonraker diretamente no seu roteador.
Perguntas frequentes
O Printer Tools usa o WebSocket do Moonraker ou sua API REST?
O Printer Tools se conecta pela API WebSocket JSON-RPC do Moonraker em /websocket para telemetria e controle em tempo real, por isso um caminho de rede estável até esse endpoint importa mais do que o sucesso de qualquer requisição REST isolada.
Com que frequência o aplicativo tenta reconectar após uma falha?
A cada 5 segundos, automaticamente, até que o WebSocket aceite a conexão novamente. Não há um limite manual de tentativas.
Perder a conexão interrompe minha impressão?
Não. O Klipper continua imprimindo na própria impressora. Quando o Printer Tools perde o WebSocket, isso só significa que o aplicativo para de receber atualizações ao vivo até reconectar.
Preciso ter o Mainsail ou o Fluidd em execução para isso funcionar?
Não. O Printer Tools se comunica diretamente com o Moonraker. O Mainsail e o Fluidd são úteis para comparar o comportamento durante a solução de problemas, mas nenhum dos dois é obrigatório.
Por que a conexão funciona no Wi-Fi, mas não pela minha VPN?
Uma VPN que não roteia tráfego para a faixa de IP local da sua rede doméstica não consegue alcançar o Moonraker diretamente. Use uma VPN configurada para alcançar essa rede, ou use o OctoEverywhere ou o Obico.
Guias relacionados
Veja a compatibilidade completa com Klipper e Moonraker
Revise os recursos compatíveis do Moonraker, os requisitos opcionais de câmera e Spoolman, as opções de acesso remoto e as limitações atuais.
Todas as suas impressoras 3D num único painel
Monitorize impressoras Bambu Lab, Klipper, OctoPrint, Creality, Snapmaker, Anycubic, Flashforge, Elegoo e Prusa a partir de uma única app
Disponível para Android, iPhone, iPad e Mac, com apps complementares para Apple Watch e Wear OS e acesso remoto opcional por VPN, OctoEverywhere ou Obico
