Exemplo Custom WebApp com ESP32 - Tutorial de Interface Web Simples para Iniciantes
Visão Geral
Este exemplo oferece um modelo completo para criar suas próprias aplicações web personalizadas, que se integram perfeitamente à biblioteca DIYables ESP32 WebApps.

O modelo CustomWebApp é perfeito para iniciantes que querem adicionar a própria interface web ao ecossistema DIYables ESP32 WebApps! Este tutorial mostra como criar uma página web simples com troca de dados bidirecional em tempo real entre o navegador web e o ESP32 via WebSocket, que pode:
- Enviar mensagens de texto do navegador web para o ESP32 instantaneamente via WebSocket
- Receber mensagens do ESP32 e exibi-las em tempo real na página web
- Manter uma conexão WebSocket persistente para comunicação contínua
- Reconectar automaticamente quando a conexão WebSocket é perdida
- Funcionar em dispositivos móveis com design responsivo
Projetado para o ESP32 - este modelo se integra perfeitamente aos apps web DIYables existentes e fornece a base para criar suas próprias interfaces IoT personalizadas!
Este modelo fornece o mínimo de código para você começar. Os usuários podem desenvolver as próprias aplicações web sofisticadas modificando este modelo. Recomenda-se conhecimento básico de programação web (HTML, CSS, JavaScript) para personalizar a interface web e adicionar recursos avançados.
O Que Você Vai Aprender
- Como criar um app web personalizado que se integra à biblioteca DIYables ESP32 WebApps
- Como adicionar sua página personalizada ao ecossistema de apps web DIYables
- Como enviar mensagens de texto do navegador web para o ESP32
- Como enviar dados do ESP32 para o navegador web
- Como tratar conexões WebSocket e a reconexão automática
- Como criar interfaces web responsivas para celular
- Como usar o sistema de modelos da DIYables ESP32 WebApps para um desenvolvimento rápido
Recursos
- Integração com DIYables ESP32 WebApps: Integra-se perfeitamente ao ecossistema da biblioteca DIYables ESP32 WebApps
- Código de Modelo Mínimo: Fornece uma base simples que você pode expandir e personalizar
- Desenvolvimento Baseado em Modelo: Ponto de partida completo que você pode modificar para criar aplicações sofisticadas
- Mensagens de Texto Simples: Envie mensagens entre o navegador web e o Arduino
- Reconexão Automática: Reconecta automaticamente quando a conexão é perdida
- Responsivo para Celular: Funciona perfeitamente em celulares, tablets e computadores
- Amigável para Iniciantes: Código limpo e simples, fácil de entender
- Framework Extensível: Requer conhecimento básico de programação web (HTML/CSS/JavaScript) para personalização avançada
Hardware Necessário
Or you can buy the following kits:
| 1 | × | DIYables ESP32 Starter Kit (ESP32 included) | |
| 1 | × | DIYables ESP32 S3 Starter Kit (ESP32 S3 included) | |
| 1 | × | DIYables Sensor Kit (18 sensors/displays) |
Como Começar
Você pode começar a criar seu app web personalizado para a placa ESP32 seguindo estas etapas principais:
- Execute o Modelo de App Personalizado Padrão na sua placa ESP32
- Teste e Verifique se o App Web Personalizado Padrão Funciona Corretamente
- Entenda o Protocolo de Comunicação e Como Ele Funciona em Segundo Plano
- Modifique o Modelo para Adaptá-lo à Sua Aplicação
- Gerencie Vários Apps Web Personalizados - Guia Essencial para Evitar Conflitos
Vamos começar, um por um.
Execute o Modelo de App Personalizado Padrão na sua placa ESP32
Passos Rápidos
- Se esta é a primeira vez que você usa o ESP32, consulte o tutorial sobre como configurar o ambiente para ESP32 no Arduino IDE
- Conecte a placa ESP32 ao seu computador usando um cabo USB
- Abra o Arduino IDE no seu computador
- Selecione a placa ESP32 apropriada (por exemplo, ESP32 Dev Module) e a porta COM
- Navegue até o ícone Libraries na barra esquerda do Arduino IDE
- Pesquise "DIYables ESP32 WebApps" e encontre a biblioteca DIYables ESP32 WebApps da DIYables
- Clique no botão Install para instalar a biblioteca

