Painel Financeiro com ESP32-S3 e Atualização OTA: Projeto Passo a Passo

Introdução

Este tutorial apresenta a construção de um Painel Financeiro baseado no microcontrolador ESP32-S3, com tela touch de 7 polegadas. O dispositivo exibe, em tempo real, cotações de câmbio e criptomoedas (USD, EUR, BTC), condições climáticas e a hora atual. O firmware inclui atualização OTA (over-the-air): novas versões são baixadas pela internet e instaladas na própria placa, sem cabo USB.

O material está dividido em duas partes e é direcionado a quem está começando em projetos embarcados: cada comando é explicado passo a passo, sem exigir conhecimento prévio de C++, Git ou programação — o agente de IA da IDE cobre o código. Na primeira, o objetivo é só baixar o projeto pronto e fazer o painel funcionar — instalar ferramentas, gravar pela USB e configurar a WiFi. Na segunda, com o hardware já útil, o foco é modificar o firmware com a ajuda de IDEs de IA — Codex, Claude Code e Antigravity, que embutem o agente de cada empresa — publicar o projeto no seu GitHub e liberar atualizações OTA. Ao final, o painel estará operacional e apto a receber versões novas pela rede.

O que você vai aprender:

• Instalar Python, PlatformIO Core e Git e usá-los pelo terminal
• Baixar o projeto, compilar e gravar o firmware no ESP32-S3
• Configurar WiFi e preferências pela página web do painel
• Pedir alterações de personalização em IDEs de IA (Codex, Claude Code, Antigravity)
• Publicar o projeto no GitHub e liberar updates por tag/Release

Material utilizado: a placa deste projeto é a ESP32-8048S070, conhecida como CYD (Chinese Yellow Display), disponível na loja RoboBuilders.

Parte 1 — Baixar o projeto e fazer o painel funcionar

Nesta parte o código já está pronto em um endereço público na internet. Você instala o ambiente no computador, baixa esses arquivos, grava na placa e configura a rede. Não é necessário criar conta no GitHub nem publicar nada.

Passo 1 — Instalar as ferramentas

Para transformar o código-fonte em firmware na placa, o computador precisa de um conjunto mínimo de ferramentas. São três programas com papéis distintos:

Ferramenta	Função prática nesta parte
Python	Base em que o PlatformIO roda
PlatformIO Core	Compila o C++, baixa libs (LVGL etc.) e grava o ESP32
Git	Baixa o projeto pronto do GitHub para o seu computador

Tudo acontece pelo terminal — uma janela em que você digita comandos em texto. No Windows, abra o menu Iniciar, digite cmd ou powershell e abra o aplicativo. No Linux/macOS, use o app Terminal. Cada comando abaixo termina com Enter; se aparecer erro, leia a mensagem com calma (a tabela do final do post cobre os casos mais comuns).

Instale na ordem Python → PlatformIO → Git e confirme cada um com --version antes de passar ao próximo. Pular a verificação costuma gerar erros confusos na gravação.

1.1 Python

O PlatformIO é escrito em Python. Sem o interpretador instalado e acessível no terminal, o comando pio simplesmente não existe para o sistema. Por isso o Python é o primeiro item.

Windows

1. Baixe o instalador em python.org/downloads
2. Na primeira tela do instalador, marque a caixa Add Python to PATH — se esquecer, o terminal não encontra python nem pip
3. Conclua a instalação
4. Feche qualquer terminal aberto e abra um novo (o PATH só vale para janelas novas)

Linux: sudo apt install python3 python3-pip
macOS: brew install python

Confirme:

python --version

A resposta deve ser algo como Python 3.11.x ou Python 3.12.x. Se o Windows sugerir a Microsoft Store em vez de mostrar a versão, o PATH não está correto — volte ao instalador e marque a opção.

O que é PATH? É a lista de pastas que o terminal percorre para localizar programas. “Adicionar ao PATH” significa: quando você digita python, o Windows sabe em qual pasta procurar. Sem isso, aparece a mensagem clássica de comando não reconhecido.

1.2 pip

O pip é o instalador de pacotes do Python. Em vez de baixar o PlatformIO manualmente em um site, você pede ao pip: “instale o pacote platformio”. Em instalações recentes do Python o pip já vem incluso; mesmo assim, vale confirmar.

pip --version

Se o terminal disser que pip não existe:

python -m ensurepip --upgrade

Depois teste pip --version de novo. Em alguns Windows o pip isolado falha, mas a forma abaixo funciona — use-a sem medo no restante do tutorial:

python -m pip install <pacote>

💡 Dica: python -m pip e pip fazem a mesma coisa; a primeira forma não depende tanto do PATH dos “Scripts” do Python.

1.3 PlatformIO Core

