Exemplo Arduino Custom WebApp - Tutorial Simples de Interface Web para Iniciantes
Visão Geral
Este exemplo oferece um modelo completo para você criar seus próprios aplicativos web personalizados, que se integram perfeitamente à biblioteca DIYables WebApps.

O modelo CustomWebApp é perfeito para iniciantes que querem adicionar a sua própria interface web ao ecossistema DIYables 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 Arduino via WebSocket, que pode:
- Enviar mensagens de texto do navegador web para o Arduino instantaneamente via WebSocket
- Receber mensagens do Arduino 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 for perdida
- Funcionar em dispositivos móveis com design responsivo
Projetado para o Arduino Uno R4 WiFi e o DIYables STEM V4 IoT - este modelo se integra perfeitamente aos web apps DIYables existentes e fornece a base para você criar suas próprias interfaces IoT personalizadas!
Este modelo fornece o código mínimo para você começar. Os usuários podem desenvolver seus próprios aplicativos web sofisticados modificando este modelo. Conhecimento básico de programação web (HTML, CSS, JavaScript) é recomendado para personalizar a interface web e adicionar recursos avançados.
O Que Você Vai Aprender
- Como criar um web app personalizado que se integra à biblioteca DIYables WebApps
- Como adicionar a sua página personalizada ao ecossistema de web apps DIYables
- Como enviar mensagens de texto do navegador web para o Arduino
- Como enviar dados do Arduino 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 do DIYables WebApps para um desenvolvimento rápido
Recursos
- Integração com o DIYables WebApps: Integra-se perfeitamente ao ecossistema da biblioteca DIYables 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 aplicativos sofisticados
- 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ções avançadas
- 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
Hardware Necessário
Or you can buy the following kits:
| 1 | × | DIYables STEM V4 IoT Starter Kit (Arduino included) | |
| 1 | × | DIYables STEM V4B IoT Starter Kit (Arduino included) | |
| 1 | × | DIYables Sensor Kit (18 sensors/displays) |
Como Começar
Você pode começar a criar o seu web app personalizado para a placa Arduino Uno R4/DIYables STEM V4 IoT seguindo estas etapas principais:
- Execute o Modelo de App Personalizado Padrão na Sua Placa Arduino
- Teste e Verifique se o Web App Personalizado Padrão Funciona Corretamente
- Entenda o Protocolo de Comunicação e Como Ele Funciona nos Bastidores
- Modifique o Modelo para Adaptá-lo ao Seu Aplicativo
- Gerencie Vários Web Apps Personalizados - Guia Essencial de Prevenção de Conflitos
Vamos começar, um por um.
Execute o Modelo de App Personalizado Padrão na Sua Placa Arduino
Passos Rápidos
- Se esta é a sua primeira vez usando o Arduino Uno R4 WiFi/DIYables STEM V4 IoT, consulte o tutorial sobre como configurar o ambiente para o Arduino Uno R4 WiFi/DIYables STEM V4 IoT no Arduino IDE
- Conecte a placa Arduino Uno R4/DIYables STEM V4 IoT ao seu computador usando um cabo USB
- Abra o Arduino IDE no seu computador
- Selecione a placa Arduino Uno R4 apropriada (por exemplo, Arduino Uno R4 WiFi) e a porta COM
- Vá até o ícone Libraries na barra lateral esquerda do Arduino IDE
- Pesquise por "DIYables WebApps" e encontre a biblioteca DIYables WebApps da DIYables
- Clique no botão Install para instalar a biblioteca

- Será solicitado que você instale algumas outras dependências de bibliotecas
- Clique no botão Install All para instalar todas as dependências da biblioteca

- No Arduino IDE, vá em File > Examples > DIYables WebApps > CustomWebApp
- Você verá 4 arquivos que formam o modelo completo do web app personalizado:
- CustomWebApp.ino - Código principal do Arduino (é aqui que você adiciona a sua lógica personalizada!)
- CustomWebApp.h - Arquivo de cabeçalho (define a interface com a biblioteca DIYables 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 a sua interface web aqui!)
- Configure as definições de WiFi alterando estas linhas em CustomWebApp.ino:
Etapa 5: Fazer Upload e Testar
- Clique no botão Upload no Arduino IDE para fazer o upload do código para o Arduino UNO R4/DIYables STEM V4 IoT
- Abra o Serial Monitor para ver o status da conexão
- Anote o endereço IP exibido no Serial Monitor
- Abra o Serial Monitor
- Confira o resultado no Serial Monitor. Ele se parece com o abaixo
- Se você não vir nada, reinicie a placa Arduino.
- 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:

