Iniciando com ESP32

Iniciando com ESP32Instalação Bibliotecas Espressif para ESP32IDEs para programaçãoConstruindo o Primeiro Projeto (Teste)Detalhes + específicos

Instalação Bibliotecas Espressif para ESP32

Instruções gerais ➔ ESP-IDF Programming Guide.

Para começar a trabalhar com uma placa ESP32 você necessita dos seguintes softwares:

software_ESP32

Toolchain para criar, compilar, testar e gravar o código que roda no chip das ESP32;
Ferramentas de build (Build Tools) — CMake e Ninja — para compilar uma aplicação completa para o ESP32;
ESP-IDF, que essencialmente contém a API (bibliotecas de software e código-fonte) para o ESP32 e scripts para operar o toolchain.

Para tanto, use o gerenciador ESP-IDF (*Installation Manager ou EIM) disponível para multiplataformas:

IDEs para programação

As versões do ESP-IDF instaladas por meio do EIM podem ser utilizadas nas seguintes IDEs, proporcionando uma experiência de desenvolvimento com interface gráfica:

Espressif-IDE baseada no Eclipse CDT
Ela inclui plugins do IDF para Eclipse, plugins essenciais do Eclipse CDT e outros plugins de terceiros da plataforma Eclipse para dar suporte à construção de aplicações ESP-IDF.
Microsoft Visual Studio Code integrado à extensão ESP-IDF para VS Code (ou consulte diretamente: https://github.com/espressif/vscode-esp-idf-extension)
Ele permite desenvolver, compilar, gravar e monitorar aplicações ESP-IDF diretamente no Visual Studio Code. Obs.: Exige o aprendizado de uma série de atalhos pelo teclado para sua operação, como Ctrl + Shift + P para gerenciar arquivos ou configurações simples.
Recomendada a instalação das extensões:
- C++
- PlatformIO IDE ➔ Link da Extensão (para instalação no VSCode), Como usar.
- ESP-IDF Extension for VS Code ➔ Ver recomendações da Espressif. Note que esta extensão exige uma ordem correta de ativação.
Uso da CLion (da JetBrains)
- O CLion (JetBrains) é um ambiente de desenvolvimento integrado (IDE) multiplataforma para programação em C e C++. Ele oferece suporte dedicado ao ESP-IDF, permitindo que os desenvolvedores trabalhem de forma integrada com o framework ESP-IDF. Usa o mouse (tradicional apontar e clicar, você não precisa "adivinhar" comandos de teclado).
  A partir da versão v2025.1.1, o CLion está disponível gratuitamente se você o utilizar para contribuir com projetos de código aberto, aprender ou ensinar C/C++, desenvolver uma aplicação para uso pessoal ou trabalhar em outros projetos não comerciais.
- Downloads:
  - da versão independente, através de Toolbox App;
  - ou como pacote snap para usuários de Ubuntu.
  - Necessário instalar as ferramentas (toolchains) necessárias ➔ Ver documentação oficial.
- Configurações: Para configurar um projeto ESP-IDF no CLion, siga o tutorial "Working with ESP-IDF in CLion". Ele fornece instruções detalhadas sobre como configurar um projeto, compilar uma aplicação, gravá-la em uma placa e depurá-la. Você também pode consultar a documentação do CLion sobre o ESP-IDF.
Uso de editores do tipo Sublime Text + Terminal. Eventualmente pode ser usado o plugin Deviot. Instruções da Espressif aqui.

Ou você pode simplesmente usar a Linha de comandos (terminal).

Construindo o Primeiro Projeto (Teste)

Se você quiser testar a construção (compilação do primeiro projeto): Build Your First Project. No terminal bastaria fazer:

No Windows:
1. Abra o aplicativo ESP-IDF Installation Manager (eim).
2. No painel (Dashboard), você verá todas as versões do ESP-IDF instaladas.
  Selecione a versão que deseja utilizar e clique em "Open IDF Terminal" para iniciar uma sessão de terminal com o ambiente do ESP-IDF ativado.
3. Ativação usando a CLI do EIM:
  Após a instalação bem-sucedida do ESP-IDF, o EIM cria atalhos na sua área de trabalho para iniciar um terminal com o ambiente do ESP-IDF já ativado.
  Por exemplo, clique no atalho IDF_v5.4.2_Powershell para abrir uma sessão do PowerShell com o ambiente configurado.
  Feito isso, você terá ativado com sucesso o ambiente do ESP-IDF no seu terminal. Todos os comandos subsequentes do ESP-IDF devem ser executados neste terminal ativado.
4. Inicie o projeto: copie o get-started/hello_world para o diretório ~/esp:
```
cd %userprofile%\esp
xcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world
```
5. Conecte seu dispositivo:
  Os nomes das portas seriais começam com COM no Windows.
6. Configure seu projeto:
  Navegue até o diretório hello_world, defina o ESP32 como alvo e execute o utilitário de configuração do projeto, o menuconfig:
```
cd %userprofile%\esp\hello_world
idf.py set-target esp32
idf.py menuconfig
```
  Após abrir um novo projeto, você deve primeiro definir o alvo com o comando idf.py set-target esp32. Observe que compilações e configurações existentes no projeto, caso existam, são descartadas e reinicializadas durante esse processo. O alvo pode ser salvo em uma variável de ambiente para permitir que essa etapa seja totalmente ignorada. Consulte "Selecionar o Chip Alvo: set-target" para obter mais informações.
  Atenção
  Se você utilizar a placa ESP32-DevKitC com o módulo ESP32-SOLO-1, ou a placa ESP32-DevKitM-1 com o módulo ESP32-MIN1-1/1U, por favor, habilite o modo de núcleo único (CONFIG_FREERTOS_UNICORE) no menuconfig antes de gravar os exemplos.
7. Construa (Build) o projeto:
  Compile o projeto executando:
```
idf.py build
```
  Este comando compila a aplicação e todos os componentes do ESP-IDF e, em seguida, gera o bootloader, a tabela de partições e os binários da aplicação.
  Se não houver erros, o processo de build é concluído com a geração dos arquivos binários .bin do firmware.
8. Realize o "Flash" no dispositivo:
  Para gravar no ESP32 os binários que você acabou de compilar na etapa anterior, é necessário executar o seguinte comando:
```
idf.py -p PORT flash
```
  Substitua PORT pelo nome da porta USB da sua placa ESP32. Se PORT não for definido, o idf.py tentará conectar-se automaticamente usando as portas USB disponíveis.
  Para mais informações sobre os argumentos do idf.py, consulte idf.py.
  Nota
  A opção flash compila e grava o projeto automaticamente; portanto, não é necessário executar idf.py build.
  Encontrou problemas durante a gravação? Consulte as "Additional Tips". Você também pode consultar a página de Solução de Problemas de Gravação ou o guia para Estabelecer Conexão Serial com o ESP32 para obter informações mais detalhadas.
9. Resultado esperado:
  Se não houver problemas ao final do processo de gravação, a placa reiniciará e iniciará a aplicação "hello_world".
10. Monitorando a saída:
  Para verificar se o "hello_world" está realmente em execução, digite idf.py -p PORT monitor (não se esqueça de substituir PORT pelo nome da sua porta serial).
  Este comando inicia o aplicativo IDF Monitor.
  Após a rolagem dos logs de inicialização e diagnóstico, você deverá ver "Hello world!" exibido pela aplicação.
  Para sair do monitor do IDF, use o atalho Ctrl + ].
  Se o monitor do IDF falhar logo após o upload ou se, em vez das mensagens acima, você visualizar caracteres aleatórios e sem sentido (como os mostrados abaixo), é provável que sua placa utilize um cristal de 26 MHz. A maioria dos projetos de placas de desenvolvimento utiliza 40 MHz; por isso, o ESP-IDF adota essa frequência como padrão.

