Guias · 10 min de leitura

Pacote de placas ESP32 não instala: como resolver os erros na Arduino IDE

O pacote de placas ESP32 não instala na Arduino IDE? Use a URL certa e resolva Error downloading, tempo limite, antivírus, proxy e restos de pacotes antigos, ou instale offline.

Quando o pacote de placas ESP32 não instala na Arduino IDE, você está diante do obstáculo mais comum de quem começa com o ESP32: o esp32 nunca aparece no Gerenciador de Placas, a instalação para no meio com “Error downloading” ou estoura o tempo limite depois de minutos de espera. O problema quase sempre vem de uma destas cinco fontes: uma URL do Gerenciador de Placas errada ou desatualizada, uma conexão de internet lenta ou restrita, um antivírus travando arquivos, downloads antigos que ficaram pela metade e restos de pacotes mais antigos no disco.

Neste guia você vai primeiro fazer uma instalação limpa, passo a passo, e depois encontrar a solução que corresponde à mensagem de erro na sua tela. Também vai ver como instalar offline em redes restritas de escolas e escritórios, como obter uma saída detalhada com o Arduino CLI e como escolher entre os cores 2.x e 3.x. Por fim, um pequeno sketch de teste confirma que a instalação funciona de verdade.

Placa de desenvolvimento ESP32 DevKit
ESP32 DevKit: para programá-lo na Arduino IDE, primeiro é preciso instalar o pacote de placas da Espressif.

O que é o pacote de placas ESP32 e por que ele é tão grande?

Recém-instalada, a Arduino IDE só conhece as placas da própria Arduino. Para o ESP32 você precisa do pacote (core) arduino-esp32, da Espressif. Ele é muito mais do que alguns arquivos: inclui as toolchains de compilação Xtensa e RISC-V, as bibliotecas do ESP-IDF, a ferramenta de gravação esptool e ferramentas de sistema de arquivos. As versões 3.x atuais baixam centenas de megabytes e ocupam vários gigabytes depois de descompactadas. Quanto maior o download, maior a chance de ele ser interrompido, e é daí que vem a maioria dos erros.

Instalação limpa, passo a passo

  1. Use a versão 2.x mais recente da Arduino IDE; a base Java antiga da 1.8.x às vezes não consegue abrir conexões seguras com alguns servidores.
  2. Abra Arquivo > Preferências (no macOS, Arduino IDE > Configurações).
  3. Cole este endereço no campo URLs do Gerenciador de Placas Adicionais: https://espressif.github.io/arduino-esp32/package_esp32_index.json. Se você já tiver outras URLs, coloque cada uma em uma linha.
  4. Clique em OK e espere a IDE baixar o índice de pacotes, na parte de baixo da janela.
  5. Abra o Gerenciador de Placas na barra lateral esquerda, digite esp32 e clique em Instalar em esp32 by Espressif Systems. O pacote “Arduino ESP32 Boards”, da própria Arduino, serve só para o Nano ESP32; não confunda os dois.
  6. Quando terminar, escolha ESP32 Dev Module ou o modelo da sua placa em Ferramentas > Placa.
O endereço https://dl.espressif.com/dl/package_esp32_index.json, que aparece em tutoriais mais antigos, não é mais atualizado e só lista versões muito velhas. Se ele ainda estiver na sua lista, apague-o; ter duas URLs diferentes do ESP32 ao mesmo tempo bagunça a lista de versões e pode fazer os downloads falharem.

Tabela de soluções por mensagem de erro

Quando a instalação falha, o painel Saída, na parte de baixo da IDE, mostra uma mensagem comprida. Você não precisa decifrar tudo: encontre a expressão-chave na tabela abaixo e aplique a solução ao lado. Se aparecerem várias, a última linha costuma ser a causa real.