- Ou 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 Web App Personalizado Padrão Funciona Corretamente
Ao executar 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 Send: Clique para enviar a sua mensagem (ou pressione Enter)
- Exibição das Mensagens do Arduino: Mostra as mensagens recebidas do Arduino em texto azul
Comportamento do Arduino:
- Resposta Eco: Quando você envia "Hello" pela web, o Arduino responde com "Echo: Hello"
- Atualizações Periódicas: O Arduino 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 Send 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 nos Bastidores
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 "Identificadores de App") que ajudam o código do Arduino e os clientes web a filtrar as mensagens que pertencem a eles. Isso é essencial porque a sua aplicação pode incluir vários web apps, e cada app precisa processar somente as suas próprias mensagens, ignorando as demais:
Lado do Arduino (CustomWebApp.h e CustomWebApp.cpp)
Lado do JavaScript (custom_page_html.h)
Benefícios deste design:
- Fonte única de 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 web app personalizado para adaptá-lo ao seu projeto. No entanto, ao criar mais de um app personalizado, lembre-se de alterá-lo para evitar conflitos.
- Ao alterar o identificador, garanta que o valor no JavaScript (arquivo .h) e no código do Arduino (arquivo .cpp) seja o mesmo (por exemplo, ambos usam "TEMP:" ou ambos usam "SENSOR:").
- Identificadores pré-reservados pelos apps integrados: Os identificadores a seguir já são usados pelos aplicativos integrados do DIYables WebApps e devem ser evitados:
- Identificadores de app principais: "CHAT:", "MONITOR:", "PLOTTER:", "DIGITAL_PINS:", "JOYSTICK:", "SLIDER:", "TABLE:", "RTC:", "ROTATOR:", "GAUGE:"
- Identificadores de subprotocolo: "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 acrescenta automaticamente o identificador do app (que é "CUSTOM:" neste modelo) usando a constante APP_IDENTIFIER e então envia a mensagem ao Arduino via WebSocket. A mensagem realmente enviada é: CUSTOM:Hello
- A biblioteca DIYables 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 então repassa a mensagem restante Hello chamando a função de callback implementada no seu arquivo .ino
- A sua aplicação trata a mensagem: A 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 uma resposta
- A sua aplicação chama sendToWeb(): No seu arquivo .ino, você chama customPage.sendToWeb("Temperature: 25°C") para enviar dados ao navegador web
- A classe CustomWebAppPage adiciona o identificador e faz o broadcast: A classe CustomWebAppPage adiciona automaticamente o identificador do app, usando a sua constante APP_IDENTIFIER, à sua mensagem e faz o broadcast de CUSTOM:Temperature: 25°C para todos os clientes web conectados via WebSocket
- O JavaScript recebe e filtra a mensagem: O navegador web recebe CUSTOM:Temperature: 25°C por meio do manipulador de eventos ws.onmessage, mas o JavaScript só processa 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 maneiras diferentes, dependendo das necessidades da sua aplicação
- CustomWebApp.ino - Sketch principal do Arduino com a lógica da sua aplicação
- CustomWebApp.h - Arquivo de cabeçalho que define a classe da página personalizada (interface da 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 Arduino:
Quando você digita uma mensagem na interface web e clica no botão de enviar, por exemplo: Hello, acontece o fluxo abaixo:
Do Arduino para a Página Web:
Quando o seu Arduino 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 ao Seu Aplicativo
O modelo foi projetado para ser facilmente personalizável para as suas necessidades específicas. Veja como adaptá-lo:
1. Integração de Hardware
Adicione a Inicialização do Hardware
Na função setup() de CustomWebApp.ino:
Trate Comandos Personalizados
Estenda a função de callback para tratar os seus comandos personalizados:
Envie Dados de Sensores em Tempo Real
2. Personalização da Interface Web
Modifique o Layout HTML
Edite o HTML em custom_page_html.h para alterar a interface:
Personalize o Processamento do JavaScript
Atualize a função ws.onmessage para tratar tipos de dados específicos:
Adicione Estilos
Personalize o CSS para a sua aplicação:
Outras Personalizações
Além de modificar a interface web e a integração de hardware, você também pode personalizar como o seu app aparece no ecossistema DIYables WebApps:
1. Personalize o Caminho do App
Você pode alterar o caminho da URL em que o seu web app personalizado fica acessível, 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 seu 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 minúsculas e hifens: Siga as convenções de URLs da web para melhor compatibilidade
2. Personalize o Cartão do App na Página Inicial
Você pode personalizar como o seu app aparece na página inicial do DIYables WebApps modificando o método getNavigationInfo() na sua implementação:
Cartão de App Básico:
Cartão de App Avançado com CSS Inline:
Gerencie Vários Web Apps Personalizados - Guia Essencial de Prevenção de Conflitos
Ao desenvolver vários aplicativos web personalizados, é fundamental evitar conflitos entre os diferentes apps. Suponha que queremos adicionar três apps personalizados chamados "Temperature Monitor", "Motor Controller" e "Sensor Dashboard" ao nosso projeto Arduino. Veja como garantir que eles funcionem juntos de forma harmoniosa:
1. Use Identificadores de App Exclusivos
Cada web app 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 web app 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 Único 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 em busca de 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 diretrizes, você pode criar vários aplicativos web personalizados que funcionam juntos sem interferir uns nos outros nem em outros DIYables WebApps.
Exemplo do Mundo Real
Quer ver um projeto completo criado com este modelo de web app personalizado? Confira este projeto de sensor de cor, que demonstra como criar um aplicativo web totalmente funcional:
📱 Tutorial do Web App: Arduino Uno R4 - Sensor de Cor via 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 web app personalizado aos seus próprios projetos de sensor!