stackchan-kai engineering handbook

Reference docs for stackchan-kai — no_std Rust firmware for the M5Stack CoreS3 Stack-chan, plus the host simulator, networking + voice crates, and a stack of embedded-hal-async driver crates.

Pages

• Architecture overview — the engine, the firmware’s task graph, and how the host sim mirrors it.
• HTTP control plane — LAN-scoped routes for live state, manual control, persistent config, and the embedded operator dashboard.
• Behavior flags — operator reference for the behavior: block in STACKCHAN.RON (which flags exist, defaults, reboot semantics).
• Modifier authoring guide — adding a new behavior to the engine.
• Naming conventions — rules for Intent / Modifier / Skill / ChirpKind / OverrideSource names, with citations.
• Signal channels — the typed Signal<…, T> pattern that wires sensors to the render task.
• Dance choreography — JSON keyframe stream over POST /dance, channel-wise sampling semantics, and DancePlayer lifecycle.
• Voice agent — wake-word + sidecar onboarding flow. Start here when enabling the voice path.
• Sidecar agent — wire protocol for the operator-supplied HTTP agent that handles STT + LLM + emotion-tagging.
• UDP audio debug — tee the microphone capture to a LAN UDP target for aplay / nc inspection.
• Typed-error catalog — every driver crate’s Error<E> enum.

Source layout

crates/
├── stackchan-core              # no_std engine (Entity, Director, Modifier, Skill, Phase, Clock)
├── stackchan-sim               # host simulator (FakeClock, Framebuffer, viz binary)
├── stackchan-net               # no_std wire formats: RON config, HTTP parsers, MCP, BLE codecs, OTA, …
├── stackchan-tts               # no_std + alloc speech surface: SpeechBackend trait + BakedBackend + VoiceVox
├── stackchan-audio-features    # no_std streaming log-mel frontend for on-device keyword spotting
├── stackchan-desktop-protocol  # no_std + alloc Claude Desktop Hardware Buddy NUS protocol
├── stackchan-firmware          # CoreS3 firmware binary (embassy + esp-rtos)
├── esp-tflite-micro-sys        # FFI bindings for TFLite-micro + esp-nn (vendored C/C++)
├── tracker                     # block-grid motion tracker + Viola–Jones face cascade
└── driver crates               # axp2101, aw9523, aw88298, bm8563, bmi270, bmm150,
                                # es7210, ft6336u, gc0308, ir-nec, ltr553, py32,
                                # scservo, si12t

See STABILITY.md for the graduation rules.