wendy-lite

Wendy Lite

Wendy Lite 是适用于 ESP32-C6 微控制器的 WebAssembly（WASM）运行时固件。它让开发者能够使用 C、Rust、Swift、Zig、TypeScript 或 WAT 编写应用，将其编译为 WASM，并在设备上运行，同时完全访问硬件。

核心概念

• WAMR 运行时：使用 WebAssembly Micro Runtime 执行 WASM 二进制文件
• 主机导入：WASM 应用从 "wendy" 模块导入函数以访问硬件
• 回调系统：异步事件（GPIO 中断、定时器、BLE）通过导出的 wendy_handle_callback 分发
• 闪存持久化：WASM 二进制文件存储在闪存分区 wasm_a（2MB）中，并在启动时自动加载
• 多语言：应用可使用 C、Rust、Swift 6.0+、Zig、TypeScript 或原始 WAT 编写

项目结构

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

编写 WASM 应用

C（推荐用于入门）

#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);
    }
}

构建：

cd wasm_apps
make blink

或手动构建：

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

Swift（推荐用于应用开发）

Swift 应用使用 https://github.com/wendylabsinc/wendy-lite 中的 WendyLite Swift 软件包，该软件包为所有 WASM 主机导入提供类型安全的封装。

完整的 Swift API 参考、Package.swift 设置和示例，请参阅 references/swift-sdk.md。

要点：

• 需要 Swift 6.0+，并支持 Embedded Swift
• 使用 @_cdecl("_start") 作为 WASM 入口点
• 不进行堆分配——使用栈分配的元组缓冲区
• 仅使用 StaticString——不在运行时构造字符串
• 通过 UnsafeRawPointer 将 UnsafePointer<UInt8> 转换为 UnsafePointer<CChar>，以用于 API 调用
• 使用 wendy run 构建并部署

快速入门：

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)
}

其他语言

语言	构建命令	要求
Rust	make rust_blink	rustup（非 Homebrew Rust）
Zig	make zig_blink	Zig 0.13+
WAT	make wat_blink	WABT（wat2wasm）

应用要求

1. 导出 _start 函数作为入口点
2. 从 "wendy" 模块导入主机函数
3. 对于异步回调，导出 wendy_handle_callback(int handler_id, int arg0, int arg1, int arg2)
4. 调用 sys_yield() 以允许分发回调

硬件访问概览

子系统	关键函数	说明
GPIO	gpio_configure、gpio_read、gpio_write、gpio_set_pwm、gpio_analog_read、gpio_set_interrupt	支持输入、输出、PWM、ADC 和中断
I2C	i2c_init、i2c_scan、i2c_write、i2c_read、i2c_write_read	固件已预先初始化总线 0
NeoPixel	neopixel_init、neopixel_set、neopixel_clear	通过 RMT 控制 WS2812 RGB LED
定时器	timer_delay_ms、timer_millis、timer_set_timeout、timer_set_interval	阻塞式延迟和异步回调
UART	uart_open、uart_write、uart_read、uart_set_on_receive	带回调的串口
SPI	spi_open、spi_transfer、spi_close	全双工主机
存储	storage_get、storage_set、storage_delete、storage_exists	持久化 NVS 键值存储
系统	sys_reboot、sys_uptime_ms、sys_device_id、sys_yield	设备信息和控制
OTel	otel_log、otel_metric_*、otel_span_*	结构化日志、指标和追踪
BLE	ble_init、ble_advertise_start、ble_gatts_*、ble_gattc_*	可选，默认禁用
WiFi	wifi_connect、wifi_status、wifi_get_ip、wifi_ap_start	面向应用的 WiFi 控制
套接字	net_socket、net_connect、net_send、net_recv	TCP/UDP，可选
TLS	tls_connect、tls_send、tls_recv	安全连接
控制台	wendy_print	输出到 UART 和 USB

启动与生命周期

1. 固件初始化 NVS、WAMR 池、HAL、USB、BLE 配网和 WiFi
2. WASM 管理器线程启动，并注册所有 HAL 导出项
3. 从闪存分区 wasm_a 自动加载 WASM（如果存在）
4. 在专用线程（8KB 栈）中运行 WASM _start()
5. 事件循环处理上传、运行、停止和重置请求

上传 WASM 二进制文件

• WiFi：完成 WiFi 配网后，通过 UDP 监听器进行 HTTP 下载
• USB CDC：采用包含 PING、UPLOAD（START/CHUNK/DONE）、RUN、STOP、RESET 消息的线协议
• Flash：写入 wasm_a 分区，并附带 4 字节大小头信息，重启后仍会保留

BLE 配网

设备通过 BLE 广播为“Wendy-XXXX”。客户端可以：

1. 通过 BLE 扫描发现设备
2. 通过 GATT 特征发送 WiFi SSID/密码
3. 设备连接 WiFi 并启动 mDNS + UDP 监听器

构建固件

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

Wokwi 模拟器

项目包含 wokwi.toml 和 diagram.json，可在没有实体开发板的情况下进行硬件模拟。

内存限制

• WAMR 池：229KB（在 WiFi/BLE 启动前预分配）
• WASM 栈：8KB，堆：8KB
• Flash：总计 4MB（1.875MB 固件、2MB WASM、64KB 应用存储）
• 将 WiFi/PHY IRAM 转存至 Flash，以释放约 15-25KB DIRAM

参考文件

根据需要加载以下文件，了解特定主题：

• references/swift-sdk.md - WendyLite Swift 包：Package.swift 设置、完整的 Swift API 参考、Embedded Swift 限制、栈缓冲区模式、代码示例
• references/wasm-api.md - 完整的 WASM 应用 API：所有主机导入项、常量、回调系统，以及各子系统的函数签名和用法（C 级别）
• references/firmware-config.md - ESP-IDF sdkconfig 选项、分区表、功能标志、内存调优、组件启用/禁用