Painel Web de Teste e Diagnóstico de GPIOs com ESP32

Quando desenvolvemos projetos com microcontroladores, montamos protótipos em protoboards ou finalizamos a soldagem de placas de circuito impresso, surge uma tarefa repetitiva: testar individualmente cada pino e periférico. Tradicionalmente, isso exige escrever programas de teste temporários, compilar e regravar o microcontrolador dezenas de vezes para verificar se um relé atraca, se um botão está funcionando ou se há curto-circuito em uma trilha.

O projeto de código aberto ROBOBUILDERS RB0718 resolve esse problema transformando a placa ESP32 em um gabarito de bancada completo e portátil. Ao ligar a alimentação, o microcontrolador sobe um ponto de acesso sem fio autônomo com Portal Captivo. Você se conecta diretamente pelo celular ou computador — sem depender de roteadores ou internet — e ganha acesso a um painel gráfico e a uma API REST para acionar saídas, ler entradas e calibrar pulsos em tempo real.

Neste artigo, vamos explorar a fundo o funcionamento do projeto disponível no repositório oficial da RoboBuilders no GitHub, detalhando o que cada recurso faz, como a arquitetura foi planejada e o passo a passo para compilar e usar na sua bancada.

1. Visão Geral do Projeto

O ROBOBUILDERS RB0718 é um firmware de teste e diagnóstico de hardware (Hardware Diagnostic & Board Test) concebido para a placa de desenvolvimento ESP32 DevKit equipada com o módulo de radiofrequência ESP32-WROOM-32 e conector USB Type-C.

Interface web de diagnóstico do projeto RB0718 no ESP32 exibindo controle de GPIOs e teste de hardware

Para que serve o projeto na prática?

Validação Rápida de Bancada: Permite testar LEDs, buzinas, optoacopladores, módulos de relé e sensores sem escrever uma única linha de código descartável.
Homologação e Controle de Qualidade (QC): Em ambientes educacionais ou de produção, possibilita checar rapidamente se todos os pinos de uma placa recém-adquirida estão saudáveis antes de iniciar uma montagem complexa.
Controle Remoto sem Infraestrutura: Por operar em modo SoftAP autônomo, o sistema funciona em qualquer local: bancadas industriais, veículos, feiras de robótica e oficinas sem rede Wi-Fi local.
Acionamento Local via API REST: Disponibiliza rotas HTTP estruturadas em JSON, permitindo que scripts de bancada em Python, Shell ou Node.js enviem comandos automatizados para a placa.

2. Especificações de Hardware

A aplicação foi otimizada para aproveitar os recursos de processamento dual-core e a memória Flash SPI do microcontrolador ESP32:

Item	Especificação Detalhada
Identificador do Projeto	ROBOBUILDERS RB0718
Placa de Referência	ESP32 DevKit V1 / NodeMCU-32S (conector USB Type-C)
Microcontrolador	ESP32-WROOM-32 (Xtensa® Dual-Core 32-bit LX6 operando a 240 MHz)
Capacidade de Memória	4 MB de Memória Flash SPI externa e 520 KB de SRAM interna
Conexão de Dados	Porta USB Type-C com interface de comunicação serial nativa
Conversor USB-Serial	Chip de ponte CH340C ou CP2102 com circuito auto-reset integrado
LED Onboard (Built-in)	LED azul acoplado diretamente à GPIO 2 (ou GPIO 23 conforme a variante)
Botões Táteis Físicos	Botão `BOOT / IO0` (GPIO 0) e Botão `EN / RST` (Reset de hardware)
Níveis Lógicos das GPIOs	3.3V DC (máximo de 40 mA por pino; corrente recomendada de até 12 mA)
Tensão de Alimentação	5V DC via conector USB Type-C ou 5V a 9V DC pelo pino `VIN`

⚠️ Atenção elétrica: as portas GPIO do ESP32 toleram apenas 3,3V. Conectar sinais lógicos de 5V diretamente nas entradas sem circuito divisor de tensão resistivo ou conversor de nível lógico bidirecional pode queimar os transistores internos do chip.

3. Mapeamento de Pinos (Pinout Oficial)

O firmware mapeia de forma segura 24 pinos do barramento de expansão, separando claramente os pinos de uso geral daqueles com restrições elétricas de arquitetura:

Periférico / Pino	GPIO (ESP32)	Direção Padrão	Nível / Lógica	Descrição Técnica
💡 LED Built-in	`GPIO 2`	OUTPUT	Nível HIGH (3.3V)	LED onboard indicador de atividade e status visual da placa
🔘 Botão Físico BOOT	`GPIO 0`	INPUT_PULLUP	Nível LOW (0V)	Chave de usuário e pino de bootstrapping de inicialização
⚙️ GPIOs Digitais de E/S	`4, 5, 12, 13, 14, 15, 16, 17, 18, 19, 21, 22, 23, 25, 26, 27, 32, 33`	OUTPUT / INPUT	Configurável	Barramento digital completo para relés, transistores e atuadores
📥 Pinos Input-Only	`34, 35, 36 (VP), 39 (VN)`	INPUT	Apenas Entrada	Entradas analógicas ADC1. Não possuem resistores pull-up ou transistores de saída
🔌 UART0 Serial	`GPIO 1 (TX) / GPIO 3 (RX)`	UART Hardware	115.200 bps	Linha de comunicação serial conectada ao chip de conversão USB Type-C