O PlatformIO Core (CLI) é a ferramenta central do dia a dia neste projeto. Com ele você:

• declara a placa e as bibliotecas no platformio.ini
• baixa automaticamente LovyanGFX, LVGL, ArduinoJson etc.
• compila o código C++ para o ESP32-S3
• grava o resultado na flash pela USB
• abre o Monitor Serial para ler os logs

Não é obrigatório instalar a extensão do VS Code neste tutorial: usamos só a linha de comando (pio).

pip install platformio

ou:

python -m pip install platformio

Confirme:

pio --version

Deve aparecer algo como PlatformIO Core, version 6.x. Na primeira vez que você compilar o projeto (Passo 4), o PlatformIO ainda baixa o toolchain do ESP32 (compilador e ferramentas). Isso pode levar vários minutos e consumir bastante rede — deixe terminar; fechar no meio costuma deixar o ambiente pela metade.

1.4 Git

Nesta parte o Git serve para uma coisa: baixar o projeto pronto da internet para uma pasta no seu PC. Conta no GitHub, envio de alterações, tags e Releases ficam na Parte 2.

O comando que faz esse download completo se chama git clone — ele será explicado no Passo 2. Sem Git, ainda dá para baixar um ZIP na página do projeto, mas o Git deixa a pasta pronta também para a Parte 2.

• Windows: baixe em git-scm.com e avance com as opções padrão
• Linux: sudo apt install git
• macOS: brew install git (ou ferramentas de linha de comando do Xcode)

git --version

Quando python --version, pio --version e git --version responderem sem erro, o ambiente está pronto para baixar o código.

Passo 2 — Baixar o código do projeto

Neste tutorial o firmware já está escrito e testado: interface na tela, WiFi, servidor web e a lógica de OTA (que você só vai usar de verdade na Parte 2). Seu trabalho agora não é digitar centenas de linhas — é obter uma cópia local e gravá-la na placa.

O projeto está em um endereço público no GitHub: não precisa estar logado para baixar. A conta e o repositório próprio só entram quando você for publicar updates (Parte 2).

Para baixar, usamos o Git com o comando git clone. Em termos simples, clonar significa: criar na sua máquina uma cópia fiel de todos os arquivos do projeto que estão na internet (e também o histórico de versões, que será útil depois). É o equivalente prático a “baixar o projeto inteiro de uma vez”, com a vantagem de já ficar ligado ao endereço original.

1. Abra o terminal.
2. Entre na pasta onde quer guardar o projeto. No Windows, um exemplo comum:

cd Desktop

(Se preferir outra pasta, use cd até chegar nela. cd significa “change directory” — mudar de pasta.)

3. Baixe o projeto e entre nas pastas:

git clone https://github.com/luanvieiramendes/ROBOBUILDERS.git
cd ROBOBUILDERS
cd "RB1212/Projeto - Painel Financeiro com ESP32-S3 e Atualização OTA"

O que cada linha faz:

Comando	Efeito
git clone ...	Baixa o projeto e cria a pasta ROBOBUILDERS com todos os arquivos
cd ROBOBUILDERS	Entra nessa pasta
cd "RB1212/Projeto - Painel Financeiro com ESP32-S3 e Atualização OTA"	Entra na pasta do projeto — é aqui que existe o platformio.ini

As aspas no comando são obrigatórias: o nome da pasta tem espaços, e sem elas o terminal interpretaria cada palavra como uma pasta diferente.

Confira se está no lugar certo. No Windows digite dir; no Linux/macOS, ls. Você deve ver platformio.ini e a pasta src. Se não vir, ainda não está na pasta do projeto — os comandos pio do Passo 4 vão falhar se rodarem na pasta errada.

Para inspecionar o código no navegador antes (opcional): github.com/luanvieiramendes/ROBOBUILDERS.

Daqui em diante, sempre que o tutorial pedir um comando pio, o terminal precisa estar dentro da pasta do projeto. Se você fechar a janela e abrir outra, volte com cd até ela.

Passo 3 — Estrutura do projeto

Antes de gravar, vale um minuto só para reconhecer o que veio na pasta baixada. Não é preciso abrir os arquivos ainda — na Parte 2, quem lê o código é o agente de IA. Aqui o objetivo é saber onde as coisas moram, para não se perder.

Projeto - Painel Financeiro com ESP32-S3 e Atualização OTA/
├── platformio.ini                  # regras de compilação: placa, libs, porta USB
├── README.md                       # apresentação do projeto
├── .gitignore                      # arquivos que o Git ignora no build
├── .github/
│   └── workflows/
│       └── build-release.yml      # usado na Parte 2 (Release automática)
└── src/
    ├── main.cpp                   # ponto de entrada: liga tela, WiFi, web e OTA
    ├── LGFX_ESP32_8048S070.h      # pinos e timings da tela desta placa
    ├── lv_conf.h                  # opções da biblioteca gráfica LVGL
    ├── app_config.h/.cpp          # grava WiFi e preferências na memória NVS
    ├── web_server.h/.cpp          # página HTTP que você abre no navegador
    ├── ota_updater.h/.cpp         # pergunta ao GitHub e baixa o .bin
    └── version.h                  # número da versão + qual repo consultar no OTA

