Esp32 Setup

ESP-IDF Installation

If ~/esp/esp-idf/ does not exist, install it:

mkdir -p ~/esp && cd ~/esp
git clone -b v5.3.2 --recursive https://github.com/espressif/esp-idf.git
cd esp-idf && ./install.sh esp32s3

The "detached HEAD" warning on clone is normal — ESP-IDF releases are tags, not branches.

To activate in any shell session: . ~/esp/esp-idf/export.sh

Important: Use dot-sourcing (. file) not source file — the latter may not persist PATH in all shell contexts.

Critical Lessons Learned (from debugging real builds)

1. Legacy I2C Driver Required

The ES8311 (espressif/es8311 ^1.0.0) and TCA9554 (espressif/esp_io_expander_tca9554 ^1.0.1) components use the legacy I2C driver API (driver/i2c.h), NOT the new I2C master driver (driver/i2c_master.h).

• Use i2c_param_config() + i2c_driver_install(), NOT i2c_new_master_bus()
• Pass i2c_port_t (e.g., I2C_NUM_0) to es8311_create() and esp_io_expander_new_i2c_tca9554(), NOT a bus handle

2. Required includes (commonly missed)

• ESP_RETURN_ON_ERROR macro requires #include "esp_check.h" — add this to ANY .c file that uses it (audio, wifi, display, etc.)
• esp_timer_create(), esp_timer_start_periodic(), esp_timer_handle_t, esp_timer_create_args_t require #include "esp_timer.h"
• These are NOT pulled in transitively by other ESP-IDF headers — you must include them explicitly

3. esp-tls PRIV_REQUIRES naming

• The component name is esp-tls (hyphen), NOT esp_tls (underscore) — the underscore variant fails to resolve
• For esp_crt_bundle_attach, include "esp_crt_bundle.h" and add mbedtls to PRIV_REQUIRES

4. CMakeLists PRIV_REQUIRES (known working set)

PRIV_REQUIRES
    driver
    esp_wifi
    esp_http_client
    esp_lcd
    nvs_flash
    esp_psram
    json
    mbedtls
    esp-tls

5. Component Dependencies (known working versions)

# idf_component.yml