mirror of
https://github.com/qmk/qmk_firmware.git
synced 2024-12-25 10:59:54 +00:00
f6a7f4d4ac
Co-authored-by: peepeetee <43021794+peepeetee@users.noreply.github.com> Co-authored-by: Joy Lee <chang.li@westberrytech.com> Co-authored-by: LitoMore <LitoMore@users.noreply.github.com> Co-authored-by: Dasky <32983009+daskygit@users.noreply.github.com>
330 lines
15 KiB
Markdown
330 lines
15 KiB
Markdown
# 刷写指引及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模式：
|
||
* 点击 `RESET` 键码
|
||
* 如果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内重置两次）：
|
||
* 点击 `RESET` 键码
|
||
* 如果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秒时间可以刷写）：
|
||
* 点击 `RESET` 键码
|
||
* 如果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模式：
|
||
* 点击 `RESET` 键码
|
||
* 在按住 `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模式：
|
||
* 点击 `RESET` 键码
|
||
* 在按住“盐键”（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模式：
|
||
* 点击 `RESET` 键码
|
||
* 如果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秒时间可以刷写）：
|
||
* 点击 `RESET` 键码（对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`: 同 `:avrdude` 一样会刷写固件，但额外地会设置手性设置到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秒时间可以刷写）：
|
||
* 点击 `RESET` 键码（对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模式：
|
||
* 点击 `RESET` 键码（有可能只能进入到“安全”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模式：
|
||
* 点击 `RESET` 键码
|
||
* 双击PCB上的 `nRST` 键
|
||
2. 等待操作系统识别到设备
|
||
3. 将.uf2文件拷贝到新出现的USB存储设备上
|
||
4. 等待设备恢复可用状态
|