Leitura prática dessa árvore:

• Tudo que é código da placa fica em src/.
• Tudo que é como compilar/gravar no PC fica no platformio.ini.
• A pasta .github/ só entra em ação na Parte 2, quando você publicar tags.

Se no futuro você só quiser mudar a porta COM, edita o platformio.ini. Com essa visão da pasta, o Passo 4 fica mais simples: você está “enviando o conteúdo de src/ para a flash”, mediado pelo PlatformIO.

Passo 4 — Primeira gravação (compile e upload)

Até aqui o firmware existe só no disco do computador. A placa ainda não o executa. Este passo faz duas coisas em sequência:

1. Compilar — traduzir o C++ em um binário que o ESP32-S3 entende
2. Upload (gravar) — copiar esse binário para a memória flash da placa pela USB

A primeira instalação precisa do cabo. Atualização pela internet (OTA) só entra na Parte 2, depois que o painel já está na WiFi e aponta para o seu GitHub.

4.1 Conectar e achar a porta serial

1. Conecte a placa ao PC com um cabo USB que transmita dados. Cabos baratos “só de carga” alimentam a tela mas o computador não vê a porta serial — sintoma clássico: nada aparece em “Portas (COM e LPT)”.
2. Se a tela acender fraca ou reiniciar sozinha, a porta USB do PC pode estar com pouca corrente. Prefira USB 3.0 (azul).
3. Descubra o nome da porta serial — é o endereço que o PlatformIO usa para falar com a placa:

Sistema	Como descobrir
Windows	Clique com o botão direito em Iniciar → Gerenciador de Dispositivos → Portas (COM e LPT) → procure algo como “USB-SERIAL CH340”. Anote COM5, COM3, COM7…
Linux	No terminal: ls /dev/ttyUSB* ou ls /dev/ttyACM*
macOS	ls /dev/cu.usbserial-*

4. Se o Windows não listar nenhuma porta, instale o driver USB-serial. Esta placa usa o chip CH340; sem o driver, o chip aparece no Gerenciador de Dispositivos em “Outros dispositivos” com um ponto de exclamação amarelo (USB-SERIAL CH340). Passo a passo:

   1. Baixe o driver no site oficial da WCH: CH341SER — driver USB-serial (ZIP)
   2. Extraia o ZIP (botão direito → Extrair tudo)
   3. Execute o SETUP.EXE com botão direito → Executar como administrador
   4. No instalador, clique em INSTALL e aguarde a mensagem de sucesso
   5. Reconecte o cabo USB da placa

   Pronto: o Gerenciador deve mostrar USB-SERIAL CH340 (COMx) em Portas (COM e LPT), sem exclamação. Se ainda não aparecer, reinicie o PC e confira se o arquivo veio mesmo do site da WCH — evite sites de “driver updater”, que instalam programas indesejados.

   💡 Dica: no Linux o driver do CH340 já vem no kernel (módulo ch341) — normalmente nenhum passo extra é necessário. No macOS o driver nativo costuma funcionar; se não, use o mesmo pacote da WCH para macOS.

5. Abra o arquivo platformio.ini em um editor de texto (Bloco de Notas, VS Code, etc.). Localize as linhas upload_port e monitor_port. Se a sua porta não for COM5, altere as duas para o valor que você anotou:

upload_port = COM5
monitor_port = COM5

No Linux/macOS o valor é o caminho completo, por exemplo /dev/ttyUSB0. Salve o arquivo.

4.2 Compilar e gravar

Confirme no terminal que você ainda está na pasta do projeto (dir/ls deve mostrar platformio.ini). Então execute:

pio run -e esp32-8048s070 -t upload

Leitura do comando:

• pio run — pede ao PlatformIO para construir o projeto
• -e esp32-8048s070 — usa o ambiente definido no platformio.ini (placa e libs certas)
• -t upload — depois de compilar, grava na placa

Na primeira execução espere vários minutos: download do toolchain, das bibliotecas e a compilação em si. Linhas longas de log são normais. O sucesso costuma terminar com SUCCESS e algo como Hard resetting via RTS pin... — a placa reinicia sozinha com o firmware novo. A tela deve acender (pode levar alguns segundos para a UI aparecer).

Se o upload ficar em Connecting... e falhar: muitas placas ESP32 precisam entrar em modo de gravação manualmente. Segure o botão BOOT, inicie o comando de upload de novo e solte o BOOT quando o terminal mostrar que está conectando. Em alguns modelos ajuda um toque rápido em RESET logo antes.