Por que os pinos 34, 35, 36 e 39 são especiais?

No circuito interno do silício do ESP32, as portas GPI 34, 35, 36 e 39 são conectadas exclusivamente ao conversor analógico-digital ADC1. Elas não possuem transistores de acionamento push-pull nem resistores internos de pull-up/pull-down. Por essa razão, a interface web trava essas portas como apenas leitura (Input-Only), protegendo o hardware de configurações impossíveis.

4. Recursos do Painel Web

A interface gráfica foi construída como uma Single Page Application (SPA) em modo escuro (Dark Mode), com visual moderno e responsivo para celulares e monitores de bancada:

Recursos do Painel Web RB0718 com teste de LED, Relé, Botão Boot e mapeamento de GPIOs

4.1 Seção 1 — Teste Rápido de Hardware

Focada em checagens imediatas na bancada:

Card do LED Onboard: Permite alternar o estado da saída (Ligar/Desligar) ou disparar um pulso de piscar (Piscar 500ms).
Card do Relé de Potência: Permite ligar o relé ou disparar um pulso de acionamento de 1 segundo (Pulso 1s), ideal para testar travas elétricas, solenoides ou lâmpadas.
Card da Chave BOOT (GPIO 0): Mostra em tempo real se o botão físico da placa está solto (SOLTO - HIGH) ou sendo mantido pressionado (PRESSIONADO - LOW).
Telemetria do Microcontrolador: Exibe a frequência do clock (240 MHz), o tempo ininterrupto de atividade (Uptime) e a quantidade de memória RAM Heap livre.

4.2 Seção 2 — Mapeamento & Controle Geral de GPIOs

Controle Individual: Cada pino possui seu próprio cartão interativo. Clicar sobre o card comuta o nível de saída entre 0V (LOW) e 3,3V (HIGH).
Comandos em Lote: Os botões ”⚡ Ligar Todas as Saídas” e ”🛑 Desligar Todas” acionam ou desenergizam todos os pinos de saída simultaneamente com um único clique.
Configuração de Modo (Ícone ⚙️): Permite alterar dinamicamente a função do pino entre Saída Digital (OUTPUT) e Entrada com Pull-Up (INPUT_PULLUP).
Leitura em Tempo Real: Pinos configurados como entrada analógica ou digital exibem o valor de leitura atualizado automaticamente na tela.

5. Documentação da API REST

Além da interface visual no navegador, o firmware embarca um servidor HTTP assíncrono que responde a requisições no formato RESTful JSON. Qualquer equipamento na rede Wi-Fi pode controlar a placa por software.

`GET /api/status`

Retorna a telemetria do processador e o estado de todas as portas mapeadas:

curl http://192.168.4.1/api/status

Resposta JSON:

{
  "uptime": 42,
  "free_heap": 218450,
  "chip_model": "ESP32-D0WDQ6",
  "cpu_freq": 240,
  "pins": [
    { "pin": 2, "mode": 0, "val": 1 },
    { "pin": 0, "mode": 1, "val": 1 },
    { "pin": 16, "mode": 0, "val": 0 },
    { "pin": 34, "mode": 1, "val": 0 }
  ]
}

`GET /api/toggle?pin=<gpio>`

Inverte imediatamente o estado lógico da porta digital (de 0 para 1 ou de 1 para 0):

# Alterna o estado do relé conectado na GPIO 16
curl "http://192.168.4.1/api/toggle?pin=16"

`GET /api/pulse?pin=<gpio>&ms=<tempo>`

Dispara um pulso em nível alto (3.3V) pelo tempo definido em milissegundos, retornando automaticamente para nível baixo:

# Gera um pulso de 500 ms na GPIO 2 (pisca o LED)
curl "http://192.168.4.1/api/pulse?pin=2&ms=500"

`GET /api/mode?pin=<gpio>&mode=<0_ou_1>`

Muda o papel do pino em tempo de execução:

mode=0: Configura como Saída Digital (OUTPUT).
mode=1: Configura como Entrada com Pull-Up (INPUT_PULLUP).

# Configura a GPIO 4 como saída digital
curl "http://192.168.4.1/api/mode?pin=4&mode=0"

`GET /api/all?state=<0_ou_1>`

Comuta todas as portas de saída simultaneamente:

# Liga todas as saídas (3.3V)
curl "http://192.168.4.1/api/all?state=1"

# Desliga todas as saídas (0V)
curl "http://192.168.4.1/api/all?state=0"

6. Estrutura do Repositório

O projeto foi organizado de maneira modular para suportar tanto fluxos profissionais de compilação via terminal quanto a clássica Arduino IDE:

