Wendy Lite

Wendy Lite is a WebAssembly (WASM) runtime firmware for ESP32-C6 microcontrollers. It enables developers to write apps in C, Rust, Swift, Zig, TypeScript, or WAT, compile them to WASM, and run them on the device with full hardware access.

Key Concepts

• WAMR Runtime: Uses WebAssembly Micro Runtime to execute WASM binaries
• Host Imports: WASM apps import functions from the

  "wendy"

  module to access hardware
• Callback System: Async events (GPIO interrupts, timers, BLE) dispatched via exported

  wendy_handle_callback

• Flash Persistence: WASM binaries stored in flash partition

  wasm_a

  (2MB), auto-loaded on boot
• Multi-language: Apps can be written in C, Rust, Swift 6.0+, Zig, TypeScript, or raw WAT

Project Structure

wendy-lite/
├── main/wendy_main.c              # Firmware entry point, WASM lifecycle manager
├── components/
│   ├── wendy_wasm/                # WAMR integration (load, run, stop modules)
│   ├── wendy_hal/                 # Hardware: GPIO, I2C, RMT, NeoPixel, Timer
│   ├── wendy_hal_export/          # Registers HAL as WASM host imports
│   ├── wendy_usb/                 # USB CDC wire protocol for app upload
│   ├── wendy_wifi/                # WiFi station + HTTP binary download
│   ├── wendy_ble_prov/            # BLE WiFi provisioning ("Wendy-XXXX")
│   ├── wendy_cloud_prov/          # Cloud device certificate provisioning
│   ├── wendy_callback/            # Async ISR-safe event dispatch (max 32 handlers)
│   ├── wendy_storage/             # NVS key-value storage for apps
│   ├── wendy_uart/                # UART serial communication
│   ├── wendy_spi/                 # SPI bus master
│   ├── wendy_sys/                 # System: reboot, uptime, device ID
│   ├── wendy_otel/                # OpenTelemetry: logs, metrics, traces
│   ├── wendy_ble/                 # BLE peripheral/central (optional)
│   ├── wendy_net/                 # TCP/UDP sockets, DNS, TLS (optional)
│   ├── wendy_wasi_shim/           # WASI compatibility layer
│   ├── wendy_safety/              # Memory safety
│   └── wendy_app_usb/             # USB from WASM app perspective (optional)
├── wasm_apps/                     # Example WASM applications
│   ├── include/wendy.h            # App API header (all host imports)
│   ├── Makefile                   # Build system for all app languages
│   ├── blink/                     # C: GPIO LED blink
│   ├── i2c_sensor/                # C: BMP280 I2C sensor reader
│   ├── swift_display/             # Swift 6.0+ embedded WASM app
│   ├── rust_blink/                # Rust WASM app
│   ├── zig_blink/                 # Zig WASM app
│   └── wat_blink/                 # Raw WebAssembly Text
├── partitions.csv                 # Flash layout (nvs, factory, wasm_a, storage)
├── sdkconfig.defaults             # ESP-IDF + WAMR + feature flags
└── diagram.json                   # Wokwi simulator circuit

Writing WASM Apps

C (Recommended for Getting Started)

#include "wendy.h"

void _start(void) {
    gpio_configure(2, WENDY_GPIO_OUTPUT, WENDY_GPIO_PULL_NONE);
    for (int i = 0; i < 10; i++) {
        gpio_write(2, 1);
        timer_delay_ms(500);
        gpio_write(2, 0);
        timer_delay_ms(500);
    }
}

Build:

cd wasm_apps
make blink

Or manually:

clang --target=wasm32 -O2 -nostdlib -I include \
  -Wl,--no-entry -Wl,--export=_start -Wl,--allow-undefined \
  -o app.wasm app.c

Swift (Recommended for App Development)

Swift apps use the WendyLite Swift package from https://github.com/wendylabsinc/wendy-lite, which provides type-safe wrappers around all WASM host imports.

See

references/swift-sdk.md