Se quiser apenas testar se o projeto compila, sem gravar (útil quando a placa não está à mão):

pio run -e esp32-8048s070

Erros de compilação (arquivo não encontrado, lib faltando) quase sempre significam pasta errada ou pio incompleto no Passo 2 — volte e confirme pio --version e o cd até a pasta do projeto.

Passo 5 — Monitor Serial

Depois do upload, a tela pode até ligar, mas ela não mostra tudo o que o firmware está fazendo por baixo: se a WiFi falhou, qual IP recebeu, se a config foi lida da NVS. Essas mensagens saem pela USB em texto — é o Monitor Serial.

Pense nele como o console de depuração do painel. Nesta parte, o diagnóstico de WiFi e boot começa por aqui. (Mensagens de OTA também aparecem no log; na Parte 1 você só precisa delas se quiser confirmar a versão gravada.)

Com a placa conectada e a mesma porta do Passo 4:

pio device monitor -p COM5 -b 115200

• -p COM5 — porta serial (troque pela sua)
• -b 115200 — velocidade (baud rate), a mesma do monitor_speed no platformio.ini

Se a porta estiver ocupada (outro monitor aberto, Arduino IDE, etc.), o comando falha — feche o outro programa e tente de novo. Para sair do monitor, use Ctrl+C.

Exemplo de saída com WiFi já configurada:

[Config] carregado
WiFi conectado! IP: 192.168.1.57
[OTA] versao atual 2.0.7 (207)
[OTA] ja atualizado

O que observar:

Mensagem	Significado
[Config] carregado	Preferências lidas da NVS
WiFi conectado! IP: ...	Rede ok — anote esse IP para o Passo 6
[OTA] versao atual ...	Firmware se identificou
Painel-Config / falha WiFi	Ainda não há rede salva — use o AP no próximo passo

Reiniciar a placa (botão RESET ou desconectar/reconectar USB) enquanto o monitor está aberto faz o log do boot aparecer de novo do zero — útil se você perdeu as primeiras linhas.

💡 Dica: ao modificar o código com IDEs de IA (Parte 2), peça sempre para manter os Serial.println nas etapas críticas (WiFi, save de config, início/fim do OTA). Sem log, depurar embarcado vira adivinhação.

Passo 6 — Configurar e usar o painel

O firmware não exige que você recompile só para trocar WiFi ou moeda. Ele sobe um servidor web na porta 80 na própria placa. Qualquer navegador na mesma rede (ou no Access Point temporário) abre essa página e grava as preferências na NVS.

Há dois caminhos de acesso, conforme o estado da rede:

6.1 Ainda sem WiFi (primeira configuração)

Se o Monitor Serial mostrou falha de WiFi ou mencionou o AP:

1. No celular ou notebook, abra a lista de redes WiFi
2. Conecte-se à rede Painel-Config
3. Senha: 12345678
4. No navegador, acesse exatamente: http://192.168.4.1/

Essa é a placa agindo como um “roteadorzinho” temporário. Enquanto você estiver nesse AP, a internet do celular pode cair — é esperado. Use a página só para informar o SSID e a senha da sua rede doméstica/escritório e salvar.

Depois do save, a placa tenta conectar na WiFi verdadeira. Volte ao Monitor Serial (Passo 5) e procure a linha com o IP da LAN (algo como 192.168.x.x). Esse IP substitui o 192.168.4.1 daqui pra frente.

6.2 Já conectado na sua WiFi

Com o IP anotado no Monitor Serial:

1. Conecte o PC ou celular na mesma rede que o painel (não use dados móveis isolados)
2. Abra o navegador em http://IP-DO-PAINEL — por exemplo http://192.168.1.57

Se a página não abrir, confira: IP digitado certo, painel e dispositivo na mesma WiFi, e se o roteador não está com “isolamento de clientes” (comum em WiFi de hotel/convidado).

6.3 O que configurar na página

Na interface web você normalmente encontra:

• WiFi — SSID e senha (o essencial na primeira vez)
• Moedas — pares como USD-BRL, EUR-BRL, BTC-BRL
• Clima — cidade (e coordenadas, conforme a implementação)
• Tela — brilho e tema claro/escuro

(Os controles de OTA na página existem, mas ainda não vamos publicar Release nem forçar update remoto — isso é a Parte 2.)

Salve as alterações e observe a tela do painel: as cotações e o clima devem começar a aparecer após a placa consultar as APIs pela internet. Se a UI ficar vazia, o Monitor Serial costuma mostrar erro de WiFi ou de HTTP — volte ao Passo 5 antes de mudar código.

