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

DIYablesWebAppServer(int httpPort = 80, int websocketPort = 81)

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
bool begin()

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
bool begin(const char* ssid, const char* password)

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
void loop()

Trata as requisições HTTP e a comunicação WebSocket. Deve ser chamada no loop principal.

bool isConnected()

Retorna true se o WiFi estiver conectado.

String getIPAddress()

Retorna o endereço IP do Arduino como uma string.

Gerenciamento de Aplicações
void addApp(DIYablesWebAppPageBase* app)

Adiciona uma aplicação web ao servidor.

  • app: Ponteiro para uma instância de aplicação web
void removeApp(const String& path)

Remove uma aplicação web pelo seu caminho de URL.

  • path: Caminho de URL da aplicação (por exemplo, "/chat")
DIYablesWebAppPageBase* getApp(const String& path)

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
void setNotFoundPage(const DIYablesNotFoundPage& page)

Define a página 404 Not Found (opcional).

  • page: Instância da página 404
Acesso a Apps Especializados
DIYablesWebDigitalPinsPage* getWebDigitalPinsPage()

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
DIYablesWebSliderPage* getWebSliderPage()

Obtém a instância da página de slider, se ela foi adicionada.

  • Retorna: Ponteiro para a página de slider ou nullptr
DIYablesWebJoystickPage* getWebJoystickPage()

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

DIYablesWebAppPageBase(const String& pagePath)

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)

virtual void handleHTTPRequest(IWebClient& client) = 0

Trata as requisições HTTP desta página. Método virtual puro.

  • client: Interface do cliente web para enviar a resposta
virtual void handleWebSocketMessage(IWebSocket& ws, const char* message, uint16_t length) = 0

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
virtual const char* getPageInfo() const = 0

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: ")
virtual String getNavigationInfo() const = 0

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)

virtual void onWebSocketConnection(IWebSocket& ws)

Chamado quando uma nova conexão WebSocket é estabelecida.

  • ws: Nova conexão WebSocket
virtual void onWebSocketClose(IWebSocket& ws)

Chamado quando uma conexão WebSocket é encerrada.

  • ws: Conexão WebSocket encerrada

Métodos Comuns

const char* getPagePath() const

Obtém o caminho de URL desta página.

  • Retorna: String com o caminho da página
bool isEnabled() const

Verifica se a página está habilitada no momento.

  • Retorna: true se estiver habilitada, false se estiver desabilitada
void setEnabled(bool enable)

Habilita ou desabilita a página.

  • enable: true para habilitar, false para desabilitar

Métodos Utilitários

void sendHTTPHeader(IWebClient& client, const char* contentType = "text/html")

Envia os cabeçalhos HTTP padrão ao cliente.

  • client: Interface do cliente web
  • contentType: Tipo MIME (padrão: "text/html")
void sendWebSocketMessage(IWebSocket& ws, const char* message)

Envia uma mensagem a um cliente WebSocket específico.

  • ws: Conexão WebSocket de destino
  • message: Mensagem a enviar
void broadcastToAllClients(const char* message)

Transmite uma mensagem a todos os clientes WebSocket conectados.

  • message: Mensagem a transmitir
void sendLargeHTML(IWebClient& client, const char* html)

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

class CustomPage : public DIYablesWebAppPageBase { public: CustomPage() : DIYablesWebAppPageBase("/custom") {} void handleHTTPRequest(IWebClient& client) override { sendHTTPHeader(client); client.println("<html><body>Custom Page</body></html>"); } void handleWebSocketMessage(IWebSocket& ws, const char* message, uint16_t length) override { // Handle WebSocket messages sendWebSocketMessage(ws, "Response: " + String(message)); } const char* getPageInfo() const override { return " 🔧 Custom Page: "; } String getNavigationInfo() const override { return "<a href=\"/custom\" class=\"app-card custom\">" "<h3>🔧 Custom</h3><p>Custom functionality</p></a>"; } };

Classes de Aplicações Web

DIYablesHomePage

Central de navegação que oferece links para todas as aplicações habilitadas.

Construtor

DIYablesHomePage()

Caminho da URL

  • Caminho: / (raiz)

DIYablesWebChatPage

Interface de chat interativa para comunicação bidirecional com o Arduino.

Construtor

DIYablesWebChatPage()

Caminho da URL

  • Caminho: /webchat

Métodos

void onWebChatMessage(std::function<void(const String&)> callback)

Define o callback para as mensagens de chat recebidas.

void sendToWebChat(const String& message)

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

DIYablesWebMonitorPage()

Caminho da URL

  • Caminho: /webmonitor

Métodos

void onWebMonitorMessage(std::function<void(const String&)> callback)

Define o callback para as mensagens recebidas do monitor.

void sendToWebMonitor(const String& message)

Envia uma mensagem para a interface do web monitor.

DIYablesWebDigitalPinsPage

Controle e monitore os pinos digitais 0-13 pela interface web.

Construtor

DIYablesWebDigitalPinsPage()

Caminho da URL

