stackchan-mcp

**English** | [日本語](README.ja.md) # stackchan-mcp An MCP (Model Context Protocol) bridge for the **M5Stack official [StackChan](https://docs.m5stack.com/ja/StackChan)** (2025 Kickstarter shipping kit), letting any LLM client drive the device. > Born out of the [stack-chan project](https://github.com/stack-chan/stack-chan) community (originated by Shinya Ishikawa in 2021). This repository targets the M5Stack official StackChan kit that grew out of that lineage. ``` ┌─────────────┐ stdio MCP ┌──────────────┐ WebSocket MCP ┌──────────────┐ │ MCP client │ ─────────────────▶ │ gateway │ ──────────────────▶ │ ESP32 (CoreS3│ │ (e.g.Claude)│ ◀───────────────── │ (Python) │ ◀────────────────── │ +StackChan) │ └─────────────┘ │ │ └──────────────┘ │ /capture │ ◀── HTTP POST (JPEG) ──┘ └──────────────┘ ``` From any MCP client (Claude Code / Claude Desktop / others) you can call StackChan operations such as head movement, camera capture, touch sensor reads, and avatar expression switches. ## Repository layout This repository is a monorepo. | Directory | Contents | |---|---| | `firmware/` | Full git subtree of [78/xiaozhi-esp32](https://github.com/78/xiaozhi-esp32). The custom StackChan board lives at `firmware/main/boards/stackchan/`. | | `gateway/` | Python MCP gateway. stdio MCP server (LLM side) + WebSocket MCP client (ESP32 side) + HTTP capture server. | | `docs/` | [`architecture.md`](docs/architecture.md): full component diagram, tool name mapping, photo flow, auth, phase roadmap. [`firmware-sync.md`](docs/firmware-sync.md): upstream xiaozhi-esp32 sync playbook. [`remote-access.md`](docs/remote-access.md): Tailscale Funnel setup for non-LAN use. | | `examples/` | Optional, unmaintained examples. [`cloudflare-relay/`](examples/cloudflare-relay/): Cloudflare Workers WebSocket relay for reaching the gateway from outside the local LAN. | ## Target hardware **M5Stack official [StackChan kit](https://docs.m5stack.com/ja/StackChan)** (Kickstarter 2025 shipping version). The firmware in this repository is meant to replace the kit's [factory firmware](https://docs.m5stack.com/ja/StackChan#%E5%87%BA%E8%8D%B7%E6%99%82%E3%83%95%E3%82%A1%E3%83%BC%E3%83%A0%E3%82%A6%E3%82%A7%E3%82%A2). | Part | Spec | |---|---| | **Body** | M5Stack CoreS3 (ESP32-S3, 16MB Flash, 8MB PSRAM) | | **Neck servos** | SCS0009 ×2 (yaw + pitch, serial bus, TX=GPIO6, RX=GPIO7) | | **Camera** | GC0308 (DVP, 320×240) | | **Touch** | FT6336 / Si12T | | **Display** | ILI9342 (SPI, 320×240) | > A self-built stack-chan (following the original [stack-chan project](https://github.com/stack-chan/stack-chan) design) may also work as long as the pin assignments and I2C addresses match. Reports and PRs welcome. ## Tools (callable by MCP clients via the gateway) | Tool | Description | Status | |---|---|---| | `get_status` | Gateway connection state | ✅ | | `get_device_info` | ESP32 device state (battery / volume / WiFi / etc.) | ✅ | | `take_photo(question?)` | Capture a frame, save as JPEG, return the path + inline image block | ✅ | | `set_volume(volume)` | Speaker volume (0-100) | ✅ | | `set_brightness(brightness)` | Screen brightness (0-100) | ✅ | | `set_off_timeout(seconds)` | Persistent idle screen-off timeout (0..86400 seconds; default 300, 0 disables). Requires firmware 1.17.0+ | ✅ | | `get_off_timeout` | Read the persistent screen-off timeout and current screen state. Requires firmware 1.17.0+ | ✅ | | `move_head(yaw, pitch, speed?)` | Move the neck (servos). `pitch` is constrained to `5..85` — the M5Stack-recommended operating range. For the wider firmware hard clamp (`0..88`), use the firmware-side `set_head_angles` device tool instead. | ✅ | | `get_touch_state` | Touch sensor state (press / release / stroke / etc.) | ✅ | | `get_touch_sensor_enabled` | Read whether head-touch detection is enabled. The NVS-backed setting persists across reboot. | ✅ | | `set_touch_sensor_enabled(enabled)` | Enable or disable head-touch detection. Disabling stops both the firmware local motion response and MCP `stackchan/event` emission, and persists across reboot. | ✅ | | `set_avatar(face)` | Switch avatar expression (`idle` / `happy` / `thinking` / `sad` / `surprised` / `embarrassed`), or `off` to hide the avatar and disable blink so the underlying WiFi config / OTA / settings screens are visible. Any other face brings the avatar back and restores blink. | ✅ | | `set_blink(state)` | Blink on/off | ✅ | | `set_mouth(state)` | Mouth open/close (one-shot, held until next call) | ✅ | | `set_mouth_sequence(steps)` | Queue and play a list of `{shape, duration_ms}` steps locally for TTS lip-sync — no per-step WebSocket RTT jitter | ✅ | | `check_vm_en` | Check servo power supply (VM EN HIGH) state | ✅ | | `set_led(index, r, g, b)` | Set one of the 12 base RGB LEDs (index `0..11`, channels `0..255`) | ✅ | | `set_all_leds(r, g, b)` | Set all 12 base RGB LEDs to the same color | ✅ | | `set_leds(colors)` | Batch-set the first N LEDs from a `[[r,g,b], ...]` array in a single I2C burst (use this for animations / multi-color patterns); trailing LEDs keep their previous color | ✅ | | `clear_leds` | Turn all 12 base RGB LEDs off | ✅ | | `say(text, voice?, speaker_id?, reference_audio?)` | Speak text on the device speaker via gateway-side TTS. A supported expression emoji in the text can switch the avatar face in the same call. Default engine: **VOICEVOX** (runs as a separate HTTP service — see [TTS setup](#optional-tts-setup-voicevox)). Requires the `[tts]` extra. | ✅ | | `listen(duration_ms?, engine?, language?, model?, motion?, look_up_pitch?)` | Capture a short utterance from the device microphone and transcribe it via gateway-side STT. Default engine: **faster-whisper** (local, MIT) — see [STT setup](#optional-stt-setup-faster-whisper). Optional `motion` feedback can show the `thinking` face or tilt the head up during capture. Requires the `[stt-faster-whisper]` (or `[stt-openai]`) extra and a firmware update with the inbound `listen` wire type. | ✅ | | `beat_mode_start(motion_intensity?, sensitivity?, color?, duration_sec?)` | Start gateway-only beat mode: continuously capture ambient device audio through the existing `listen` wire path, estimate BPM in the gateway, and drive free-running beat-synced head sway plus base-ring LED flashes. `sensitivity` tunes the onset floor for quiet rooms or loud venues. Beat mode requests the firmware raw capture profile so music bypasses speech-oriented AFE suppression. While active, `listen()` is mutually exclusive; `say()` may interrupt and beat mode re-arms listening afterwards. Requires the `[stt]` extra for Opus decoding. | ✅ | | `beat_mode_stop()` | Stop beat mode and send `listen.stop` best-effort while retaining the latest rolling audio buffer for clip export until the next beat-mode start or gateway restart. | ✅ | | `beat_mode_update(motion_intensity?, sensitivity?, color?, blink_rate?, motion_enabled?, led_enabled?)` | Update beat-mode VJ parameters without restarting capture. | ✅ | | `beat_meta_snapshot()` | Poll the latest beat-mode metadata: active state, BPM, confidence, active sensitivity/minimum onset floor, last beat/audio timestamps, capture health, counters, and current motion/LED parameters. | ✅ | | `beat_clip_save(seconds?)` | Save the latest rolling beat-mode audio window as a 16 kHz mono WAV temp file and return its path plus actual captured duration. Clip files persist on disk; the caller is responsible for deleting them when no longer needed. | ✅ | | `stackchan_follow_pose_stream(action, url, ...)` | Subscribe to an arbitrary external WebSocket pose-stream and drive the head to follow incoming `yaw` / `pitch` frames 1:1 within the SCS0009 working range. `action` switches between `start` / `stop` / `status`. Includes per-axis flip, pitch-center offset, downsample rate cap, angular-velocity clamp, and reconnect with exponential backoff; the initial pose is seeded from the device so the angular-velocity clamp is anchored at the real servo position from the first frame. The upstream server's protocol (zero-offset commands, source dispatching, transport) is intentionally outside this gateway's scope. | ✅ | | `stackchan_follow_led_stream(action, url, target, ...)` | Subscribe to an arbitrary external WebSocket LED-frame stream and forward validated `colors` frames to either the built-in 12-LED base ring or a Port B WS2812 strip. `event` frames bypass the rate gate; `continuous` frames are capped by `max_fps`. | ✅ | See `gateway/README.md` for full schemas. ## Quick start ### 1. Flash the firmware (CoreS3) There are two paths. **Option A** is recommended for first-time users — no toolchain setup needed. **Option B** is for contributors who want to build from source. #### Option A: Flash a pre-built binary (recommended for end users) Download the latest firmware bundle from the [Releases page](https://github.com/kisaragi-mochi/stackchan-mcp/releases) — pick the most recent `firmware-v*` release and grab `merged-binary.bin` (and optionally `xiaozhi.bin`). Then flash with `esptool.py`: ```bash # Replace --port with your platform's serial device: # macOS: /dev/cu.usbmodem* (e.g. /dev/cu.usbmodem1101) # Linux: /dev/ttyUSB0 or /dev/ttyACM0 # Windows: COM3 (or whichever it shows up as in Device Manager) # Clean install (resets NVS — Wi-Fi settings will need to be re-entered): esptool.py --chip esp32s3 --port /dev/cu.usbmodem1101 -b 460800 \ write_flash 0x0 merged-binary.bin # Or, app-only update (preserves NVS — keeps your Wi-Fi setup): esptool.py --chip esp32s3 --port /dev/cu.usbmodem1101 -b 460800 \ write_flash 0x20000 xiaozhi.bin ``` No ESP-IDF or Docker setup needed. #### Option B: Build from source with Docker (for contributors) This repository uses git submodules under `firmware/components/`. If you cloned without `--recursive`, initialize them first: ```bash git submodule update --init --recursive ``` Then build: ```bash cd firmware docker run --rm --cpus=4 --ulimit nofile=65536:65536 \ -v $PWD:/project -w /project espressif/idf:v5.5.2 \ python ./scripts/release.py stackchan # → releases/v2.2.6_stackchan.zip # Flash (after USB-connecting the CoreS3). # Replace --port with your platform's serial device — see the Option A # note above for the macOS/Linux/Windows mapping. esptool.py --chip esp32s3 --port /dev/cu.usbmodem1101 -b 460800 \ write_flash 0x0 build/merged-binary.bin ``` The `--cpus=4` flag caps Docker container parallelism so the concurrent LVGL / `xiaozhi-fonts/emoji_*.c` compile steps stay within the memory budget on macOS Docker hosts (OrbStack / Docker Desktop). Without it, `ninja` autodetects job count from `/proc/cpuinfo` and the resulting parallel `gcc` pressure can exhaust container memory mid-LVGL with `Cannot allocate memory` — even on hosts with ample physical RAM (tracked as #112). The `--ulimit nofile=65536:65536` flag separately avoids a `Too many open files` failure during the same LVGL compile step under the default file-descriptor limit. Linux hosts with higher defaults are unaffected, but passing both flags unconditionally is safe and matches CI. After flashing, WiFi configuration happens on first boot — connect from a smartphone to the setup UI (the xiaozhi-esp32 standard flow). On a local network, the gateway advertises `_stackchan-mcp._tcp.local.` by default. Fresh firmware can use that mDNS/DNS-SD record to find the WebSocket endpoint automatically when no primary URL has been saved yet. mDNS discovery requires NVS `websocket.url` to be empty. ### Configuring the WebSocket gateway URL and auth token Primary URL resolution order: 1. NVS `websocket.url` 2. mDNS `_stackchan-mcp._tcp.local.` when `CONFIG_STACKCHAN_MDNS_DISCOVERY` is enabled and the primary NVS URL is empty 3. `CONFIG_DEFAULT_WEBSOCKET_URL` 4. Empty/fail with a boot log error Existing `websocket.fallback_url` and `CONFIG_DEFAULT_WEBSOCKET_FALLBACK_URL` candidates are still tried after the primary candidate path above. `CONFIG_FORCE_DEFAULT_WEBSOCKET_URL=y` remains an explicit exception for stale-NVS recovery: a non-empty Kconfig URL wins and mDNS discovery is skipped. The gateway advertises mDNS by default; run `stackchan-mcp --no-mdns` to disable advertisement. To compile out firmware discovery, set `CONFIG_STACKCHAN_MDNS_DISCOVERY=n`. Discovery requires UDP multicast on the local LAN, and some routers or VLANs block it. When multiple gateways are visible, the firmware tries each usable IPv4 address from every supported gateway service discovered in one browse, and logs the accepted instance count and candidate address list. mDNS only discovers the URL; `websocket.token` / `CONFIG_DEFAULT_WEBSOCKET_TOKEN` still control authentication. For LAN auto-discovery with an automatic out-of-LAN relay fallback, keep NVS `websocket.url` empty and store the relay URL in `websocket.fallback_url`. With that profile, mDNS candidates are tried first, and the relay is tried later if the local discovery path does not complete the WebSocket server hello flow. Automatic recovery after a gateway host IPv4 change requires both sides of the paired mDNS fix: Gateway vA.B.C+ refreshes the advertised service when the host address changes, and Firmware vX.Y.Z+ tries all supported mDNS service instances from a browse. Earlier firmware may keep trying a stale cached instance until reboot. The firmware reads these NVS keys for the gateway connection: - `websocket.url` — the gateway WebSocket URL (e.g. `ws://<gateway-host>:8765/`) - `websocket.fallback_url` — optional second gateway URL to try when `websocket.url` cannot be reached or does not complete the server hello flow - `websocket.token` — the bearer token sent as `Authorization: Bearer <token>`, matched against `STACKCHAN_TOKEN` / `BEARER_TOKEN` on the gateway side (leave both empty to skip authentication entirely) There are four practical ways to provide them, plus one temporary source-level escape hatch: 1. **Build-time defaults via Kconfig (recommended for developers)**: run `idf.py menuconfig` → `Component config` → `Xiaozhi Assistant`, and set: - `Default WebSocket gateway URL (fallback when NVS is empty)` → `CONFIG_DEFAULT_WEBSOCKET_URL` (e.g. `ws://<gateway-host>:8765/`) - `Fallback WebSocket gateway URL` → `CONFIG_DEFAULT_WEBSOCKET_FALLBACK_URL` - `Default WebSocket auth token (fallback when NVS is empty)` → `CONFIG_DEFAULT_WEBSOCKET_TOKEN` (leave empty if your gateway accepts unauthenticated connections) By default these only apply when the corresponding NVS key is empty. For first-time flashes onto a fresh device this is exactly what you want. If both a primary and fallback URL are configured, the firmware tries them in deterministic order and keeps the first candidate that completes the WebSocket server hello flow. 2. **Use the on-device WiFi config UI (recommended for fresh users)**: while the device is in WiFi configuration mode, open the captive portal at `http://192.168.4.1`, switch to the **Advanced** tab, and fill in: - **WebSocket Gateway URL** (e.g. `ws://<gateway-host>:8765/`) — the primary gateway candidate. - **Fallback Gateway URL** (e.g. `wss://<relay-host>/`) — optional second candidate, tried only after the primary candidate fails the server-hello flow. - **Gateway Token** — optional bearer token, sent as `Authorization: Bearer <token>` to both candidates when set. The current value is never displayed (the WiFi config AP is unauthenticated, so the GET endpoint reports only whether a token is configured). Leave the field blank to keep the existing token, type a new value to update it, or hit ❌ to fall back to the build-time `CONFIG_DEFAULT_WEBSOCKET_TOKEN`. On stock builds where no Kconfig default is set this disables auth; on builds that ship a default token, ❌ reverts to that default rather than truly clearing authentication. To switch the device to an unauthenticated gateway on a build that ships a default token, rebuild the firmware with the Kconfig default empty (or set a non-empty token on the gateway side that matches the build default). Submit to persist the values to the `websocket` NVS namespace (`websocket.url` / `websocket.fallback_url` / `websocket.token`); they are read on the next boot. This is the intended path for end users running a pre-built firmware. Clearing a URL field with the ❌ button and submitting again falls back to the matching `CONFIG_DEFAULT_WEBSOCKET_*` Kconfig value (or to "no fallback" when no Kconfig default is set). 3. **Use the runtime MCP tools over an established connection**: `gateway_config_get` reports `websocket.url`, `websocket.fallback_url`, whether a token is set, `force_mode`, `discovery_enabled`, and the connected candidate URL without exposing the token value. `gateway_config_set` accepts optional `url`, `fallback_url`, and `token` strings. Passing an empty string clears that NVS key; for example `url=""` restores the mDNS discovery path on the next reconnect. Changes are persisted immediately but do not trigger a disconnect, reconnect, or reboot. 4. **Write `websocket.url` / `websocket.fallback_url` / `websocket.token` directly to NVS** (advanced): for example with a custom NVS-write tool over serial. Same persistence semantics as the WiFi config UI and runtime MCP tools; primarily useful for batch provisioning. 5. **Temporary source hardcode (not recommended)**: editing `websocket_protocol.cc` can unblock local experiments, but keep it out of commits. Common gateway URL setups: | Mode | Primary URL | Fallback URL | | --- | --- | --- | | LAN auto-discovery with relay fallback | empty (mDNS) | `wss://<relay-host>/` | | Fixed local only | `ws://<gateway-host>:8765/` | empty | | Relay only | `wss://<relay-host>/` | empty | | Fixed local with relay fallback | `ws://<gateway-host>:8765/` | `wss://<relay-host>/` | #### Existing devices with stale NVS — `CONFIG_FORCE_DEFAULT_WEBSOCKET_URL` If you are flashing onto a device that previously ran upstream xiaozhi-esp32 firmware, NVS will already contain `websocket.url=wss://api.tenclass.net/...` written by the upstream OTA-config path. In this case the empty-NVS fallback in option 1 above will **not** trigger, and the device will keep trying to talk to tenclass instead of your local gateway. If the device can still establish a stackchan-mcp connection through any candidate, call `gateway_config_set` with `url=""` to clear the stale primary NVS URL and restore the mDNS discovery path on the next reconnect. If the stale URL prevents any stackchan-mcp connection from being established, use the force-override switch without erasing all of NVS (which would also drop WiFi credentials): - `Force CONFIG_DEFAULT_WEBSOCKET_URL/TOKEN to override NVS` → `CONFIG_FORCE_DEFAULT_WEBSOCKET_URL=y` When set, **non-empty** Kconfig URL/token values override whatever NVS holds. Empty Kconfig values still fall through to the NVS-based behaviour, so leaving the token Kconfig empty keeps any NVS-stored token in use. The boot log will show `FORCE: overriding NVS websocket.url with Kconfig: NVS=... -> ...` so you can verify the override fired. This switch is the recommended way to bring ex-xiaozhi hardware onto a local stackchan-mcp gateway, and to lock CI/dev images to a known gateway URL. The switch is opt-in so end-user devices configured at runtime keep their NVS-priority semantics. #### Developer-local overrides — `sdkconfig.defaults.local` For local hardware testing, do not put personal gateway URLs or tokens in the tracked `firmware/sdkconfig.defaults`. Instead, create a gitignored local file: ```bash cd firmware cat > sdkconfig.defaults.local <<'EOF' CONFIG_DEFAULT_WEBSOCKET_URL="ws://<your-lan-ip>:8765/" CONFIG_DEFAULT_WEBSOCKET_FALLBACK_URL="wss://<relay-host>/" CONFIG_DEFAULT_WEBSOCKET_TOKEN="<your-dev-token>" CONFIG_FORCE_DEFAULT_WEBSOCKET_URL=y EOF ``` Both `python ./scripts/release.py <board>` and plain `idf.py build` will read this file when it exists. The file is ignored by git, so personal settings cannot be added accidentally with `git add -A`. ### 2. Start the gateway The gateway can either be installed as the published PyPI package (recommended for end users) or run from this repository as a checkout (recommended for contributors who want to follow `main`). #### Option A: install as a tool (recommended for end users) For an isolated install that does not collide with your system Python or other Python projects, use one of: ```bash uv tool install stackchan-mcp # or pipx install stackchan-mcp ``` Then run the gateway: ```bash stackchan-mcp ``` If you prefer a project-managed virtualenv, `pip install stackchan-mcp` inside an active venv works as well, and `python -m stackchan_mcp` inside that venv is equivalent to `stackchan-mcp`. Just avoid `pip install` against the system Python (PEP 668). The `STACKCHAN_TOKEN`, `VISION_HOST`, and other settings documented in [`gateway/README.md`](gateway/README.md#setup) can be supplied via environment variables, the active shell, or a `.env` file in the working directory. #### Option B: from source via uv (contributors) ```bash cd gateway cp .env.example .env # set STACKCHAN_TOKEN / VISION_HOST uv sync uv run python -m stackchan_mcp ``` If the gateway is restarted while the ESP32 is already connected, the firmware automatically retries the WebSocket connection while idle. The retry delay starts at 5 seconds and backs off up to 60 seconds; use `get_status` to confirm that the device has reappeared. The same retry path also fires for any post-handshake server-initiated close — gateway crashes, TLS-layer resets, and gateway configurations that tear the WebSocket session down after the handshake — so the device recovers automatically once the gateway accepts the next connection attempt. For non-LAN setups, see [`docs/remote-access.md`](docs/remote-access.md) for the Tailscale Funnel flow and the `VISION_URL` capture callback setting. ### 3. Register as an MCP client (Claude Code example) Add to `~/.claude.json`. If you installed via `pip install stackchan-mcp`: ```json { "mcpServers": { "stackchan-mcp": { "type": "stdio", "command": "stackchan-mcp", "env": { "STACKCHAN_TOKEN": "your-secret-token-here", "VISION_HOST": "your.host.lan.ip" } } } } ``` If you installed from source via `uv`: ```json { "mcpServers": { "stackchan-mcp": { "type": "stdio", "command": "uv", "args": [ "run", "--directory", "/path/to/stackchan-mcp/gateway", "python", "-m", "stackchan_mcp" ] } } } ``` See `gateway/README.md` for details. ### Gateway user-defaults TOML file The Python gateway can optionally read user-local default argument values from a TOML file under the OS-standard user config directory: - Linux / XDG: `~/.config/stackchan-mcp/user-defaults.toml` - macOS: `~/Library/Application Support/stackchan-mcp/user-defaults.toml` - Windows: `%APPDATA%\stackchan-mcp\user-defaults.toml` The exact path is resolved with `platformdirs`, and the gateway logs the resolved path at startup. The tracked `user-defaults.toml.example` file at the repository root is the template. The file is an overlay on top of the MCP schema defaults. If the file is absent or empty, schema defaults are used. If a key is omitted from the file, that key keeps its schema default. Explicit MCP tool-call arguments always take precedence over the file, so the order is: explicit argument > user-defaults file > schema default. This is a gateway-side Python setting. It is separate from the firmware-side NVS connection settings exposed by `gateway_config_get` / `gateway_config_set` (added in PR #293). Those tools read or update the device's saved WebSocket connection settings; this TOML file only changes default MCP argument values used by the Python gateway. Minimal example: ```toml [tool.stackchan_follow_pose_stream] smoothing_window = 1 downsample_hz = 20 max_step_deg = 30 [tool.stackchan_follow_led_stream] target = "base_ring" max_fps = 30 source_filter = "stage" ``` ### follow_led_stream WebSocket LED frames `stackchan_follow_led_stream(action="start", url=..., target=...)` connects from the gateway to an external WebSocket URL as a client. It validates incoming LED frames and forwards them to one of two targets: - `target="base_ring"` writes the built-in 12-LED base ring through `set_leds`. Omit `led_count`, or pass `12`. - `target="port_b"` writes a WS2812 strip on Port B through `port_b_ws2812_set_strip`. `led_count` is required (`1..256`), and the gateway sends `port_b_ws2812_init` on stream start and after device reconnect. Frame schema: ```json {"ts": 1751234567890, "kind": "event", "colors": [[255, 0, 0], [0, 0, 255]]} ``` `ts` must be numeric. `kind` is either `event` or `continuous`. `continuous` frames are downsampled to `max_fps` (default `30`), while `event` frames bypass that gate so beat flashes are not silently dropped. `colors` must be a non-empty array of `[r,g,b]` integer triples (`0..255`) and must fit the target capacity. Optional string fields `source` and `frame` can be matched with `source_filter` and `frame_filter`. Manual fallback does not need a switching step: when the stream is stopped or the upstream WebSocket is disconnected, plain `set_leds` and `port_b_ws2812_*` calls still work normally. TOML overlay example: ```toml [tool.stackchan_follow_led_stream] target = "port_b" led_count = 24 max_fps = 30 source_filter = "stage" frame_filter = "calibrated" ``` ### Measured guidance (real device, home WLAN) - Wire round-trip per frame: ~40-50 ms median → effective dispatch rate ~20 fps - Recommended `max_fps: 20` — feeding more than the effective rate only increases continuous-frame drops (event frames are never dropped) - While the stream is active the gateway forces WiFi power save off (restored on stop); without it dispatch latency spikes to 300-1100 ms ### 4. Optional: TTS setup (VOICEVOX) To make the device speak, install the `[tts]` extra and run a [VOICEVOX](https://voicevox.hiroshiba.jp/) engine alongside the gateway. VOICEVOX runs as a separate HTTP service, so its LGPL-3.0 license stays scoped to that process — the MIT-licensed gateway only issues HTTP requests against it. #### Run the engine (Docker) ```bash docker run --rm -p '127.0.0.1:50021:50021' \ voicevox/voicevox_engine:cpu-ubuntu20.04-latest ``` The engine listens on port 50021 by default. The CPU image is fine for short sentences; GPU images are also published upstream. #### Install the TTS extra ```bash pip install 'stackchan-mcp[tts]' # or, equivalently: pip install 'stackchan-mcp[tts-voicevox]' ``` This pulls in `httpx` (HTTP client) and `opuslib` (Opus encoder bindings). The encoder needs `libopus` on the system — `brew install opus` on macOS, `sudo apt-get install libopus0` on Debian/Ubuntu. #### Configure (optional) | Environment variable | Default | Notes | |---|---|---| | `STACKCHAN_VOICEVOX_URL` | `http://127.0.0.1:50021` | VOICEVOX engine URL. | | `STACKCHAN_VOICEVOX_DEFAULT_SPEAKER` | `3` | Default speaker ID (Zundamon normal). See the [VOICEVOX speaker list](https://github.com/VOICEVOX/voicevox_engine) for other options. | #### Try it From an MCP client: ``` say(text="こんにちは、わたしはスタックチャンです") ``` The gateway POSTs to VOICEVOX, decodes the returned WAV, resamples to 16 kHz mono, encodes Opus frames (60 ms each), and pushes them as WebSocket binary frames to the device — which decodes and plays them through its speaker. **No firmware changes are required**: the existing audio decoder pipeline already accepts these frames. The TTS framework is engine-agnostic, so additional engines plug in behind the same `say` API — see the Irodori engine below. `say` also accepts supported expression emoji in the text: happy (😊 😄 😀 😁 🙂 😆 🥰 😍 😋 🤗), sad (😢 😭 😞 😔 ☹️ 🙁 😿), surprised (😲 😮 😯 😱 🤯), embarrassed (😳 😅 🫣), and thinking (🤔 🧐 💭). The first mapped emoji changes the avatar face in the same MCP call before speech; unmapped emoji do not change the face. VOICEVOX and other engines without emoji-style support strip all emoji before synthesis. If stripping leaves empty text, the face change is attempted and speech is skipped. #### Alternative engine: Irodori Irodori is a second TTS engine that calls an external synthesis service returning MP3. It plugs into the same `say` pipeline as VOICEVOX (MP3 is decoded to 16 kHz mono PCM, then encoded to Opus), and it receives emoji embedded in the input text verbatim so they can act as voice-style cues. There is **no default endpoint** — the synthesis backend is a hosted service, and shipping a hard-coded URL would point every install at someone else's deployment. You must self-host a compatible synthesis API (for example, duplicate the reference Hugging Face Space, or run your own service that honours the same request/response contract) and point the gateway at it. Install the extra: ```bash pip install 'stackchan-mcp[tts-irodori]' ``` This pulls in `httpx`, `opuslib`, and `miniaudio` (a small self-contained MP3/audio decoder with prebuilt wheels, so no extra system library is needed beyond the `libopus` that `opuslib` already requires). Configure via environment variables (URL and key are read from the environment only — never commit them): | Environment variable | Default | Notes | |---|---|---| | `STACKCHAN_IRODORI_URL` | _(required)_ | Synthesis endpoint URL of your self-hosted service. Unset → the engine still lists but `say(voice="irodori")` returns a clear error. | | `STACKCHAN_IRODORI_KEY` | _(none)_ | Optional API key, forwarded as a query parameter. | | `STACKCHAN_IRODORI_SPEAKER` | `3` | Default speaker identifier. | | `STACKCHAN_IRODORI_STEPS` | `24` | Default diffusion step count (higher = slower, higher quality). | Select Irodori per call: ``` say(text="やったね😊", voice="irodori") ``` Or make it the default engine for every `say` call that omits `voice`: ```bash export STACKCHAN_TTS_ENGINE=irodori ``` VOICEVOX remains the default when `STACKCHAN_TTS_ENGINE` is unset, and an explicit `voice` argument always overrides the default. #### Alternative engine: ElevenLabs ElevenLabs is a cloud TTS engine that plugs into the same `say` pipeline (the MP3 reply is decoded to 16 kHz mono PCM, then encoded to Opus). Unlike VOICEVOX/Irodori there is nothing to self-host — you need an [ElevenLabs](https://elevenlabs.io/) account and API key, and each `say` call bills your ElevenLabs quota. Install the extra: ```bash pip install 'stackchan-mcp[tts-elevenlabs]' ``` Configure via environment variables (the key is read from the environment only — never commit it): | Environment variable | Default | Notes | |---|---|---| | `ELEVENLABS_API_KEY` | _(required)_ | Your ElevenLabs API key. `STACKCHAN_ELEVENLABS_KEY` is also accepted and wins when both are set. | | `STACKCHAN_ELEVEN_VOICE_<NAME>` | _(none)_ | Voice map: each variable names one speaker, e.g. `STACKCHAN_ELEVEN_VOICE_RACHEL=<voice id>` makes `speaker_name="rachel"` work. | | `STACKCHAN_ELEVEN_DEFAULT_SPEAKER` | _(none)_ | Speaker used when a call omits `speaker_name`. If unset and exactly one voice is mapped, that voice is the default. | | `STACKCHAN_ELEVEN_MODEL` | `eleven_v3` | ElevenLabs model identifier. | Select ElevenLabs per call — the speaker selector is the string `speaker_name` (not the numeric `speaker_id`, which is VOICEVOX-shaped); a raw ElevenLabs voice ID is also accepted and passed through verbatim: ``` say(text="Hello!", voice="elevenlabs", speaker_name="rachel") ``` Or make it the default engine: ```bash export STACKCHAN_TTS_ENGINE=elevenlabs ``` ### 5. Optional: STT setup (faster-whisper) To let the device hear, install one of the `[stt-*]` extras and pair it with a firmware that supports the inbound `listen` wire type (present from this release onward). The gateway sends a `listen.start` notification, the firmware opens the microphone, and the inbound Opus frames are decoded and transcribed locally — no audio leaves your machine when you use the default `faster-whisper` engine. #### Install the STT extra For local transcription with [faster-whisper](https://github.com/SYSTRAN/faster-whisper) (MIT-licensed, CTranslate2-based, runs on CPU): ```bash pip install 'stackchan-mcp[stt-faster-whisper]' ``` For the [OpenAI Whisper API](https://platform.openai.com/docs/guides/speech-to-text) (cloud, useful when local compute is constrained): ```bash pip install 'stackchan-mcp[stt-openai]' export OPENAI_API_KEY=sk-... ``` Both extras include the base `[stt]` extra which pulls in `opuslib` for decoding the inbound frames. The decoder needs the system `libopus` library — `brew install opus` on macOS, `sudo apt-get install libopus0` on Debian/Ubuntu (this is the same prerequisite as the `[tts]` extra). #### Configure (optional) | Environment variable | Default | Notes | |---|---|---| | `STACKCHAN_FASTER_WHISPER_MODEL` | `base` | Model identifier — `tiny` / `base` / `small` / `medium` / `large-v3`. Larger models are more accurate but slower and use more memory. | | `STACKCHAN_FASTER_WHISPER_DEVICE` | `cpu` | `cpu` / `cuda` / `auto`. | | `STACKCHAN_FASTER_WHISPER_COMPUTE_TYPE` | `int8` | `int8` / `float16` / `float32`. | | `STACKCHAN_OPENAI_WHISPER_MODEL` | `whisper-1` | OpenAI Whisper model identifier (only `whisper-1` is currently exposed by the API). | #### Try it From an MCP client: ``` listen(duration_ms=5000, language="ja") ``` The gateway sends `{"type":"listen","state":"start","mode":"manual"}` to the device, buffers the Opus frames the device streams up for the capture window, then sends `{"type":"listen","state":"stop"}` and hands the buffered audio to the registered STT engine. The first call to the `faster-whisper` engine downloads the chosen model (~140 MB for `base`) into the Hugging Face cache; subsequent calls reuse it. For visible capture feedback, pass `motion="face-only"` to show the `thinking` avatar during capture and restore `idle` at the end, or `motion="look-up"` to preserve yaw, tilt pitch to `look_up_pitch` (default 50°, valid 5..85°), show `thinking`, and hold that pose on success. The STT framework is engine-agnostic — additional engines (Vosk, whisper.cpp, cloud providers) can be added without changing the `listen` API. ### 6. Optional: enable event notifications Stack-chan physical events (today: touch tap / stroke; the structure allows additional subtypes to be appended later) can be delivered through three notification channels. All channels are disabled by default; opt in via `~/.config/stackchan-mcp/notify.yml`. More than one channel can be enabled at the same time; each event is then delivered over every enabled channel. Pick whichever match the host you are integrating with: - `channels` — Claude Code plugin path. Notifications are injected into the running session as `<channel ...>` blocks via Claude Code's experimental Channels capability. Use this when Stack-chan is wired into Claude Code as an installed plugin and you want events to reach the conversation in-band. - `jsonl` — Out-of-process file integration. Each event is appended as a single JSON line to a file you configure. Use this when an external host (anything other than Claude Code, or your own pipeline) needs to ingest events asynchronously by tailing a file. - `legacy_event` — Pre-plugin MCP notification. The gateway emits the self-defined `stackchan/event` MCP notification method, which existed before the Channels capability shipped. Use this for backward compatibility when the host wires the gateway via `~/.claude.json` `mcpServers` rather than the Claude Code plugin path. See `notify.example.yml` for the full annotated configuration reference. #### Channel: `channels` (Claude Code plugin path) Use when Stack-chan is loaded as a Claude Code plugin and you want events delivered as in-session channel blocks. This channel uses an experimental MCP capability that may evolve. Enable in `notify.yml`: ```yaml channels: enabled: true ``` Delivered as a `<channel ...>` block injected into the Claude Code session, for example: ``` <channel source="plugin:stackchanmcp:stackchanmcp" ...>head was tapped</channel> ``` Setup: 1. Plugin installation — install this repository as a Claude Code plugin from the `kisaragi-mochi-channels` marketplace: ```bash claude plugin install stackchanmcp@kisaragi-mochi-channels ``` For local development against your working copy, pass `--plugin-dir /path/to/stackchan-mcp` instead of installing from the marketplace; Claude Code starts the gateway under `${CLAUDE_PLUGIN_ROOT}/gateway` via the bundled `.mcp.json`. 2. Host environment setup — the Channels delivery path requires three host-side names to be aligned with the gateway's MCP server name (`stackchanmcp`, no hyphen): - The plugin's `.mcp.json` `mcpServers` key for this gateway must be `stackchanmcp`. If you previously wired the gateway under a different key, rename it. - Claude Code's `settings.local.json` `enabledMcpjsonServers` whitelist must include `stackchanmcp`. - The Channels allowlist requires a system-wide approval — Claude Code does not honor user-level (e.g. `~/.claude/settings.json`) settings for the Channels allowlist. On macOS, create or edit `/Library/Application Support/ClaudeCode/managed-settings.json` (requires `sudo`): ```json { "channelsEnabled": true, "allowedChannelPlugins": ["stackchanmcp@kisaragi-mochi-channels"] } ``` 3. Receiver side — launch Claude Code with the Channels flags: ```bash claude --channels plugin:stackchanmcp@kisaragi-mochi-channels \ --dangerously-load-development-channels plugin:stackchanmcp@kisaragi-mochi-channels ``` The `--channels` flag attaches the channel source to the gateway and injects `<channel source="plugin:stackchanmcp:stackchanmcp" ...>` blocks into the session. The `--dangerously-load-development-channels` flag is currently required alongside `--channels` because the plugin's Channels capability is experimental; the approved-allowlist-only path without this flag has been verified not to deliver notifications in current Claude Code versions. The flag is expected to become optional once the plugin's Channels capability stabilizes. Important — pre-plugin wiring does not receive Channels: if you previously wired this gateway via `~/.claude.json` `mcpServers` (the pre-plugin path), that wiring does not receive `<channel ...>` injections. Claude Code only attaches a channel source to plugin-loaded MCP servers. Before switching to the plugin path, stop any existing gateway process to release the ESP32 ownership lock; the plugin-loaded gateway will otherwise fail to acquire it. If you prefer to keep the `~/.claude.json` wiring, use the `legacy_event` or `jsonl` channel below — both work without plugin loading. Other hosts: - Hosts with a `claude/channel`-compatible receiver: open that receiver per the host's documentation. Compatibility with hosts other than Claude Code has not been verified in this repository. - Hosts without a Channels receiver: use the `jsonl` channel below. ##### Migration from the previous `stackchan-mcp` (hyphenated) form If you enabled Channels using the older `stackchan-mcp` server-name form, rename to the current `stackchanmcp` form (no hyphen) in all four places to keep the host MCP client and the gateway aligned: - Plugin / server name: change `stackchan-mcp` to `stackchanmcp` in your host's `.mcp.json` `mcpServers` key, in `settings.local.json` `enabledMcpjsonServers` whitelist, and in the `--channels` / `--dangerously-load-development-channels` flag arguments. - Channels flag form: change from `--channels server:stackchan-mcp` to `--channels plugin:stackchanmcp@kisaragi-mochi-channels`. The plugin form is the supported form now that the marketplace manifest is published. - system-wide allowlist: ensure `/Library/Application Support/ClaudeCode/managed-settings.json` has `allowedChannelPlugins` listing `stackchanmcp@kisaragi-mochi-channels` (not the old `stackchan-mcp` form). Without all four renames the host MCP client logs `Channel notifications skipped: server <name> not in --channels list for this session` and the notifications never reach the session. #### Channel: `jsonl` (out-of-process file integration) Use when an external host or your own pipeline needs to ingest events asynchronously by tailing a file. This is the simplest channel to wire into anything that is not Claude Code. Enable in `notify.yml`: ```yaml jsonl: enabled: true path: ~/.claude/stackchan-events.jsonl ``` Each event is appended as one JSON line to the configured path. The file is created if it does not exist, and existing entries are preserved. Each line carries: - `event_type` — top-level event type (currently `"touch"`). - `subtype` — subtype within the event type (currently `"tap"` or `"stroke"`). - `duration_ms` — firmware-reported duration of the event in milliseconds. - `ts` — firmware uptime in milliseconds (monotonic). - `ts_unix` — wall-clock timestamp when the gateway recorded the event. - `session_id` — gateway session identifier. - `action` — avatar action keyword for the event subtype (e.g. `head_pat`, `head_stroke`). The built-in default templates always populate this, and `messages:` overrides are also required to specify `action`, so this field is present for every supported subtype. The rendered wording (e.g. `head was tapped`) is what the `channels` channel delivers as the human-readable message; it is not stored in the JSONL record itself. A delivered tap-and-stroke pair looks like: ```json {"event_type": "touch", "subtype": "tap", "duration_ms": 0, "ts": 123456, "ts_unix": 1717862400.0, "session_id": "abc-123", "action": "head_pat"} {"event_type": "touch", "subtype": "stroke", "duration_ms": 720, "ts": 124000, "ts_unix": 1717862400.7, "session_id": "abc-123", "action": "head_stroke"} ``` The top-level `event_type` and `subtype` correspond to the rows in "Supported event subtypes" below. #### Channel: `legacy_event` (pre-plugin backward compatibility) Use when the gateway is wired into the host via `~/.claude.json` `mcpServers` (the pre-plugin path) and you want events without switching the host over to the plugin form. Enable in `notify.yml`: ```yaml legacy_event: enabled: true ``` The gateway emits the self-defined `stackchan/event` MCP notification method. The notification params carry the same fields as the JSONL record above, except that `ts_unix` is not included (it is added only by the JSONL writer). The host is responsible for surfacing the notification — Claude Code's pre-plugin path historically displayed the rendered template inline; other hosts may handle the notification differently. #### Supported event subtypes The currently supported physical events are listed below. The structure is intentionally extensible: additional `touch` subtypes or new top-level types (e.g. `motion`, `voice`) can be appended in future releases without rewriting this section. | Type | Subtype | Default `action` | Default `template` | | --- | --- | --- | --- | | `touch` | `tap` | `head_pat` | `head was tapped` | | `touch` | `stroke` | `head_stroke` | `head was stroked for {duration_ms}ms` | The built-in defaults are phrased experientially — describing what the device felt rather than naming a mechanical event — so the consuming agent reads them as first-person narration. The `{duration_ms}` placeholder is substituted from the event payload; unknown placeholders are preserved verbatim. ##### Overriding the wording Add a `messages:` block to `~/.config/stackchan-mcp/notify.yml` to override the per-subtype `action` and `template`. Only the subtypes you list are overridden; everything else keeps the defaults above. ```yaml # ~/.config/stackchan-mcp/notify.yml messages: touch: tap: action: head_pat template: "got a head pat" stroke: action: head_stroke template: "head being stroked for {duration_ms}ms" ``` Both `action` and `template` are required for each overridden subtype. The `action` value is forwarded in the event metadata, so keep it stable if a downstream consumer keys off it. See `notify.example.yml` for the full annotated reference. ## About the avatar images `firmware/main/boards/stackchan/avatar_images.cc` is a **pure black RGB565 placeholder**. The firmware builds and runs, but the screen will display nothing. For a personal avatar, keep PNG sources outside git and generate ignored local override files: ```bash cd firmware python scripts/avatar_convert/convert_avatars.py ``` By default, the converter reads PNGs from `~/.stackchan/avatar/` and writes: - `firmware/main/boards/stackchan/avatar_images.local.cc` - `firmware/main/boards/stackchan/avatar_images.local.h` These local files are ignored by git. When `avatar_images.local.cc` exists, the StackChan firmware build uses it instead of the tracked black placeholder, so `git pull` will not overwrite your personal avatar. The tracked `avatar_images.cc` / `avatar_images.h` files are public placeholder files. Maintainers who intentionally need to refresh those tracked files can pass `--tracked`, but personal avatars should use the default local output path. If you add a local avatar after you have already built the firmware once, remove `firmware/build/` and rebuild so CMake can pick up the new local override. Symbol list (see `avatar_images.h`): - Expressions (6): `avatar_idle`, `avatar_happy`, `avatar_thinking`, `avatar_sad`, `avatar_surprised`, `avatar_embarrassed` - Eyes (3): `avatar_eyes_open`, `avatar_eyes_half`, `avatar_eyes_closed` - Mouth (5): `avatar_mouth_closed`, `avatar_mouth_half`, `avatar_mouth_open`, `avatar_mouth_e`, `avatar_mouth_u` Expected PNG filenames under `~/.stackchan/avatar/`: - Expressions: `idle.png`, `happy.png`, `thinking.png`, `sad.png`, `surprised.png`, `embarrassed.png` - Eyes: `eyes_open.png`, `eyes_half.png`, `eyes_closed.png` - Mouth: `mouth_closed.png`, `mouth_half.png`, `mouth_open.png`, `mouth_e.png`, `mouth_u.png` Do not commit personal PNGs, generated local avatar files, photos, or other user-specific assets. ## Hardware safety notes > ⚠️ **Y-axis (pitch) safe range — two-tier guard** The pitch axis is guarded by two complementary tiers, both encoded in firmware and surfaced through the `set_head_angles` MCP tool description: | Tier | Range | Enforcement | Rationale | |---|---|---|---| | **Tier 1 — Hard clamp** | `0..+88°` | Silent clamp + `ESP_LOGW` | Prevents mechanical damage. Lower bound `0°` leaves ~1° margin above the validated mechanical end-stop on M5Stack CoreS3 + SCS0009 hardware (PR #81). Upper bound `88°` sits ~1° inside the audible sub-stall boundary observed at `pitch=89°` during the Issue #98 on-device sweep ("ji-ji-" gear strain sound). | | **Tier 2 — Recommended operating range** | `5..+85°` | Accept + `ESP_LOGI` (soft signal) | The M5Stack-documented sweet spot for long-term servo reliability. Single requests outside this range are not hardware-damaging, but sustained operation outside `5..85°` may stress the servo over time. | M5Stack's official documentation states: > The movement angle of the StackChan Y-axis servo (vertical direction) is recommended to be controlled within 5 ~ 85°. Operating at extreme angles may cause **servo stall and permanent damage**. > — https://docs.m5stack.com/en/StackChan ("Motion Angle Notice") The `set_head_angles` MCP tool declares pitch with a fully permissive schema range — the entire `int` value range, `std::numeric_limits<int>::min()` to `std::numeric_limits<int>::max()`, corner values included; the firmware-side handler is the authoritative Tier 1 enforcement layer. Any narrower schema range would cause `McpServer::Property` to reject sufficiently-extreme out-of-range requests (e.g. `pitch=200` or `pitch=INT_MIN`) before the handler could clamp / log them, leaving the documented Tier 1 behavior unreachable for those callers — see #98. Requests below `0°` are silently raised to `0°` (with `ESP_LOGW`), requests above `88°` are silently lowered to `88°` (with `ESP_LOGW`), and requests inside `[0, 88]` but outside `[5, 85]` are accepted with an `ESP_LOGI` soft signal. Older callers that targeted `-30..+30°` continue to work without modification (the negative half clamps to `0°`). Conversely, the **gateway-side `move_head` MCP tool** — the one LLM-driven clients see in the tool list above — declares a restrictive `pitch=5..85` / `yaw=-90..90` schema and re-enforces the same bounds in the gateway `call_tool` handler as belt-and-suspenders. This rejects out-of-recommended requests at the MCP boundary so an agent cannot accidentally trigger the bus-hang risk tracked in [#100](https://github.com/kisaragi-mochi/stackchan-mcp/issues/100) from a pose-reset call like `move_head(yaw=0, pitch=0)`. Callers that need explicit access to the firmware Tier 1 hard clamp (for diagnostics, recovery sequences, or other expert use cases) should bypass `move_head` and call the firmware-side `set_head_angles` device tool directly — see [#109](https://github.com/kisaragi-mochi/stackchan-mcp/issues/109). The X-axis (yaw, `-90..+90°`) is not subject to a comparable hardware restriction — M5Stack's documentation explicitly notes "No angle restriction is required for the X-axis" — and remains usable across its full declared range. See [#80](https://github.com/kisaragi-mochi/stackchan-mcp/issues/80) for the lower-bound engineering background and [#98](https://github.com/kisaragi-mochi/stackchan-mcp/issues/98) for the two-tier upper-bound widening (firmware hard clamp `30°` → `88°`, with the M5Stack-recommended `5..85°` operating range surfaced as a soft-signal tier). ## Known issues - The servo bus may hang on large-angle abrupt reversals (e.g. +60° → -60°). A fix is in progress via Motion::update_task interpolation. - The touch sensor (Si12T) occasionally drops tap events. Sensitivity register tuning has room to improve here. ## License The canonical firmware build path (`firmware/scripts/release.py stackchan`) produces an **MIT-licensed end-to-end** binary. The GPL-3.0 SCServo_lib sources remain in the tree as an opt-in fallback during the migration tracked in [#79](https://github.com/kisaragi-mochi/stackchan-mcp/issues/79). | Scope | License | |---|---| | `gateway/`, top-level, all of `firmware/` in the **canonical build** (`release.py stackchan` appends `CONFIG_STACKCHAN_SERVO_FEETECH=y` and links the MIT [`feetech_scs_esp_idf`](https://github.com/necobit/feetech_scs_esp_idf) driver vendored under `firmware/components/feetech_scs/`) | **MIT License** (see `LICENSE`) | | **SCServo_lib-derived files** under `firmware/main/boards/stackchan/` (SCS.{cc,h}, SCSCL.{cc,h}, SCSerial.{cc,h}, INST.h, SCServo.h) — only linked when `CONFIG_STACKCHAN_SERVO_SCSCL=y` is selected (e.g. via `sdkconfig.defaults.local`) | **GNU GPL-3.0** (see `firmware/main/boards/stackchan/SCServo_lib_LICENSE.txt`) | The `gateway/` runs as an independent Python process and only talks to the ESP32 over the network (WebSocket), so it stays usable and derivable under the **MIT License** regardless of which servo driver the firmware-side build selects. The gateway's `win_amd64` PyPI wheel additionally bundles `opus.dll` built from upstream Opus source by the publish workflow. That native binary ships under the **BSD 3-clause license + Xiph extension**; the notice is shipped in every distribution form as `gateway/LICENSE-THIRD-PARTY`. Non-Windows wheels and the sdist do not contain the binary — they rely on the system `libopus`. See `gateway/stackchan_mcp/_libs/SOURCES.md` for the per-release SHA256 and build provenance. > **Note for direct `idf.py` users with a pre-existing `firmware/sdkconfig`:** > ESP-IDF persists Kconfig choices into `firmware/sdkconfig`, and a > change to the Kconfig `default` does not retroactively rewrite that > file. The canonical build path enforces the MIT driver at the > `release.py` layer (via `sdkconfig_append`), so rebuilding via > `release.py stackchan` reliably produces the MIT default binary. > If you bypass `release.py` and call `idf.py` directly on a workspace > that previously selected SCSCL, you may need to run `idf.py menuconfig` > (or delete `firmware/sdkconfig`) to pick up the new default. > **GPL-3.0 fallback build (opt-in):** > The original SCServo_lib sources are still shipped in the repository > as a safety net while the migration tracked in #79 is in its > observation period. To build against them, add > `CONFIG_STACKCHAN_SERVO_SCSCL=y` to `firmware/sdkconfig.defaults.local`; > `release.py` merges this in **after** `sdkconfig_append`, so it > overrides the FEETECH default. In that configuration the firmware > binary statically links the GPL-3.0 sources and is therefore > **effectively distributed under GPL-3.0**. Once the observation > period closes without regressions the GPL files are scheduled for > removal (Phase B of #79). ### upstream `firmware/` is taken in via git subtree from [78/xiaozhi-esp32](https://github.com/78/xiaozhi-esp32) (MIT) — specifically the [kisaragi-mochi/xiaozhi-esp32](https://github.com/kisaragi-mochi/xiaozhi-esp32) fork. See [`docs/firmware-sync.md`](docs/firmware-sync.md) for the upstream sync playbook. The SCServo_lib sources under `firmware/main/boards/stackchan/` (`SCS.{cc,h}`, `SCSCL.{cc,h}`, `SCSerial.{cc,h}`, `INST.h`, `SCServo.h`) originate from [Feetech](https://www.feetechrc.com/)'s SCServo SDK and entered this repository through the same `kisaragi-mochi/xiaozhi-esp32` fork's `main/boards/stackchan/` directory at the firmware subtree merge. They remain GPL-3.0 (see `firmware/main/boards/stackchan/SCServo_lib_LICENSE.txt`). ## Related projects - [M5Stack official StackChan documentation](https://docs.m5stack.com/ja/StackChan) — official documentation for the target hardware (factory firmware / wiring / API reference / etc.) - [xiaozhi-esp32](https://github.com/78/xiaozhi-esp32) — the base ESP32 LLM client firmware - [stack-chan](https://github.com/stack-chan/stack-chan) — the original StackChan project (Shinya Ishikawa) - [stackchan-arduino](https://github.com/stack-chan/stackchan-arduino) — Arduino-side servo control library (Takao Akaki / mongonta0716); this firmware references the SCS0009 positioning timing established there - [m5stack-avatar](https://github.com/stack-chan/m5stack-avatar) — Avatar rendering library widely used by StackChan firmware - [Model Context Protocol](https://modelcontextprotocol.io) — the MCP protocol specification ## Contributing Issues and PRs are welcome. We aim to provide something the StackChan community can use as-is. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the development flow. ## Trademarks "StackChan" and "スタックチャン" are registered trademarks of Shinya Ishikawa, the originator of the stack-chan project. This repository uses these names in reference to the M5Stack official StackChan kit it targets.