Fim da Parte 1. Se a tela mostra dados e a página web responde, o painel está funcionando. A Parte 2 é opcional no sentido de “o hardware já presta”; ela ensina a modificar o firmware e a publicar atualizações OTA no seu GitHub.

Parte 2 — Modificar o firmware com IDEs de IA e publicar por OTA

A partir daqui o objetivo muda: em vez de só usar o projeto pronto, você vai personalizá-lo e publicar versões novas pela internet (tag → Release → download na placa).

O método desta parte também mudou em relação ao que era comum há alguns anos: você não precisa mais estudar o código arquivo por arquivo. Em vez disso, você abre o projeto em uma IDE de IA — Codex, Claude Code ou Antigravity — que traz embutido o agente de código da respectiva empresa, e pede, em linguagem natural (português basta), a alteração que quiser. O agente lê os arquivos, edita o que for preciso e compila para você conferir.

Seu papel deixa de ser “programador” e passa a ser gerente do agente: preparar o contexto, pedir com clareza, conferir o resultado e publicar. Os Passos 7 a 9 montam esse fluxo de trabalho; os Passos 10 e 11 continuam com o GitHub e o OTA.

Passo 7 — Conhecer as IDEs de IA (Codex, Claude Code e Antigravity)

Uma IDE de IA é um ambiente de desenvolvimento — como o VS Code, mas com IA no comando — que traz embutido o agente de código da respectiva empresa: um programa que trabalha como um estagiário muito rápido e aplicado na sua pasta. Ele lê os arquivos do projeto, entende o que foi pedido, edita o código e ainda roda comandos para validar (como o pio run da Parte 1). A diferença para um chatbot comum é justamente essa: o agente opera sobre os arquivos reais da sua máquina, e a IDE é o lugar onde ele trabalha.

As três opções mais comuns hoje:

Ferramenta (IDE)	Empresa	Como funciona
Codex	OpenAI	IDE e terminal com o agente Codex embutido; integra com o ChatGPT
Claude Code	Anthropic	Roda no terminal ou no editor com o agente Claude embutido
Antigravity	Google (Gemini)	IDE da plataforma de desenvolvimento do Google, com o agente Gemini por trás

Todos exigem uma conta (alguns com planos pagos ou limites diários). Os nomes e comandos de instalação mudam com o tempo — consulte a documentação oficial de cada um. O que importa para este tutorial é o fluxo comum:

1. Abra o terminal na pasta do projeto da Parte 1 — a mesma que contém platformio.ini e src/.
2. Abra a IDE nessa pasta (cada ferramenta tem seu comando ou botão; algumas abrem em uma aba do navegador).
3. Pronto: a IDE carrega o projeto e o agente dela já enxerga o firmware inteiro. É a partir daí que você pede as alterações (Passo 8).

⚠️ Atenção: o agente da IDE pode executar comandos no seu computador (incluindo pio). Isso é normal e útil — mas é o motivo do Passo 9: confira o que ele mudou antes de gravar na placa.

Passo 8 — Pedir a alteração ao agente

A qualidade do resultado depende muito do pedido. Um bom pedido tem quatro partes:

1. O quê — a alteração desejada, em linguagem natural
2. Onde — o arquivo (ou o comportamento) envolvido
3. Limites — o que não pode mudar
4. Validação — pedir para compilar e mostrar o que mudou

8.1 As regras de casa (cole antes do primeiro pedido)

Para não ter surpresa, envie este bloco uma vez antes de começar a trabalhar com o agente:

Você vai trabalhar no firmware do Painel Financeiro (PlatformIO, placa esp32-8048s070).

Regras:
- No final de cada alteração, compile com: pio run -e esp32-8048s070
- NÃO altere src/LGFX_ESP32_8048S070.h (pinos e timings da tela)
- NÃO altere a lógica de OTA em src/ota_updater.h / src/ota_updater.cpp
- NÃO altere .github/workflows/build-release.yml
- NÃO mude a versão em src/version.h a menos que eu peça explicitamente
- Ao terminar, mostre um resumo curto: arquivos alterados e motivo

Os agentes mais novos dessas IDEs leem automaticamente um arquivo de instruções fixo no projeto (geralmente AGENTS.md ou CLAUDE.md) — se a sua ferramenta suportar, você pode salvar essas regras nesse arquivo e elas valem para sempre, sem colar toda vez.

8.2 Fichas de pedido prontas

Exemplos que você pode adaptar para as personalizações mais comuns deste projeto:

Trocar as moedas exibidas

“Mude as moedas padrão em src/app_config.h / src/app_config.cpp para USD-BRL, EUR-BRL, GBP-BRL e BTC-BRL, mantendo o limite máximo de 6. Compile e me mostre o que mudou.”

Cidade padrão do clima

