Configurando o Arduino IDE para trabalho com ESP32

Um guia passo a passo para instalar o Arduino IDE, adicionar suporte à placa ESP32 e carregar seu primeiro sketch em um ESP32-S2, ESP32-S3 ou ESP32-C6.

Se você nunca usou o Arduino IDE antes, o processo parece mais complicado do que realmente é. Existem três partes: instalar o IDE, instalar o pacote de suporte da placa ESP32 e depois escolher a placa e a porta corretas. A maioria dos problemas que as pessoas encontram ocorre na última parte, portanto as configurações da placa são cobertas em detalhes mais adiante.

Este guia assume que você está usando Arduino IDE 2, que é a versão atual e a que você deve estar usando para trabalho com ESP32. O IDE antigo 1.8.x ainda funciona, mas o gerenciador de placas é mais lento e o editor é muito menos útil.

O que você precisa antes de começar

• Uma máquina Windows, macOS ou Linux com alguns gigabytes livres. O núcleo ESP32 e suas cadeias de ferramentas são um download grande.
• Um cabo USB que transmita dados. Isso confunde as pessoas constantemente. Muitos cabos USB-C fornecidos com telefones e baterias portáteis são apenas para carregamento, e a placa simplesmente nunca aparecerá.
• Uma placa ESP32. As instruções abaixo cobrem as variantes S2, S3 e C6.
• Uma conexão de internet razoável para o download inicial.

Etapa 1: Instalar o Arduino IDE

Vá para arduino.cc/en/software e baixe a versão atual para seu sistema operacional. O site oferecerá primeiro uma página de doação. Você pode pular isso e ir direto para o download.

• Windows: escolha o instalador em vez do ZIP. Aceite os prompts do driver se aparecerem durante a instalação.
• macOS: abra a imagem de disco e arraste o aplicativo para Aplicativos. No primeiro lançamento, você pode precisar aprová-lo em Privacidade e Segurança.
• Linux: o AppImage é o menos problemático. Marque como executável e execute-o. Você também precisará se adicionar ao grupo dialout, que é coberto sob drivers abaixo.

Figura 1: A página de download em arduino.cc

Inicie o IDE quando a instalação terminar. Ele criará uma pasta sketchbook em sua área de documentos e uma pasta de configurações oculta. Vale a pena saber onde está a pasta de configurações, porque se o suporte da placa entrar em colapso, o conserto mais rápido é deletar parte dela e começar novamente:

• Windows: %LOCALAPPDATA%\Arduino15
• macOS: ~/Library/Arduino15
• Linux: ~/.arduino15

Etapa 2: Instalar o núcleo ESP32

Abra o gerenciador de placas. É o segundo ícone de cima na barra de ferramentas esquerda, ou Ferramentas > Placa > Gerenciador de Placas. Digite esp32 na caixa de pesquisa e aguarde um momento para que a lista seja carregada.

Guias mais antigas, incluindo muitos que ainda estão no topo dos resultados de pesquisa, dizem para colar uma URL customizada em Preferências antes de fazer isso. Nas versões atuais do IDE, isso geralmente não é necessário, portanto tente a pesquisa primeiro e veja o que aparece. Se o pacote Espressif estiver listado, continue direto. Se não estiver, há um pequeno desvio abaixo que vai resolver.

Você provavelmente verá duas entradas, e importa qual você escolhe:

• Arduino ESP32 Boards, por Arduino. Este pacote contém apenas o Arduino Nano ESP32. Não fornecerá as entradas do módulo de desenvolvimento S2, S3 ou C6. A menos que você possua um Nano ESP32, este não é o que você quer.
• esp32, por Espressif Systems. Este é o que você precisa. Escolha a versão 3.x mais recente no menu suspenso de versão e clique em Instalar.

O download possui centenas de megabytes uma vez que as cadeias de ferramentas do compilador estão incluídas, portanto dê tempo. A barra de progresso fica parada por longos períodos enquanto desempacota. Não feche o IDE no meio do processo. Se falhar no meio, execute-o novamente em vez de assumir que funcionou.

Figura 2: Dois pacotes, nomes similares. Você quer esp32 por Espressif Systems.

Figura 3: O campo de URLs adicionais do gerenciador de placas em Preferências

Etapa 3: Drivers USB, ou a falta deles

Se você precisa de um driver depende inteiramente de como a placa se conecta ao seu computador, não de qual chip ela usa.