No macOS/Linux:
1. Abra a aplicação eim e em Manage Installation > Open Dashboard > selecione a versão do ESP-IDF que pretende usar.
2. Depois no eim clique em Open IDF Terminal para iniciar uma seção no terminal ativando o ambiente "ESP-IDF".
3. No terminal surge uma mensagem como: source "/Users/username/.espressif/tools/activate_idf_v5.4.2.sh"
4. Copie e rode este comando.
5. Inicie um projeto, por exemplo o "Hello World":
  Copie o projeto get-started/hello_world para o diretório ~/esp:
```
cd ~/esp
cp -r $IDF_PATH/examples/get-started/hello_world .
```
6. Conecte seu dispositivo: Ele ficará visível assumindo os seguintes padrões:
  - Linux: começando com /dev/tty.
  - macOS: começando com /dev/cu.
  Se você não tiver certeza de como verificar o nome da porta serial, consulte "Estabelecer Conexão Serial com o ESP32" para obter detalhes completos.
7. Configure seu projeto: Navegue até o diretório hello_world, defina o ESP32 como alvo e execute o utilitário de configuração do projeto, o menuconfig:
```
cd ~/esp/hello_world
idf.py set-target esp32
idf.py menuconfig
```
  Após abrir um novo projeto, você deve primeiro definir o alvo com o comando idf.py set-target esp32. Observe que compilações e configurações existentes no projeto, caso existam, são descartadas e reinicializadas durante esse processo. O alvo pode ser salvo em uma variável de ambiente para permitir que essa etapa seja totalmente ignorada. Consulte "Selecionar o Chip Alvo: set-target" para obter mais informações.