“Altere a cidade padrão do clima no firmware para Curitiba (latitude -25.42, longitude -49.27). Ajuste também as coordenadas padrão e garanta que a página web continue funcionando. Compile e mostre o resumo.”

Tema e cores

“Mude o tema padrão do painel para o tema claro, e troque a cor de destaque (accent) para laranja #F97316 em src/main.cpp e, se existir, na página web em src/web_server.cpp. Compile e mostre o resumo.”

Layout da tela

“Reorganize os cards de moedas em 2 colunas de 3 em src/main.cpp, respeitando a resolução de 800×480 e o código atual de layout. Se o layout ficar apertado com 4 ou 6 moedas, corrija de forma proporcional. Compile e mostre o resumo.”

Textos da página web

“Na página web embutida em src/web_server.cpp, reescreva o texto do rodapé da aba Sistema para: ‘Atualizações pela internet (OTA) a cada 6h ou manualmente’. Compile e mostre o resumo.”

Subir a versão (para OTA)

“Em src/version.h, suba o FIRMWARE_VERSION para “2.0.8” e o FIRMWARE_VERSION_CODE para 208. NÃO mude mais nada. Compile e mostre o resumo.”

Duas observações sobre esses pedidos:

• O “Compile e mostre o resumo” no final é obrigatório no seu padrão: transforma o agente de “editor de texto” em “revisor que se verifica”.
• O exemplo da versão existe porque o OTA só atualiza se a versão subir — a regra completa vem no Passo 11.

8.3 Se o agente errar ou travar

Não se frustre e não tente consertar o código na mão: cole o erro de volta no chat e peça para corrigir, explicando onde ocorreu (compile, gravação ou tela). O ciclo de trabalho com IA é exatamente esse — pedir, validar, corrigir — e ele converge mais rápido do que procurar o erro linha a linha.

Passo 9 — Conferir o trabalho do agente e gravar

O agente erra como qualquer programador — o que muda é a velocidade. Por isso, antes de gravar na placa, confira em três níveis:

1. O que mudou (diff). Peça ao agente para rodar git diff e ler as alterações — ou peça um resumo. Você não precisa entender a sintaxe C++ toda: procure o senso comum — o arquivo pedido foi alterado, e a tela (LGFX_ESP32_8048S070.h), o OTA (ota_updater) e o workflow não foram tocados.

2. Compilação. Quando o agente terminar, ele deve ter rodado o pio run do Passo 8.1. Se não rodou, rode você mesmo (ou peça a ele):

pio run -e esp32-8048s070

Erro de compilação → volte ao 8.3 e cole o erro no agente. Não grave um firmware que não compilou.

3. Gravar e testar na placa. Compilou? Grave e observe:

pio run -e esp32-8048s070 -t upload

Depois abra o Monitor Serial (Passo 5) e confira na tela: a alteração apareceu? O boot está limpo (sem erro de WiFi ou de HTTP)? Se algo estiver estranho, o log diz o quê — e o agente corrige.

Se o agente alterou arquivos demais ou quebrou o que não devia, dá para voltar atrás de forma simples:

git restore src/

Esse comando devolve os arquivos de src/ ao estado do último commit (a versão da Parte 1) — refaça o pedido com instruções mais restritas.

💡 Dica: a gravação por USB é sempre o que leva o código novo para a placa. Se você pediu uma mudança e a tela continua igual, não é o agente que errou — é o firmware antigo ainda na flash.

Passo 10 — Conta GitHub, repositório próprio e apontar o firmware

Quando o sistema do celular atualiza, o aparelho baixa a nova versão da nuvem do fabricante e instala sozinho — sem cabo, sem loja de assistência. Com o painel é a mesma mecânica: a “nuvem” dele é um repositório seu no GitHub, e cada versão nova publicada lá (uma Release com o firmware .bin) é baixada pela WiFi e instalada na própria placa — é o OTA do Passo 11.

Mas atenção: essa atualização em nuvem só faz sentido quando a placa não está na sua mesa. Se o painel for instalado em uma parede, dentro de um quadro ou em outro prédio, ficar “espetando” o cabo USB a cada versão do projeto não é opção — é exatamente aí que o OTA paga o investimento. Para uma placa que vive do seu lado, o cabo do Passo 4 continua sendo o caminho mais simples. A pergunta que decide é: vou precisar atualizar o firmware sem estar fisicamente perto da placa? Se sim, a nuvem é a resposta — e este Passo 10 monta essa infraestrutura, com uma única regravação por USB na transição (item 3 abaixo), como a primeira conexão do celular: daí em diante, tudo chega pela internet.

Até aqui o painel funciona com o firmware do repositório de referência (luanvieiramendes/ROBOBUILDERS). Para suas modificações e updates OTA, três coisas precisam ficar alinhadas:

