| title | Docs Index |
|---|---|
| description | Index of the StackChan tech reference documentation. |
Curated reference for the StackChan voice robot stack. The top-level README.md
covers how to deploy it; these docs cover what it is underneath — hardware,
protocols, upstream model facts, and capabilities we aren't yet using.
Every file here cites upstream sources so a future agent (or human) can re-verify claims against the canonical specs rather than trusting our paraphrase.
| If you're trying to… | Read |
|---|---|
| Understand the overall shape | architecture.md |
| Know what the physical robot can do | hardware.md |
| Understand the voice pipeline (ASR/TTS/VAD) | voice-pipeline.md |
| Understand the brain (the pi agent + model matrix) | brain.md |
| Know what's on the wire between components | protocols.md |
| See every cross-layer signal at a glance | interaction-map.md |
| Know what mode the robot is in (and what the LEDs mean) | modes.md |
| Find features we aren't using yet | latent-capabilities.md |
| Pick an LLM backend | llm-backends.md |
| Run a live-device bench verification session | bench-runbook.md |
| Run the full-feature UAT session (filmed for Dotty's channel) | uat-runbook.md |
| Turn UAT clips into YouTube Shorts in Dotty's voice | uat-social.md |
| Jump to an upstream repo or spec | references.md |
docs/
├── README.md ← you are here (index)
├── architecture.md ← high-level data flow, actor responsibilities
├── hardware.md ← M5Stack StackChan body + firmware lineage + MCP tool catalog
├── voice-pipeline.md ← xiaozhi-esp32-server, FunASR/Whisper, VAD, Piper/EdgeTTS
├── brain.md ← the pi agent runtime + model matrix + dashboard service
├── protocols.md ← Xiaozhi WebSocket, MCP-over-WS, pi RPC, emotion
├── interaction-map.md ← every cross-layer signal: source, dest, protocol, notes
├── modes.md ← behavioural mode taxonomy + LED contract + transitions
├── latent-capabilities.md ← upstream features we could wire up (cross-refs ROADMAP.md)
├── llm-backends.md ← side-by-side comparison of LLM backend options
├── bench-runbook.md ← ordered live-device bench session plan (epic #122)
├── uat-runbook.md ← full-feature UAT session script, filmed for YouTube
├── uat-social.md ← Dotty's-channel production guide for UAT clips
├── uat-results-template.csv ← slicer-ready results log template
└── references.md ← canonical URLs, licenses, model cards, spec docs
- TL;DR at the top of each file — 3-6 bullets, scannable in the first 40 lines.
- Tables over prose for dense facts — specs, tunables, method signatures.
- Grep-bait headers — e.g.
## MCP tool handshake,## session/prompt— so you can navigate by header search. - Relative links only —
[voice-pipeline.md](./voice-pipeline.md); never absolute paths. - Freshness footer — every non-index file ends with
Last verified: YYYY-MM-DD. - Placeholders for per-deployment values —
<XIAOZHI_HOST>,<XIAOZHI_USER>, etc. (mapping lives with the deployer, not in this repo). - Soft claims where unverified — if a fact came from a secondary source or we couldn't verify, the text says so rather than pretending to cite upstream.
../README.md— deployment & ops (commands, layout, troubleshooting).../CLAUDE.md— agent orientation for this repo specifically.../bridge.py,../custom-providers/— canonical source for the dashboard service and the custom ASR/LLM/TTS provider patches.- These
docs/— the why and the what else is possible behind the above.
Each sub-file has a Last verified: date. Freshness decays roughly as follows:
| Topic | Half-life | Why |
|---|---|---|
| Hardware spec | Years | M5Stack CoreS3 revisions are slow |
| Protocol spec | Months | xiaozhi is actively evolving |
| Model facts (Qwen3) | Weeks-months | OpenRouter pricing and model revisions churn |
| Latent capabilities | Months | Upstream adds features regularly |
If you're reading this a year from now, treat the protocol + model claims as starting points for re-verification, not ground truth.
Last verified: 2026-05-22.