Blog
Tutorial ESP32 WiFiManager para Configuração de WiFi
Se você já enviou um projeto com ESP32 contendo credenciais de Wi-Fi codificadas, você já sabe o que acontece a seguir. Funciona perfeitamente em seu banco de testes, conectado à sua rede doméstica, e então é enviado para um cliente, ou um prédio diferente, ou um país diferente, e subitamente se torna um dispositivo inutilizável até que alguém o reprograme. Esta é uma das dores de cabeça mais comuns no desenvolvimento de produtos de IoT e também uma das mais evitáveis. É exatamente esse o problema para o qual o WiFiManager foi construído.
Então vamos começar: o que é, como realmente funciona por baixo dos panos e como você pode colocá-lo em funcionamento em seu próprio projeto ESP32, começando com uma rápida verificação de instalação e avançando para o tipo de configuração que você realmente desejaria enviar.
Por que credenciais codificadas de forma rígida simplesmente não funcionam
Todos nós já escrevemos esta linha em algum momento:
WiFi.begin("MyHomeNetwork", "password123");
E para experiências em bancada, não há nada de errado com isso. Mas no momento em que seu projeto precisar sair da bancada, essa abordagem começa a causar problemas reais:
- Não há flexibilidade para quem o utiliza. Quem implanta o dispositivo precisa saber o SSID e a senha exatos antes mesmo de fazer o flash, caso contrário, será necessário acesso físico posteriormente apenas para alterar uma configuração.
- É um risco de segurança. As credenciais embutidas diretamente no firmware estão lá em texto simples, prontas para qualquer um que desmonte o binário.
- Não escala. Tem dez unidades indo para dez sites diferentes? Isso são dez builds de firmware diferentes, ou uma quantidade enorme de reconfiguração manual.
O que realmente queremos é que o dispositivo solicite ao usuário final os detalhes do Wi-Fi, os salve e se reconecte automaticamente toda vez que for iniciado, sem que tenhamos que mexer no código novamente. Essa é a lacuna que o WiFiManager preenche, e ele faz isso muito bem.
O que é WiFiManager
WiFiManager é uma biblioteca de código aberto, originalmente escrita por tzapu e agora mantida por tablatronix, que oferece ao seu projeto ESP32 (ou ESP8266) uma maneira auto-contida e baseada na web para configurar o Wi-Fi. Em vez de codificar credenciais, o dispositivo inicia no modo Access Point, transmite sua própria rede Wi-Fi e exibe uma página web simples onde o usuário pode selecionar sua rede em uma lista escaneada e digitar a senha.
Uma vez que o usuário clica em salvar, o WiFiManager grava as credenciais na memória flash e tenta se conectar. A partir daí, toda vez que o dispositivo inicializa, ele tenta primeiro as credenciais salvas e só retorna ao modo de configuração se a conexão falhar. Todo esse padrão é chamado de portal cativo, e você quase certamente já se deparou com ele antes: é o mesmo truque que exibe uma página de login assim que você se conecta ao WiFi de um hotel ou aeroporto.
Como o ESP32 WiFiManager Funciona
A Fundação: Modos WiFi do ESP32
O rádio de 2,4 GHz do ESP32 pode operar em três modos diferentes:
- Modo Estação (STA): o ESP32 age como um cliente WiFi comum, conectando-se ao seu roteador da mesma forma que seu laptop ou telefone fariam.
- Modo Ponto de Acesso (AP): O ESP32 cria sua própria rede, permitindo que outros dispositivos se conectem diretamente a ele.
- Modo Duplo (AP+STA): e é aqui que reside a inteligência — o ESP32 pode transmitir sua própria rede ao mesmo tempo em que escaneia ou se conecta a outro roteador.
Quando o dispositivo inicia em um local novo, sem credenciais salvas, o WiFiManager o coloca no modo AP e começa a transmitir um SSID — algo como ESP32-Setup. Isso dá ao seu telefone um acesso: uma ponte direta para o hardware antes que ele tenha sequer tocado na internet.
A Interceptação: Redirecionamento DNS
Ok, então seu telefone ingressou na rede do ESP32. Como fazemos para acessarmos a página de configuração sem que alguém precise digitar um endereço IP manualmente? Nós sequestramos o DNS.
Normalmente, quando você digita uma URL em seu navegador, um servidor DNS a traduz para um endereço IP nos bastidores. Enquanto está no modo de configuração, o ESP32 executa seu próprio pequeno servidor DNS — exceto que, em vez de responder corretamente, ele responde a todas as consultas com seu próprio endereço, geralmente 192.168.4.1. Não importa se seu telefone está perguntando por google.com ou qualquer outra coisa; a resposta é sempre “eu”.”
A Armadilha: Portais Cativos
Aquele truque de DNS é exatamente o que faz a mágica do portal cativo acontecer. E você já viu isso antes, provavelmente sem perceber: ao conectar-se ao Wi-Fi de um aeroporto ou hotel.
Celulares e laptops modernos verificam automaticamente, no momento em que se conectam a uma nova rede, se essa rede requer um login. Dispositivos Apple, por exemplo, enviam um ping discretamente para um endereço específico em segundo plano para descobrir. Como nosso ESP32 intercepta todas as requisições DNS, ele também captura essa verificação em segundo plano. Em vez da resposta esperada, ele devolve nossa página de configuração HTML personalizada. O sistema operacional do telefone vê isso e abre uma janela do navegador de imediato. Ninguém precisa procurar um endereço IP; ele simplesmente aparece.
Salvar para mais tarde: Armazenamento Não Volátil (NVS)
Após alguém digitar os detalhes de seu Wi-Fi e clicar em “Salvar”, o ESP32 precisa de uma maneira de se lembrar disso, mesmo após o corte de energia.
Placas mais antigas dependiam de EEPROM para isso, mas o ESP32 utiliza algo mais novo chamado NVS, ou Non-Volatile Storage (Armazenamento Não Volátil). Pense nisso como um simples armazenamento chave-valor, alocado em sua própria partição dedicada da memória flash.
O SSID e a senha são gravados como valores de string sob chaves específicas. Na próxima vez que o dispositivo inicializar, o firmware verifica primeiramente o NVS e, se encontrar algo válido, ele ignora todo o processo de Access Point e se conecta silenciosamente em modo Station. Sem portal, sem complicações, apenas uma inicialização normal.
Restrições Profissionais: Considerações sobre Memória
Aqui está uma comparação útil: é um pouco como aplicar regras de Design para Fabricação a um layout de PCB para economizar espaço na placa. Você tem que gerenciar a memória do seu firmware da mesma forma cuidadosa.
Executar um Ponto de Acesso (Access Point), um servidor web e um servidor DNS simultaneamente consome uma quantidade considerável da RAM do ESP32. Deixar esses serviços ativos após a conexão já ter sido estabelecida priva a sua aplicação real da memória que ela poderia necessitar.
O melhor a se fazer para qualquer coisa que vá para produção é desativar esses serviços de configuração no momento em que você obtiver uma conexão bem-sucedida. Pare os servidores web e DNS, libere seus recursos assim que autoConnect() retornar, e você terá essa memória de volta para o que realmente importa: amostrar sensores, executar inferências, gerenciar energia, o que quer que seu projeto precise fazer.
Como Instalar o WiFiManager no ESP32
Se você estiver utilizando o Arduino IDE ou o PlatformIO, a instalação é descomplicada.
Arduino IDE: abra o Gerenciador de Bibliotecas (Sketch > Incluir Biblioteca > Gerenciar Bibliotecas), pesquise por “WiFiManager by tzapu” e instale a versão mais recente, atualmente 2.0.17.
- Clique no gerenciador de bibliotecas
- Digite WiFiManager e instale WiFiManager por tzapu
Antes de começar a configurar parâmetros personalizados e persistência de NVS, vale a pena confirmar se o mínimo necessário funciona primeiro. A biblioteca inclui um exemplo que faz exatamente isso, procure em Arquivo > Exemplos > WiFiManager > Basic
Programe isso e, assumindo que não haja rede salva, seu telefone deverá imediatamente oferecer a opção de se conectar a “ESP32-Setup”, e a página de configuração deverá aparecer. Assim que você confirmar que isso está funcionando, estará pronto para construir a versão completa.
Uma informação que vale a pena saber: existem algumas ramificações (forks) do WiFiManager circulando no ecossistema, algumas com correções adicionais específicas para ESP32 já incluídas. Portanto, se você encontrar problemas de compatibilidade em um core ESP32 mais recente, vale a pena verificar exatamente qual ramificação você realmente baixou.
Configuração de um ESP32 WiFiManager em Ambiente de Produção
Uma chamada autoConnect() simples é excelente para provar o conceito, mas uma implantação real geralmente requer um pouco mais: campos personalizados, como um endereço de servidor MQTT, uma maneira de apagar credenciais salvas sem regravar o firmware (re-flashing) e um tempo limite razoável para que o dispositivo não permaneça no modo de configuração indefinidamente, esgotando a bateria.
Aqui está um esboço completo que lida com todos os três, construído em torno de três peças que trabalham juntas.
- Gerenciamento de memória. Em vez de espalhar leituras e escritas de flash por toda a função `setup()`, as escondemos em funções auxiliares `loadConfig()` e `saveConfig()`. Dessa forma, é imediatamente óbvio, num relance, exatamente quais partes do código estão acessando o armazenamento persistente:
- O "escape hatch" (descarga de emergência). Antes de tocarmos em qualquer funcionalidade de Wi-Fi, verificamos primeiro um botão de reset físico. Isso é mais importante do que parece: caso a pilha de Wi-Fi fique travada em algum ponto futuro, um usuário sem outro recurso necessita de um caminho garantido para sair. Verificar substituições de hardware antes de qualquer outra coisa significa que esse caminho nunca poderá ser bloqueado pelo que vier depois dele:
- O fluxo de configuração. O fluxo em si é agradável e linear: carregar o que foi salvo, passá-lo para o portal como os valores padrão, tentar conectar e esta parte é importante apenas reescrever para a memória flash se o usuário realmente alterou algo. Não faz sentido gastar um ciclo de gravação na memória flash apenas para salvar novamente o que já estava lá:
Reunindo tudo, você tem um fluxo de provisionamento completo e autônomo: ele verifica reinicializações manuais, carrega o que já está salvo, permite que o usuário visualize e substitua isso por meio de um portal cativo, conecta-se e apenas persiste o que realmente mudou. Sem serviço em nuvem, sem aplicativo complementar e nada fora do próprio dispositivo.
Problemas Comuns do WiFiManager para ESP32
Algumas coisas frequentemente confundem as pessoas com o WiFiManager, de forma que valem a pena ser destacadas antes que você mesmo as encontre:
- O portal cativo nem sempre aparece automaticamente. Algumas versões do Android e telefones gerenciados corporativamente atrasam ou desativam essa detecção. Sempre imprima o endereço IP do portal (192.168.4.1 por padrão) para o console serial, para que alguém possa acessá-lo manualmente se o pop-up nunca aparecer.
- autoConnect() bloqueia por padrão. Enquanto o dispositivo está no modo AP, o restante do seu código setup() não será executado. Se você precisa que outras coisas aconteçam durante o provisionamento, considere o modo não bloqueante do WiFiManager em vez disso.
- O NVS pode ser corrompido após uma atualização do core. A atualização do core do ESP32 para Arduino ocasionalmente altera o layout da partição do NVS, fazendo com que as credenciais antigas sejam lidas como dados inválidos. Um apagamento limpo do NVS ou uma chamada defensiva de resetSettings() em caso de falha de conexão é mais seguro do que assumir que os dados antigos ainda são válidos.
- Proteja sua AP com senha. Por padrão, essa rede de configuração está totalmente aberta. Qualquer pessoa próxima pode se conectar a ela e visualizar ou alterar as configurações do seu WiFi. Passe uma senha como segundo argumento para autoConnect() e essa porta se fechará.
O WiFiManager é adequado para o seu projeto ESP32?
Para a maioria dos projetos de consumo e produtos comerciais de pequeno porte, o WiFiManager atinge um ponto ideal: sem dependências externas, um fluxo de configuração que as pessoas já entendem de redes WiFi de hotéis e aeroportos, e praticamente nenhum código para implementá-lo.
Dito isto, não é adequado para tudo. Para implantações industriais "headless" – pense em um dispositivo parafusado em uma parede sem tela e sem acesso físico fácil – você provavelmente se beneficiará mais de uma rede de fallback codificada e um caminho de provisionamento remoto via BLE ou API de back-end, em vez de depender de alguém se aproximar e conectar seu telefone ao AP do dispositivo. E se você já está utilizando o ESP-IDF em vez do Arduino, vale a pena comparar isso com o provisionamento nativo de Wi-Fi da própria Espressif, que adiciona provisionamento baseado em BLE ao lado da abordagem usual de SoftAP/portal cativo e tende a se encaixar de forma mais natural em uma base de código IDF existente.
Mas para tudo o que está entre os projetos de criação, as pequenas startups de hardware, o problema de “esta coisa precisa funcionar nas casas de dez clientes diferentes sem dez compilações de firmware diferentes’, o WiFiManager ainda é uma das maneiras mais simples e testadas em batalha para resolver o provisionamento de Wi-Fi no ESP32.
Considerações Finais
Este é o fim deste tutorial do ESP32 WiFiManager. Assim que tiver a configuração básica funcionando, as credenciais de Wi-Fi codificadas não deverão mais fazer parte do seu fluxo de trabalho de implantação do ESP32.
Se você encontrar problemas ao construir um produto IoT baseado em ESP32, você sempre poderá discutir seu projeto com PCBCool. Também lançamos recentemente um Sistema de cotação online, tornando mais fácil para empresas e fabricantes obterem orçamentos para projetos de PCB e PCBA. Se tiver um projeto relacionado, sinta-se à vontade para experimentá-lo.
Perguntas Frequentes
A razão principal é que cada camada adicionada torna o processo de fabricação mais difícil de controlar. Mais camadas significam mais chances de defeitos nas camadas internas, problemas de alinhamento, falhas de laminação e refugo.
As ilhas BGA são pequenas e densamente espaçadas, de modo que pequenos erros de fabricação podem facilmente se tornar problemas de montagem.
Sam K atua em sistemas eletrônicos embarcados, com foco em projeto de hardware, desenvolvimento de PCB, programação de firmware e integração de sistemas. Ele também apoia a otimização de desempenho e auxilia na transformação de ideias de produtos eletrônicos em soluções confiáveis e funcionais no mundo real.
