刷机指南

下文括号里的“橙 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`