1. Uma conta no GitHub e um repositório seu e público
2. O código enviado (push) para esse repositório
3. O version.h na placa apontando para esse endereço — o que exige uma regravação USB

Sem o item 3, publicar no GitHub não muda o que a placa consulta.

10.1 Criar a conta (se ainda não tiver)

1. Acesse github.com
2. Sign up e confirme o e-mail
3. Anote o nome de usuário — ele entra nas URLs abaixo (github.com/SEU-USUARIO/...)

10.2 Criar o repositório vazio

1. No GitHub, botão verde New repository
2. Repository name: por exemplo painel-financeiro-esp32 (sem espaços, sem acentos)
3. Visibility: Public — o firmware baixa o .bin sem token; repo privado quebraria o OTA como está
4. Não marque README, .gitignore ou license — o clone já tem os arquivos; um README inicial complica o primeiro push
5. Create repository

A URL ficará no formato:

https://github.com/SEU-USUARIO/painel-financeiro-esp32.git

10.3 Apontar o remote e enviar o código

Quando você baixou o projeto na Parte 1 com git clone, o Git guardou o endereço de origem (origin) apontando para o repositório original. Agora esse endereço precisa apontar para o seu:

git remote -v
git remote set-url origin https://github.com/SEU-USUARIO/painel-financeiro-esp32.git
git push -u origin main

Rode isso na pasta do clone que contém .git (em geral ROBOBUILDERS). Na primeira autenticação o Git pode abrir o navegador ou pedir um Personal Access Token. Se a branch local não for main, use git branch -M main antes do push.

Deu certo se: ao abrir https://github.com/SEU-USUARIO/painel-financeiro-esp32 você vê platformio.ini, src/ e .github/.

10.4 Apontar o firmware para o seu repositório e regravar pela USB

Duas opções — a primeira usa o agente que você já tem:

Opção A — pedir ao agente (recomendado):

“Em src/version.h, troque o GITHUB_REPO para “SEU-USUARIO/painel-financeiro-esp32” e atualize o GITHUB_API_LATEST para “https://api.github.com/repos/SEU-USUARIO/painel-financeiro-esp32/releases/latest\”. Compile e mostre o resumo.”

Opção B — na mão: edite src/version.h:

#define GITHUB_REPO "SEU-USUARIO/painel-financeiro-esp32"
#define GITHUB_API_LATEST "https://api.github.com/repos/SEU-USUARIO/painel-financeiro-esp32/releases/latest"

Em ambos os casos, salve e repita o upload do Passo 4 (pio run -e esp32-8048s070 -t upload). Sem essa gravação, a placa continua consultando o repo antigo.

O .gitignore já ignora .pio/, .vscode/ e *.log.

Passo 11 — Publicar uma versão nova e atualizar pela internet

Com o painel apontando para o seu GitHub, a atualização sem cabo segue esta ordem. Antes, dois termos novos: a tag é uma etiqueta que o Git coloca em um ponto do histórico — por exemplo v2.0.8 — e a Release é a página pública que o GitHub cria a partir da tag, com os arquivos prontos anexados (o .bin). Publicar uma versão nova é, então:

1. Subir o número da versão em version.h (e incluir as modificações de código da Parte 2)
2. commit + push em main
3. Criar a tag vX.Y.Z e fazer push da tag
4. O Actions compila e cria a Release com o .bin
5. O painel detecta versão maior, baixa e reinicia

Armadilhas clássicas:

• Push só de main → gera artifact, não a Release que o ESP32 usa
• Tag ≤ versão na placa → log [OTA] ja atualizado e nenhum download

11.1 Subir a versão no código

Você já tem a ficha do Passo 8.2 — use-a:

“Em src/version.h, suba o FIRMWARE_VERSION para “2.0.8” e o FIRMWARE_VERSION_CODE para 208. NÃO mude mais nada. Compile e mostre o resumo.”

(Se preferir na mão: altere as duas linhas do arquivo — texto e código juntos. Conta do projeto: major*100 + minor*10 + patch.)

Não grave esse version.h novo na placa por USB agora — a placa deve permanecer em 2.0.7 para encontrar o 2.0.8 na Release. Se você alterou outros arquivos (UI, defaults etc.), inclua-os no mesmo commit.

11.2 Commit, push, tag e push da tag

git add src/version.h
git commit -m "chore: bump 2.0.8"
git push origin main

git tag v2.0.8
git push origin v2.0.8

A última linha dispara o workflow de Release.

11.3 Conferir no GitHub

1. Aba Actions → workflow verde (Build and Release Firmware)
2. Aba Releases → anexos firmware-v2.0.8.bin e/ou firmware-latest.bin

Sem o .bin na Release, o download na placa falha (HTTP 404).

11.4 Ver a placa atualizar

O firmware checa cerca de 15 s após ligar e a cada 6 h. Também dá para forçar na página web (controles de OTA).

