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.
• 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.
• 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, validators
├── stackchan-tts       # no_std + alloc speech surface: SpeechBackend trait + BakedBackend
├── stackchan-firmware  # CoreS3 firmware binary (embassy + esp-rtos)
├── tracker             # block-grid motion tracker for the camera path
└── driver crates       # axp2101, aw9523, aw88298, bm8563, bmi270, bmm150,
                        # es7210, ft6336u, gc0308, ir-nec, ltr553, py32,
                        # scservo, si12t

See STABILITY.md for the graduation rules.