Compilando código no ESP-IDF “Puro”

Seguem instruções para compilação e transferência de código para placas ESP32 usando um fluxo de trabalho como:

Fluxo adotado:

Sublime Text
     ↓
main.c
[com seção final:
void app_main(void)]
     ↓
Terminal do macOS
     ↓
idf.py build
     ↓
idf.py flash
     ↓
idf.py monitor

Ambiente:

• macOS
• ESP-IDF 6.1.0 (“Stable”)
• ESP-IDF Installation Manager (EIM)
• projeto C nativo ESP-IDF
• Sublime Text como editor
• terminal como ambiente de build/flash/monitor

Estruturar Pastas do Projeto

Estrutura Esperada

O compilador ESP-IDF espera uma estrutura de arquivos do tipo:

~/Documentos/ESP32/Projeto/
├── CMakeLists.txt
└── main/
    ├── CMakeLists.txt
    └── main.c

O main.c seria o seu código principal.

Você deve gerar os arquivos:CMakeLists.txt e main/CMakeLists.txt.

Obs.: Um projeto já criado e compilado pelo ESP-IDF pode conter ainda a pasta sdkconfig:

~/Documentos/ESP32/Projeto/
├── CMakeLists.txt
├── sdkconfig
└── main/
    ├── CMakeLists.txt
    └── main.c

Mas o arquivo sdkconfig não é gerado manualmente. Ele é gerado pelo próprio ESP-IDF quando:

1. Na pasta raiz do projeto:

   cd ESP32/Projeto1
   

2. Com ambiente ESP-IDF carregado (terminal aberto via EIM):

   idf.py menuconfig
   

   Isso abre a configuração do ESP-IDF.

3. Depois de sair/salvar, aparecerá:

   Projeto1/
   ├── CMakeLists.txt
   ├── sdkconfig
   └── main/
       ├── CMakeLists.txt
       └── main.c
   

   O sdkconfig é um arquivo gerado/configurado pelo ESP-IDF e não é recomendável começar digitando seu conteúdo manualmente.

Então…

1. Criar Pastas

Então sugere-se (no terminal) fazer algo como:

mkdir -p ~/Documents/ESP32  # criar a pasta ESP32 em Documentos se ainda não existir
cd ~/Documents/ESP32        # ir até a pasta
mkdir Projeto1              # criar a pasta associada com novo Projeto
cd Projeto1
mkdir main

Isto gera uma estrutura inicial como:

~/Documents/ESP32/Projeto1/
└── main/

2. Criar o CMakeLists.txt principal

Na pasta ../Projeto1/:

xxxxxxxxxx
touch CMakeLists.txt    # cria arquivo se ele não existe

Conteúdo:

xxxxxxxxxx
cmake_minimum_required(VERSION 3.16)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(Projeto1)

Portanto:

xxxxxxxxxx
../Projeto1/
├── CMakeLists.txt
└── main/

3. Criar main/CMakeLists.txt

Entre em main:

xxxxxxxxxx
cd main
touch CMakeLists.txt

Para o nosso projeto com GPIO + DAC + GPTimer, usamos:

xxxxxxxxxx
idf_component_register(
    SRCS "main.c"
    INCLUDE_DIRS "."
)

Eventualmente o main/CMakeLists.txt precisa declarar os drivers usados, por exemplo:

xxxxxxxxxx
idf_component_register(
    SRCS "main.c"
    INCLUDE_DIRS "."
    REQUIRES
        esp_driver_dac
        esp_driver_gptimer
        esp_driver_gpio
)

4. Criar o main.c

Ainda em main:

xxxxxxxxxx
touch main.c

Depois podemos abrir no Sublime Text:

xxxxxxxxxx
subl main.c

A estrutura completa passa a ser:

xxxxxxxxxx
../Projeto1/
├── CMakeLists.txt
└── main/
    ├── CMakeLists.txt
    └── main.c

Depois…

5. Selecionar o chip

IPORTANTE: Os próximos comandos/estapas já consideram que você esteja usando o terminal com ambiente Python ativado para uso pelo ESP-IDF. Se ainda não o fez, entre no App gráfico EIM e selecione: XXX. Note a opção para ativar o terminal em:

Antes de compilar, devemos informar ao ESP-IDF que nossa placa é o ESP32 clássico:

xxxxxxxxxx
idf.py set-target esp32

Isso também participa da geração/configuração do sdkconfig.

Depois:

xxxxxxxxxx
idf.py menuconfig

e podemos conferir as configurações.

Obs.: comandos dados à partir da pasta raiz (../Projeto1/) dentro do ambiente ESP-IDF (terminal ativado via EMI). Estes comandos são realizados uma única vez.

6. Compilar

Na pasta raiz (../Projeto1/):

xxxxxxxxxx
idf.py build

Se tudo estiver correto, será criada a pasta:

