Native Apps for Wendy Lite

Overview

Wendy Lite is a runtime for Espressif ESP32 microcontrollers. It handles your device's connectivity and lets you write your own native applications, build them, and deploy them to it.

Native apps are built with Espressif's tooling, in particular ESP-IDF, version 5.5. ESP-IDF lets you write your application in C or C++. Because it is driven by CMake, you can also integrate other compiled languages, such as Rust or Swift.

The Wendy CLI is your entry point to the device. It lets you:

• install Wendy Lite on a device,
• configure Wi-Fi and cloud access,
• build and deploy your native application.

Deployment can happen over three transports:

Configuring a device can additionally go over Bluetooth Low Energy (BLE). BLE is there mainly to reach a device in the situations where neither Wi-Fi nor USB is available.

Prerequisites

Before you start, you need:

• Wendy CLI — installs Wendy Lite on a device, configures it, and builds and deploys your application.
• EIM, the ESP-IDF Installation Manager — Espressif's tool for managing the ESP-IDF development environment (toolchains, Python environment, SDK versions). Wendy Lite supports ESP-IDF 5.5; the Wendy CLI manages this environment for you, so you never need to pin a version yourself.
• a device already flashed with Wendy Lite.

Getting Started with Wendy Lite walks through installing both tools and flashing a device.

When you install Wendy Lite on your device, ensure you pick the variant labeled native app support. If you are not sure whether your installed version supports native apps, run wendy device info to check.

Anatomy of a Wendy Lite native app

A Wendy Lite native app is an ordinary ESP-IDF project with two additions:

• a wendy.json manifest in the project root.
• the wendy_core component.

wendy_core is what makes your application a Wendy app rather than a bare ESP-IDF firmware. It runs your code inside the Wendy environment, so that the device can be managed by the Wendy CLI and reached through Wendy Cloud.

Creating an app therefore comes down to three steps:

1. Create an ESP-IDF project.
2. Declare wendy_core in the project's dependencies.
3. Call wendy_core_init() at the very beginning of app_main().

Step 1 — Create an ESP-IDF project

Use the standard ESP-IDF project layout: a top-level CMakeLists.txt, a main component, a sdkconfig.defaults holding your build configuration, and a wendy.json manifest:

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

wendy.json looks like this:

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

sdkconfig is generated, not authored. It's created on first build and can be regenerated whenever the target changes, so changes made directly to it can be lost. Store your configuration in sdkconfig.defaults instead, or, if you really want to rely on it, keep sdkconfig itself in your git repo.

Step 2 — Declare the wendy_core dependency

Add wendy_core to your component manifest, 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)

Step 3 — Initialize Wendy Core

wendy_core_init() must be the first function your application calls:

#include "wendy_core.h"

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

    /* Your application starts here. */
}

This call brings up the agent that handles all communication with the Wendy environment. Nothing else in your application may run before it.

Starting from an example

The quickest way to start a project is to copy an existing one. The blink-rgb project is a deliberately minimal example: it shows how a project for Wendy Lite is laid out and how wendy_core is integrated.

Its main/main.c calls wendy_core_init() first, as in Step 3 above, then adds a simple blink loop:

#include <stdio.h>
#include <stdbool.h>

#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "rgb_led.h"

#include "wendy_core.h"

#define RGB_LED_GPIO 8

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

    ESP_ERROR_CHECK(rgb_led_init(RGB_LED_GPIO, 1));

    bool on = false;
    while (true) {
        on = !on;
        if (on) {
            ESP_ERROR_CHECK(rgb_led_set(0, 24, 24, 0));
        } else {
            ESP_ERROR_CHECK(rgb_led_clear());
        }
        vTaskDelay(pdMS_TO_TICKS(500));
    }
}

What Wendy Lite owns, and what your app must not touch

Wendy Lite handles communication for you. It owns and initializes the communication controllers and peripherals:

• USB
• Wi-Fi
• Bluetooth Low Energy (BLE) — the system uses it above all to configure the device when Wi-Fi and USB are not available.

Your application is free to use these channels, but it must never configure them itself. Do not initialize the Wi-Fi or BLE controller, and do not set up the network stack: use what Wendy Lite has already configured.

Do not use the USB Serial/JTAG controller as a console. Wendy Lite claims that peripheral and drives the console itself. Configuring it from your application, or using it for your own I/O, will conflict with the system.

Building and deploying

One command covers the whole cycle. Run it from your project directory:

wendy run

wendy run compiles the project, pushes the resulting application to the device, and starts it. It selects the right ESP-IDF toolchain version for you, so you do not have to pin one yourself. The application is pushed over USB, over the local network, or (soon) through the cloud.

To rebuild the project entirely from scratch, delete build, sdkconfig, and managed_components, then run wendy run again. Also delete dependencies.lock if you want to move to more recent versions of your dependencies (such as wendy_core).

The Project Remains a Normal ESP-IDF Project

Your application can use ESP-IDF components, managed components, Kconfig options, and peripheral drivers, exactly as in any other ESP-IDF project — except for the restrictions listed above. This is especially important for displays, cameras, audio, and other hardware that needs full access to the native ESP-IDF APIs.

By including a partition table that matches the one Wendy Lite itself uses for the installed firmware variant, you can still compile and deploy through classic IDF commands:

idf.py set-target esp32c6
idf.py menuconfig
idf.py build
idf.py -p /dev/cu.usbmodemXXXX flash monitor

There is no CLI command yet to fetch this partition table. Extract the partitions.csv file that corresponds to your Wendy Lite variant from the wendy-lite repository, add it to your project, and enable it in sdkconfig.defaults:

CONFIG_PARTITION_TABLE_CUSTOM=y
CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions.csv"

Without this, idf.py flash uses the project's default partition table instead, which can overwrite or omit Wendy Lite's reserved partitions.