- Você será solicitado a instalar algumas outras dependências da biblioteca
- Clique no botão Install All para instalar todas as dependências da biblioteca

- No Arduino IDE, vá em File > Examples > DIYables ESP32 WebApps > CustomWebApp
- Você verá 4 arquivos que formam o modelo completo do app web personalizado:
- CustomWebApp.ino - Código principal do ESP32 (é aqui que você adiciona sua lógica personalizada!)
- CustomWebApp.h - Arquivo de cabeçalho (define a interface com a biblioteca DIYables ESP32 WebApps)
- CustomWebApp.cpp - Arquivo de implementação (trata a integração com o framework da biblioteca)
- custom_page_html.h - Design da página web (personalize sua interface web aqui!)
- Configure o WiFi alterando estas linhas em CustomWebApp.ino:
Passo 5: Upload e Teste
- Clique no botão Upload no Arduino IDE para fazer o upload do código para o ESP32
- Abra o Serial Monitor para ver o status da conexão
- Anote o endereço IP exibido no Serial Monitor
- Abra o Serial Monitor
- Veja o resultado no Serial Monitor. Ele deve ser parecido com o abaixo
- Se você não vir nada, reinicie a placa ESP32.
- Anote o endereço IP exibido e digite esse endereço na barra de endereços de um navegador web no seu smartphone ou PC.
- Exemplo: http://192.168.0.2
- Você verá a página inicial como na imagem abaixo:

- Clique no link Web Custom e você verá a interface do app Web Custom como abaixo:

