firmware-esp32

Firmware ESP32 (PlatformIO: Arduino primeiro, ESP-IDF quando necessário)

Carregue também embedded-c-cpp para padrões de codificação, arquitetura, testes unitários e depuração geral. Esta skill contém as partes específicas do ESP32.

Primeiro, identifique o projeto

Encontrar	Onde	Por que importa
Chip e módulo exatos (ESP32-WROOM-32E, ESP32-S3-WROOM-1-N16R8, ESP32-C3-MINI-1...)	platformio.ini board =, usuário, serigrafia da placa	Cores, pinos, PSRAM, USB, ADC diferem muito entre variantes
Framework	framework = arduino, espidf, ou arduino, espidf	API e modelo de configuração
Versão do Arduino core (2.x ou 3.x)	linha do log de build framework-arduinoespressif32 @ x.y.z, linha platform =, ou ESP_ARDUINO_VERSION_MAJOR	Várias APIs mudaram na 3.x (LEDC, timers) — código escrito para a versão errada não compila
Tamanho de Flash / PSRAM	nome do módulo (N16R8 = 16 MB flash, 8 MB octal PSRAM), board_upload.flash_size	Partições, alocação de memória
Conexões da placa	usuário/esquemático	Evitar pinos strapping e pinos usados por flash/PSRAM/USB/LEDs

Se a variante for desconhecida e a tarefa envolver pinos, periféricos, alimentação ou memória, descubra antes de escrever código — um pino que funciona em um S3 pode impedir um ESP32 clássico de inicializar.

Arduino ou ESP-IDF?

Fique com Arduino (padrão)	Migre para ESP-IDF (no PlatformIO: framework = espidf) ou Arduino + IDF (framework = arduino, espidf)
Protótipos e maioria dos produtos	Necessidade de alterar opções do sdkconfig que o core pré-compilado do Arduino não expõe (rollback OTA, secure boot, flash encryption, PM auto light-sleep, core-dump-to-flash, configurações do FreeRTOS)
Muitas bibliotecas disponíveis	Últimos recursos do IDF, controle rígido de memória/desempenho
Iteração rápida	Endurecimento para produção

O Arduino no ESP32 já executa sobre FreeRTOS + ESP-IDF, então APIs do IDF (esp_*, xTaskCreatePinnedToCore, nvs_*, esp_sleep_*, heap_caps_*) funcionam a partir do código Arduino. "Arduino como componente IDF" (arduino, espidf) mantém as bibliotecas Arduino e adiciona controle do sdkconfig — o caminho usual de migração.

Configuração, templates de platformio.ini e mudanças de API 2.x vs 3.x: references/platformio-setup.md.

Regras que evitam as falhas clássicas do ESP32

1. Pinos: nunca use pinos de flash (GPIO6–11 no ESP32), pinos de PSRAM (16/17 no WROVER; 33–37 em módulos S3 octal-PSRAM) ou pinos USB ao usar USB; trate pinos strapping (ESP32: 0, 2, 5, 12, 15) como "apenas com cuidado" — GPIO12 puxado alto no boot faz módulos flash 3,3 V falharem ao inicializar. ADC2 não funciona enquanto o Wi-Fi estiver ligado (ESP32 clássico): use pinos ADC1. Tabelas completas por variante: references/pins-and-variants.md.
2. Não bloqueie loop() ou uma tarefa para sempre: loops while longos sem delay()/vTaskDelay() disparam o watchdog de tarefa; while (WiFi.status() != WL_CONNECTED) precisa de um timeout.
3. ISRs: marque com IRAM_ATTR, mantenha-as pequenas, sem Serial.print, sem delay, sem chamadas Wi-Fi; passe o trabalho para uma tarefa (fila / notificação de tarefa / flag). Variáveis compartilhadas volatile + seção crítica (portENTER_CRITICAL_ISR spinlock — o ESP32 é dual-core).
4. Pilhas de tarefas são em bytes no ESP-IDF/Arduino (diferente do FreeRTOS vanilla em palavras). Meça com uxTaskGetStackHighWaterMark(NULL) (bytes). O loop() do Arduino tem 8 KB por padrão (SET_LOOP_TASK_STACK_SIZE(16 * 1024); para alterar).
5. Fonte de alimentação: a transmissão Wi-Fi consome picos de ~300–500 mA. "Brownout detector was triggered" significa corrigir a alimentação (regulador, capacitor de desacoplamento, cabo) — não desabilite o detector de brownout.
6. Heap: evite concatenação de String em loops e new/malloc frequentes (fragmentação ao longo de dias); pré-aloque. Verifique ESP.getFreeHeap() / heap_caps_get_minimum_free_size(MALLOC_CAP_8BIT) ao longo do tempo.
7. Desgaste de NVS/flash: não grave Preferences/NVS em toda iteração do loop; grave apenas quando houver mudança, com limitação de taxa.
8. Operações irreversíveis: gravação de eFuse, secure boot, flash encryption em modo release são permanentes. Nunca execute espefuse.py burn_*, habilite estas opções no sdkconfig, ou erase_flash em um dispositivo com dados, sem confirmação explícita do usuário.

Build, upload, monitor (PlatformIO)

pio run -e <env>                       # build
pio run -e <env> -t upload             # gravar via USB/serial
pio device monitor -e <env>            # monitor serial (usa monitor_speed / monitor_filters)
pio run -e <env> -t upload -t monitor  # ambos
pio run -e <env> -t uploadfs           # gravar pasta data/ como imagem LittleFS/SPIFFS
pio run -e <env> -t erase              # apagar flash inteiro (pergunta primeiro: apaga NVS/credenciais Wi-Fi)
pio run -e <env> -t menuconfig         # apenas ESP-IDF / arduino+espidf
pio test -e native                     # testes unitários no host (veja embedded-c-cpp)

O upload falha com "Failed to connect / Wrong boot mode detected" → segure BOOT (GPIO0 / GPIO9 no C3), toque EN/RST, solte BOOT; verifique se o cabo transporta dados; feche qualquer outro monitor serial que esteja segurando a porta. Confirme se a placa está conectada e qual porta antes de fazer upload (pio device list).

Quando trava ou reinicia

A saída serial copiável é a evidência chave. Ative monitor_filters = esp32_exception_decoder e build_type = debug para que os backtraces sejam decodificados para arquivo:linha. Então veja references/panics-and-debug.md para: tipos de Guru Meditation (LoadProhibited, StoreProhibited, IllegalInstruction, Load/Store access fault no RISC-V), stack canary, watchdog de tarefa/interrupção, códigos rst:, brownout, loops de boot, depuração com JTAG (debug_tool = esp-builtin no S3/C3/C6).

Arquivos de referência

Arquivo	Leia quando
references/platformio-setup.md	Criando/consertando platformio.ini, escolhendo plataforma/versão do core, mudanças de API Arduino 2.x→3.x, PSRAM, USB-CDC serial, partições e sistema de arquivos, usando ESP-IDF no PlatformIO, sdkconfig
references/pins-and-variants.md	Escolhendo ou revisando pinos, comparando ESP32/S2/S3/C3/C6, ADC, touch, pinos de wake de deep sleep
references/rtos-memory-power.md	Tarefas, cores, ISRs, filas, watchdog, pilha/heap/PSRAM, IRAM, deep/light sleep, bateria
references/panics-and-debug.md	Qualquer travamento, reset, watchdog, brownout, loop de boot, falha de upload, depuração JTAG, core dumps, motivo do reset
references/connectivity-ota-security.md	Robustez de Wi-Fi/BLE, NVS/Preferences, atualizações OTA e rollback, secure boot / flash encryption