Referência da API da Biblioteca DIYables ESP32 WebApps - Documentação Completa
Visão Geral
A biblioteca DIYables ESP32 WebApps oferece uma solução modular completa para criar aplicações web baseadas em WebSocket no ESP32. Ela inclui vários aplicativos web prontos e um framework flexível para criar aplicações personalizadas.
A biblioteca usa uma arquitetura modular, na qual você inclui somente os aplicativos web de que precisa, economizando memória e melhorando o desempenho.
Recursos
- Arquitetura Modular: Adicione somente os apps web de que você precisa para otimizar o uso de memória
- Eficiente em Memória: Cada app web pode ser habilitado/desabilitado de forma independente
- Mais de 11 Aplicações Web Prontas para Uso: Controle completo do ESP32 sem conhecimento de programação web
- Framework de App Web Personalizado: Crie suas próprias aplicações usando o sistema de classe base
- Comunicação em Tempo Real: Baseada em WebSocket para atualizações instantâneas
- Design Responsivo: Funciona em desktop, tablet e dispositivos móveis
- Integração Fácil: API simples baseada em callbacks
- Suporte a Vários Apps: Permite adicionar vários apps web ao mesmo tempo
Classes Principais
DIYablesWebAppServer
A classe de servidor principal, que gerencia as aplicações web, as requisições HTTP e a comunicação WebSocket.
Construtor
Cria uma instância do servidor de apps web.
- httpPort: Porta do servidor HTTP (padrão: 80)
- websocketPort: Porta do WebSocket (padrão: 81)
Métodos
Configuração e Conexão
Inicializa a conexão de rede (para Ethernet ou conexões pré-configuradas) e inicia o servidor web.
- Retorna: true se for bem-sucedido, false se falhar
- Caso de uso: Para o suporte futuro a Ethernet ou quando as credenciais de WiFi já estão pré-configuradas
Inicializa a conexão WiFi e inicia o servidor web.
- ssid: Nome da rede WiFi
- password: Senha do WiFi
- Retorna: true se for bem-sucedido, false se falhar
- Caso de uso: Conexão WiFi padrão com credenciais
Trata as requisições HTTP e a comunicação WebSocket. Deve ser chamada no loop principal.
Retorna true se o WiFi estiver conectado.
Retorna o endereço IP do Arduino como uma string.
Gerenciamento de Aplicações
Adiciona uma aplicação web ao servidor.
- app: Ponteiro para uma instância de aplicação web
Remove uma aplicação web pelo seu caminho de URL.
- path: Caminho de URL da aplicação (por exemplo, "/chat")
Obtém uma aplicação web pelo seu caminho de URL.
- path: Caminho de URL da aplicação
- Retorna: Ponteiro para o app ou nullptr se não for encontrado
Define a página 404 Not Found (opcional).
- page: Instância da página 404
Acesso a Apps Especializados
Obtém a instância da página de pinos digitais, se ela foi adicionada.
- Retorna: Ponteiro para a página de pinos digitais ou nullptr
Obtém a instância da página de slider, se ela foi adicionada.
- Retorna: Ponteiro para a página de slider ou nullptr
Obtém a instância da página de joystick, se ela foi adicionada.
- Retorna: Ponteiro para a página de joystick ou nullptr
Classes Base
DIYablesWebAppPageBase
Classe base abstrata da qual todas as aplicações web herdam. Fornece a funcionalidade comum para o tratamento de HTTP, a comunicação WebSocket e o gerenciamento de páginas.
Construtor
Cria uma instância de página base com o caminho de URL especificado.
- pagePath: Caminho de URL da página (por exemplo, "/web-joystick")
Métodos Virtuais (Devem ser implementados pelas classes derivadas)
Trata as requisições HTTP desta página. Método virtual puro.
- client: Interface do cliente web para enviar a resposta
Trata as mensagens WebSocket desta página. Método virtual puro.
- ws: Interface da conexão WebSocket
- message: Conteúdo da mensagem recebida
- length: Tamanho da mensagem
Retorna a string de identificação da página, usada na exibição das informações de conexão. Método virtual puro.
- Retorna: String de informações da página (por exemplo, "🕹️ Web Joystick: ")
Retorna o HTML do botão de navegação da página inicial. Método virtual puro.
- Retorna: String HTML do cartão de navegação
Métodos Virtuais (Sobrescritas opcionais)
Chamado quando uma nova conexão WebSocket é estabelecida.
- ws: Nova conexão WebSocket
Chamado quando uma conexão WebSocket é encerrada.
- ws: Conexão WebSocket encerrada
Métodos Comuns
Obtém o caminho de URL desta página.
- Retorna: String com o caminho da página
Verifica se a página está habilitada no momento.
- Retorna: true se estiver habilitada, false se estiver desabilitada
Habilita ou desabilita a página.
- enable: true para habilitar, false para desabilitar
Métodos Utilitários
Envia os cabeçalhos HTTP padrão ao cliente.
- client: Interface do cliente web
- contentType: Tipo MIME (padrão: "text/html")
Envia uma mensagem a um cliente WebSocket específico.
- ws: Conexão WebSocket de destino
- message: Mensagem a enviar
Transmite uma mensagem a todos os clientes WebSocket conectados.
- message: Mensagem a transmitir
Envia um conteúdo HTML grande usando codificação de transferência em blocos (chunked).
- client: Interface do cliente web
- html: Conteúdo HTML a enviar
Exemplo de Uso
Classes de Aplicações Web
DIYablesHomePage
Central de navegação que oferece links para todas as aplicações habilitadas.
Construtor
Caminho da URL
- Caminho: / (raiz)
DIYablesWebChatPage
Interface de chat interativa para comunicação bidirecional com o Arduino.
Construtor
Caminho da URL
- Caminho: /webchat
Métodos
Define o callback para as mensagens de chat recebidas.
Envia uma mensagem para a interface do web chat.
DIYablesWebMonitorPage
Serial monitor baseado na web, para saída em tempo real e entrada de comandos.
Construtor
Caminho da URL
- Caminho: /webmonitor
Métodos
Define o callback para as mensagens recebidas do monitor.
Envia uma mensagem para a interface do web monitor.
DIYablesWebDigitalPinsPage
Controle e monitore os pinos digitais 0-13 pela interface web.
Construtor
Caminho da URL
- Caminho: /webdigitalpins
Métodos
Habilita um pino para controle pela web.
- pin: Número do pino (0-13)
- mode: WEB_PIN_OUTPUT ou WEB_PIN_INPUT
Define o callback para operações de escrita no pino (pinos de saída).
Define o callback para operações de leitura do pino (pinos de entrada).
Define o callback para mudanças de modo do pino.
Atualiza o estado do pino em tempo real para os clientes web.
DIYablesWebSliderPage
Controle com dois sliders para aplicações analógicas/PWM.
Construtor
Caminho da URL
- Caminho: /webslider
Métodos
Define o callback para mudanças nos valores dos sliders vindas da web.
- Parâmetros: slider1 (0-255), slider2 (0-255)
Define o callback para quando o cliente web solicita os valores atuais.
Envia os valores dos sliders para a interface web.
DIYablesWebJoystickPage
Controle de joystick 2D para aplicações de robótica e posicionamento.
Construtor
- autoReturn: Define se o joystick volta ao centro automaticamente
- sensitivity: Porcentagem mínima de movimento para disparar as atualizações
Caminho da URL
- Caminho: /webjoystick
Métodos
Define o callback para o movimento do joystick vindo da web.
- Parâmetros: x (-100 a 100), y (-100 a 100)
Define o callback para quando o cliente web solicita a posição atual.
Envia a posição do joystick para a interface web.
Define o comportamento de retorno automático.
Define a sensibilidade do movimento (porcentagem).
DIYablesWebPlotterPage
Visualização de dados em tempo real com suporte a várias séries de dados.
Construtor
Caminho da URL
- Caminho: /webplotter
Métodos
Define o título do gráfico.
Define os rótulos dos eixos.
Habilita ou desabilita o escalonamento automático do eixo Y.
Define o número máximo de pontos de dados a exibir.
Adiciona um ponto de dados a uma série.
Limpa todos os dados do gráfico.
DIYablesNotFoundPage
Página opcional de erro 404, para uma melhor experiência do usuário.
Construtor
Exemplo de Uso Básico
Visão Geral das Aplicações Web
Página Inicial
- URL: http://[esp32-ip]/
- Finalidade: Central de navegação
- Recursos: Links para todas as aplicações habilitadas, status da conexão
Aplicação WebChat
- URL: http://[esp32-ip]/webchat
- Finalidade: Interface de comunicação bidirecional
- Recursos: Mensagens em tempo real, histórico de mensagens, status do WebSocket
Web Monitor
- URL: http://[esp32-ip]/webmonitor
- Finalidade: Substituto do serial monitor
- Recursos: Saída serial em tempo real, entrada de comandos, tema escuro
Controle de Pinos Digitais pela Web
- URL: http://[esp32-ip]/webdigitalpins
- Finalidade: Controlar os pinos digitais 0-13
- Recursos: Controle individual de pinos, operações em lote, status em tempo real
Controle com Slider pela Web
- URL: http://[esp32-ip]/webslider
- Finalidade: Controle analógico/PWM duplo
- Recursos: Dois sliders independentes (0-255), valores predefinidos, feedback em tempo real
Controle com Joystick pela Web
- URL: http://[esp32-ip]/webjoystick
- Finalidade: Controle de posição 2D para robôs/veículos
- Recursos: Controle por toque/mouse, exibição de coordenadas, ajuste de sensibilidade
Web Plotter
- URL: http://[esp32-ip]/webplotter
- Finalidade: Visualização de dados em tempo real
- Recursos: Várias séries de dados, escalonamento automático, títulos e eixos configuráveis
Comunicação WebSocket
Todas as aplicações usam WebSocket na porta 81 para comunicação em tempo real:
- URL do WebSocket: ws://[esp32-ip]:81
- Conexão: Reconexão automática ao desconectar
- Protocolo: Formato de mensagem baseado em texto
Formatos de Mensagem
Mensagens do WebChat
- Da Web: Mensagem de texto direta
- Para a Web: Mensagem de texto direta
Mensagens do Web Monitor
- Da Web: Mensagem de texto direta
- Para a Web: Mensagem de texto direta
Mensagens dos Pinos Digitais Web
- Da Web: Formato JSON: {"pin": 13, "state": 1}
- Para a Web: Formato JSON: {"pin": 13, "state": 1}
Mensagens do Web Slider
- Da Web: Formato JSON: {"slider1": 128, "slider2": 255}
- Para a Web: Formato JSON: {"slider1": 128, "slider2": 255}
Mensagens do Web Joystick
- Da Web: Formato JSON: {"x": 50, "y": -25}
- Para a Web: Formato JSON: {"x": 50, "y": -25}
Mensagens do Web Plotter
- Da Web: Não se aplica (somente exibição)
- Para a Web: Formato JSON: {"series": "temp", "x": 10.5, "y": 23.4}
Tratamento de Erros
A biblioteca inclui tratamento automático de erros para:
- Falhas na conexão WiFi
- Desconexões do WebSocket
- Formatos de mensagem inválidos
- Limites de conexões de clientes
Uso de Memória
Benefícios da Arquitetura Modular: Inclua somente as aplicações web de que você precisa para otimizar o uso de memória.
Uso aproximado de memória por componente:
- DIYablesWebAppServer: ~8KB de Flash, ~2KB de RAM
- DIYablesHomePage: ~3KB de Flash, ~1KB de RAM
- DIYablesWebChatPage: ~6KB de Flash, ~1.5KB de RAM
- DIYablesWebMonitorPage: ~5KB de Flash, ~1.5KB de RAM
- DIYablesWebDigitalPinsPage: ~8KB de Flash, ~2KB de RAM
- DIYablesWebSliderPage: ~6KB de Flash, ~1.5KB de RAM
- DIYablesWebJoystickPage: ~7KB de Flash, ~1.5KB de RAM
- DIYablesWebPlotterPage: ~10KB de Flash, ~2KB de RAM
- Buffer do WebSocket: ~1KB de RAM por conexão
Total com todos os apps habilitados: ~53KB de Flash, ~12KB de RAM
Configuração mínima (servidor + página inicial + 1 app): ~17KB de Flash, ~4.5KB de RAM
Observações de Segurança
- Nenhuma autenticação implementada (adequado somente para redes locais)
- Use somente em redes confiáveis
- Considere adicionar autenticação para implantações públicas
Solução de Problemas
Problemas Comuns
- Não consigo conectar ao WiFi
- Verifique o SSID e a senha
- Verifique se a rede é de 2.4GHz (não de 5GHz)
- Verifique a intensidade do sinal
- A conexão WebSocket falha
- Verifique se o endereço IP está correto
- Verifique as configurações do firewall
- Tente outro navegador
- Alto uso de memória
- Desabilite as aplicações não utilizadas
- Limite as conexões simultâneas
- Reinicie o ESP32 se ocorrer fragmentação de memória
- Resposta lenta
- Verifique a intensidade do sinal WiFi
- Reduza a frequência das mensagens WebSocket
- Use funções de callback mais curtas
Projetos de Exemplo
Aplicações de Exemplo
A biblioteca DIYables ESP32 WebApps inclui exemplos completos projetados para a plataforma educacional ESP32:
Exemplos Disponíveis
- Exemplo Chat: Interface de comunicação bidirecional
- Exemplo WebMonitor: Substituto do serial monitor com recursos aprimorados
- Exemplo WebDigitalPins: Controle todos os pinos digitais com feedback visual
- Exemplo WebSlider: Controle analógico/PWM duplo com valores predefinidos
- Exemplo WebJoystick: Controle de posição 2D para projetos de robótica
- Exemplo MultipleWebApps: Todas as aplicações em execução ao mesmo tempo
Veja a pasta examples/ para projetos completos e a pasta docs/ para instruções detalhadas de configuração.
Interfaces de Abstração de Plataforma
A biblioteca DIYables ESP32 WebApps usa uma camada de abstração de plataforma, com interfaces que permitem o suporte a várias plataformas de hardware. Essas interfaces separam a funcionalidade central do WebApp das implementações específicas de cada plataforma.
Interfaces Principais
IWebClient
Interface para conexões de cliente HTTP.
IWebSocket
Interface para conexões WebSocket com suporte a comunicação bidirecional.
IWebServer
Interface para a funcionalidade de servidor HTTP.
IWebSocketServer
Interface para o servidor WebSocket com gerenciamento de conexões.
INetworkProvider
Interface para o gerenciamento da conectividade de rede.
IServerFactory
Interface de fábrica (factory) para criar implementações específicas de cada plataforma.
Exemplo de Implementação de Plataforma
No ESP32, as interfaces são implementadas usando a biblioteca DIYables_ESP32_WebServer:
Adicionando Suporte a Novas Plataformas
Para adicionar suporte a uma nova plataforma (por exemplo, ESP32):
- Implemente todas as interfaces para a plataforma de destino
- Crie uma ServerFactory que instancia as suas implementações
- Trate o uso de rede e os protocolos WebSocket específicos da plataforma
- Teste com as classes WebApp existentes (nenhuma alteração é necessária)
Exemplo de uso com diferentes plataformas:
Benefícios do Design Baseado em Interfaces
- Independência de Plataforma: A lógica central do WebApp funciona em qualquer plataforma
- Extensibilidade: Fácil de adicionar suporte a novos hardwares
- Manutenibilidade: O código específico de cada plataforma fica isolado
- Testabilidade: As interfaces podem ser simuladas (mock) em testes unitários
- Consistência: A mesma API em todas as plataformas suportadas
Suporte Atual a Plataformas
- ✅ ESP32: Totalmente implementado e testado
- 🔄 ESP32: Disponível como extensão separada - DIYables_WebApps_ESP32
- 🚀 Plataformas Futuras: Podem ser adicionadas usando o mesmo padrão de interface