Placas com USB nativo

O S2, S3 e C6 têm um periférico USB integrado ao silício. Se o soquete USB em sua placa vai diretamente para o chip, nenhum driver é necessário no Windows 10 ou 11, macOS ou qualquer distribuição Linux atual. A placa aparece como um dispositivo serial padrão por si só.

Placas com uma ponte USB para serial

Muitas placas de desenvolvimento ajustam um chip de ponte separado para que uploads funcionem da forma tradicional. Se sua placa tem um desses, instale o driver correspondente:

• CP2102 ou CP2102N: o driver Silicon Labs CP210x VCP.
• CH340 ou CH9102: o driver WCH.
• FTDI: o driver FTDI VCP, embora o Windows geralmente já forneça isso.

Alguns painéis S3 têm dois soquetes USB, um conectado à ponte e um conectado ao chip. Eles se comportam diferentemente e produzem nomes de porta diferentes. Anote qual soquete você conectou, porque importa quando você chegar às configurações da placa.

Permissões do Linux

No Linux, a porta existirá, mas você não poderá abri-la até que seu usuário esteja no grupo dialout:

sudo usermod -a -G dialout $USER

Faça logout e login novamente para que isso tenha efeito. Em algumas distribuições, o grupo é chamado de uucp.

Etapa 4: Selecione sua placa

Vá para Ferramentas > Placa > esp32 e você verá uma lista muito longa. Se sua placa tem uma entrada específica por nome, use-a, porque o fabricante já definiu o tamanho da flash, PSRAM e definições de pino para você. Se não, use a entrada do módulo de desenvolvimento genérico:

• ESP32-S2: ESP32S2 Dev Module
• ESP32-S3: ESP32S3 Dev Module
• ESP32-C6: ESP32C6 Dev Module

A lista é longa o suficiente para que a rolagem seja dolorosa. No Arduino IDE 2, você pode usar o menu suspenso do seletor de placa no topo da janela e digitar nele, o que é muito mais rápido.

Figura 4: Escolhendo o módulo de desenvolvimento correto

Etapa 5: As opções de placa que realmente importam

Assim que uma placa é selecionada, o menu Ferramentas é preenchido com opções. A maioria delas pode ser deixada como está. Estas são as que causar problemas se estiverem erradas.

Configuração	ESP32-S2	ESP32-S3	ESP32-C6
USB CDC On Boot	Ativado	Ativado	Ativado
Modo USB	Não oferecido	CDC de hardware e JTAG	Não oferecido
Tamanho da Flash	Corresponder ao módulo	Corresponder ao módulo	Corresponder ao módulo
PSRAM	Ativado apenas se instalado	QSPI ou OPI, conforme instalado	Não suportado
Frequência de CPU	240 MHz	240 MHz	160 MHz
Esquema de Partição	Padrão para começar	Padrão para começar	Padrão para começar
Velocidade de Upload	921600, reduzir se não confiável	921600, reduzir se não confiável	921600, reduzir se não confiável
Nível de Debug do Núcleo	Nenhum	Nenhum	Nenhum

USB CDC On Boot

Esta é a causa mais comum de "meu sketch faz upload mas o monitor serial mostra nada". Em uma placa usando USB nativo, a porta serial com a qual você está conversando é criada pelo sketch em si. Se USB CDC On Boot está desativado, Serial é roteado para os pinos UART de hardware em vez do soquete USB, e você não verá nada na tela. Configure para Ativado.

Se sua placa usa um chip de ponte USB para serial separado, deixe desativado, porque nesse caso Serial indo para os pinos UART é exatamente o que você quer.

Tamanho da flash e esquema de partição

Configure o tamanho da flash para corresponder ao módulo, não ao maior valor da lista. Se você disser ao IDE que tem 16MB e o módulo tem apenas 4MB, o upload pode parecer bem-sucedido e depois a placa entrará em loop de inicialização ou perderá suas configurações armazenadas.

O esquema de partição padrão é bom até que seu sketch compilado exceda a partição de aplicação. Quando o IDE começa a reclamar que o sketch é muito grande, mude para um dos esquemas de aplicação maiores. Se você pretende fazer atualizações em tempo real, você precisa de um esquema com duas partições de aplicação, pois OTA escreve a nova imagem na sobressalente antes de mudar.

PSRAM