A mensagem contémO que significaSolução
Error downloading ... package_esp32_index.jsonNão é possível acessar o índice de pacotesConfira a URL letra por letra e abra-a em um navegador; se ela não carregar, o problema é a sua rede ou o proxy
context deadline exceeded, Client.Timeout exceeded, DEADLINE_EXCEEDEDO download estourou o tempo limiteAumente o tempo limite, tente uma rede cabeada ou o hotspot do celular
TLS handshake timeout, x509: certificate signed by unknown authorityNão foi possível estabelecer uma conexão seguraAcerte a data e a hora do computador; em rede corporativa, informe as configurações de proxy
checksum mismatch, archive hash differs, CRC doesn't matchO arquivo baixado está corrompido ou incompletoApague os arquivos do ESP32 na pasta staging e instale de novo
Access is denied, moving extracted archive, renameO antivírus ou outro programa travou um arquivoAdicione a pasta Arduino15 às exclusões do antivírus e reinicie a IDE
no space left on deviceO disco está cheioLibere pelo menos 5 GB de espaço em disco e remova versões antigas do core
403 Forbidden, 404 Not Found (github.com)O GitHub está bloqueado ou o endereço está desatualizadoTente outra rede e atualize a IDE e a URL
O esp32 não aparece no Gerenciador de PlacasFalta a URL ou o índice não foi atualizadoAdicione a URL e reinicie a IDE

Tempo limite e conexões lentas

O caso mais comum é a conexão cair enquanto um dos arquivos grandes da toolchain está sendo baixado. A Arduino IDE 2.x usa o Arduino CLI por baixo dos panos, e o tempo limite de rede padrão dele pode ser curto demais para conexões lentas. Tente primeiro as soluções simples: uma conexão cabeada ou o hotspot do celular em vez do Wi-Fi, desligar ou ligar a VPN, ou tentar de novo quando a rede estiver tranquila. Se uma instalação foi interrompida, a IDE não baixa de novo os arquivos já concluídos quando você a reinicia, então algumas tentativas podem bastar para chegar lá.

Se o problema continuar, aumente o tempo limite. Com a IDE fechada, abra .arduinoIDE/arduino-cli.yaml, na sua pasta de usuário, em um editor de texto, acrescente uma seção network: e, indentada abaixo dela, a linha connection_timeout: 600s. Isso aumenta a espera para 10 minutos e funciona nas versões atuais da IDE, que trazem o Arduino CLI 1.x; se a sua IDE for mais antiga, atualize-a antes. Em redes corporativas, informe o endereço de proxy exigido em Preferências > Rede, na IDE.

Antivírus, firewall e proxy

No Windows, uma instalação que para perto do fim com “Access is denied” ou “moving extracted archive” costuma ser culpa do antivírus. Descompactar o pacote cria milhares de arquivos pequenos; o Windows Defender ou outra ferramenta de segurança trava esses arquivos para examiná-los, e a IDE não consegue movê-los para o lugar. A solução é adicionar a pasta Arduino15 às exclusões do antivírus durante a instalação; excluir só essa pasta é mais seguro do que desligar a proteção por completo. Em redes de escolas e empresas, um firewall também pode bloquear os servidores de download do GitHub. Se o índice de pacotes abre no navegador, mas a instalação continua falhando, peça o endereço do proxy ao administrador da rede, ou instale o pacote em casa e leve-o com o método offline descrito mais abaixo.

Sistema operacionalPasta Arduino15Downloads parciais (staging)
Windows%LOCALAPPDATA%\Arduino15%LOCALAPPDATA%\Arduino15\staging\packages
macOS~/Library/Arduino15~/Library/Arduino15/staging/packages
Linux~/.arduino15~/.arduino15/staging/packages

Limpeza de restos de pacotes antigos

