ESP32

Avoid common ESP32 mistakes — GPIO conflicts, WiFi+ADC2 trap, deep sleep gotchas, and FreeRTOS pitfalls.

Security Scan

This is an instruction-only skill that provides ESP32 hardware/SDK guidance; its requirements and instructions match its stated purpose and it does not request elevated access or install code.

Purpose & Capability

The name/description (ESP32 gotchas) align with the SKILL.md content (GPIO, deep sleep, WiFi, FreeRTOS, power, OTA, etc.). There are no unrelated environment variables, binaries, or config paths requested.

Instruction Scope

SKILL.md is purely advisory documentation about development pitfalls and API usage on ESP32 boards. It does not instruct the agent to read local files, access credentials, call external endpoints, or perform system operations outside its stated scope.

Install Mechanism

No install spec or code files are present; this is instruction-only so nothing will be downloaded or written to disk during install.

Credentials

The skill requires no environment variables, credentials, or configuration paths — proportional for a documentation-style skill.

Persistence & Privilege

always:false and default invocation settings are used. The skill does not request persistent presence or permissions to modify other skills or system-wide settings.

Assessment

This skill is a read-only reference of ESP32 best-practices and appears safe to install. Keep in mind: 1) The guidance may be version- or board-specific — verify details against your board's datasheet and the Espressif SDK/Arduino core you use. 2) Do not blindly disable hardware protections (e.g., esp_brownout_disable()) — that can cause unstable behavior on battery-powered devices. 3) OTA and partition advice depends on your partition scheme; test OTA in a controlled environment. 4) ADC/GPIO and deep-sleep wakeup pin lists vary by chip revision/module — double-check for your variant. If you need code or automated tasks, prefer a skill that clearly declares any installs or required credentials; this skill is purely advisory and contains no hidden install steps.

GPIO Restrictions

• Strapping pins boot behavior — GPIO0, GPIO2, GPIO12, GPIO15 affect boot mode
• GPIO6-11 connected to flash — don't use, crashes immediately
• GPIO34-39 input only — no output, no pullup/pulldown
• ADC2 unusable with WiFi active — use ADC1 (GPIOs 32-39) when WiFi enabled

Deep Sleep

• Only RTC GPIOs for wakeup — GPIO0, 2, 4, 12-15, 25-27, 32-39
• RTC_DATA_ATTR for persistent variables — regular RAM lost in deep sleep
• esp_sleep_enable_ext0_wakeup() for single pin — ext1 for multiple pins
• WiFi reconnect takes 1-3 seconds after wake — plan for this delay

WiFi Gotchas

• Call WiFi.mode() before WiFi.begin() — mode affects behavior
• WiFi.setAutoReconnect(true) doesn't always work — implement reconnect in loop
• Event-driven with WiFi.onEvent() more reliable — don't poll WiFi.status()
• Static IP faster than DHCP — saves 2-5 seconds on connect

FreeRTOS

• Default stack too small for printf/WiFi — use 4096+ for complex tasks
• Task watchdog triggers at 5s default — call vTaskDelay() or feed watchdog
• xTaskCreatePinnedToCore() for core affinity — WiFi on core 0, your code on core 1
• delay() yields to scheduler — vTaskDelay(pdMS_TO_TICKS(ms)) in tasks

Memory

• Heap fragments over time — preallocate buffers, avoid repeated malloc/free
• ESP.getFreeHeap() for monitoring — log periodically in long-running apps
• PSRAM available on some boards — heap_caps_malloc(size, MALLOC_CAP_SPIRAM)
• String concatenation fragments heap — use reserve() or char arrays

Peripherals

• No native analogWrite() — use LEDC: ledcSetup(), ledcAttachPin(), ledcWrite()
• I2C needs external pullups usually — internal pullups too weak for fast speeds
• SPI CS pin must be managed — SPI.begin() doesn't auto-configure
• UART0 is Serial/USB — use UART1/2 for external devices

OTA Updates

• Needs two OTA partitions — default partition scheme may have only one
• Check ESP.getFreeSketchSpace() — OTA fails silently if not enough space
• ArduinoOTA blocks during update — handle in loop, not in time-critical code

Power

• Brown-out detector resets at ~2.4V — esp_brownout_disable() if using battery
• WiFi TX uses 300mA peaks — power supply must handle spikes
• Deep sleep ~10µA — but RTC peripherals add more if enabled