esp-idf-knowledge-patch

# ESP-IDF Knowledge Patch Use this skill when updating an ESP-IDF application, component, build, or tool integration and the failure may come from a renamed API, removed component, changed default, or stricter contract. Start with the breaking-change triage, then open the topic reference that matches the affected subsystem. ## Reference index | Reference | Topics | | --- | --- | | [build-and-components.md](references/build-and-components.md) | Toolchains, warnings, Kconfig, dependencies, managed components, tools, size output, bootloader | | [drivers-and-hardware.md](references/drivers-and-hardware.md) | Touch, TWAI, legacy-driver replacements, GPIO, MCPWM, I2C, DMA, LCD, SPI, PSRAM, flash | | [connectivity.md](references/connectivity.md) | Bluetooth, Ethernet, esp-netif, DHCP, SNTP, ping, provisioning, Wi-Fi, NAN, HTTP server | | [security-and-crypto.md](references/security-and-crypto.md) | SHA, ESP-TLS, Mbed TLS, PSA Crypto, secure boot, BluFi, NVS encryption | | [runtime-and-diagnostics.md](references/runtime-and-diagnostics.md) | Logging, VFS, libc, sleep, app trace, SystemView, gcov, FreeRTOS, core dumps, OTA | ## Breaking-change triage Check failures in this order: 1. Treat warnings, orphan sections, and Kconfig parser failures as real build blockers. Fix the diagnostic or placement; use compatibility switches only as temporary migration aids. 2. Audit `idf_component.yml`, `REQUIRES`, and `PRIV_REQUIRES`. Split drivers and formerly built-in libraries no longer arrive through broad transitive dependencies. 3. Replace removed legacy drivers with their handle-based or channel-based successors. Do not mix the legacy and event-driven TWAI drivers. 4. Add FreeRTOS headers explicitly where public driver or event headers used to supply them indirectly. 5. Review networking callbacks and structures. Several callback arguments, flexible-array fields, and init/error semantics changed. 6. Initialize PSA Crypto before direct cryptographic or certificate use, and ensure NVS is initialized before persistent PSA keys are accessed. 7. Revalidate libc assumptions, constructor ordering, IRAM placement, and scripts that parse `idf.py size` output. ## Build and dependency essentials ### Make warnings and linker placement explicit - Correct warning-producing code first. In particular, call allocation APIs with the element count before the element size: `calloc(n, sizeof(int))`. - Linker orphan sections are errors by default. Place them with a linker fragment rather than depending on incidental linker behavior. - Default warnings are errors. A global warning-disable setting can unblock a port temporarily, but it also hides diagnostics introduced by a new toolchain. - Project Kconfig files must satisfy esp-idf-kconfig v3 syntax. ### Declare what each component uses Name every `esp_driver_*` dependency used by a component. Also add direct dependencies for headers that moved behind component boundaries, including `esp_common`, `esp_usb_cdc_rom_console`, `esp_trace`, and managed components where applicable. Common manifest migrations include: | Former assumption | Current dependency or approach | | --- | --- | | Built-in `json` | `espressif/cjson`; keep using `cJSON.h` | | Built-in ESP-MQTT | `espressif/mqtt`; keep using `mqtt_client.h` | | Built-in provisioning | `espressif/network_provisioning` | | Built-in SystemView | `espressif/esp_sysview` | | Built-in gcov | `espressif/esp_gcov` and `esp_gcov.h` | | Bundled Catch2 | Managed Catch2 3.x component | ## Driver migration essentials Use these replacements as entry points; the hardware reference carries field, callback, and configuration details. | Removed or legacy interface | Preferred interface | | --- | --- | | ADC legacy driver | `esp_adc` | | MCPWM legacy driver | `esp_driver_mcpwm` | | Timer group | `driver/gptimer.h` | | Legacy I2S | `driver/i2s_std.h`, `i2s_pdm.h`, or `i2s_tdm.h` | | PCNT | `driver/pulse_cnt.h` | | RMT legacy API | `driver/rmt_tx.h`, `rmt_rx.h`, and `rmt_encoder.h` | | DAC legacy API | one-shot, continuous, or cosine DAC headers | | Sigma-delta legacy API | `driver/sdm.h` | | `gdma_new_channel` | `gdma_new_ahb_channel` or `gdma_new_axi_channel` | | `ledc_timer_set` | `ledc_timer_config` or `ledc_set_freq` | The redesigned touch driver is `esp_driver_touch_sens` with `driver/touch_sens.h`. The event-driven TWAI interface uses `esp_driver_twai`, `esp_twai.h`, and `esp_twai_onchip.h`; receive from `on_rx_done` with `twai_node_receive_from_isr`. ## Connectivity migration essentials - Replace unsafe assumptions around `esp_netif_next`. Prefer `esp_netif_find_if`; otherwise execute traversal in a controlled TCP/IP context. - Configure SoftAP DNS offers at runtime with `esp_netif_dhcps_option` and `esp_netif_set_dns_info`. - Replace old ping helpers with sessions from `ping/ping_sock.h`, and include `esp_sntp.h` instead of `sntp.h`. - Use Wi-Fi events for DPP, PHY APIs for antenna control, and `esp_now_set_peer_rate_config` for ESP-NOW peer rates. - Initialize newly added structure fields with designated initializers, especially NAN USD and off-channel request structures. - A repeated `esp_wifi_init` is an error; do not use it as an idempotent initialization probe. ## Security migration essentials ### PSA and TLS Call `psa_crypto_init()` before direct cryptographic, certificate, or TLS use. Normal startup performs initialization, but code that runs outside that path must not assume it. Import hardware-backed ECDSA keys with `psa_import_key` and an `esp_ecdsa_opaque_key_t` representation. If a non-mbedTLS transport is required, enable `CONFIG_ESP_TLS_CUSTOM_STACK`, implement `esp_tls_stack_ops_t`, and register it before opening connections. Create connections from an `esp_tls_t` returned by `esp_tls_init`; the old HTTP connection convenience function is unavailable. ### SHA and persistent keys Select the SHA mode with `esp_sha_set_mode` before calling the block or DMA sub-functions. Persistent PSA storage uses NVS, so initialize NVS first and handle its availability as a dependency of persistent key operations. ## Runtime and tooling essentials ### Logging Prefer `ESP_LOG_BUFFER_HEX` and `ESP_LOG_BUFFER_CHAR`. Device-side log colors are off by default because IDF Monitor colors on the host; either enable device colors for another monitor or use `idf.py monitor --disable-auto-color`. Log V2 is selected with `CONFIG_LOG_VERSION`. In a V2 handler use `esp_log` and `esp_log_va` for internal formatting. Dynamic formatting and execution-context detection are V2-only, so keep shared code within the V1-compatible subset when both modes must work. ### Libc, sleep, and memory placement PicolibC shares stdin, stdout, and stderr globally. Select full Newlib when code depends on task-local Newlib reentrancy internals; the compatibility switch is not a complete emulation. Use standard `<signal.h>` and `<dirent.h>` includes. Use `esp_sleep_get_wakeup_causes()` when more than one wake source can fire and test the returned bitmap with `BIT(cause)`. If interrupt-time code requires FreeRTOS or ring-buffer functions in IRAM, enable the respective IRAM options explicitly. ### Tool-facing contracts - Supply `--port` or `ESPPORT` to every `idf.py efuse*` command. - Consume `idf.py size --format json2`; its region and part data are hierarchical rather than flat. - Treat core dumps as ELF with SHA-256 only. - Enable the partial-download option before relying on partial HTTPS OTA. ## High-value new behavior ### Dynamic HTTP request headers `CONFIG_HTTPD_MAX_REQ_HDR_LEN` is an allocation ceiling. The HTTP server now allocates request-header memory according to the received header size up to that limit, so capacity planning should consider peak concurrent requests rather than assuming a fixed per-request allocation. ### Multiple wakeup causes ```c uint32_t causes = esp_sleep_get_wakeup_causes(); if (causes & BIT(ESP_SLEEP_WAKEUP_TIMER)) { handle_timer_wakeup(); } ``` ### Explicit constructor priority Unprioritized `.init_array` and legacy `.ctors` ordering changed. Express a real dependency with `__attribute__((constructor(PRIO)))`—lower priorities run first—or move the dependency into explicit startup registration. ## Migration workflow 1. Pin the failing target and reproduce with a clean configure/build. 2. Classify the failure as build/dependency, driver, connectivity, security, or runtime/tooling. 3. Open the matching reference and apply every related structure, callback, dependency, and default change together. 4. Remove temporary suppression switches once the code compiles cleanly. 5. Exercise hardware and error paths; many migrations change runtime semantics even when the replacement compiles. 6. Re-run host tooling and schema consumers, especially monitor, efuse, size, unit-test, core-dump, and OTA workflows.