Se você já instalou o ESP32 de outro jeito (por exemplo, manualmente pelo GitHub) ou adicionou uma versão antiga anos atrás, a nova instalação pode entrar em conflito com arquivos velhos. Sinais típicos: a instalação termina sem erros, mas o ESP32 aparece duas vezes na lista de placas; a compilação mostra avisos “multiple libraries were found”; ou a IDE insiste em usar uma versão antiga. Estes passos garantem um começo totalmente limpo.

  1. Feche a Arduino IDE por completo.
  2. Apague a pasta packages/esp32 e o arquivo package_esp32_index.json dentro da Arduino15.
  3. Apague os arquivos parciais do ESP32 em staging/packages (os que começam com esp32-, xtensa-, riscv32- e esptool).
  4. Se a sua pasta do sketchbook (normalmente Documentos/Arduino) tiver uma pasta hardware/espressif, remova-a também; ela sobrou de uma instalação manual antiga e entra em conflito com a instalação feita pelo Gerenciador de Placas.
  5. Abra a IDE, confira se só a URL atual do ESP32 ficou em Preferências e instale o pacote de novo.
Na maioria dos casos, basta clicar uma vez em Remover no pacote esp32, no Gerenciador de Placas, e instalá-lo de novo; apague pastas manualmente só se isso não resolver. Se quiser um backup antes, copiar a pasta packages de dentro da Arduino15 é tudo de que você precisa.

Instalação offline e manual

Em um laboratório de escola com internet restrita ou em uma conexão muito lenta, o caminho mais confiável é instalar o pacote em um computador com internet boa e copiá-lo para o outro. Isso funciona sem sustos entre dois computadores com o mesmo sistema operacional, porque os compiladores são específicos de cada sistema: um pacote instalado no Windows não roda no macOS.

  1. Instale a Arduino IDE e o pacote ESP32 do jeito normal no computador com internet boa.
  2. Copie a pasta packages/esp32 e o arquivo package_esp32_index.json da pasta Arduino15 desse computador para um pen drive.
  3. No computador de destino, abra e feche a Arduino IDE uma vez, para que a pasta Arduino15 seja criada.
  4. Cole o que você copiou nos mesmos lugares da pasta Arduino15 do computador de destino e adicione a mesma URL do ESP32 em Preferências.
  5. Abra a IDE; o Gerenciador de Placas vai mostrar o esp32 como instalado, e as placas ESP32 vão aparecer em Ferramentas > Placa.

Um segundo caminho é baixar pelo navegador os arquivos em que a IDE empaca e colocá-los na pasta staging/packages. Antes de instalar, a IDE confere essa pasta; se o nome do arquivo e o checksum baterem exatamente com o índice de pacotes (package_esp32_index.json), ela pula o download e descompacta o arquivo direto. A linha “Downloading” do painel Saída mostra qual arquivo é necessário. Um terceiro caminho, para desenvolvedores, é clonar o repositório do GitHub em hardware/espressif, no seu sketchbook, mas esse método não pode ser usado junto com uma instalação pelo Gerenciador de Placas.

Instalação detalhada com o Arduino CLI

A IDE só mostra uma mensagem de erro curta. Se você quiser ver exatamente em que arquivo e em que etapa a instalação falha, dá para fazer o mesmo trabalho pela linha de comando, com o Arduino CLI. Como a IDE 2.x já usa essa ferramenta em segundo plano, um pacote instalado pelo CLI também aparece na IDE, desde que os dois usem a mesma pasta de dados.

ComandoO que faz
arduino-cli config initCria o arquivo de configuração
arduino-cli config add board_manager.additional_urls https://espressif.github.io/arduino-esp32/package_esp32_index.jsonAdiciona a URL do pacote ESP32
arduino-cli core update-indexBaixa os índices de pacotes
arduino-cli core install esp32:esp32 -vInstala o pacote ESP32 com saída detalhada
arduino-cli core install esp32:[email protected]Instala uma versão específica
arduino-cli core listLista os cores instalados e as respectivas versões

Como escolher a versão certa do core

O Gerenciador de Placas sempre sugere a versão mais nova, mas a mais nova nem sempre é a certa para todo projeto. Na versão 3.0, o arduino-esp32 passou para o ESP-IDF 5 e algumas funções mudaram: o PWM agora usa ledcAttach no lugar de ledcSetup e ledcAttachPin, e os timers usam timerBegin(frequency) no lugar de timerBegin(0, 80, true). É por isso que uma biblioteca ou um tutorial antigo, escrito para a 2.x, pode não compilar na 3.x. No Gerenciador de Placas, você pode escolher qualquer versão na lista suspensa abaixo do pacote e instalá-la; só uma versão fica instalada por vez.