  • Caminho: /webdigitalpins

Métodos

void enablePin(int pin, int mode)

Habilita um pino para controle pela web.

  • pin: Número do pino (0-13)
  • mode: WEB_PIN_OUTPUT ou WEB_PIN_INPUT
void onPinWrite(std::function<void(int, int)> callback)

Define o callback para operações de escrita no pino (pinos de saída).

void onPinRead(std::function<int(int)> callback)

Define o callback para operações de leitura do pino (pinos de entrada).

void onPinModeChange(std::function<void(int, int)> callback)

Define o callback para mudanças de modo do pino.

void updatePinState(int pin, int state)

Atualiza o estado do pino em tempo real para os clientes web.

DIYablesWebSliderPage

Controle com dois sliders para aplicações analógicas/PWM.

Construtor

DIYablesWebSliderPage()

Caminho da URL

  • Caminho: /webslider

Métodos

void onSliderValueFromWeb(std::function<void(int, int)> callback)

Define o callback para mudanças nos valores dos sliders vindas da web.

  • Parâmetros: slider1 (0-255), slider2 (0-255)
void onSliderValueToWeb(std::function<void()> callback)

Define o callback para quando o cliente web solicita os valores atuais.

void sendToWebSlider(int slider1, int slider2)

Envia os valores dos sliders para a interface web.

DIYablesWebJoystickPage

Controle de joystick 2D para aplicações de robótica e posicionamento.

Construtor

DIYablesWebJoystickPage(bool autoReturn = true, float sensitivity = 10.0)
  • 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

void onJoystickValueFromWeb(std::function<void(int, int)> callback)

Define o callback para o movimento do joystick vindo da web.

  • Parâmetros: x (-100 a 100), y (-100 a 100)
void onJoystickValueToWeb(std::function<void()> callback)

Define o callback para quando o cliente web solicita a posição atual.

void sendToWebJoystick(int x, int y)

Envia a posição do joystick para a interface web.

void setAutoReturn(bool autoReturn)

Define o comportamento de retorno automático.

void setSensitivity(float sensitivity)

Define a sensibilidade do movimento (porcentagem).

DIYablesWebPlotterPage

Visualização de dados em tempo real com suporte a várias séries de dados.

Construtor

DIYablesWebPlotterPage()

Caminho da URL

  • Caminho: /webplotter

Métodos

void setPlotTitle(const String& title)

Define o título do gráfico.

void setAxisLabels(const String& xLabel, const String& yLabel)

Define os rótulos dos eixos.

void enableAutoScale(bool enable)

Habilita ou desabilita o escalonamento automático do eixo Y.

void setMaxSamples(int maxSamples)

Define o número máximo de pontos de dados a exibir.

void addDataPoint(const String& seriesName, float x, float y)

Adiciona um ponto de dados a uma série.

void clearPlot()

Limpa todos os dados do gráfico.

DIYablesNotFoundPage

Página opcional de erro 404, para uma melhor experiência do usuário.

Construtor

DIYablesNotFoundPage()

Exemplo de Uso Básico

#include <DIYablesWebApps.h> // WiFi credentials const char* ssid = "YOUR_WIFI_SSID"; const char* password = "YOUR_WIFI_PASSWORD"; // Create server and web applications DIYablesWebAppServer webAppsServer(80, 81); DIYablesHomePage homePage; DIYablesWebChatPage chatPage; DIYablesWebMonitorPage monitorPage; void setup() { Serial.begin(9600); // Add only the applications you need webAppsServer.addApp(&homePage); webAppsServer.addApp(&chatPage); webAppsServer.addApp(&monitorPage); // Optional: Add 404 page webAppsServer.setNotFoundPage(DIYablesNotFoundPage()); // Start server if (webAppsServer.begin(ssid, password)) { Serial.println("Server started successfully"); Serial.print("IP: "); Serial.println(webAppsServer.getIPAddress()); } // Setup callbacks chatPage.onWebChatMessage([](const String& message) { Serial.println("Chat: " + message); chatPage.sendToWebChat("Arduino received: " + message); }); } void loop() { webAppsServer.loop(); delay(10); }

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

Compatibilidade com Navegadores

Navegadores compatíveis:

  • Chrome 50+
  • Firefox 45+
  • Safari 10+
  • Edge 79+
  • Navegadores móveis (iOS Safari, Chrome Mobile)

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

  1. 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

  1. A conexão WebSocket falha

- Verifique se o endereço IP está correto

- Verifique as configurações do firewall

- Tente outro navegador

  1. 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

