刷機指南

下文括號裡的“橙 1”等指主機板佈局圖中按鍵與開關的編號。

整機有三處可以刷寫的韌體：

韌體	晶片	檔案
Linux 系統	樹莓派計算模組 CM4 / CM5（帶 eMMC）	Raspberry Pi OS 映像
協處理器韌體	ESP32-S3	`typixdeck_esp32s3_full_YYYYMMDD.bin`（單檔案完整映像）
鍵盤韌體	STM32F042（QMK）	`keebdeck_6r11c_default_YYYYMMDD.bin`

推薦流程：先把 Linux 裝好；之後 ESP32 和鍵盤都在這臺機器自己的 Linux 裡用命令列刷。 不需要電腦，不需要撥任何開關，也不需要用側面的除錯口。

0. 按鍵與開關位置

名稱（圖中編號）	外形 / 絲印	作用
電源開關（橙 1）	頂邊右側撥動開關，絲印 ON / OFF	整機總電源，含 ESP32 和鍵盤 MCU 的 3.3V
ESP32 BOOT（橙 2）	頂邊側貼的矩形小鍵	按住時復位 = ESP32 進下載模式；平時按一下 = 螢幕在 Pi / ESP 之間切換
ESP32 復位（橙 3）	圓形按鍵，絲印 S3_EN	ESP32 復位
Pi BOOT（橙 4）	圓形按鍵，絲印 Boot，緊挨 S3_EN	按住上電 = 計算模組 eMMC 進 USB 刷機模式
USB 模式開關（灰 3）	頂邊左側撥動開關，絲印 Host / Device	平時保持 Host；只有刷 eMMC 時撥到 Device

Lite 版（無 eMMC）不用這一節：TF 卡在電腦上用 Raspberry Pi Imager 寫好插上即可。

帶 eMMC 的模組，eMMC 要先通過 rpiboot 掛成 U 盤再寫入：

電腦上執行 rpiboot，模組會以 U 盤形式出現：

# macOS / Linux，使用 raspberrypi/usbboot 原始碼編譯的版本（macOS 不要用 brew 版）
sudo ./rpiboot -d mass-storage-gadget64

CM4 與 CM5 命令相同。

注意：CM5 刷 eMMC 時不要插 TF 卡；rpiboot 在 macOS 上必須前臺執行，放後臺會靜默退出。

韌體是單個完整映像，從地址 0 一次寫入即可。

韌體正常執行時：發一條魔法串，ESP32 自動重啟進下載模式，不用按鍵：
Terminal window
```
echo "EGGFLY_REBOOT_TO_BOOT_MODE" | sudo tee /dev/ttyACM0
```
按鍵方式：按住 ESP32 BOOT（橙 2）不放，按一下 S3_EN（橙 3），先松復位鍵再松 BOOT。
冷啟動方式：整機 OFF，按住 ESP32 BOOT 不放，電源撥 ON，保持 2 秒再鬆開。 ESP32 會一直停在下載模式，等 Linux 啟動完成後再刷。

確認：

lsusb | grep 303a

看到 303a:1001 或 303a:0009 即已進入下載模式。

sudo apt install esptool
esptool --no-stub --chip esp32s3 -p /dev/ttyACM0 -b 460800 \
  write_flash 0x0 typixdeck_esp32s3_full_YYYYMMDD.bin

樹莓派系統自帶的 esptool 版本較老，--no-stub 必須加。

再次 lsusb，看到 303a:80c3，螢幕出現開機動畫即成功。

鍵盤正常工作時：同時按 Fn + ◇（菱形鍵） 或 Sym + ◇，立即進入 DFU。
全新空片：上電自動進 DFU。
韌體壞、按鍵無反應：整機 OFF，用鑷子把鍵盤面左下角 R58 空焊盤靠內的一端短接到 3.3V，同時電源撥 ON，保持 1 秒再撤掉（BOOT0 拉高進入 ROM DFU）。

確認：

lsusb | grep 0483:df11

sudo apt install dfu-util
sudo dfu-util -a 0 -d 0483:df11 -s 0x08000000:leave -D keebdeck_6r11c_default_YYYYMMDD.bin

:leave 表示刷完自動跳轉執行，不用斷電。刷完鍵盤立即恢復輸入，lsusb 看到 c182:6b11 KeebDeck 6R11C。

現象	處理
`lsusb` 看不到 303a 裝置	ESP32 韌體死迴圈時 USB 會反覆列舉失敗，Hub 會放棄。改用“冷啟動方式”進下載模式
esptool 報錯找不到 stub	加 `--no-stub`
刷完 ESP32 螢幕沒反應	按一下 S3_EN，確認 `lsusb` 已變成 `303a:80c3`
鍵盤刷完沒有特殊鍵功能	刷成了觸點檢測版（diag），刷回 default 版
rpiboot 一直等不到裝置	確認 USB 模式開關在 Device、用的是底部 USB-C 口、按住 Pi BOOT 時才上電
想保留 ESP32 裡的語言等設定	完整映像會清空設定區；只想升級程式時改刷 `write_flash 0x10000 app.bin`