---
title: ESP32 (beta)
description: Develop and deploy native ESP-IDF apps to supported ESP32 devices with Wendy
---
## ESP32 with Wendy
Wendy supports regular, native [ESP-IDF](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/get-started/) 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.
**Supported targets:** ESP32-C5, ESP32-C6, ESP32-C61, ESP32-P4, and ESP32-S3. When the installer offers multiple firmware variants, choose one labeled **native app support**. ESP32-P4 support is available for the boards listed by the installer.
## What You'll Need
- A supported ESP32 development board
- A USB data cable
- The Wendy CLI ([install it](../../#1-install-the-wendy-cli))
- The [ESP-IDF Installation Manager (`eim`)](https://dl.espressif.com/dl/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:
```bash
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:
```bash
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:
```text
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
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:
```json
{
"$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`:
```yaml
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`:
```cmake
idf_component_register(SRCS "main.c"
INCLUDE_DIRS "."
REQUIRES wendy_core)
```
Then call `wendy_core_init()` as the very first thing in `app_main()`:
```c
#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](../../advanced/wendy-lite/native-apps/) 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:
```sh
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:
```bash
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](../../advanced/wendy-lite/) for the WASM SDK, host API, and deployment details.
## Next Steps
- Read [Native Apps for Wendy Lite](../../advanced/wendy-lite/native-apps/) for more details
- Read the [`wendy run` reference](../../advanced/clients/wendy-cli/commands/run/)
- Read the [`wendy install` ESP32 reference](../../advanced/clients/wendy-cli/commands/os/install/#esp32-wendy-lite-path)