keychron_qmk_firmware/docs/zh-cn/flashing.md

# 刷写指引及Bootloader资料

<!---
  original document: 0.15.12:docs/flashing.md
  git diff 0.15.12 HEAD -- docs/flashing.md | cat
-->

用于键盘的bootloader有很多种，几乎每一种都在使用私有的刷写协议及工具。幸运的是，形如[QMK工具箱](https://github.com/qmk/qmk_toolbox/releases)这样的工程目标就是尽量支持这些工具，本文会探讨各种bootloader的差异，以及可用的刷写方案。

针对基于AVR的键盘，QMK会自动检查所要刷写的 `.hex` 文件大小是否与在 `rules.mk` 中设置的 `BOOTLOADER` 值所匹配，同时会输出字节大小信息（及最大限制）。

同时也可以使用CLI工具刷写键盘，执行：
```
$ qmk flash -kb <keyboard> -km <keymap>
```
更多信息参见文档[`qmk flash`](zh-cn/cli_commands.md#qmk-flash)。

## Atmel DFU

Atmel系列的DFU bootloader默认配备在所有USB AVR系列上（16/32U4RC除外），广泛用于一些PCB上具备私有集成电路模块（IC）的键盘上（老款OLKB、Clueboards等）。有些使用的是LUFA实现的DFU bootloader，或是QMK的分支版本（新款OLKB），后者对硬件功能进行了扩充加强。

为保证对DFU bootloader的兼容性，请确保在 `rules.mk` 中存在如下部分内容（可选的值还有 `lufa-dfu` 或 `qmk-dfu`）：

```make
# 选择Bootloader
BOOTLOADER = atmel-dfu
```

兼容的刷写工具：

* [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases)（推荐的图形化工具）
* [dfu-programmer](https://github.com/dfu-programmer/dfu-programmer) / QMK中将构建目标设为 `:dfu`（推荐的命令行工具）

刷写过程：

1. 使用如下任一方式进入bootloader模式：
    * 点击 `QK_BOOT` 键码
    * 如果PCB上有 `RESET` 键，点击之
    * 快速短接一下RST到GND
2. 等待操作系统识别到设备
3. 清空flash存储数据（如果使用QMK工具箱或CLI的 `make`会自动进行）
4. 将.hex文件刷写进去
5. 重置设备进入应用模式（如上，会自动进行）

### QMK DFU

QMK维护了[一个LUFA DFU bootloader的分支版本](https://github.com/qmk/lufa/tree/master/Bootloaders/DFU)，其可以进行一次矩阵扫描来退出bootloader进入应用模式，同时会让LED闪烁或蜂鸣器响一声。若要启用该功能，将以下定义添加到 `config.h`：

```c
#define QMK_ESC_OUTPUT F1  // COL pin if COL2ROW
#define QMK_ESC_INPUT  D5  // ROW pin if COL2ROW
// 可选:
//#define QMK_LED E6
//#define QMK_SPEAKER C6
```
目前来讲不推荐将 `QMK_ESC` 键设置成与[Bootmagic](zh-cn/feature_bootmagic.md)同一个键，否则按下该键时只会让MCU在bootloader模式上反复进出。

制造商及型号字符串自动从 `config.h` 中获取，并会在型号后追加 " Bootloader"。

要生成该bootloader，需指定 `bootloader` 构建目标，即 `make planck/rev4:default:bootloader`。要生成可部署到正式产品的.hex文件（同时包含QMK及bootloader），使用 `production` 构建目标，即 `make planck/rev4:default:production`。

### `make` 构建目标

* `:dfu`: 每5秒检测一次直到发现可用的DFU设备，然后进行固件刷写。
* `:dfu-split-left` 和 `:dfu-split-right`: 同 `:dfu` 一样会刷写固件，但额外地会设置手性设置到EEPROM中，对于基于Elite-C的分体式键盘这是理想的方法。

## Caterina

Arduino及其仿制板使用[Caterina bootloader](https://github.com/arduino/ArduinoCore-avr/tree/master/bootloaders/caterina)或某种变体（使用Pro Micro或其仿制芯片、Pololu A-Star等构建的所有键盘），并基于虚拟串口使用AVR109协议进行通信。

为确保对Caterina bootloader的兼容性，请添加如下代码块至 `rules.mk`：

```make
# 选择Bootloader
BOOTLOADER = caterina
```

兼容的刷写工具：

* [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases) （推荐的图形化工具）
* [avrdude](https://www.nongnu.org/avrdude/) QMK中须基于 `avr109` 编程器 / `:avrdude` 构建目标 （推荐的命令行工具）
* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS)

刷写过程：

1. 使用如下任一方式进入bootloader模式（进入该模式后只有7秒时间可以刷写；一些型号需要你在750ms内重置两次）：
    * 点击 `QK_BOOT` 键码
    * 如果PCB上有 `RESET` 键，点击之
    * 快速短接一下RST到GND
2. 等待操作系统识别到设备
3. 将.hex文件刷写进去
4. 等待设备自动重置

### `make` 构建目标

* `:avrdude`: 每5秒检测一次直到发现可用的Caterina设备（通过检测新COM端口），然后进行固件刷写。
* `:avrdude-loop`: 同 `:avrdude` 一样刷写固件，但会在一个设备刷写完后再次尝试刷写。主要用于批量刷写设备。按 Ctrl+C 以终止循环检测。
* `:avrdude-split-left` 和 `:avrdude-split-right`: 同 `:avrdude` 一样会刷写固件，但额外地会设置手性设置到EEPROM中，对于基于Pro Micro的分体式键盘这是理想的方法。

## HalfKay

HalfKay是一款由PJRC开发的超精简的bootloader，且呈现为HID设备（因此不需要额外的驱动），在所有的Teensys，即"the 2.0"，上已经预刷写过。该bootloader目前是闭源的，因此一旦覆写（即通过ISP刷入其它bootloader）掉，就无法复原了。

为确保对Halfkay bootloader的兼容性，请添加如下代码块至 `rules.mk`：

```make
# 选择Bootloader
BOOTLOADER = halfkay
```

兼容的刷写工具：

* [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases)（推荐的图形化工具）
* [Teensy Loader Command Line](https://www.pjrc.com/teensy/loader_cli.html) / QMK中将构建目标设为 `:teensy`（推荐的命令行工具）
* [Teensy Loader](https://www.pjrc.com/teensy/loader.html)

刷写过程：

1. 使用如下任一方式进入bootloader模式（进入该模式后只有7秒时间可以刷写）：
    * 点击 `QK_BOOT` 键码
    * 如果Teensy上或PCB上有 `RESET` 键，点击之
    * 快速短接一下RST到GND
2. 等待操作系统识别到设备
3. 将.hex文件刷写进去
4. 重置设备进入应用模式（可能会自动进行）

## USBasploader

USBasploader是一款来源于[Objective Development](https://www.obdev.at/products/vusb/usbasploader.html)的bootloader。它通过模拟出一个USBasp ISP编程器来运行V-USB以用于一些形如ATmega328P这样的“非USB AVR芯片”。

为确保对USBasploader bootloader的兼容性，请添加如下代码块至 `rules.mk`：

```make
# 选择Bootloader
BOOTLOADER = usbasploader
```

兼容的刷写工具：

* [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases)（推荐的图形化工具）
* [avrdude](https://www.nongnu.org/avrdude/) QMK中须基于 `usbasp` 编程器 / `:usbasp` 构建目标（推荐的命令行工具）
* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS)

刷写过程：

1. 使用如下任一方式进入bootloader模式：
    * 点击 `QK_BOOT` 键码
    * 在按住 `BOOT` 按钮时，快速点击一下PCB上的 `RESET`
2. 等待操作系统识别到设备
3. 将.hex文件刷写进去
4. 点击PCB上的 `RESET` 按钮或将RST短接至GND一下。

## BootloadHID

BootloadHID是一款用于AVR微控制器的bootloader，其呈现为HID输入设备，和HalkKay很像，因此在Windows下也无需安装驱动。

为确保对bootloadHID bootloader的兼容性，请添加如下代码块至 `rules.mk`：

```make
# 选择Bootloader
BOOTLOADER = bootloadhid
```

兼容的刷写工具：

* [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases)（推荐的图形化工具）
* [bootloadHID CLI](https://www.obdev.at/products/vusb/bootloadhid.html) / QMK中将构建目标设为 `:bootloadhid`（推荐的命令行工具）
* [HIDBootFlash](http://vusb.wikidot.com/project:hidbootflash)


刷写过程：

1. 使用如下任一方式进入bootloader模式：
    * 点击 `QK_BOOT` 键码
    * 在按住“盐键”（salt key）时插入键盘 - 在PS2AVRGB板上，通常在MCU的A0及B0引脚上有这个按键，否则请查看键盘的使用说明。
2. 等待操作系统识别到设备
3. 将.hex文件刷写进去
4. 重置设备到应用模式（可能会自动进行）

### QMK HID

QMK维护了[一个LUFA HID bootloader的分支版本](https://github.com/qmk/lufa/tree/master/Bootloaders/HID)，通过USB HID节点设备进行刷写，工作模式类似于PJRC的Teensy Loader刷写器以及HalfKay bootloader。其可以进行一次矩阵扫描来退出bootloader进入应用模式，同时会让LED闪烁或蜂鸣器响一声。

为确保对QMK HID bootloader的兼容性，请添加如下代码块至 `rules.mk`：

```make
# 选择Bootloader
BOOTLOADER = qmk-hid
```

要启用额外的功能支持，请添加如下定义至 `config.h`：

```c
#define QMK_ESC_OUTPUT F1  // COL pin if COL2ROW
#define QMK_ESC_INPUT  D5  // ROW pin if COL2ROW
// 可选:
//#define QMK_LED E6
//#define QMK_SPEAKER C6
```

目前来讲不推荐将 `QMK_ESC` 键设置成与[Bootmagic Lite](zh-cn/feature_bootmagic.md)同一个键，否则按下该键时只会让MCU在bootloader模式上反复进出。

制造商及型号字符串自动从 `config.h` 中获取，并会在型号后追加 " Bootloader"。

要生成该bootloader，需指定 `bootloader` 构建目标，即 `make planck/rev4:default:bootloader`。要生成可部署到正式产品的.hex文件（同时包含QMK及bootloader），使用 `production` 构建目标，即 `make planck/rev4:default:production`。

兼容的刷写工具：

* TBD
  * 目前只能选择使用该 [Python脚本](https://github.com/qmk/lufa/tree/master/Bootloaders/HID/HostLoaderApp_python), 或从LUFA仓库中构建[`hid_bootloader_cli`](https://github.com/qmk/lufa/tree/master/Bootloaders/HID/HostLoaderApp)。Homebrew也许（即将）能直接支持（通过 `brew install qmk/qmk/hid_bootloader_cli`）。

刷写过程：

1. 使用如下任一方式进入bootloader模式：
    * 点击 `QK_BOOT` 键码
    * 如果PCB上有 `RESET` 键，点击之
    * 快速短接一下RST到GND
2. 等待操作系统识别到设备
4. 将.hex文件刷写进去
5. 重置设备进入应用模式（可能会自动进行）

### `make` 构建目标

* `:qmk-hid`: 每5秒检测一次直到发现可用的DFU设备，然后进行固件刷写。

## STM32/APM32 DFU

所有的STM32及APM32 MCU系列，除F103型号外（参见[STM32duino小节](#stm32duino)）都在出场时预装了bootloader且无法修改或删除。

为确保对STM32-DFU bootloader的兼容性，请添加如下代码块至 `rules.mk`（可选替代项为 `apm32-dfu`）：

```make
# 选择Bootloader
BOOTLOADER = stm32-dfu
```

兼容的刷写工具：

* [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases) （推荐的图形化工具）
* [dfu-util](https://dfu-util.sourceforge.net/) / QMK中将构建目标设为 `:dfu-util`（推荐的命令行工具）

刷写过程：

1. 使用如下任一方式进入bootloader模式（进入该模式后只有7秒时间可以刷写）：
    * 点击 `QK_BOOT` 键码（对STM32F042设备可能无效）
    * 如果有重置电路，点击PCB上的 `RESET` 键；有些主控板上可能会有一个开关需要先打开
    * 否则，你需要将 `BOOT0` 接线到VCC（通过 `BOOT0` 按钮或跳线），短接 `RESET` 至GND（通过 `RESET` 按钮或条线），然后断开 `BOOT0` 的接线。
2. 等待操作系统识别到设备
3. 将.bin文件刷写进去
4. 重置设备进入应用模式（可能会自动进行）

### `make` 构建目标

* `:dfu-util`: 每5秒检测一次直到发现可用的STM32 bootloader设备，然后进行固件刷写。
* `:dfu-util-split-left` 和 `:dfu-util-split-right`: 同 `:dfu-util` 一样会刷写固件，但额外地会设置手性设置到EEPROM中，对于基于Proton-C的分体式键盘这是理想的方法。
* `:st-link-cli`: 通过ST-Link CLI工具集而非dfu-util进行刷写，需要有ST-Link电子狗。
* `:st-flash`: 通过[STLink工具](https://github.com/stlink-org/stlink)内的 `st-flash` 工具而非dfu-util进行刷写，需要有ST-Link电子狗。

## STM32duino :id=stm32duino

该bootloader几乎是STM32F103板专用，该型号出厂不带USB DFU bootloader。其源代码及预编译好的二进制文件[在这里](https://github.com/rogerclarkmelbourne/STM32duino-bootloader)。

为确保对STM32duino bootloader的兼容性，请添加如下代码块至 `rules.mk`：

```make
# 选择Bootloader
BOOTLOADER = stm32duino
```

兼容的刷写工具：

* [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases) （推荐的图形化工具）
* [dfu-util](https://dfu-util.sourceforge.net/) / QMK中将构建目标设为 `:dfu-util`（推荐的命令行工具）

刷写过程：

1. 使用如下任一方式进入bootloader模式（进入该模式后只有7秒时间可以刷写）：
    * 点击 `QK_BOOT` 键码（对STM32F042设备可能无效）
    * 如果有重置电路，点击PCB上的 `RESET` 键；有些主控板上可能会有一个开关需要先打开
    * 否则，你需要将 `BOOT0` 接线到VCC（通过 `BOOT0` 按钮或跳线），短接 `RESET` 至GND（通过 `RESET` 按钮或条线），然后断开 `BOOT0` 的接线。
2. 等待操作系统识别到设备
3. 将.bin文件刷写进去
4. 重置设备进入应用模式（可能会自动进行）

## Kiibohd DFU

Input Club出品的键盘使用NXP Kinetis微控制器而非STM32，并使用了独有的[自制bootloader](https://github.com/kiibohd/controller/tree/master/Bootloader)，然而处理器 及协议上两者大部分是一致的。

在 `rules.mk` 中该bootloader的设置项为 `kiibohd`，但既然该bootloader仅用在Input Club主控板上，就不必要设置到键映射或是用户级<!--译：不清楚这里的“user level”是个啥……-->了。

兼容的刷写工具：

* [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases)（推荐的图形化工具）
* [dfu-util](https://dfu-util.sourceforge.net/) / QMK中将构建目标设为 `:dfu-util`（推荐的命令行工具）

刷写过程：

1. 使用如下任一方式进入bootloader模式：
    * 点击 `QK_BOOT` 键码（有可能只能进入到“安全”bootloader模式，参见[这里](https://github.com/qmk/qmk_firmware/issues/6112)）
    * 如果PCB上有 `RESET` 键，点击之
2. 等待操作系统识别到设备
3. 将.bin文件刷写进去
4. 重置设备进入应用模式（可能会自动进行）

## tinyuf2

键盘可以考虑支持tinyuf2 bootloader，目前唯一支持的设备是F401/F411 blackpill。

在 `rules.mk` 中该bootloader的设置项为 `tinyuf2`，也可指定到键映射及用户级中。

为确保对tinyuf2 bootloader的兼容性，请添加如下代码块至 `rules.mk`：

```make
# 选择Bootloader
BOOTLOADER = tinyuf2
```

兼容的刷写工具：

* 任何具备文件拷贝能力的程序，如 _macOS Finder_ 或 _Windows Explorer_ *。

刷写过程：

1. 使用如下任一方式进入bootloader模式：
    * 点击 `QK_BOOT` 键码
    * 双击PCB上的 `nRST` 键
2. 等待操作系统识别到设备
3. 将.uf2文件拷贝到新出现的USB存储设备上
4. 等待设备恢复可用状态