Manual ESP32

Como montar e programar uma placa ESP32 com display OLED pra exibir QR Code PIX e confirmar pagamento automaticamente.

Lista de materiais (BoM)

Total: ~R$ 100 por unidade. Em compras maiores (10+), cai pra ~R$ 70/un.

Esquema de ligação (ESP32 ↔ OLED I2C)

Software necessário

1. Baixe o Arduino IDE (versão 2.x): arduino.cc/software
2. Instale o suporte a ESP32:
   1. Arquivo → Preferências → URLs adicionais de gerenciadores de placa
   2. Cole: https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
   3. Ferramentas → Placa → Gerenciador de Placas → busca "ESP32" e instala (Espressif Systems)
3. Selecione a placa: Ferramentas → Placa → ESP32 Arduino → ESP32 Dev Module
4. Instale as bibliotecas (Sketch → Incluir biblioteca → Gerenciar bibliotecas):
   • ArduinoJson (Benoit Blanchon)
   • Adafruit GFX Library
   • Adafruit SSD1306

Cadastrando o dispositivo na plataforma

1. Logado como empresa, vai em Dispositivos → Novo dispositivo.
2. Preenche nome (ex: "Lavanderia - Máquina 1"), tipo "esp32", local.
3. Sistema retorna o Device Token (algo como dev_xxxxxxxxxxxx...).
4. ⚠️ Copia o token agora — ele não é mostrado de novo.

Sketch Arduino

Cole no Arduino IDE. Edite as 4 linhas de configuração no topo:

// ============== CONFIG ==============
#define WIFI_SSID     "SEU_WIFI"
#define WIFI_PASS     "SUA_SENHA_WIFI"
#define DEVICE_TOKEN  "dev_xxxxxxxxxxxx"  // do painel
#define API_BASE      "https://SEU-DOMINIO.com"
#define FIRMWARE_VER  "esp32_pix-1.0.0"

O sketch completo está disponível em examples/esp32_pix.ino no repositório do projeto. Copie esse arquivo inteiro pro seu Arduino IDE.

Compilando e gravando

1. Conecta o ESP32 no PC via USB.
2. Ferramentas → Porta → seleciona a porta COM/tty do ESP32.
3. Clica no botão de Upload (seta pra direita).
4. Aguarda compilar e fazer upload (~30s).
5. Abre o Monitor Serial em 115200 baud pra ver os logs.

Como o sistema funciona em operação

1. ESP32 liga → conecta no Wi-Fi → manda heartbeat pra plataforma.
2. A cada 5 segundos, busca cobrança ativa em /api/v1/devices/current-charge.
3. Quando o operador cria cobrança no painel (ou via API), a placa pega no próximo poll e mostra o valor + descrição no display.
4. Em paralelo, faz long polling em /api/v1/devices/wait-payment — fica esperando até 30s por uma confirmação.
5. Cliente paga PIX → MP confirma → plataforma libera o long polling → ESP32 mostra "PAGO!" + valor por 5 segundos.
6. Volta a buscar próxima cobrança.

Integrando com hardware do equipamento

Pra liberar máquina (catraca, válvula de água, motor, relé):

1. Conecta um módulo relé 5V num GPIO livre (ex: GPIO 23).
2. No callback de pagamento aprovado, ativa o GPIO por X segundos:

void onPaymentApproved(float amount) {
  showApproved(amount);
  digitalWrite(RELAY_PIN, HIGH);  // liga máquina
  delay(60000);                   // 60s de operação
  digitalWrite(RELAY_PIN, LOW);   // desliga
}

Troubleshooting

Display não acende

• Confere fiação (VCC/GND não trocados, SDA/SCL nos GPIOs corretos).
• Confere endereço I2C — alguns OLED são 0x3C, outros 0x3D. No sketch: display.begin(SSD1306_SWITCHCAPVCC, 0x3C)

Wi-Fi não conecta

• ESP32 só funciona em Wi-Fi 2.4 GHz. Se seu roteador é dual-band (5 GHz), crie SSID separado pra 2.4 GHz ou desliga 5 GHz temporariamente pra teste.
• Confere SSID/senha — case-sensitive.
• Verifica se a placa não está longe demais do roteador.

"Device token inválido" no monitor serial

• Token expirou ou foi revogado. Vai no painel → Dispositivos → "Gerar novo token" e atualiza no sketch.

Cobrança não aparece no display

• Confere no painel se a cobrança está com status pending (não expired).
• Confere se a empresa conectou Mercado Pago (badge verde "Conectado").
• Confere se a conta MP da empresa tem chave PIX cadastrada.

"Pago!" não aparece após pagamento

• Verifica que o webhook do MP está configurado no painel dev MP apontando pro nosso sistema.
• Confira se sua URL APP_URL é HTTPS pública (MP não chama localhost).
• No painel da empresa, abre a cobrança e veja se o status atualizou pra "approved" — se sim, o problema é só de comunicação ESP32 ↔ servidor (talvez Wi-Fi instável).

Recursos avançados

Múltiplos devices no mesmo equipamento

Cada placa tem token próprio. Você pode ter, por exemplo, 1 ESP32 controlando 4 lavadoras — cada uma com display próprio mas todas registradas como devices distintos.

Tempo de QR personalizado por device

No painel → Dispositivos → Editar → campo "Tempo do QR". Útil quando o equipamento tem mais ou menos fricção (ex: catraca rápida = 5min, estacionamento = 60min).

Display TFT colorido

Substitua a Adafruit_SSD1306 pela TFT_eSPI (configurando o User_Setup.h). A API REST do nosso lado não muda.