Referência da API da Biblioteca DIYables WebApps - Documentação Completa
Visão Geral
A biblioteca DIYables WebApps oferece uma solução modular completa para criar aplicativos web baseados em WebSocket no Arduino Uno R4 WiFi e no DIYables STEM V4 IoT. Ela inclui vários aplicativos web prontos e um framework flexível para criar aplicativos personalizados. Especialmente otimizada para a plataforma educacional DIYables STEM V4 IoT, com recursos de IoT avançados e integração de sensores embutida.
A biblioteca usa uma arquitetura modular, na qual você inclui apenas os aplicativos web de que precisa, economizando memória e melhorando o desempenho.
Recursos
- Arquitetura Modular: Adicione somente os web apps de que você precisa para otimizar o uso de memória
- Eficiente em Memória: Cada web app pode ser ativado/desativado de forma independente
- Mais de 11 Aplicativos Web Prontos para Usar: Controle completo do Arduino sem conhecimento de programação web
- Framework de Web App Personalizado: Crie seus próprios aplicativos usando o sistema de classe base
- Comunicação em Tempo Real: Baseada em WebSocket para atualizações instantâneas
- Design Responsivo: Funciona em computadores, tablets e dispositivos móveis
- Integração Fácil: API simples baseada em callbacks
- Suporte a Vários Apps: Permite adicionar vários web apps simultaneamente
- Extensível para Outras Plataformas: Atualmente implementado para o Arduino Uno R4 WiFi, mas pode ser estendido para outras plataformas de hardware. Veja DIYables_WebApps_ESP32
Classes Principais
DIYablesWebAppServer
A classe principal do servidor, que gerencia os aplicativos web, as requisições HTTP e a comunicação WebSocket.
Construtor
Cria uma instância do servidor de web apps.
- 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 bem-sucedido, false se falhar
- Caso de uso: Para 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 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 chamado no loop principal.
Retorna true se o WiFi estiver conectado.
Retorna o endereço IP do Arduino como uma string.
Gerenciamento de Aplicativos
Adiciona um aplicativo web ao servidor.
- app: Ponteiro para uma instância de aplicativo web
Remove um aplicativo web pelo seu caminho de URL.
- path: Caminho de URL do aplicativo (por exemplo, "/chat")
Obtém um aplicativo web pelo seu caminho de URL.
- path: Caminho de URL do aplicativo
- 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 todos os aplicativos 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 é fechada.
- ws: Conexão WebSocket fechada
Métodos Comuns
Obtém o caminho de URL desta página.
- Retorna: String do caminho da página
Verifica se a página está atualmente ativada.
- Retorna: true se ativada, false se desativada
Ativa ou desativa a página.
- enable: true para ativar, false para desativar
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 para um cliente WebSocket específico.
- ws: Conexão WebSocket de destino
- message: Mensagem a ser enviada
Transmite (broadcast) uma mensagem para todos os clientes WebSocket conectados.
- message: Mensagem a ser transmitida
Envia conteúdo HTML grande usando codificação de transferência em blocos (chunked).
- client: Interface do cliente web
- html: Conteúdo HTML a ser enviado
Exemplo de Uso
Classes de Aplicativos Web
DIYablesHomePage
Hub central de navegação, com links para todos os aplicativos ativados.
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 de chat web.
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 monitor web.
DIYablesWebDigitalPinsPage
Controle e monitore os pinos digitais 0-13 pela interface web.
Construtor
Caminho da URL
- Caminho: /webdigitalpins
Métodos
Ativa 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 no 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 as mudanças de valor 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: Se o joystick retorna ao centro automaticamente
- sensitivity: Porcentagem mínima de movimento para acionar 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.
Ativa ou desativa o dimensionamento 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 de erro 404 opcional para uma melhor experiência do usuário.
Construtor
Exemplo Básico de Uso
Visão Geral dos Aplicativos Web
Página Inicial
- URL: http://[arduino-ip]/
- Finalidade: Hub central de navegação
- Recursos: Links para todos os aplicativos ativados, status da conexão
Aplicativo WebChat
- URL: http://[arduino-ip]/webchat
- Finalidade: Interface de comunicação bidirecional
- Recursos: Mensagens em tempo real, histórico de mensagens, status do WebSocket
Web Monitor
- URL: http://[arduino-ip]/webmonitor
- Finalidade: Substituto do serial monitor
- Recursos: Saída serial em tempo real, entrada de comandos, tema escuro
Controle de Pinos Digitais Web
- URL: http://[arduino-ip]/webdigitalpins
- Finalidade: Controlar os pinos digitais 0-13
- Recursos: Controle individual de pinos, operações em lote, status em tempo real
Controle de Slider Web
- URL: http://[arduino-ip]/webslider
- Finalidade: Controle analógico/PWM duplo
- Recursos: Dois sliders independentes (0-255), valores predefinidos, retorno em tempo real
Controle de Joystick Web
- URL: http://[arduino-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://[arduino-ip]/webplotter
- Finalidade: Visualização de dados em tempo real
- Recursos: Várias séries de dados, dimensionamento automático, títulos e eixos configuráveis
Comunicação WebSocket
Todos os aplicativos usam WebSocket na porta 81 para comunicação em tempo real:
- URL do WebSocket: ws://[arduino-ip]:81
- Conexão: Reconexão automática em caso de desconexão
- 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 de Pinos Digitais Web
- Da Web: Formato JSON: {"pin": 13, "state": 1}
- Para a Web: Formato JSON: {"pin": 13, "state": 1}
Mensagens do Slider Web
- Da Web: Formato JSON: {"slider1": 128, "slider2": 255}
- Para a Web: Formato JSON: {"slider1": 128, "slider2": 255}
Mensagens do Joystick Web
- 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 apenas os aplicativos 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 ativados: ~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
- Desative os aplicativos não utilizados
- Limite as conexões simultâneas
- Reinicie o Arduino 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
Aplicativos de Exemplo
A biblioteca DIYables WebApps inclui exemplos completos projetados para a plataforma educacional Arduino Uno R4 WiFi e DIYables STEM V4 IoT:
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 retorno 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: Todos os aplicativos executados simultaneamente
Compatibilidade de Hardware
- Recomendado: DIYables STEM V4 IoT (recursos aprimorados, sensores integrados)
- Compatível: Arduino Uno R4 WiFi
Recursos do Tutorial
Tutoriais completos passo a passo disponíveis em:
- Newbiely.com/tutorials/arduino/arduino-uno-r4-wifi-web-apps
- Guias específicos do DIYables STEM V4 IoT e exemplos de integração de sensores
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 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 principal 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 à 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
Para o Arduino Uno R4 WiFi, as interfaces são implementadas usando a biblioteca UnoR4WiFi_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 instancie 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 principal do WebApp funciona em qualquer plataforma
- Extensibilidade: Fácil de adicionar suporte a novo hardware
- Manutenibilidade: O código específico de cada plataforma fica isolado
- Testabilidade: As interfaces podem ser simuladas (mock) para testes unitários
- Consistência: A mesma API em todas as plataformas suportadas
Plataformas Suportadas Atualmente
- ✅ Arduino Uno R4 WiFi: Totalmente implementado e testado
- 🔄 ESP32: Disponível como extensão separada - DIYables_WebApps_ESP32
- 🚀 Futuras Plataformas: Podem ser adicionadas usando o mesmo padrão de interface