Reinicie a placa com o Monitor Serial aberto:

[OTA] atual=207 latest=208 url=.../firmware-v2.0.8.bin
[OTA] Atualizacao disponivel: v2.0.8
[OTA] iniciando download ...
[OTA] sucesso, reiniciando...

Após o reboot, o log deve mostrar 2.0.8 / 208 — update sem cabo.

⚠️ Atenção: git push origin vX.Y.Z é obrigatório; a tag deve ser maior que a versão na placa; o repositório deve permanecer público.

Problemas comuns e soluções

Sintoma	O que verificar	Solução
python / pio não reconhecido	PATH ou terminal antigo	Reinstalar Python com PATH; abrir terminal novo
Placa não aparece em COM	Cabo só de carga / driver	Cabo de dados; instalar o driver (Passo 4.1)
Upload falha em Connecting...	Modo gravação	Segurar BOOT, iniciar upload, soltar
Tela lavada / branca	Alimentação / cabo	Fonte 5V 2A, cabo bom; brilho ~180; PWM 44100 Hz
Cores invertidas	Ordem de cores	setColorOrder / setInvert no LGFX
WiFi não conecta	SSID/senha	AP 192.168.4.1 → configurar rede
Agente não compilou	Pedido sem validação	Refazer pedido com “Compile e mostre o resumo” (Passo 8.2)
Agente alterou arquivos demais	git diff	git restore src/ e refazer o pedido (Passo 9)
[OTA] ja atualizado	Tag ≤ versão da placa	Tag com código maior + push da tag
Release não aparece	Só push de main	git push origin vX.Y.Z
[OTA] download HTTP 404	Nome do .bin	Release com firmware-vX.Y.Z.bin ou firmware-latest.bin
Guru Meditation no download	Stack da task OTA	Pedir ao agente para manter 32768 em xTaskCreatePinnedToCore
API HTTP 403	Rate-limit da API GitHub	Fallback por redirect já está no código

Próximos passos sugeridos: gráfico histórico de câmbio, troca de moeda no touch, MQTT para Home Assistant, página em LittleFS — todos pedíveis ao agente com as fichas do Passo 8.2.

Conclusão

O tutorial separou dois objetivos: na Parte 1, o painel sai dos arquivos baixados e passa a funcionar na mesa (ferramentas, USB, WiFi, página web); na Parte 2, o mesmo projeto vira base para modificações suas — com a diferença de que quem escreve o código agora é o agente de IA da sua IDE (Codex, Claude Code ou Antigravity), e o seu papel é pedir bem, conferir o resultado e publicar. Resumo do que foi feito:

• Passo 1 — Instalar as ferramentas: Python, PlatformIO Core e Git instalados e verificados no terminal
• Passo 2 — Baixar o código do projeto: cópia local do firmware de referência obtida com git clone, na pasta RB1212/Projeto - Painel Financeiro com ESP32-S3 e Atualização OTA
• Passo 3 — Estrutura do projeto: mapa de platformio.ini, src/ e .github/ para saber onde cada coisa mora
• Passo 4 — Primeira gravação: driver CH340 instalado quando necessário, porta serial configurada e firmware gravado por USB pela primeira vez
• Passo 5 — Monitor Serial: leitura dos logs de boot, WiFi e versão para diagnosticar o painel
• Passo 6 — Configurar e usar o painel: WiFi, moedas, clima e brilho ajustados pela página web da placa
• Passo 7 — Conhecer as IDEs de IA: Codex, Claude Code e Antigravity apresentadas como os ambientes que rodam o agente de cada empresa
• Passo 8 — Pedir a alteração ao agente: regras de casa e fichas de pedido prontas para personalizar o firmware em linguagem natural
• Passo 9 — Conferir o trabalho do agente e gravar: diff, compilação e upload como rotina de validação antes de testar na placa
• Passo 10 — Conta GitHub, repositório próprio e apontar o firmware: a “nuvem” do painel montada, com o version.h apontando para o seu repositório
• Passo 11 — Publicar uma versão nova e atualizar pela internet: bump de versão, tag e Release gerando a atualização sem cabo

O fio condutor da evolução continua o mesmo: USB quando muda o endereço do repo ou na primeira gravação; depois, versão nova + tag no GitHub. As regras que não mudam: GITHUB_REPO apontando para o seu repositório, versão sempre maior a cada Release, e o fluxo tag → Release → OTA mantido.

Referência do projeto: github.com/luanvieiramendes/ROBOBUILDERS

Solução de problemas

Olá! Sou o assistente técnico da RoboBuilders. Descreva seu problema com o Painel Financeiro com ESP32-S3 e Atualização OTA: Projeto Passo a Passo e eu ajudarei a encontrar a solução.

Enviar

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