VersãoBase ESP-IDFChips compatíveisQuando escolher
1.0.63.3Só ESP32Só para recompilar um projeto muito antigo do jeito que está
2.0.174.4ESP32, S2, S3, C3Bibliotecas ainda não atualizadas para a 3.x e tutoriais mais antigos
3.x (atual)5.xESP32, S2, S3, C3, C6, H2 e mais recentesO padrão para projetos novos e chips novos

Se você quer que o seu código compile nas duas versões, use a macro de versão. O exemplo abaixo faz o LED da placa acender e apagar suavemente; se ESP_ARDUINO_VERSION_MAJOR for 3 ou mais, ele compila as funções novas de PWM; caso contrário, as antigas. O mesmo truque vale para código de timers e de pinos de toque.

C++ (Arduino IDE)
1// Hem 2.x hem 3.x çekirdekte derlenen PWM örneği / PWM example that builds on both 2.x and 3.x cores
2const int LED_PIN  = 2;
3const int PWM_FREQ = 5000;     // 5 kHz
4const int PWM_RES  = 8;        // 8 bit: 0-255
5
6void setup() {
7#if ESP_ARDUINO_VERSION_MAJOR >= 3
8  ledcAttach(LED_PIN, PWM_FREQ, PWM_RES);   // 3.x: pin tabanlı API / pin-based API
9#else
10  ledcSetup(0, PWM_FREQ, PWM_RES);          // 2.x: önce kanal kurulur / set up the channel first
11  ledcAttachPin(LED_PIN, 0);
12#endif
13}
14
15void loop() {
16  for (int duty = 0; duty <= 255; duty++) {
17#if ESP_ARDUINO_VERSION_MAJOR >= 3
18    ledcWrite(LED_PIN, duty);               // 3.x: pin numarası / pin number
19#else
20    ledcWrite(0, duty);                     // 2.x: kanal numarası / channel number
21#endif
22    delay(5);
23  }
24}

Como testar a instalação

Não suponha que está tudo funcionando só porque a instalação terminou. Carregue o sketch abaixo e abra o Monitor Serial em 115200 baud; você vai ver a versão do core instalado, a versão do ESP-IDF, o modelo do chip e o tamanho da flash, e o LED da placa vai piscar. Se aparecerem erros na compilação, o problema ainda é a instalação; se o carregamento terminar com “Failed to connect”, o problema passou a ser a placa, o cabo ou o driver.

C++ (Arduino IDE)
1// ESP32 kart paketi kurulum testi / ESP32 board package install test
2// Seri Monitör: 115200 baud / Serial Monitor: 115200 baud
3
4const int LED_PIN = 2;      // çoğu DevKit'te dahili LED / onboard LED on most DevKits
5
6void setup() {
7  Serial.begin(115200);
8  delay(1000);
9  Serial.printf("Arduino-ESP32 core: %d.%d.%d\n",
10                ESP_ARDUINO_VERSION_MAJOR, ESP_ARDUINO_VERSION_MINOR, ESP_ARDUINO_VERSION_PATCH);
11  Serial.printf("ESP-IDF: %s\n", ESP.getSdkVersion());
12  Serial.printf("Yonga / Chip: %s rev %d, %d cekirdek / cores\n",
13                ESP.getChipModel(), ESP.getChipRevision(), ESP.getChipCores());
14  Serial.printf("Flash: %u MB, CPU: %u MHz\n",
15                (unsigned)(ESP.getFlashChipSize() / (1024 * 1024)), (unsigned)ESP.getCpuFreqMHz());
16  pinMode(LED_PIN, OUTPUT);
17}
18
19void loop() {
20  digitalWrite(LED_PIN, !digitalRead(LED_PIN));   // LED yanıp söner / LED blinks
21  delay(500);
22}
Se o ESP32 nem aparece na lista de portas, o que falta é o driver USB, não o pacote de placas; veja o guia de instalação do driver CH340. Se o código compila, mas o carregamento termina com “Failed to connect”, o método do botão BOOT do guia ESP32 Failed to connect resolve.