- Você também pode acessar a página diretamente pelo endereço IP seguido de /custom. Por exemplo: http://[IP_ADDRESS]/custom
Teste e Verifique se o App Web Personalizado Padrão Funciona Corretamente
Quando você executa o modelo CustomWebApp padrão, é isto que você deve ver:
Na Interface Web:
- Status da Conexão: Mostra "Connected" em azul quando o WebSocket está ativo
- Caixa de Entrada de Mensagem: Campo de texto para digitar mensagens para o Arduino
- Botão Enviar: Clique para enviar sua mensagem (ou pressione Enter)
- Exibição das Mensagens do Arduino: Mostra em texto azul as mensagens recebidas do ESP32
Comportamento do ESP32:
- Resposta Eco: Quando você envia "Hello" pela web, o ESP32 responde com "Echo: Hello"
- Atualizações Periódicas: O ESP32 envia mensagens de tempo de atividade a cada 5 segundos: "Arduino uptime: X seconds"
- Serial Monitor: Todas as mensagens recebidas são registradas para depuração
Teste a Comunicação:
- Digite uma mensagem na caixa de entrada (por exemplo, "test message")
- Clique em Enviar ou pressione Enter
- Verifique o Serial Monitor - você deve ver: "Received from web: test message"
- Verifique a página web - você deve ver: "Echo: test message"
- Aguarde alguns segundos - você verá mensagens periódicas de tempo de atividade atualizadas a cada 3 segundos (por exemplo, "Arduino uptime: 15 seconds", "Arduino uptime: 18 seconds", etc.)
Entenda o Protocolo de Comunicação e Como Ele Funciona em Segundo Plano
Entender os mecanismos internos ajuda você a personalizar o modelo com eficiência.
Sistema de Identificador de App
O modelo CustomWebApp usa tags de mensagem exclusivas (chamadas de "App Identifiers") que ajudam o código do ESP32 e os clientes web a filtrar as mensagens que pertencem a eles. Isso é essencial porque sua aplicação pode incluir vários apps web, e cada app precisa processar somente as próprias mensagens, ignorando as outras:
Lado do ESP32 (CustomWebApp.h e CustomWebApp.cpp)
Lado do JavaScript (custom_page_html.h)
Benefícios deste design:
- Fonte única da verdade: Altere o identificador em um único lugar por linguagem
- Sem strings mágicas: Elimina o "CUSTOM:" fixo espalhado pelo código
- Segurança de tipos: O uso de constantes evita erros de digitação
- Extensível: Fácil de criar vários apps personalizados com identificadores diferentes
- Evita conflito de dados entre vários apps: Cada app usa um identificador exclusivo para evitar interferência nas mensagens
- Profissional: Segue os princípios de design orientado a objetos
Observações Importantes:
- Você pode manter o identificador atual "CUSTOM:" ao modificar este modelo de app web personalizado para adaptá-lo ao seu projeto. No entanto, ao criar mais de um app personalizado, certifique-se de alterá-lo para evitar conflitos.
- Se alterar o identificador, certifique-se de que o valor no JavaScript (arquivo .h) e no código do ESP32 (arquivo .cpp) seja o mesmo (por exemplo, ambos usam "TEMP:" ou ambos usam "SENSOR:").
- Identificadores já reservados pelos apps integrados: Os identificadores a seguir já são usados pelos apps integrados da DIYables ESP32 WebApps e devem ser evitados:
- Identificadores dos apps principais: "CHAT:", "MONITOR:", "PLOTTER:", "DIGITAL_PINS:", "JOYSTICK:", "SLIDER:", "TABLE:", "RTC:", "ROTATOR:", "GAUGE:"
- Identificadores de subprotocolos: "TIME:", "DATETIME:", "JOYSTICK_CONFIG:", "PLOTTER_DATA:", "PLOTTER_CONFIG:", "SLIDER_VALUES:", "TABLE_CONFIG:", "TABLE_DATA:", "VALUE_UPDATE:", "PIN_CONFIG:", "PIN_STATES:", "PIN_UPDATE:"
- O JavaScript adiciona o identificador: O JavaScript anexa automaticamente o identificador do app (que é "CUSTOM:" neste modelo) usando a constante APP_IDENTIFIER e depois envia a mensagem ao ESP32 via WebSocket. A mensagem enviada de fato é: CUSTOM:Hello
- A biblioteca DIYables ESP32 WebApps recebe: A biblioteca recebe a mensagem CUSTOM:Hello e a repassa ao seu método CustomWebAppPage::handleWebSocketMessage
- A classe CustomWebAppPage remove o identificador: Em handleWebSocketMessage, a classe CustomWebAppPage verifica se a mensagem começa com o seu APP_IDENTIFIER, remove o identificador usando .substring(APP_IDENTIFIER.length()) e depois repassa a mensagem restante Hello chamando a função de callback implementada no seu arquivo .ino
- Sua aplicação trata a mensagem: Sua aplicação no arquivo .ino recebe somente Hello e pode tratar a mensagem de acordo com a sua lógica personalizada. O modelo atual apenas a imprime e envia de volta uma resposta
- Sua aplicação chama sendToWeb(): No seu arquivo .ino, você chama customPage.sendToWeb("Temperature: 25°C") para enviar os dados ao navegador web
- A classe CustomWebAppPage adiciona o identificador e transmite: A classe CustomWebAppPage adiciona automaticamente o identificador do app, usando a constante APP_IDENTIFIER, à sua mensagem e transmite CUSTOM:Temperature: 25°C a todos os clientes web conectados via WebSocket
- O JavaScript recebe e filtra a mensagem: O navegador web recebe CUSTOM:Temperature: 25°C pelo manipulador de eventos ws.onmessage, mas o JavaScript processa somente as mensagens que começam com APP_IDENTIFIER e remove o identificador usando .substring(APP_IDENTIFIER.length())
- A página web exibe a mensagem limpa: O modelo atual exibe a mensagem limpa Temperature: 25°C (sem o identificador) na seção "Message from Arduino". Você pode personalizar o JavaScript para analisar e exibir os dados de outras formas, dependendo das necessidades da sua aplicação
- CustomWebApp.ino - Sketch principal do ESP32 com a lógica da sua aplicação
- CustomWebApp.h - Arquivo de cabeçalho que define a classe da página personalizada (interface com a biblioteca)
- CustomWebApp.cpp - Implementação com a lógica de comunicação (código da biblioteca)
- custom_page_html.h - Interface HTML separada para facilitar a personalização
Fluxo de Comunicação
Da Página Web para o ESP32:
Quando você digita uma mensagem na interface web e clica no botão de enviar, por exemplo: Hello, acontece o fluxo abaixo:
Do ESP32 para a Página Web:
Quando o seu ESP32 quer enviar dados para a interface web, por exemplo: Temperature: 25°C, acontece o fluxo abaixo:
Visão Geral da Arquitetura
O exemplo CustomWebApp é composto por quatro arquivos principais:
Modifique o Modelo para Adaptá-lo à Sua Aplicação
O modelo foi projetado para ser facilmente personalizável de acordo com as suas necessidades. Veja como adaptá-lo:
1. Integração com Hardware
Adicionar a Inicialização do Hardware
Na função setup() de CustomWebApp.ino:
Tratar Comandos Personalizados
Estenda a função de callback para tratar seus comandos personalizados:
Enviar Dados de Sensores em Tempo Real
2. Personalização da Interface Web
Modificar o Layout HTML
Edite o HTML em custom_page_html.h para mudar a interface:
Personalizar o Processamento em JavaScript
Atualize a função ws.onmessage para tratar tipos de dados específicos:
Adicionar Estilo
Personalize o CSS da sua aplicação:
Outras Personalizações
Além de modificar a interface web e a integração com o hardware, você também pode personalizar como o seu app aparece no ecossistema DIYables ESP32 WebApps:
1. Personalizar o Caminho do App
Você pode alterar o caminho da URL em que o seu app web personalizado é acessado, modificando o construtor no seu arquivo de cabeçalho:
Caminho Padrão:
Exemplos de Caminhos Personalizados:
Observações Importantes:
- O caminho deve começar com "/": Sempre comece o caminho com uma barra
- Use nomes descritivos: Escolha caminhos que descrevam claramente a função do seu app
- Evite conflitos: Não use caminhos já ocupados por apps integrados, como /chat, /monitor, /plotter, etc.
- Use letras minúsculas e hífens: Siga as convenções de URL da web para maior compatibilidade
2. Personalizar o Cartão do App na Página Inicial
Você pode personalizar como o seu app aparece na página inicial da DIYables ESP32 WebApps modificando o método getNavigationInfo() no seu arquivo de implementação:
Cartão de App Básico:
Cartão de App Avançado com CSS Inline:
Gerencie Vários Apps Web Personalizados - Guia Essencial para Evitar Conflitos
Ao desenvolver vários aplicativos web personalizados, é fundamental evitar conflitos entre os diferentes apps. Vamos supor que queremos adicionar três apps personalizados chamados "Temperature Monitor", "Motor Controller" e "Sensor Dashboard" ao nosso projeto ESP32. Veja como garantir que eles funcionem juntos em harmonia:
1. Use Identificadores de App Exclusivos
Cada app web personalizado deve ter um identificador exclusivo para evitar conflitos de mensagens:
Exemplo: App Temperature Monitor
Exemplo: App Motor Controller
Exemplo: App Sensor Dashboard
2. Use Caminhos de Página Exclusivos
Cada app web precisa de um caminho de URL exclusivo:
3. Use Nomes de Classe Exclusivos
Evite conflitos de nomes usando nomes de classe descritivos:
4. Organize Vários Apps em Um Projeto
Veja como estruturar um projeto com vários apps personalizados:
5. Boas Práticas para Vários Apps
Organização dos Arquivos
Navegação Entre os Apps
Atualize o método getNavigationInfo() em cada app para oferecer uma navegação fácil:
6. Testando Vários Apps
Ao testar vários apps:
- Teste cada app individualmente primeiro
- Verifique o Serial Monitor para ver conflitos de mensagens
- Verifique se os identificadores exclusivos estão funcionando corretamente
- Teste a navegação entre os diferentes apps
- Monitore o uso de memória com vários apps carregados
Seguindo estas orientações, você pode criar vários aplicativos web personalizados que funcionam juntos sem problemas, sem interferir uns nos outros nem em outros apps da DIYables ESP32 WebApps.
Exemplo do Mundo Real
Quer ver um projeto completo criado com este modelo de app web personalizado? Confira este projeto de sensor de cor, que demonstra como criar uma aplicação web totalmente funcional:
📱 Tutorial do App Web: ESP32 - Sensor de Cor pela Web
Este exemplo mostra uma implementação completa com:
- Exibição de detecção de cor em tempo real
- Interface web interativa para as leituras do sensor
- Comunicação WebSocket para atualizações instantâneas
- Design responsivo para celular
🎥 Tutorial em Vídeo: Assista à construção e à demonstração completas no YouTube
Este projeto é uma excelente referência para entender como adaptar o modelo de app web personalizado aos seus próprios projetos com sensores!