Ative PSRAM apenas se o módulo o tiver fisicamente. Ativar em um módulo sem ele produzirá falhas de inicialização ou um fluxo de erros na saída serial. No S3, você também deve escolher entre QSPI e OPI, e fazer isso errado causa os mesmos sintomas. Verifique o número da peça do módulo se não tiver certeza. O C6 não tem suporte PSRAM, portanto a opção não aparece.

Figura 5: As opções de placa no menu Ferramentas

Etapa 6: Encontre a porta

Conecte a placa e procure em Ferramentas > Porta. No Windows você verá um número COM. No macOS você verá algo começando com /dev/cu.usbmodem para USB nativo ou /dev/cu.usbserial para um chip de ponte. No Linux, será /dev/ttyACM0 ou /dev/ttyUSB0.

Se nada aparecer, trabalhe nisso nesta ordem:

1. Tente um cabo diferente. Isso resolve o problema mais frequentemente do que qualquer outra coisa.
2. Tente um soquete USB diferente, de preferência um diretamente na máquina em vez de através de um hub.
3. Verifique se a placa tem um chip de ponte que precisa de um driver.
4. No Windows, abra o Gerenciador de Dispositivos e procure por um dispositivo desconhecido aparecendo e desaparecendo conforme você conecta a placa.

Há um comportamento com USB nativo que surpreende todo mundo na primeira vez. A porta pertence ao sketch em execução, portanto desaparece na redefinição e reaparece um ou dois segundos depois. Se você fazer upload de um sketch que falha no início, a porta pode desaparecer permanentemente até que você force a placa no modo de download.

Etapa 7: Forçando o modo de download

Se o upload falhar com uma mensagem sobre falha na conexão, você precisa colocar o chip em seu bootloader manualmente. A sequência é sempre a mesma:

1. Mantenha pressionado o botão BOOT (às vezes marcado IO0).
2. Pressione e solte o botão RESET (às vezes marcado EN ou RST).
3. Solte BOOT.

A placa está agora em seu bootloader ROM, esperando. Em uma placa USB nativo, ela será enumerada como uma porta serial diferente neste ponto, portanto volte a Ferramentas > Porta e selecione a nova antes de fazer upload. Assim que o upload terminar, pressione RESET por si só para executar o sketch, e a porta original voltará.

Figura 6: Botões BOOT e RESET - No Mercury o botão POWER é RESET, e o BUTTON é o botão BOOT por exemplo.

Etapa 8: Um primeiro sketch para provar a cadeia de ferramentas

Resista ao desejo de começar com piscar. Em muitas placas de desenvolvimento S3 e C6, o LED embarcado é do tipo RGB endereçável em vez de um simples, portanto um sketch de piscar padrão não faz nada e você fica se perguntando se o upload funcionou. Imprima algo em série, pois isso informa que o chip está realmente executando seu código e confirma as configurações da placa ao mesmo tempo.

void setup() {
  Serial.begin(115200);
  delay(2000);   // permite que a porta serial USB se enumere antes de imprimir

  Serial.println();
  Serial.println("ESP32 está vivo");
  Serial.print("Modelo do chip: ");
  Serial.println(ESP.getChipModel());
  Serial.print("Núcleos       : ");
  Serial.println(ESP.getChipCores());
  Serial.print("Bytes de flash: ");
  Serial.println(ESP.getFlashChipSize());
  Serial.print("Heap livre    : ");
  Serial.println(ESP.getFreeHeap());
}

void loop() {
  Serial.print("tempo decorrido ms: ");
  Serial.println(millis());
  delay(1000);
}

Clique na seta para fazer upload, depois abra o Monitor Serial com o ícone de lupa no canto superior direito e configure a taxa de transmissão para 115200. Você deve ver o chip se relatar. Se a linha do modelo diz ESP32-S3 e você selecionou uma placa S3, tudo do IDE até o silício está comunicando corretamente.

O atraso de dois segundos no início está lá propositalmente. Com USB nativo, o host leva um momento para abrir a porta após a redefinição, e qualquer coisa impressa antes disso é perdida. Não substitua com um simples loop while (!Serial);, porque em uma placa alimentada por bateria sem computador conectado, isso travará para sempre. Se você quer esperar corretamente, coloque um tempo limite nele:

while (!Serial && millis() < 3000) {
  delay(10);
}

Etapa 9: Instalar bibliotecas