8. Construa o projeto:
  Compile o projeto executando:
```
idf.py build
```
  Este comando compila a aplicação e todos os componentes do ESP-IDF e, em seguida, gera o bootloader, a tabela de partições e os binários da aplicação.
  Se não houver erros, o processo de build é concluído com a geração dos arquivos binários .bin do firmware.
9. Realize o Flash no dispositivo:
  Para gravar no ESP32 os binários que você acabou de compilar na etapa anterior, é necessário executar o seguinte comando:
```
idf.py -p PORT flash
```
  Substitua PORT pelo nome da porta USB da sua placa ESP32. Se a PORT não for definida, o idf.py tentará conectar-se automaticamente usando as portas USB disponíveis.
  Nota
  A opção flash compila e grava o projeto automaticamente; portanto, não é necessário executar idf.py build.
  Encontrou problemas durante a gravação? Consulte as "Additional Tips". Você também pode consultar a página de Solução de Problemas de Gravação ou o guia para Estabelecer Conexão Serial com o ESP32 para obter informações mais detalhadas.
10. Resultado Esperado:
  Se não houver problemas ao final do processo de gravação (flash), a placa e iniciará a aplicação "hello_world".
  Se você quiser usar a IDE Eclipse ou o VS Code em vez de executar o idf.py, consulte o Eclipse Plugin ou a VSCode Extension.
11. Monitore a saída:
  Para verificar se o "hello_world" está realmente em execução, digite idf.py -p PORT monitor (não se esqueça de substituir PORT pelo nome da sua porta serial).
  Este comando inicia o aplicativo IDF Monitor.
  Após a rolagem dos logs de inicialização e diagnóstico, você deverá ver "Hello world!" exibido pela aplicação.
  Para sair do monitor do IDF, use o atalho Ctrl + ].
  Se o monitor do IDF falhar logo após o upload ou se, em vez das mensagens acima, você visualizar caracteres aleatórios e sem sentido (como os mostrados abaixo), é provável que sua placa utilize um cristal de 26 MHz. A maioria dos projetos de placas de desenvolvimento utiliza 40 MHz; por isso, o ESP-IDF adota essa frequência como padrão.

Detalhes + específicos

Sobre:

Fernando Passold, em 23/08/2026