aboutsummaryrefslogtreecommitdiff
path: root/docs/zh-cn/flashing.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/zh-cn/flashing.md')
-rw-r--r--docs/zh-cn/flashing.md329
1 files changed, 0 insertions, 329 deletions
diff --git a/docs/zh-cn/flashing.md b/docs/zh-cn/flashing.md
deleted file mode 100644
index 559b8742d0..0000000000
--- a/docs/zh-cn/flashing.md
+++ /dev/null
@@ -1,329 +0,0 @@
-# 刷写指引及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. 等待设备恢复可用状态