按下 → 說話 → Muse 回應。
先追求可靠與低延遲，不先搬回伺服馬達、表情動畫或完整舊功能。能穩定完成一輪對話，就是第一版成功。
M5Stack CoreS3 · 桌上型端點
把魚丸
變成桌上的 Muse。
保留 StackChan 的角色感，用目前官方 SDK 已收錄的 CoreS3 board profile：按下、說話、取得回應。先跑通可靠的語音 loop，再決定要不要讓頭重新動起來。
PUSH → TALK → REPLY
2.4 GHz
WI-FI ONLY
WI-FI ONLY
01 /
What are we building?
不是重做一台機器人。
是換掉它的大腦連線。
StackChan 的 CoreS3 已經有螢幕、麥克風、喇叭、按鍵與 Wi‑Fi。Muse Gadgets 把它變成一個專用 endpoint：硬體收音、顯示狀態；Muse 負責理解、推理與回答。
1 loop
一次只消掉一個風險：先備份，再編譯；先離線燒錄，再進配對。
02 /
Bench checklist
把這些放上工作桌。
硬體沿用現成 StackChan；開發端建議走 Windows + WSL2。USB 線一定要能傳資料，不只是充電。
StackChan／M5Stack CoreS3
ESP32‑S3、320×240 觸控螢幕、雙麥克風與喇叭。兩台功能相同時，選較容易拆下與接 USB 的那一台作 dev unit。
USB‑C 資料線＋穩定供電
燒錄失敗的第一嫌疑通常不是 code，而是線材、USB passthrough 或供電。先排除這三件事。
WSL2 + usbipd
讓 Windows 把 CoreS3 的 USB serial 裝置交給 Linux。進 WSL 後應看得到 /dev/ttyACM* 或 /dev/ttyUSB*。
ESP‑IDF v6.0.1
這是官方專案指定版本。Arduino IDE 不能直接編譯這個 ESP‑IDF / CMake 專案。
Muse App + 2.4 GHz Wi‑Fi
手機用來配對；裝置接家中 2.4 GHz 網路。還需要 Muse Gadgets SDK token。
03 /
Signal path
開發、配對、對話。
三條路徑不要混在一起。
StackChan / CoreS3
- 按鍵／觸控
- 麥克風輸入
- 畫面與喇叭輸出
BLE 配對
Wi‑Fi 執行
Wi‑Fi 執行
Muse App
- Developer mode
- 找到 MuseGadget
- 帳號與網路設定
ACCOUNT
SESSION
SESSION
個人助理
- 語音轉文字
- 理解與回應
- 文字／圖片回到裝置
電腦只參與 build 與 flash；裝置正常運作後，對話路徑不需要 WSL2。第一版也不經過舊 StackChan 的 PC WebSocket server。
04 /
From backup to hello
七步，把端點跑起來。
本頁固定在官方 repository 的 commit 693cde9：它已包含 CoreS3 的 Espressif BSP、螢幕／觸控、AW88298 擴大器、ES7210 麥克風與 AXP2101 電源控制。所有命令都在 WSL2 執行，只需換掉實際 serial port。
先備份現在的 StackChan 韌體
不要用「反正 GitHub 有 code」代替完整 flash image。先讀取 flash ID，確認容量，再做一份可回復的二進位備份。
# 先找 port
ls /dev/ttyACM* /dev/ttyUSB* 2>/dev/null
# 讀取晶片與 flash 資訊
python -m esptool --chip esp32s3 --port /dev/ttyACM0 flash-id
# CoreS3 常見為 16 MB；仍以 flash-id 實測為準
python -m esptool --chip esp32s3 --port /dev/ttyACM0 \
read-flash 0x0 0x1000000 stackchan-original-16mb.bin
sha256sum stackchan-original-16mb.bin
ls -lh stackchan-original-16mb.binGate：備份檔大小應與偵測到的 flash 容量一致，而且 SHA‑256 已記下；否則先不要往下燒錄。
取得 Muse Gadgets SDK token
登入 Muse Gadgets 的 token 頁面建立 token。它會寫進 firmware；不要貼進 Git repo 或公開截圖。若頁面或地區資格未開放，先停在這一步。
官方說明：每台 gadget 配對都需要 token；同一個 token 可用的裝置數量有限。若外洩，就在原頁撤銷並重建 firmware。
下載 SDK，固定 ESP‑IDF v6.0.1
官方是純 ESP‑IDF 專案。先安裝 Linux prerequisites，再 clone SDK 與指定版本的 ESP‑IDF。
git clone https://github.com/facebookincubator/muse-gadget-sdk
cd muse-gadget-sdk
git checkout 693cde9a884ad1edc87251b9f8944815f8de4809
cd esp32
git clone -b v6.0.1 --recursive \
https://github.com/espressif/esp-idf.git ~/esp/esp-idf-v6
~/esp/esp-idf-v6/install.sh esp32s3
. ~/esp/esp-idf-v6/export.sh每次開新的 WSL terminal，都要再執行
. ~/esp/esp-idf-v6/export.sh。驗證官方 CoreS3 profile，再寫入設定
這個固定 revision 內有 sdkconfig.muse-m5stack-cores3 與 board_m5stack_cores3.c，由 Espressif BSP 帶起 ILI9342C 螢幕、FT6336U 觸控、AW88298 擴大器與 ES7210 麥克風。先讓 helper 產生專屬 build directory，再用 menuconfig 寫入 token。
# 三項驗證都應通過
test -f devices/sdkconfig.muse-m5stack-cores3
test -f components/muse/boards/board_m5stack_cores3.c
grep -n 'CoreS3' AGENTS.md
# 第一次 build 會建立 build-muse-m5stack-cores3/sdkconfig
tools/muse/board.sh build cores3
# 填入 ESP32 Device SDK → Muse Gadgets SDK token
idf.py -B build-muse-m5stack-cores3 menuconfig不要跳過三檔驗證。若你沒有固定在上面的 commit，SDK 可能已變更；此時以 checkout 內的
AGENTS.md 為準，不要拿其他 ESP32‑S3 profile 代替 CoreS3。編譯，先驗證輸出再碰板子
build 成功不代表硬體一定支援，但它至少證明 toolchain、dependencies、token 與 target 組態可以一起產生 firmware。
. ~/esp/esp-idf-v6/export.sh
tools/muse/board.sh build cores3
# 檢查固定的 CoreS3 build directory 與燒錄參數
ls -lh build-muse-m5stack-cores3
cat build-muse-m5stack-cores3/flash_args燒錄並看 serial log
確認 USB port 沒被 Windows 端其他 serial tool 佔用。燒錄後立刻 monitor，才能分辨是 boot、Wi‑Fi、audio 還是配對階段失敗。
# 把 PORT 換成實際裝置；先燒錄，再開 monitor
PORT=/dev/ttyACM0
tools/muse/board.sh flash cores3 "$PORT"
idf.py -B build-muse-m5stack-cores3 -p "$PORT" monitor
# monitor 內按 Ctrl + ] 離開CoreS3 沒有一般 BOOT 鍵。若 esptool 連不上，長按底部 RST 約 3 秒，直到綠燈亮起進入 bootloader，再重試。不要一失敗就
erase-flash；那會清掉裝置狀態。用 Muse App 配對，然後開口說話
在 Muse App 打開 Settings → Devices → Developer mode，點右上角 ＋，選擇 MuseGadget-XXXXXX。裝置要求確認時，按一下左側 PWR；連線後 PWR 就是 push‑to‑talk，設定則從 Muse 畫面向左滑開啟。按住說話、放開送出，等待 Muse 回應。
橘色呼吸等待設定
藍色呼吸按鍵確認配對
藍色恆亮連 Wi‑Fi / Muse
綠色已連線
黃色閃爍重新連線
紅色閃爍查 serial log
第一次驗收句：「用一句話告訴我現在能做什麼。」刻意要求一句話，先量測 round‑trip 是否穩定，再挑戰長回答。
05 /
Known sharp edges
三個邊界，先講清楚。
第一版的目標是語音端點，不是完整復刻既有 StackChan 韌體。這些不是「日後再修的小 bug」，而是目前的設計邊界。
01
頭暫時不會動
Muse Gadget firmware 不會自動驅動 StackChan 的 SCS0009 serial servos。燒入後可對話，但頭部動作要另外做 servo porting 與安全角度限制。
02
只接 2.4 GHz Wi‑Fi
CoreS3 的 ESP32‑S3 不支援 5 GHz。請讓手機與 gadget 能使用同一個可信任的 2.4 GHz 網路；企業 Wi‑Fi 的隔離策略也可能擋住設定。
03
台灣資格要現場驗證
SDK token 頁面、Muse App 與 Developer mode 可能受帳號／地區 rollout 影響。能 compile 不等於能配對；把「拿到 token」和「App 看得到 Developer mode」當作兩個獨立 gate。
06 /
Troubleshooting
卡住先看這裡。
依層次排查：USB → toolchain → target → boot → pairing → Wi‑Fi → voice。
WSL2 看不到 CoreS3 的 serial port？
先在 Windows 確認裝置管理員有看到 USB 裝置，再用 usbipd 將它 attach 給目前的 WSL distribution。關掉可能佔用 port 的 Arduino Serial Monitor、PlatformIO 或其他 terminal，回 WSL 檢查 /dev/ttyACM* 與 /dev/ttyUSB*。
可以直接用 Arduino IDE 編譯嗎？
不行。Muse Gadgets ESP32 firmware 是 ESP‑IDF / CMake 專案，而且官方指定 ESP‑IDF v6.0.1。原本的 StackChan Arduino 環境可留著做舊韌體維護，但不是這次 build path。
repository 裡找不到 CoreS3 target 怎麼辦？
先確認目前是本頁固定的 commit 693cde9。該 revision 應存在 devices/sdkconfig.muse-m5stack-cores3 與 CoreS3 BSP board file；缺一就停止燒錄並重新檢查 checkout。不要拿其他 ESP32‑S3 target 代替。
配對清單看不到 MuseGadget？
確認裝置已進入等待設定狀態、Muse App 的 Developer mode 已開啟、手機藍牙與權限可用。仍看不到時，保留 serial log；它能判斷是 firmware 沒進 pairing mode，還是 App／帳號端未開放。
連上了，但 Muse 沒聽到我說話？
先測 push‑to‑talk 狀態是否有切換，再看 serial log 是否有 audio capture。CoreS3 的 microphone codec 設定必須與 board profile 相符；音訊錯誤不要先怪 Wi‑Fi。
怎麼回到原本的 StackChan？
用第一步保存的完整 flash image 寫回相同的 0x0 起始位址，並確認檔案容量與晶片一致。回復前先保留目前 gadget 的 serial log 與 build commit，方便之後重現。
配對安全上要注意什麼？
在可信任網路上設定，配對時用裝置實體按鍵確認。官方指出 community devices 沒有 manufacturer verification；建議支援的板子開啟 NVS encryption，避免 Wi‑Fi credential 與 device token 被直接從 flash 讀出。
THE NEXT RIGHT MOVE
先備份。
再讓它開口。
你不是在下注一個大改造；你是在建立一條可回復、可觀察、可逐步擴充的硬體路徑。