  1. 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.

class IWebClient { public: virtual ~IWebClient() = default; // Stream interface methods virtual int available() = 0; virtual int read() = 0; virtual int peek() = 0; virtual size_t write(uint8_t data) = 0; virtual size_t write(const uint8_t* buffer, size_t size) = 0; virtual void flush() = 0; // Connection management virtual bool connected() = 0; virtual void stop() = 0; // Convenience methods virtual void print(const String& str) = 0; virtual void println(const String& str) = 0; };

IWebSocket

Interface para conexões WebSocket com suporte a comunicação bidirecional.

class IWebSocket { public: enum DataType { TEXT = 1, BINARY = 2 }; enum CloseCode { NORMAL_CLOSURE = 1000, GOING_AWAY = 1001, PROTOCOL_ERROR = 1002, UNSUPPORTED_DATA = 1003, POLICY_VIOLATION = 1008, MESSAGE_TOO_BIG = 1009, INTERNAL_ERROR = 1011 }; virtual ~IWebSocket() = default; // Message handling virtual void sendText(const char* message) = 0; virtual void sendBinary(const uint8_t* data, size_t length) = 0; virtual bool isConnected() const = 0; virtual void close(CloseCode code = NORMAL_CLOSURE, const char* reason = nullptr) = 0; // Event callbacks virtual void onMessage(std::function<void(IWebSocket*, DataType, const char*, uint16_t)> callback) = 0; virtual void onClose(std::function<void(IWebSocket*, CloseCode, const char*, uint16_t)> callback) = 0; };

IWebServer

Interface para a funcionalidade de servidor HTTP.

class IWebServer { public: virtual ~IWebServer() = default; // Server lifecycle virtual bool begin() = 0; virtual void stop() = 0; virtual IWebClient* available() = 0; // Configuration virtual void setPort(uint16_t port) = 0; virtual uint16_t getPort() const = 0; };

IWebSocketServer

Interface para o servidor WebSocket com gerenciamento de conexões.

class IWebSocketServer { public: using ConnectionCallback = std::function<void(IWebSocket*)>; using MessageCallback = std::function<void(IWebSocket*, IWebSocket::DataType, const char*, uint16_t)>; virtual ~IWebSocketServer() = default; // Server lifecycle virtual bool begin() = 0; virtual void stop() = 0; virtual void listen() = 0; // Event handling virtual void onConnection(ConnectionCallback callback) = 0; virtual void onMessage(MessageCallback callback) = 0; // Broadcasting virtual void broadcastText(const char* message) = 0; virtual void broadcastBinary(const uint8_t* data, size_t length) = 0; // Configuration virtual void setPort(uint16_t port) = 0; virtual uint16_t getPort() const = 0; };

INetworkProvider

Interface para o gerenciamento da conectividade de rede.

class INetworkProvider { public: virtual ~INetworkProvider() = default; // Network lifecycle virtual bool begin(const char* ssid, const char* password) = 0; virtual void end() = 0; virtual bool isConnected() = 0; // Network information virtual String getLocalIP() = 0; virtual String getSSID() = 0; virtual int32_t getRSSI() = 0; };

IServerFactory

Interface de fábrica (factory) para criar implementações específicas de cada plataforma.

class IServerFactory { public: virtual ~IServerFactory() = default; // Factory methods virtual INetworkProvider* createNetworkProvider() = 0; virtual IWebServer* createWebServer(uint16_t port) = 0; virtual IWebSocketServer* createWebSocketServer(uint16_t port) = 0; // Platform information virtual String getPlatformName() const = 0; };

Exemplo de Implementação de Plataforma

No ESP32, as interfaces são implementadas usando a biblioteca DIYables_ESP32_WebServer:

class ESP32ServerFactory : public IServerFactory { public: INetworkProvider* createNetworkProvider() override { return new ESP32NetworkProvider(); } IWebServer* createWebServer(uint16_t port) override { return new ESP32WebServer(port); } IWebSocketServer* createWebSocketServer(uint16_t port) override { return new ESP32WebSocketServer(port); } String getPlatformName() const override { return "ESP32"; } };

Adicionando Suporte a Novas Plataformas

Para adicionar suporte a uma nova plataforma (por exemplo, ESP32):

  1. Implemente todas as interfaces para a plataforma de destino
  2. Crie uma ServerFactory que instancia as suas implementações
  3. Trate o uso de rede e os protocolos WebSocket específicos da plataforma
  4. Teste com as classes WebApp existentes (nenhuma alteração é necessária)

Exemplo de uso com diferentes plataformas:

ESP32ServerFactory factory; DIYablesWebAppServer server(factory, 80, 81); // ESP32 (hypothetical) ESP32ServerFactory esp32Factory; DIYablesWebAppServer esp32Server(esp32Factory, 80, 81);

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

※ NOSSAS MENSAGENS

  • Fique à vontade para compartilhar o link deste tutorial. Porém, por favor, não use nosso conteúdo em outros sites. Investimos muito esforço e tempo para criar este conteúdo, por favor respeite nosso trabalho!