Neste tutorial, vais aprender como instalar o core ESP32 no Arduino IDE. O ESP32 é um microcontrolador poderoso e versátil, amplamente utilizado em projetos de IoT e maker. Para programá-lo usando o Arduino IDE, precisas de instalar o core ESP32.
O core ESP32 funciona como uma ponte entre o ambiente Arduino e o hardware ESP32. Ele fornece as ferramentas, bibliotecas e definições necessárias para compilar e carregar o teu código na placa ESP32.
Vais aprender o que é um core Arduino, por que é essencial e como instalar o core ESP32 passo a passo. Também abordaremos a instalação dos drivers USB-para-Serial necessários, a seleção da placa e porta corretas, e a configuração das definições da placa. No final, estarás pronto para começar a criar os teus projetos ESP32 usando o familiar Arduino IDE.
O que é um Core no Arduino IDE?
No ecossistema Arduino, umCoreé um conjunto de componentes de software que permite ao Arduino IDE compilar e carregar código para uma família específica de microcontroladores ou placas. Atua como a ponte essencial entre os teus sketches Arduino e o hardware que queres programar. Um Arduino Core normalmente inclui várias partes-chave:
Definições da Placa
São ficheiros JSON ou de configuração que descrevem as especificações do hardware de cada placa suportada. Definem a arquitetura da CPU, velocidade do relógio, pinos disponíveis, tamanhos de memória e outros parâmetros de hardware. Por exemplo, o core ESP32 inclui definições para placas populares como o ESP32 Dev Module, variantes WROOM e WROVER.
Toolchain do Compilador
O core inclui as ferramentas de compilação e ligação necessárias, adaptadas para a arquitetura alvo. Para o ESP32, isto significa o toolchain Xtensa GCC, que compila os teus sketches Arduino em código máquina que a CPU do ESP32 pode executar.
Ferramentas de Upload
Estas ferramentas gerem o processo de gravação do código compilado na placa. Para o ESP32, o core usa o esptool.py, uma utilidade em Python que comunica via ponte USB-para-Serial para carregar o firmware.
Bibliotecas do Core
Inclui a camada de abstração de hardware (HAL), drivers periféricos e APIs Arduino adaptadas para a plataforma alvo. Para o ESP32, o core integra o FreeRTOS para multitasking, stacks Wi-Fi e Bluetooth, e outras bibliotecas especializadas para aproveitar as funcionalidades avançadas do chip.
Por que é Necessário um Core?
O Arduino IDE foi originalmente desenhado para placas baseadas em AVR como o Arduino Uno. Quando queres programar um microcontrolador diferente, como o ESP32, o IDE precisa de saber como:
- Compilar código para a nova arquitetura CPU
- Gerir funcionalidades específicas do hardware da placa
- Carregar código usando o protocolo e ferramentas adequadas
- Fornecer bibliotecas que suportem os periféricos da placa
Sem um core, o IDE não consegue comunicar com a placa nem compilar código para ela. O core permite usar o mesmo código ou código muito semelhante para muitos microcontroladores diferentes e normalmente simplifica o código também.
Por exemplo, o seguinte código mostra o clássico Blink para o Arduino IDE que pisca um LED ligado ao GPIO 2 a cada segundo:
#define LED_PIN 2
void setup() {
pinMode(LED_PIN, OUTPUT);
}
void loop() {
digitalWrite(LED_PIN, HIGH);
delay(1000);
digitalWrite(LED_PIN, LOW);
delay(1000);
}
O mesmo código usando o ESP-IDF, que é um IDE específico para programação ESP32, é muito mais longo e complexo:
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/gpio.h"
#define LED_PIN GPIO_NUM_2
void blink_task(void *pvParameter) {
while (1) {
gpio_set_level(LED_PIN, 1);
vTaskDelay(pdMS_TO_TICKS(1000));
gpio_set_level(LED_PIN, 0);
vTaskDelay(pdMS_TO_TICKS(1000));
}
}
void app_main(void) {
gpio_config_t io_conf = {
.pin_bit_mask = (1ULL << LED_PIN),
.mode = GPIO_MODE_OUTPUT,
.pull_up_en = GPIO_PULLUP_DISABLE,
.pull_down_en = GPIO_PULLDOWN_DISABLE,
.intr_type = GPIO_INTR_DISABLE
};
gpio_config(&io_conf);
xTaskCreate(blink_task, "blink_task",
2048, NULL, 5, NULL);
}
Arquitetura do Core ESP32
O Core Arduino ESP32 é construído sobre o ESP-IDF oficial da Espressif (IoT Development Framework). Ele encapsula as APIs complexas do ESP-IDF em funções e classes amigáveis ao Arduino. A arquitetura do core inclui:
- Camada de Abstração de Hardware (HAL): Simplifica o acesso aos periféricos do ESP32 como GPIO, ADC, SPI, I2C e UART.
- Kernel FreeRTOS: Permite multitasking e operações em tempo real dentro dos sketches Arduino.
- Camada API Arduino: Oferece funções Arduino familiares (
setup(),loop(),digitalWrite(),analogRead(),Serial, etc.) adaptadas para o hardware ESP32.
Esta arquitetura permite aos desenvolvedores escrever sketches Arduino que correm em microcontroladores ESP32 ou em qualquer outro microcontrolador para o qual exista um core disponível.
Instalar ou Atualizar o Arduino IDE
Antes de instalar o core ESP32, certifica-te de que tens a versão mais recente do Arduino IDE. O core ESP32 requer o Arduino IDE 1.8.13 ou superior. Usar uma versão desatualizada pode causar problemas de compatibilidade.
Visita o Arduino website. Escolhe o teu sistema operativo: Windows, macOS ou Linux e descarrega a versão estável mais recente.
Instalar o Arduino IDE
- Windows: Executa o ficheiro
.exedescarregado e segue o assistente de instalação. - macOS: Abre o ficheiro
.dmge arrasta a aplicação Arduino para a pasta Aplicações. - Linux: Extrai o arquivo descarregado e executa o script
install.sh.
Atualizar o Arduino IDE
Se já tens o Arduino IDE instalado, verifica a tua versão indo a Help > About Arduino (Windows/Linux) ou Arduino > About Arduino (macOS). Compara a tua versão com a mais recente no site Arduino.
Instalar o Driver USB-para-Serial
Para programar a tua placa ESP32 a partir do Arduino IDE, o computador deve comunicar com a placa via uma ponte USB-para-Serial. A maioria das placas de desenvolvimento ESP32 usa chips USB-para-Serial CP210x ou CH340. Instalar o driver correto garante que o computador reconhece a placa corretamente.
Identificar o Chip USB-para-Serial
Primeiro, verifica qual chip USB-para-Serial a tua placa ESP32 usa. Consulta a descrição do produto ou a serigrafia na placa perto do conector USB.
Chips comuns incluem o CP2102 / CP2104 da Silicon Labs e o CH340 / CH341 da WCH. Depois de identificar o chip, descarrega o driver apropriado:
Após descarregar: executa o instalador, segue as instruções no ecrã e reinicia o computador se for solicitado.
Verificar Instalação do Driver
Liga a tua placa ESP32 via USB. Depois:
- No Windows, abre o Gestor de Dispositivos e procura em Portas (COM & LPT). Deverás ver uma nova porta COM identificada com o nome do chip USB-para-Serial.
- No macOS ou Linux, abre um terminal e executa:
ls /dev/tty.*
Procura um dispositivo como /dev/tty.SLAB_USBtoUART (CP210x) ou /dev/tty.wchusbserialXXXX (CH340).
Se vires o dispositivo, o driver foi instalado com sucesso. Instalar o driver USB-para-Serial correto é crucial. Sem ele, o Arduino IDE não consegue carregar código na tua placa ESP32. Depois desta etapa, podes avançar para adicionar o core ESP32 ao Arduino IDE.
Adicionar o Core ESP32 ao Arduino IDE
Agora que tens o Arduino IDE pronto e o driver USB-para-Serial instalado, é hora de adicionar o core ESP32. Este passo permite que o Arduino IDE reconheça e programe placas ESP32.
Para instalar o Core ESP32, abre o Arduino IDE e vai a File > Preferences como mostrado abaixo:
Isto abre o diálogo de Preferências. No final deste diálogo encontras uma secção chamada “Additional boards manager URLs:
Clica no botão à direita, que abre outro diálogo onde podes inserir a URL de onde o core ESP32 pode ser descarregado:
Podem já existir outras URLs (no meu caso para o ESP8266 e a placa Unihiker). A esta lista adiciona a seguinte URL para o core ESP32:
https://espressif.github.io/arduino-esp32/package_esp32_index.json
Alternativamente, podes usar esta:
https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
A ordem das URLs na lista não importa. Para outras arquiteturas de microcontroladores vê esta lista de core URLs.
Instalar placas ESP32
De seguida, abre o Gestor de Placas navegando para Tools > Board > Boards Manager. Na caixa de pesquisa escreve “esp32”, encontra a entrada chamada “esp32 by Espressif Systems” e clica no botão INSTALL:
A instalação pode demorar alguns minutos enquanto descarrega todos os ficheiros necessários. Depois de instalado, fecha o Gestor de Placas.
Adicionaste com sucesso o core ESP32. Agora, o Arduino IDE pode compilar e carregar código para placas ESP32. Na próxima secção, vamos configurar as definições da placa para corresponder ao teu modelo e placa ESP32 específicos.
Configurar as Definições da Placa ESP32
Depois de instalar o core ESP32, deves configurar as definições da placa. Estas opções controlam como o Arduino IDE constrói, carrega e executa o teu sketch no ESP32. Definições corretas são críticas para uploads estáveis, uso adequado da memória e depuração confiável.
Podes encontrar todas as definições em Tools após selecionares uma placa ESP32. A imagem abaixo mostra as definições para um “ESP32S3 Dev Module”:
Por que as Definições da Placa Importam
O ESP32 é altamente configurável. Suporta múltiplos métodos de upload, layouts de flash, modos USB e opções de depuração. Portanto, definições incorretas frequentemente causam falhas no upload, loops de boot ou crashes inesperados.
No entanto, apenas algumas definições são essenciais para a maioria dos projetos. Outras são avançadas e podem permanecer nos valores padrão. As definições mais importantes são:
- Placa: Deve corresponder exatamente à tua variante ESP32.
- Velocidade de Upload: Afeta a fiabilidade do upload.
- Tamanho do Flash: Deve corresponder à memória flash onboard.
- Esquema de Partição: Controla como a memória flash é dividida.
- PSRAM: RAM externa
- Porta: Determina onde o firmware é carregado.
Quando estas estiverem corretas, a maioria dos projetos compilará e carregará sem problemas. A seguir, um pouco mais de informação sobre estas definições:
Tamanho do Flash
Esta definição deve corresponder ao chip flash físico no teu módulo ESP32. Se estiver incorreta, os uploads podem ter sucesso, mas os sketches podem falhar em tempo de execução.
Esquema de Partição
O Esquema de Partição define como a memória flash do ESP32 é dividida e alocada. Especifica onde o código da aplicação, bootloader, sistemas de ficheiros e slots opcionais de atualização OTA (Over-The-Air) são armazenados. Esta definição afeta diretamente o tamanho máximo do teu sketch e quais funcionalidades estão disponíveis.
- Escolhe Default para sketches simples.
- Usa Minimal SPIFFS se a tua aplicação for grande.
- Seleciona OTA se planeias atualizar o firmware sem fios.
Velocidade de Upload
Velocidades mais altas reduzem o tempo de upload, mas podem causar falhas em conexões USB instáveis. Se os uploads falharem, reduz a velocidade para 115200.
USB CDC e Modo USB
Estas definições são essenciais para placas ESP32-S2 e ESP32-S3. Permitem comunicação USB direta sem um conversor USB-para-Serial externo.
PSRAM
Ativa isto apenas se a tua placa incluir fisicamente PSRAM. Caso contrário, o sketch pode falhar ao arrancar. Normalmente, precisas de PSRAM para aplicações com alta exigência de RAM, como vídeo ou áudio.
Definições e suas Funções
Lista das definições mais comuns e suas funções:
| Definição | Descrição | Quando Alterar |
|---|---|---|
| USB CDC On Boot | Ativa comunicação serial USB via USB nativo em vez de UART | Ativa para placas USB-based ESP32-S2/S3 |
| Modo USB | Seleciona funcionalidade USB (CDC, HID, MSC ou desativado) | Usa CDC para suporte ao Monitor Serial |
| USB DFU On Boot | Ativa modo Device Firmware Update ao arrancar | Necessário para fluxos de flashing DFU |
| Modo de Upload | Define como o firmware é carregado (UART0, USB, OTA) | Altera apenas se usares USB ou OTA |
| Velocidade de Upload | Taxa de baud usada durante o upload | Reduz se os uploads falharem |
| Tamanho do Flash | Tamanho da memória flash onboard (ex.: 4MB, 8MB, 16MB) | Deve corresponder ao hardware |
| Modo Flash | Modo de comunicação entre ESP32 e flash (QIO, DIO, etc.) | Mantém o padrão a menos que o datasheet indique o contrário |
| Frequência do Flash | Velocidade do relógio do flash (40MHz ou 80MHz) | Reduz se ocorrer instabilidade no flash |
| Esquema de Partição | Define o layout da memória (tamanho da app, SPIFFS, OTA) | Altera para OTA ou sistemas de ficheiros |
| Apagar Todo o Flash Antes do Upload | Limpa todo o flash antes do upload | Ativa se enfrentares problemas de boot ou OTA |
| Nível de Depuração do Core | Controla a verbosidade da saída de depuração | Aumenta durante o desenvolvimento |
| PSRAM | Ativa RAM pseudo-estática externa | Ativa se a placa incluir PSRAM |
| Adaptador JTAG | Seleciona interface JTAG para depuração | Necessário apenas para depuração de hardware |
| Frequência da CPU | Define a velocidade do relógio da CPU (ex.: 80MHz, 160MHz, 240MHz) | Reduz para poupar energia |
| Arduino Corre em | Seleciona core (PRO ou APP CPU) | Mantém o padrão para a maioria dos casos |
Selecionar a Placa e Porta
Depois de configurar as definições da placa ESP32, deves selecionar a placa e porta corretas. Este passo informa o Arduino IDE qual variante ESP32 estás a usar e onde o firmware deve ser carregado. Seleções incorretas são uma das causas mais comuns de erros de upload.
Selecionar a Placa ESP32
Primeiro, abre o menu Tools > Board. Depois, desce até à secção ESP32 Arduino. Aqui encontrarás uma longa lista de placas suportadas.
Seleciona a placa que mais se aproxima do teu hardware. Por exemplo:
- ESP32 Dev Module: Genérica e amplamente compatível
- DOIT ESP32 DEVKIT V1: Placa de desenvolvimento comum
- ESP32-WROOM-DA Module: Variante específica do módulo
- ESP32-S3 Dev Module: Para placas baseadas em ESP32-S3
- ESP32-C3 Dev Module: Para placas ESP32-C3 baseadas em RISC-V
Se estiveres inseguro, começa com ESP32 Dev Module. Funciona com a maioria das placas ESP32-WROOM e é uma escolha segura.
Ligar o ESP32 ao Teu Computador
Agora liga o ESP32 ao teu computador usando um cabo USB. Usa um cabo com capacidade de dados. Cabos só para carregamento não funcionam e são uma fonte frequente de confusão. Dependendo da placa, a ligação usa:
- Um conversor USB-para-Serial externo (CP210x, CH340, FTDI)
- USB nativo (ESP32-S2, ESP32-S3, ESP32-C3)
Selecionar a Porta
De seguida, abre Tools > Port. Deverás ver uma nova porta aparecer após ligares o ESP32.
Nomes típicos de porta incluem:
- COMx no Windows
- /dev/ttyUSBx ou /dev/ttyACMx no Linux
- /dev/cu.usbserial-* ou /dev/cu.usbmodem-* no macOS
Seleciona a porta que corresponde ao teu ESP32. Se houver várias portas listadas, desliga a placa e observa qual desaparece. Depois volta a ligar e seleciona a porta que aparecer.
Testar a Instalação do Core
Depois de selecionar a placa e porta, deves verificar se o core ESP32 está instalado e a funcionar corretamente. Este passo confirma que o toolchain, definições da placa e processo de upload estão a funcionar como esperado.
Abrir um Sketch de Teste
Começa com um exemplo conhecido. Abre o clássico sketch Blink:
File > Examples > 01.Basics > Blink
void setup() {
// initialize digital pin LED_BUILTIN as an output.
pinMode(LED_BUILTIN, OUTPUT);
}
// the loop function runs over and over again forever
void loop() {
digitalWrite(LED_BUILTIN, HIGH); // turn the LED on (HIGH is the voltage level)
delay(1000); // wait for a second
digitalWrite(LED_BUILTIN, LOW); // turn the LED off by making the voltage LOW
delay(1000); // wait for a second
}
A maioria das placas ESP32 inclui um LED onboard. No entanto, o número do GPIO varia conforme a placa. Se o LED não piscar, pode ser necessário alterar a definição do pino. Para muitas placas ESP32, o LED onboard está ligado ao GPIO 2:
#define LED_BUILTIN 2
Adiciona a definição para LED_BUILTIN no topo do sketch se estiver em falta e altera o GPIO se necessário:
#define LED_BUILTIN 2
void setup() {
pinMode(LED_BUILTIN, OUTPUT);
}
void loop() {
digitalWrite(LED_BUILTIN, HIGH);
delay(1000);
digitalWrite(LED_BUILTIN, LOW);
delay(1000);
}
Compilar e Carregar o Sketch
Clica no botão Upload para gravar o sketch no ESP32.
Durante o upload, observa as mensagens de compilação e estado na parte inferior do IDE.
Em algumas placas, pode ser necessário pressionar e segurar o botão BOOT até o upload começar. Um upload bem-sucedido termina com uma mensagem semelhante a:
Leaving... Hard resetting via RTS pin...
Isto indica que o ESP32 foi programado e reiniciado.
Verificar o Resultado
Quando o ESP32 reiniciar, observa o LED onboard:
- Se o LED piscar, o core ESP32 está instalado e a funcionar corretamente.
- Se nada acontecer, verifica novamente o pino do LED e a seleção da placa.
Testar Comunicação Serial
Para confirmar ainda mais a configuração, abre o Monitor Serial: define a taxa de baud para 115200. Depois executa o seguinte sketch que imprime “test” no Monitor Serial uma vez por segundo:
void setup() {
Serial.begin(115200);
}
void loop() {
Serial.println("test");
delay(1000);
}
Se vires as mensagens no Monitor Serial, a comunicação USB e o core ESP32 estão totalmente operacionais.
Problemas Comuns na Instalação
Mesmo com uma instalação correta, podem ocorrer problemas ao trabalhar com o core ESP32. A maioria dos problemas está relacionada com drivers, definições da placa ou configuração de upload. Abaixo estão os problemas mais comuns e como resolvê-los.
ESP32 Não Aparece nas Portas
Se nenhuma porta aparecer após ligares o ESP32, o computador não está a detetar a placa. Possíveis causas e soluções:
- Instala o driver USB-para-Serial correto (CP210x, CH340 ou FTDI).
- Usa um cabo USB com capacidade de dados conhecido.
- Experimenta uma porta USB diferente no teu computador.
- Para placas ESP32-S2 ou ESP32-S3, ativa USB CDC On Boot e seleciona o modo USB Mode correto.
Reinicia o Arduino IDE após instalar os drivers.
Upload Falha com “Timed out waiting for packet header”
Este erro indica que o ESP32 não entrou no modo de flashing. Tenta:
- Pressionar e segurar o botão BOOT quando o upload começar.
- Reduzir a Velocidade de Upload para 115200.
- Verificar se a Porta correta está selecionada.
- Desativar outros programas que usem a mesma porta serial.
Upload Falha com “Wrong boot mode detected”
Podes precisar de pressionar os botões BOOT e RESET numa sequência específica, ou podes precisar de um condensador de 1µF entre RESET/ENABLE e GND. Vê o Wrong boot mode ESP32 tutorial.
Erros de Compilação Relacionados com Headers ESP32
Erros mencionando ficheiros em falta comoesp_system.h ouWiFi.h normalmente indicam um problema na instalação do core. Tenta:
- Reinstalar o core ESP32 a partir do Gestor de Placas.
- Eliminar a pasta do pacote ESP32 e instalar novamente.
- Garantir que só uma versão do core ESP32 está instalada.
Sketch Carregado mas Não Corre
Se o upload for bem-sucedido mas o ESP32 não executar o sketch, provavelmente há problemas de configuração. Verifica as seguintes definições:
- Tamanho do Flash corresponde ao hardware real.
- Esquema de Partição suporta o tamanho do teu sketch.
- PSRAM está ativado apenas se a placa o incluir.
- Apagar Todo o Flash Antes do Upload está ativado para um teste limpo.
Monitor Serial Mostra Saída Corrompida
Caracteres ilegíveis no Monitor Serial geralmente indicam incompatibilidade na taxa de baud. Para corrigir, define a taxa do Monitor Serial para coincidir comSerial.begin(). Valores comuns são 115200 ou 9600.
Para placas ESP32-S2 e ESP32-S3, verifica também se o USB CDC está ativado.
Placa Reinicia Continuamente
Reinícios repetidos podem indicar problemas de energia ou configuração. Causas comuns são:
- Energia insuficiente da porta USB
- Frequência ou modo de flash incorretos
- Detecção de brownout a causar reinícios
Experimenta um hub USB alimentado ou reduz a frequência da CPU.
Erros de Compilação ou Código Não Funciona
Por vezes precisas de fazer downgrade da versão do core ESP32, pois algumas bibliotecas não suportam versões mais recentes do ESP32, especificamente a 3.x. Normalmente, precisas de fazer downgrade para a versão 2.0.17.
Abre o BOARDS MANAGER, escreve “esp32” na barra de pesquisa, depois seleciona a versão do core “esp32 by Espressif” e clica em “UPDATE” como mostrado abaixo:
Isto irá descarregar e instalar a versão do core selecionada.
Conclusão
Neste tutorial aprendeste como instalar o core ESP32 para o Arduino IDE. O Arduino Core simplifica a programação ao fornecer um ambiente fácil de usar com funções e bibliotecas familiares. Ele abstrai os detalhes complexos do hardware, permitindo que te concentres no teu projeto em vez de código de baixo nível. Para mais informações, consulta o Espressif Installation Guide.
A principal vantagem de usar o Arduino Core é a sua acessibilidade. Iniciantes podem começar rapidamente com o desenvolvimento ESP32 sem conhecimento profundo de sistemas embebidos. A vasta comunidade Arduino e o amplo suporte de bibliotecas facilitam a resolução de problemas e a expansão dos teus projetos.
Além disso, existem outros cores para muitos outros microprocessadores, por exemplo o ESP8266, STM32 e RP2350. Isto permite programar uma grande variedade de microprocessadores diferentes dentro do mesmo IDE e com código (quase) idêntico.
No entanto, o Arduino Core também tem algumas limitações. Pode não expor todas as funcionalidades avançadas do hardware ESP32. Ajustes de desempenho e capacidades em tempo real podem ser limitados comparado com o uso do ESP32-IDF nativo (Espressif IoT Development Framework). O ESP32-IDF oferece controlo total sobre a arquitetura do chip, permitindo aplicações otimizadas e complexas, mas tem uma curva de aprendizagem mais acentuada.
Em resumo, escolhe o Arduino Core se quiseres desenvolvimento rápido, simplicidade e suporte da comunidade. Opta pelo ESP32-IDF quando precisares de máximo desempenho, controlo detalhado e acesso às funcionalidades mais recentes do ESP32.
Se tiveres alguma dúvida, sente-te à vontade para deixá-la na secção de comentários.
Boas experiências a criar ; )