Key points:

• Requires Swift 6.0+ with Embedded Swift support
• Uses

  @_cdecl("_start")

  for the WASM entry point
• No heap allocation — use stack-allocated tuple buffers

• StaticString

  only — no runtime string construction
• Cast

  UnsafePointer<UInt8>

  to

  UnsafePointer<CChar>

  via

  UnsafeRawPointer

  for API calls
• Build and deploy with

  wendy run

Quick start:

import WendyLite

@_cdecl("_start")
func start() {
    GPIO.configure(pin: 2, mode: .output)
    GPIO.write(pin: 2, level: 1)
    System.sleepMs(1000)
    GPIO.write(pin: 2, level: 0)
}

Other Languages

make rust_blink

make zig_blink

make wat_blink

App Requirements

1. Export a

   _start

   function as the entry point
2. Import host functions from the

   "wendy"

   module
3. For async callbacks, export

   wendy_handle_callback(int handler_id, int arg0, int arg1, int arg2)

4. Call

   sys_yield()

   to allow callback dispatch

Hardware Access Summary

gpio_configure

gpio_read

gpio_write

gpio_set_pwm

gpio_analog_read

gpio_set_interrupt

i2c_init

i2c_scan

i2c_write

i2c_read

i2c_write_read

neopixel_init

neopixel_set

neopixel_clear

timer_delay_ms

timer_millis

timer_set_timeout

timer_set_interval

uart_open

uart_write

uart_read

uart_set_on_receive

spi_open

spi_transfer

spi_close

storage_get

storage_set

storage_delete

storage_exists

sys_reboot

sys_uptime_ms

sys_device_id

sys_yield

otel_log

otel_metric_*

otel_span_*

ble_init

ble_advertise_start

ble_gatts_*

ble_gattc_*

wifi_connect

wifi_status

wifi_get_ip

wifi_ap_start

net_socket

net_connect

net_send

net_recv

tls_connect

tls_send

tls_recv

wendy_print

Boot & Lifecycle

1. Firmware initializes NVS, WAMR pool, HAL, USB, BLE provisioning, WiFi
2. WASM manager thread starts, registers all HAL exports
3. Auto-loads WASM from flash partition

   wasm_a

   (if present)
4. Runs WASM

   _start()

   in dedicated thread (8KB stack)
5. Event loop handles: upload, run, stop, reset requests

Uploading WASM Binaries

• WiFi: HTTP download via UDP listener after WiFi provisioning
• USB CDC: Wire protocol with PING, UPLOAD (START/CHUNK/DONE), RUN, STOP, RESET messages
• Flash: Written to

  wasm_a

  partition with 4-byte size header, persists across reboots

BLE Provisioning

Device advertises as "Wendy-XXXX" over BLE. A client can:

1. Discover the device via BLE scan
2. Send WiFi SSID/password via GATT characteristics
3. Device connects to WiFi and starts mDNS + UDP listener

Building the Firmware

# Requires ESP-IDF (v5.x) with ESP32-C6 support
idf.py set-target esp32c6
idf.py build
idf.py flash monitor

Wokwi Simulator

The project includes

wokwi.toml

diagram.json

Memory Constraints

• WAMR pool: 229KB (pre-allocated before WiFi/BLE)
• WASM stack: 8KB, heap: 8KB
• Flash: 4MB total (1.875MB firmware, 2MB WASM, 64KB app storage)
• WiFi/PHY IRAM offloaded to flash to free ~15-25KB DIRAM

Reference Files

Load these files as needed for specific topics:

• references/swift-sdk.md

  - WendyLite Swift package: Package.swift setup, complete Swift API reference, Embedded Swift constraints, stack buffer patterns, code examples

• references/wasm-api.md

  - Complete WASM app API: all host imports, constants, callback system, per-subsystem function signatures and usage (C-level)

• references/firmware-config.md

  - ESP-IDF sdkconfig options, partition table, feature flags, memory tuning, component enable/disable