ESP32 (beta)

ESP32 with Wendy

Wendy supports regular, native ESP-IDF projects on ESP32. This is the recommended way to build ESP32 apps: keep the standard ESP-IDF project layout and APIs, then use wendy run to select the correct chip target, build, deploy, reboot, and stream logs.

Swift and other WebAssembly apps remain available through the optional Wendy Lite WASM runtime, but new projects should start with native ESP-IDF unless they specifically need WASM portability.

What You'll Need

• A supported ESP32 development board
• A USB data cable
• The Wendy CLI (install it)
• The ESP-IDF Installation Manager (eim). On macOS, install it with brew install espressif/eim/eim
• An existing ESP-IDF project, or a new project created with the standard ESP-IDF tooling

Wendy uses eim to run ESP-IDF 5.5.4. If that version is not installed, the first wendy run installs it for you.

Install the Wendy Firmware

Connect Your Board

Plug the ESP32 into your development machine over USB. If the board has separate UART and native USB ports, prefer native USB.

Install the Firmware

Run:

wendy install

Select the target that matches your chip, then choose your board. For generic ESP32-C5, ESP32-C6, and ESP32-S3 boards, select the variant labeled native app support.

The CLI detects the USB serial port, verifies the chip model, downloads the correct Wendy firmware, and flashes it directly. No separate esptool installation is required.

Discover Your Device

After the board reboots, run:

wendy discover

The ESP32 can be discovered over its native USB connection or over the network after Wi-Fi provisioning.

Use a Regular ESP-IDF Project

Wendy recognizes the standard ESP-IDF project markers: a top-level CMakeLists.txt that includes project.cmake, or an sdkconfig/sdkconfig.defaults file. Keep the normal ESP-IDF layout and add a small wendy.json manifest:

hello-esp32/
├── CMakeLists.txt
├── sdkconfig.defaults
├── wendy.json
└── main/
    ├── CMakeLists.txt
    ├── idf_component.yml
    └── main.c

The top-level CMakeLists.txt remains standard ESP-IDF:

cmake_minimum_required(VERSION 3.16)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(hello_esp32)

Add a Wendy manifest using the wendy-lite device platform:

{
  "$schema": "https://wendy.dev/schemas/wendy.json",
  "appId": "com.example.hello-esp32",
  "version": "0.1.0",
  "platform": "wendy-lite",
  "entitlements": []
}

Your project also needs the wendy_core component. When it is missing, wendy run offers to add the dependency and initialize it in app_main(), then retries the build. This supports C and C++ projects with a single app_main() definition under main/. Use wendy run --yes to accept setup without a prompt.

To configure it manually, declare the dependency in main/idf_component.yml:

dependencies:
  idf:
    version: ">=5.5.0"
  wendy_core:
    git: "https://github.com/wendylabsinc/wendy-lite.git"
    path: "components/wendy_core"

Then require it from your component in main/CMakeLists.txt:

idf_component_register(SRCS "main.c"
                    INCLUDE_DIRS "."
                    REQUIRES wendy_core)

Then call wendy_core_init() as the very first thing in app_main():

#include "wendy_core.h"

void app_main(void)
{
    ESP_ERROR_CHECK(wendy_core_init());

    /* Your application starts here. */
}

wendy_core is what makes the device manageable by the Wendy CLI and reachable through Wendy Cloud. Apart from that, your app code uses normal ESP-IDF components and APIs — no other custom SDK or wrapper is required. See Native Apps for Wendy Lite for the full walkthrough, including which peripherals (USB, Wi-Fi, BLE) Wendy Lite owns and your app must not configure itself.

Start from a Template

The quickest way to start is from a template instead of building this by hand:

mkdir my-app && cd my-app
wendy init --template blink-rgb-led

This scaffolds a minimal project with the manifest and wendy_core already wired up.

Deploy

From the ESP-IDF project directory, run:

wendy run

Wendy:

1. Detects the project as ESP-IDF.
2. Reads the target from the connected device.
3. Runs idf.py set-target when the project is configured for a different chip.
4. Builds the project with ESP-IDF 5.5.4.
5. Uploads the native application firmware, reboots the ESP32, and reconnects.
6. Streams the ESP-IDF console output back to your terminal.

Optional WASM Apps

Wendy Lite can also run Swift and other WebAssembly guests on firmware variants with WASM support. This path is useful when application portability is more important than direct access to the complete ESP-IDF API. See the Wendy Lite reference for the WASM SDK, host API, and deployment details.

Next Steps

• Read Native Apps for Wendy Lite for more details
• Read the wendy run reference
• Read the wendy install ESP32 reference