📁 Documentação da placa e projeto WEB/
│
├── 📁 include/
│   └── web_page.h               --> Código HTML5, CSS3 e JS armazenado em PROGMEM
│
├── 📁 src/
│   └── main.cpp                 --> Código-fonte principal em C++ (PlatformIO)
│
├── 📁 ROBOBUILDERS_RB0718/      --> Versão empacotada para a Arduino IDE
│   ├── ROBOBUILDERS_RB0718.ino  --> Sketch Arduino
│   └── web_page.h               --> Interface web para compilação no Arduino
│
├── 📁 img/                      --> Imagens e diagramas da documentação
│   └── TELA-INICIAL.png
│
├── platformio.ini               --> Configuração de compilação do PlatformIO
└── README.md                    --> Documentação técnica resumida do GitHub

Economia inteligente de memória com `PROGMEM`

O arquivo web_page.h guarda todo o código visual (HTML, estilo CSS e lógica JavaScript) em uma única string armazenada na memória Flash SPI por meio da diretiva PROGMEM. Isso significa que a interface gráfica completa não consome a valiosa memória RAM dinâmica (DRAM) do ESP32, garantindo que o servidor web responda com estabilidade mesmo sob múltiplos acessos simultâneos.

7. Como Compilar e Gravar via PlatformIO CLI

O método recomendado pelo repositório utiliza o PlatformIO Core (CLI), dispensando interfaces pesadas e permitindo compilar diretamente pelo terminal:

Como obter apenas a pasta do projeto:

Para não baixar todos os outros arquivos do monorepo da RoboBuilders, você pode clonar exclusivamente esta pasta usando o recurso nativo Sparse-Checkout do Git:

mkdir esp32-painel && cd esp32-painel
git init
git remote add origin https://github.com/luanvieiramendes/ROBOBUILDERS.git
git config core.sparseCheckout true
git sparse-checkout set "RB0718/Documentação da placa e projeto WEB"
git pull --depth=1 origin main
cd "RB0718/Documentação da placa e projeto WEB"

(Ou baixe diretamente o arquivo .zip da pasta através do serviço [DownGit](https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/luanvieiramendes/ROBOBUILDERS/tree/main/RB0718/Documentação da placa e projeto WEB)).

Comandos de compilação e gravação:

Compilar o firmware:
```
pio run
```
(Na primeira execução, o PlatformIO baixará automaticamente a toolchain Xtensa e a biblioteca ArduinoJson).
Gravar na placa via USB Type-C: Conecte a placa ao computador com um cabo de dados e execute:
```
pio run -t upload
```
Gravar indicando a porta manualmente: Se tiver mais de uma porta COM conectada:
```
pio run -t upload --upload-port COM3
```
Abrir o Monitor Serial: Para acompanhar a inicialização da placa e os registros de rede a 115.200 bps:
```
pio device monitor
```
Limpar arquivos de compilação:
```
pio run -t clean
```

8. Opção Alternativa: Arduino IDE

Se preferir utilizar a interface tradicional da Arduino IDE:

Abra a Arduino IDE e acerte as configurações de suporte ao ESP32:
- Vá em Arquivo > Preferências e garanta que o pacote de placas ESP32 da Espressif esteja instalado.
Abra o arquivo do sketch localizado na subpasta:
ROBOBUILDERS_RB0718/ROBOBUILDERS_RB0718.ino
No menu Ferramentas > Placa > ESP32 Arduino, selecione a opção ESP32 Dev Module.
No menu Ferramentas > Porta, selecione a porta serial correspondente ao seu cabo USB.
Acesse o Gerenciador de Bibliotecas (Ctrl + Shift + I), pesquise por ArduinoJson (por Benoît Blanchon) e instale a versão 6.x.
Clique no botão Carregar (Upload) na barra de ferramentas e aguarde a mensagem de gravação concluída.

9. Acesso ao Painel Web

Com a placa gravada e alimentada via cabo USB Type-C ou fonte de bancada:

Conecte-se à rede Wi-Fi gerada:
- No celular ou notebook, procure pelas redes disponíveis e selecione:
  ROBOBUILDERS-RB0718
- A rede é aberta (não possui senha).
Abra a interface:
- O sistema operacional do celular detectará a rede sem internet e exibirá a notificação de login, abrindo o Portal Captivo automaticamente em tela cheia.
- Se o portal não abrir sozinho, basta abrir qualquer navegador web e acessar:
  👉 http://192.168.4.1

O painel carregará de imediato. A partir desse momento, você pode comutar qualquer porta, verificar o comportamento do relé ou testar a resposta de sensores em tempo real com total praticidade.

Solução de problemas

Olá! Sou o assistente técnico da RoboBuilders. Descreva seu problema com o Painel Web de Teste e Diagnóstico de GPIOs com ESP32 e eu ajudarei a encontrar a solução.

O assistente usa IA e pode errar. Confirme informações críticas no datasheet oficial do fabricante.