xxxxxxxxxx
Projeto1/
├── CMakeLists.txt
├── sdkconfig
├── main/
│   ├── CMakeLists.txt
│   └── main.c
└── build/
    └── ...

7. Gravar na ESP32

No nosso caso, a placa aparecia no macOS como algo semelhante a:

xxxxxxxxxx
/dev/cu.usbserial-001

Então:

xxxxxxxxxx
idf.py -p /dev/cu.usbserial-001 flash

ou simplesmente:

xxxxxxxxxx
idf.py flash

se tivermos configurado a porta anteriormente.

8. Monitorar comunicação serial

Para acompanhar a execução:

xxxxxxxxxx
idf.py -p /dev/cu.usbserial-001 monitor

Usar a combinação de teclas CTRL/Command+ ] para sair do modo Monitor.

9. Fazer tudo junto

Para fazer build + flash + monitor de uma só vez:

xxxxxxxxxx
idf.py -p /dev/cu.usbserial-001 flash monitor

Usar a combinação de teclas CTRL/Command+ ] para sair do modo Monitor.

Resumo dos Comandos

Dentro do abiente (Python) ativado do ESP-IDF e na pasta raiz do Projeto:

xxxxxxxxxx
idf.py set-target esp32 # indicar placa alvo
idf.py build            # compilar o projeto atual
idf.py flash            # transferir/gravar novo firmware
idf.py monitor          # ativar monitor serial 115200 bauds

Ou simplesmente:

xxxxxxxxxx
idf.py build flash monitor

Migração Arduino-IDE para ESP-IDF 6.1

Código feito para Arduino-IDE contêm as seções:

xxxxxxxxxx
void setup()
void loop()

mas programando ESP-IDF “Puro”, teremos apenas:

xxxxxxxxxx
void app_main(void)

A migração pode ainda envolver adaptação de alguns comandos:

O timer passou para o GPTimer:

xxxxxxxxxx
#include "driver/gptimer.h"

com funções:

xxxxxxxxxx
gptimer_config_t
gptimer_new_timer()
gptimer_register_event_callbacks()
gptimer_set_alarm_action()
gptimer_enable()
gptimer_start()

Atenção ao main/CMakeLists.txt

Se eventualmente forem usados três drivers novos, seu main/CMakeLists.txt precisa declarar dependências associadas aos drivers.

Por exemplo, se o seu arquivo atualmente contiver algo como:

xxxxxxxxxx
idf_component_register(SRCS "main.c"
                       INCLUDE_DIRS ".")

deve ser modificado para algo como:

xxxxxxxxxx
idf_component_register(
    SRCS "main.c"
    INCLUDE_DIRS "."
    REQUIRES
        esp_driver_dac
        esp_driver_gptimer
        esp_driver_gpio
)

Isso é importante no IDF 6.x porque os drivers foram separados em componentes próprios.

A documentação do GPIO, por exemplo, especifica explicitamente REQUIRES esp_driver_gpio; o mesmo princípio vale para GPTimer e DAC.

Referências

• ESP-IDF 6.1 Documentação oficial: https://docs.espressif.com/projects/esp-idf/en/v6.1/

  Página oficial de releases: https://github.com/espressif/esp-idf/releases A release v6.1 informa a disponibilidade pelo EIM e também pelo Git.

• Instalação usando EIM: https://docs.espressif.com/projects/esp-idf/en/stable/esp32/get-started/eim-install-idf.html

• Guia de instalação/primeiros passos para macOS: https://docs.espressif.com/projects/esp-idf/en/stable/esp32/get-started/linux-macos-setup.html

• DAC do ESP32 Documentação oficial Arduino-ESP32: https://docs.espressif.com/projects/arduino-esp32/en/latest/api/dac.html

  Numa ESP32 DevKit baseada no ESP32 original (WROOM-32), o DAC interno é de 8 bits, e:

  xxxxxxxxxx
  ESP32:
  DAC1 → GPIO25
  DAC2 → GPIO26
  

• Documentação do DAC no ESP-IDF: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/dac.html

  No ESP-IDF moderno, você deverá utilizar o driver DAC do ESP-IDF, e não dacWrite().

  O ESP-IDF 6.x também separou vários drivers em componentes próprios. A documentação de migração chama atenção justamente para: componentes como esp_driver_dac e esp_driver_gptimer possuem dependências próprias. Ver:

  • Migration from 5.5 to 6.0 > Common Changes.

• GPTimer: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/gptimer.html

  Obs.: No ESP-IDF 6.0, o antigo Timer Group driver foi removido, e o substituto é o GPTimer (driver/gptimer.h). Ver:

  • Migration from 5.5 to 6.0 > Common Changes.

• GPIO: https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/peripherals/gpio.html

  A API GPIO é fornecida pelo componente esp_driver_gpio no IDF 6.x.

• FreeRTOS no ESP-IDF: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/freertos.html

Fernando Passold, em 13/09/2026