Ainda não instala? Lista final de verificação

  • A data e a hora estão certas? Um relógio errado invalida os certificados das conexões seguras, e todos os downloads falham.
  • Seu nome de usuário tem letras acentuadas ou espaços? Algumas ferramentas falham em caminhos com caracteres acentuados ou não latinos; com a configuração directories.data do arduino-cli.yaml, você pode mover a pasta de pacotes para um caminho curto, como C:\Arduino15.
  • Limite de caminhos longos do Windows: caminhos com mais de 260 caracteres podem impedir a descompactação do pacote; ativar o suporte a caminhos longos no Windows ou manter os caminhos das pastas curtos ajuda.
  • Espaço em disco: os arquivos compactados baixados e os descompactados ficam lado a lado por um tempo durante a instalação, então mantenha pelo menos 5 GB de espaço livre.
  • Tente outra ferramenta: se a IDE falhar, tente o Arduino CLI; se ele também falhar, tente o PlatformIO, que baixa os pacotes dos próprios servidores.
  • Teste seu código enquanto espera: até a instalação ser resolvida, você pode rodar o circuito e o código no navegador com o simulador Wokwi.

Com o pacote de placas ESP32 instalado corretamente, partir para projetos com Wi-Fi, Bluetooth e sensores é questão de minutos. Se o ESP32 é novidade para você, comece por O que é o ESP32?; depois, no app BlueGrays, você pode fazer passo a passo os projetos de LED com ESP32, de LED da placa e de conexão Wi-Fi, com esquemas do circuito e código pronto para usar.

Perguntas frequentes

Por que o pacote de placas ESP32 não instala?

As causas mais comuns são uma URL do Gerenciador de Placas errada ou desatualizada, uma conexão lenta que estoura o tempo limite, um antivírus travando arquivos e downloads antigos que ficaram pela metade. Confira primeiro se a URL é https://espressif.github.io/arduino-esp32/package_esp32_index.json e depois aplique a solução que corresponde à mensagem de erro do painel Saída.

Qual é a URL correta do ESP32 para o Gerenciador de Placas?

Para a versão estável atual, use https://espressif.github.io/arduino-esp32/package_esp32_index.json. O endereço antigo, dl.espressif.com, só lista versões muito velhas; se ele ainda estiver na sua lista, remova-o, porque duas URLs do ESP32 ao mesmo tempo podem causar problemas.

Como resolver o “Error downloading” na Arduino IDE?

Primeiro tente abrir a URL do pacote em um navegador; se ela não carregar, o problema é a sua rede, o proxy ou o firewall. Se carregar, apague os arquivos parciais da pasta staging, confira o relógio do computador e recomece a instalação por uma conexão cabeada ou pelo hotspot do celular.

Devo instalar o core 2.x ou 3.x do ESP32?

Escolha a 3.x para projetos novos e chips mais recentes, como o ESP32-C6. Se uma biblioteca ou um tutorial de que você depende foi escrito para a 2.x e não compila na 3.x, instale a 2.0.17, a última versão da série 2.x. Você pode trocar de versão quando quiser pela lista suspensa do Gerenciador de Placas.

Dá para instalar o pacote ESP32 sem internet?

Sim. Instale o pacote em um computador com internet e com o mesmo sistema operacional, depois copie a pasta packages/esp32 e o arquivo package_esp32_index.json da pasta Arduino15 dele para o mesmo lugar no computador de destino. Quando você abrir a IDE, o pacote vai aparecer como instalado.

Quanto espaço em disco o pacote ESP32 ocupa?

Depende da versão; as versões 3.x atuais ocupam vários gigabytes com as toolchains e as bibliotecas. Os arquivos compactados e os descompactados coexistem durante a instalação, então manter pelo menos 5 GB de espaço livre é uma margem segura.

