Programar o ESP32 no VS Code com PlatformIO

Para quem é este tutorial

Este é o caminho para quem prefere trabalhar por interface gráfica. Todos os passos acontecem dentro do VS Code, clicando em botões — nenhum comando precisa ser digitado no terminal.

A placa-alvo é o ESP32 clássico, de dois núcleos, aquele com o módulo prateado WROOM-32 e duas fileiras de pinos. O exemplo pisca o LED azul soldado na própria placa, ligado ao GPIO 2.

Se você prefere linha de comando, ou tem a placa com display, existe o tutorial irmão de primeiros passos com ESP32-C3 e LCD de 1,44 polegadas. Escolha um dos dois: fazer os dois ao mesmo tempo só confunde.

O que instalar

São duas instalações, nesta ordem. Primeiro o Visual Studio Code, pelo site oficial, aceitando as opções padrão e deixando marcada a opção de adicionar ao PATH.

Depois, dentro do próprio VS Code, a extensão PlatformIO IDE: clique no ícone de Extensões na barra lateral esquerda, procure por PlatformIO IDE e instale a extensão da PlatformIO Labs. A primeira instalação baixa o núcleo do PlatformIO e leva alguns minutos.

Deu certo quando aparece um ícone de formiga na barra lateral e uma barra de ferramentas nova no rodapé da janela, com símbolos de casa, visto e seta.

Abrir o projeto do jeito certo

Extraia a pasta do projeto em um lugar fácil, como Documentos, e nunca trabalhe de dentro do ZIP. No VS Code, use Arquivo e depois Abrir Pasta.

Aqui mora o erro mais comum do PlatformIO: abra a pasta que contém o platformio.ini, não a pasta acima dela. Se você abrir a pasta errada, o PlatformIO não reconhece o projeto e a barra de ferramentas simplesmente não aparece — e é fácil achar que a instalação falhou.

Escolher o ambiente da placa

O mesmo projeto atende três placas diferentes: ESP32 comum, ESP32-S3 e a ESP32-C3 com display. Para o ESP32 clássico, o ambiente é o esp32dev, que já vem pronto no arquivo de configuração.

No rodapé do VS Code, clique no nome do ambiente e escolha env:esp32dev na lista que aparece no topo da janela. É esse ambiente que define o LED no GPIO 2.

Conectar a placa

Conecte o ESP32 com um cabo USB de dados — cabo de carga não transmite dados e é a causa mais comum de a placa não aparecer. Depois abra o ícone da formiga, seção Devices, e clique em Device List.

Se aparecer só a COM1, ou nenhuma porta, o motivo quase sempre é driver: o conversor USB-serial da sua placa é um CP2102 ou um CH340, e o Windows nem sempre traz o driver pronto. Veja qual chip está impresso perto do conector USB e instale o driver correspondente.

Como descobrir qual é a COM da sua placa

COM é o nome que o Windows dá à porta serial. Cada computador numera de um jeito, e o mesmo ESP32 pode ser COM3 numa máquina e COM7 em outra.

O caminho mais confiável é o Gerenciador de Dispositivos: clique no menu Iniciar, digite Gerenciador de Dispositivos, abra o resultado, procure a seção Portas (COM e LPT) e clique na seta para expandir. O número entre parênteses é a sua porta.

A placa não aparece com o nome ESP32 — ela aparece com o nome do conversor USB-serial soldado nela. É normal ver algo como Silicon Labs CP210x USB to UART Bridge (COM5) ou USB-SERIAL CH340 (COM3). Se no lugar do nome houver um triângulo amarelo, o driver não está instalado.

Existe um método infalível quando há vários dispositivos seriais no computador: abra o Gerenciador de Dispositivos com a placa desconectada e olhe a seção Portas. Conecte o cabo e olhe de novo. A porta que apareceu agora é a sua.

Vale saber que, na maioria dos casos, você não precisa dessa informação: o PlatformIO detecta a porta sozinho ao gravar. Descobrir a COM só é necessário quando há mais de um dispositivo serial ligado e ele escolhe o errado. Nesse caso, fixe a porta acrescentando duas linhas ao ambiente no platformio.ini:

E um detalhe que confunde muita gente: COM1 quase nunca é a sua placa. Ela costuma ser uma porta serial da própria placa-mãe, que existe mesmo sem nada conectado. Se só a COM1 aparece, o ESP32 não foi reconhecido.

Compilar e gravar pelos botões

Na barra do rodapé, o ícone de visto compila e o de seta para a direita grava. Clique primeiro no visto: a primeira compilação baixa o compilador e as bibliotecas, então demora alguns minutos. O resultado esperado é SUCCESS em verde no terminal.

Se aparecer FAILED, role o terminal até a primeira linha vermelha. É ela que explica a causa — a última linha quase nunca explica.

Depois clique na seta para gravar. Não retire o cabo durante a gravação. Se ficar parado em Connecting, segure o botão BOOT da placa até a gravação começar; em algumas placas é preciso pressionar EN uma vez com o BOOT pressionado e depois soltar o BOOT.

O que você deve ver

Depois da gravação a placa reinicia sozinha e o LED azul começa a piscar: um segundo aceso, um segundo apagado. Se o LED está piscando, três coisas foram validadas de uma vez — o processador, a memória flash e a comunicação USB.

Para ver o que o programa está dizendo, clique no ícone de tomada na barra do rodapé, que abre o monitor serial já na velocidade certa. A saída é esta:

As duas últimas linhas se repetem a cada segundo, acompanhando o pisca-pisca. É o comportamento correto.

Antes de gravar de novo

Feche o monitor serial no ícone de lixeira do terminal. Com o monitor aberto a porta fica ocupada, e a próxima gravação falha com erro de permissão. Esse é o segundo erro mais comum de quem está começando.

Depois que funcionar

Altere só uma coisa por vez e grave novamente a cada mudança. Comece mudando o intervalo do pisca-pisca de um segundo para 200 milissegundos, depois escreva uma frase sua no monitor serial, depois ligue um LED externo com resistor em outro GPIO.

E guarde sempre uma cópia do último programa que funcionou. Quando um experimento falhar, você volta ao ponto anterior em segundos em vez de recomeçar.