wendy-lite

Wendy Lite

Wendy Lite は、ESP32-C6 マイクロコントローラー向けの WebAssembly（WASM）ランタイムファームウェアです。開発者は C、Rust、Swift、Zig、TypeScript、または WAT でアプリを記述し、WASM にコンパイルして、ハードウェアにフルアクセスしながらデバイス上で実行できます。

主な概念

• WAMR Runtime：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 を参照してください。

主なポイント：

• Embedded Swift に対応した Swift 6.0 以降が必要です
• WASM のエントリーポイントには @_cdecl("_start") を使用します
• ヒープ割り当てはありません。スタックに割り当てられたタプルバッファーを使用してください
• StaticString のみ使用できます。実行時の文字列構築はできません
• API 呼び出しでは、UnsafePointer<UInt8> を UnsafeRawPointer を介して UnsafePointer<CChar> にキャストします
• 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：4 バイトのサイズヘッダーとともに wasm_a パーティションに書き込まれ、再起動後も保持されます

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、WASM 2MB、アプリストレージ 64KB）
• 約 15～25KB の DIRAM を確保するため、WiFi/PHY IRAM を Flash にオフロードします

参考ファイル

トピックに応じて、必要なファイルを読み込んでください。

• 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 オプション、パーティションテーブル、機能フラグ、メモリーチューニング、コンポーネントの有効化／無効化