XiaoZu — MoonBit × ESP32 开发族

XiaoZu (小族) — a minimal, field-tested development kit for building ESP32-S3 firmware with a host-testable MoonBit core and ESP-IDF C bridges.

小族:用 MoonBit 写固件核心(笔记本上就能跑测试),用 C 桥接 ESP-IDF 外设,六边形端口架构,一条命令验证。

Why XiaoZu / 为什么

• Host-testable core:the ports, session logic, and JSON/SSE stack are pure MoonBit — make test runs on your laptop, no board required.
• Frozen C ABI:ESP-IDF bridges (WiFi/NVS/HTTP/TLS, OLED+CJK display) sit behind bridge/ABI.md, a frozen extern contract with a diff gate.
• Gated vendored dependency:the moonbitlang/esp32 binding ships as a semantic fork with loud gates — a fresh clone builds reproducibly, period.
• Field-tested:the skeleton and the pitfall guide condense a multi-week firmware campaign (35+ documented pitfalls) — the build works because the failures already happened elsewhere.
• CJK OLED out of the box:7439-glyph Chinese font in the display bridge — flash and you get Chinese on a 128x32 OLED, rare among devkits.

Layout / 结构

core/            MoonBit hexagon interior: ports + ring/res (pure, host-testable)
core/agent/      Session + SSE + JSON domain (depends only on core)
main/            chat-minimal firmware driver (WiFi → session loop → serial)
bridge/          frozen C ABI contract (ABI.md); C bridges live in skeleton/
tools/           bootstrap/warnfix (mbtx), xtwrap fixes, NVS creds, ABI gate
skeleton/        ESP-IDF project (.moonbit_esp32/) + vendored esp32 overlay

Quick Start / 五分钟上手

Prerequisites / 前置:ESP-IDF v5.5.x + Xtensa toolchain (~/.espressif), esp-idf repo (~/esp/esp-idf), MoonBit toolchain (moon).

# 0. clone + bootstrap the vendored dependency (gated, idempotent)
git clone <repo-url> xiaozu && cd xiaozu
make bootstrap

# 1. host tests (no board needed / 无板可跑)
make test

# 2. build fixes (idempotent; discover toolchain + esp-idf automatically)
bash tools/fix_longcalls.sh

# 3. WiFi credentials → NVS (env-var driven; never committed)
XZ_SSID='your-wifi' XZ_PASS='your-pass' bash tools/gen_nvs.sh

# 4. build + flash
make build
make flash

# 5. watch it talk: boot → WiFi → session loop → serial replies
idf.py -C .moonbit_esp32 monitor

把 main/main.mbt 里的 SESSION_ENDPOINT 指到你的 LLM 端 (局域网 mock 或云端),串口就能看到真实模型回复。

Docs / 文档卷

spec.md(规格 SSOT)· ctx.md(坑账即时账本,C1–C22 据实)· skeleton/overlay/esp32/FORK.md(依赖分叉裁决档案)· todo.md(台账)。

License / 许可

• Code: Apache-2.0 (see LICENSE)
• CJK font (bridge/xiaozu_disp/cjk16_font.h): derived from Noto Sans SC, SIL Open Font License 1.1
• ESP-IDF components are fetched by the IDF component manager and carry their own licenses.

Family / 家族

XiaoZu is the framework; XiaoGe (小狗) is the flagship family member — a voice-enabled desk companion built on the same architecture (audio, wake word, WebSocket duplex chat).