Ver todos os projetos
LED integrado do ESP32 piscando
ES-4Iniciante

LED integrado do ESP32 piscando

Faça o LED azul integrado do ESP32 DevKit V1 piscar. Nenhum componente externo é necessário! O primeiro projeto para experimentar ao comprar um ESP32. GPIO 2 está conectado ao LED integrado.

4.8(29)
54
LED piscando com ESP32
ES-1Iniciante

LED piscando com ESP32

Ensina o uso básico de uma saída GPIO no ESP32. Fazemos um LED piscar ligando e desligando um pino digital. É a versão para ESP32 do clássico projeto blink do Arduino UNO: os comandos básicos de blink no ambiente Arduino são os mesmos, mas a disposição dos pinos e os níveis de 3,3 V dos GPIOs do ESP32 diferem dos do Arduino UNO.

4.7(37)
108
Controle de LED com botão no ESP32 (momentâneo)
ES-2Iniciante

Controle de LED com botão no ESP32 (momentâneo)

O LED acende enquanto o botão está pressionado e apaga ao soltá-lo. Mostra como usar o pino de entrada digital e o resistor pull-up interno do ESP32. O modo INPUT_PULLUP dispensa um resistor externo.

4.6(36)
57
Semáforo com ESP32
ES-5Iniciante

Semáforo com ESP32

Simulação de um semáforo real com 3 LEDs: vermelho, amarelo e verde. Os tempos se aproximam da lógica real: vermelho longo, amarelo curto e verde longo. Um exemplo clássico de controle sequencial de GPIOs.

4.4(22)
45
Leitura da intensidade da luz com módulo LDR e ESP32
ES-11Iniciante

Leitura da intensidade da luz com módulo LDR e ESP32

Acompanhe em tempo real no Monitor Serial o valor bruto do ADC do módulo LDR e a porcentagem relativa de luz calculada a partir de referências de escuridão e claridade. Essa porcentagem não é uma medida em lux. O projeto ensina a lógica de calibração do módulo. É ideal fazê-lo antes do projeto 10, pois ajuda a determinar o valor do limiar.

4.6(36)
55
Variação gradual do brilho do LED com PWM no ESP32
ES-8Iniciante

Variação gradual do brilho do LED com PWM no ESP32

Varie suavemente o brilho do LED de 0 ao máximo e do máximo a 0. Controlamos o PWM com analogWrite(), como no Arduino. A mesma sintaxe funciona sem problemas com ESP32 Arduino Core 3.0+. Basta definir o pino e usar pinMode e analogWrite.

4.8(36)
55
Conexão Wi-Fi STA com ESP32 e display LCD
ES-25Avançado

Conexão Wi-Fi STA com ESP32 e display LCD

Neste projeto, conectamos o ESP32 à rede Wi-Fi de casa no modo estação (STA), de forma segura e tolerante a falhas. Guardamos o SSID e a senha em um arquivo secrets.h separado para evitar que sejam expostos no Git, configuramos um mecanismo de reconexão automática e exibimos o nível de sinal RSSI e o endereço IP em um display LCD I2C. O LED integrado funciona como indicador de status. É um gerenciador de conexão pronto para uso em produção.

4.4(21)
38
Servidor web assíncrono com ESP32 (IP no LCD)
ES-27Avançado

Servidor web assíncrono com ESP32 (IP no LCD)

Neste projeto, transformamos o ESP32 em um servidor web assíncrono que você pode controlar pelo celular ou computador na mesma rede Wi-Fi. Com a biblioteca ESPAsyncWebServer, o servidor processa várias requisições ao mesmo tempo (ao contrário do WebServer.h tradicional, que bloqueia a execução ao processar uma requisição). Você poderá abrir o endereço IP do ESP32 no navegador e clicar nos botões ON/OFF (as rotas /on e /off) para ligar e desligar o LED conectado ao GPIO 5.

4.8(16)
26