Skip to main content

Set up ESP-IDF

Use this path when you are building firmware that runs on real ESP32 silicon. The SDK is consumed as an ordinary ESP-IDF component, so there is no separate SDK install step — you install ESP-IDF, then point your project at the esp_rmaker_neo component.

If you want to iterate on device logic without hardware, use the POSIX setup instead. Both platforms share the same source tree and the same API.

1. Install ESP-IDF​

Follow the official ESP-IDF get-started guide for your host OS: install the prerequisites, clone ESP-IDF at a supported release, run the install script, then source the export script in every shell you build from:

. $IDF_PATH/export.sh

Supported ESP-IDF releases​

ESP-IDF v6.0.2 or later. Check out release/v6.0 or a later release branch before you build. Earlier release branches are not supported — v5.5 is still built in CI, but for compile coverage only.

Supported targets​

esp32, esp32c2, esp32c3, esp32c5, esp32c6, esp32s3.

Run idf.py set-target <chip> once per project. If you never call it, the build defaults to esp32.

Flash size

The example partition tables assume 4 MB of flash (two 1920 KB app slots plus NVS and a factory partition). On a 2 MB part you must shrink the app slots or drop the second OTA slot — see Factory NVS.

2. Get the SDK​

Clone the firmware SDK repository somewhere alongside your project:

git clone <esp-rainmaker-neo-firmware-repo-url> esp-rainmaker-neo-firmware

Nothing further is needed. There is no install.sh, no submodule fetch, and no Python environment for ESP-IDF builds — third-party dependencies are vendored or pulled by the IDF component manager. (The Python virtual environment in the POSIX setup is only for POSIX builds, and the one in Tools reference is only for the manufacturing and OTA scripts.)

3. Build an example​

The in-tree examples are complete ESP-IDF projects. Start with light:

cd esp-rainmaker-neo-firmware/examples/light
idf.py set-target esp32c3
idf.py build flash monitor

The node boots, starts its serial console, and waits for provisioning. It gets its cloud credentials during that provisioning session via assisted claiming, which is enabled by default — so there is nothing to flash first, but you do need a phone app that supports claiming. If you have opted out with CONFIG_ESP_RMAKER_ASSISTED_CLAIM=n, flash a factory NVS image instead.

Continue at Configure and build for the full menuconfig / sdkconfig.defaults story.

4. Add the SDK to your own project​

Examples declare the SDK through the component manager. main/idf_component.yml uses path dependencies so no registry lookup happens:

dependencies:
  # Neo SDK
  esp_rmaker_neo:
    path: ../../../components/esp_rmaker_neo
  esp_rmaker_neo_ota:
    path: ../../../components/esp_rmaker_neo_ota

  # Common example components
  app_event_loop:
    path: ../../common/app_event_loop
  app_entry:
    path: ../../common/app_entry
  app_network:
    path: ../../common/app_network
  app_led:
    path: ../../common/app_led
  app_button:
    path: ../../common/app_button

Then require the components you use in main/CMakeLists.txt:

idf_component_register(
    SRCS "app_main.c" "app_driver.c"
    PRIV_REQUIRES esp_rmaker_neo esp_rmaker_neo_ota app_network app_event_loop app_entry esp_wifi
)

Two things to know:

  • esp_rmaker_neo is the only mandatory component. esp_rmaker_neo_ota is optional — leave it out and no OTA code is linked in. esp_rmaker_neo_common and the osal platform layer come in transitively.
  • EXTRA_COMPONENT_DIRS also works if you would rather not use the component manager. Point it at the SDK's components/ directory and REQUIRES/PRIV_REQUIRES the components by name.

The app_* components under examples/common/ are example scaffolding, not part of the SDK. They are convenient to start from — app_network in particular collapses the four-call provisioning sequence into one function — but you are free to drop them and drive the SDK directly. See Start your own project.

Next steps​