A maioria dos sensores e periféricos precisa de uma biblioteca. Use o gerenciador de bibliotecas, que é o ícone de livros na barra de ferramentas esquerda, ou Sketch > Incluir Biblioteca > Gerenciar Bibliotecas. Pesquise, escolha, instale, e o IDE oferecerá para trazer dependências também. Diga sim para essas.

Para uma biblioteca fornecida como arquivo ZIP, use Sketch > Incluir Biblioteca > Adicionar .ZIP Biblioteca. Ela é desempacotada na pasta de bibliotecas dentro de seu sketchbook, e você também pode simplesmente colocar uma pasta lá manualmente se preferir. Reinicie o IDE depois se uma biblioteca adicionada manualmente não aparecer.

Uma coisa a se observar: nem toda biblioteca Arduino funciona no ESP32, e das que funcionam, nem todas funcionam em todos os três chips. Qualquer coisa que bata em registros AVR diretamente, ou assume o conjunto periférico ESP32 clássico mais antigo, pode falhar ao compilar no C6 em particular, porque é uma parte RISC-V em vez de Xtensa. Se uma biblioteca se recusar a construir, verifique seu rastreador de problemas antes de assumir que sua configuração está quebrada.

Mantendo suas versões sob controle

Esta parte é pulada por quase todo mundo e depois causa problemas seis meses depois. A versão do núcleo com a qual você compila afeta o tempo, comportamento periférico e ocasionalmente o significado de uma chamada de API. Um projeto que construiu e voou perfeitamente na última temporada pode se comportar diferentemente após uma atualização.

Dois hábitos valem a pena formar:

• Anote a versão do núcleo e as versões de biblioteca que usou, junto com o código. Um comentário no topo do arquivo do sketch principal é suficiente.
• Não atualize o núcleo no meio de um projeto a menos que tenha um motivo. Termine, verifique, depois atualize, depois re-verifique antes de confiar nele novamente.

O gerenciador de placas permite que você escolha qualquer versão publicada no menu suspenso, não apenas a mais recente, portanto voltar é direto se uma atualização quebrar algo.

Solução de Problemas

Sintoma	Causa provável e correção
Nenhuma porta aparece	Cabo apenas de carregamento, driver de ponte faltando, ou um hub no caminho. Tente primeiro um cabo conhecido como bom.
Falha ao conectar, ou timeout aguardando cabeçalho de pacote	O chip não está no modo de download. Use a sequência BOOT e RESET, depois re-selecione a porta que aparece.
Upload bem-sucedido, mas o monitor serial está em branco	USB CDC On Boot está desativado, ou a taxa de transmissão está errada, ou você imprimiu antes da porta abrir.
Reinicializações contínuas com uma razão rst impressa em 115200	Normalmente PSRAM ativado quando não há nenhum montado, o modo PSRAM errado em um S3, ou tamanho de flash incorreto.
Detector brownout foi acionado	Corrente de alimentação insuficiente, frequentemente durante transmissão Wi-Fi. Use uma alimentação melhor ou um cabo mais curto.
Sketch muito grande	Mude para um esquema de partição com uma área de aplicativo maior.
A porta desaparece no momento em que o sketch inicia	O sketch está falhando durante a inicialização. Force o modo de download e faça upload de algo que se sabe que funciona.
Apenas o Nano ESP32 aparece na lista de placas	Você instalou Arduino ESP32 Boards em vez de esp32 por Espressif Systems. Instale o pacote Espressif também.
Placa não aparece na lista	Núcleo muito antigo, particularmente para o C6. Atualize para 3.x ou posterior.
Erros de compilação logo após instalar o núcleo	Download interrompido. Remova o pacote esp32 no gerenciador de placas e instale novamente.

Para onde ir a seguir

Assim que você tiver saída serial funcionando, você tem a parte difícil atrás de você. Tudo depois disso é apenas código. Os exemplos que vêm com o núcleo são um bom lugar para começar, e todos estão em Arquivo > Exemplos uma vez que uma placa ESP32 é selecionada. Apenas os exemplos relevantes para o chip que você escolheu serão mostrados, o que é útil em si mesmo quando você está tentando descobrir o que uma parte particular pode fazer.

Se algo neste guia não corresponder ao que você está vendo, as configurações da placa são o primeiro lugar a procurar. Nove em cada dez vezes é USB CDC On Boot, o tamanho da flash ou a configuração de PSRAM.