qmk_firmware/docs/zh-cn/flashing.md

15 KiB
Raw Blame History

刷写指引及Bootloader资料

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

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

同时也可以使用CLI工具刷写键盘执行

$ qmk flash -kb <keyboard> -km <keymap>

更多信息参见文档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-dfuqmk-dfu

# 选择Bootloader
BOOTLOADER = atmel-dfu

兼容的刷写工具:

刷写过程:

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

QMK DFU

QMK维护了一个LUFA DFU bootloader的分支版本其可以进行一次矩阵扫描来退出bootloader进入应用模式同时会让LED闪烁或蜂鸣器响一声。若要启用该功能将以下定义添加到 config.h

#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同一个键否则按下该键时只会让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或某种变体使用Pro Micro或其仿制芯片、Pololu A-Star等构建的所有键盘并基于虚拟串口使用AVR109协议进行通信。

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

# 选择Bootloader
BOOTLOADER = caterina

兼容的刷写工具:

  • QMK工具箱 (推荐的图形化工具)
  • avrdude QMK中须基于 avr109 编程器 / :avrdude 构建目标 (推荐的命令行工具)
  • 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

# 选择Bootloader
BOOTLOADER = halfkay

兼容的刷写工具:

刷写过程:

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

USBasploader

USBasploader是一款来源于Objective Development的bootloader。它通过模拟出一个USBasp ISP编程器来运行V-USB以用于一些形如ATmega328P这样的“非USB AVR芯片”。

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

# 选择Bootloader
BOOTLOADER = usbasploader

兼容的刷写工具:

  • QMK工具箱(推荐的图形化工具)
  • avrdude QMK中须基于 usbasp 编程器 / :usbasp 构建目标(推荐的命令行工具)
  • 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

# 选择Bootloader
BOOTLOADER = bootloadhid

兼容的刷写工具:

刷写过程:

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

QMK HID

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

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

# 选择Bootloader
BOOTLOADER = qmk-hid

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

#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同一个键否则按下该键时只会让MCU在bootloader模式上反复进出。

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

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

兼容的刷写工具:

  • TBD
    • 目前只能选择使用该 Python脚本, 或从LUFA仓库中构建hid_bootloader_cli。Homebrew也许即将能直接支持通过 brew install qmk/qmk/hid_bootloader_cli)。

刷写过程:

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

make 构建目标

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

STM32/APM32 DFU

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

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

# 选择Bootloader
BOOTLOADER = stm32-dfu

兼容的刷写工具:

  • QMK工具箱 (推荐的图形化工具)
  • dfu-util / 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工具内的 st-flash 工具而非dfu-util进行刷写需要有ST-Link电子狗。

STM32duino :id=stm32duino

该bootloader几乎是STM32F103板专用该型号出厂不带USB DFU bootloader。其源代码及预编译好的二进制文件在这里

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

# 选择Bootloader
BOOTLOADER = stm32duino

兼容的刷写工具:

  • QMK工具箱 (推荐的图形化工具)
  • dfu-util / 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,然而处理器 及协议上两者大部分是一致的。

rules.mk 中该bootloader的设置项为 kiibohd但既然该bootloader仅用在Input Club主控板上就不必要设置到键映射或是用户级了。

兼容的刷写工具:

  • QMK工具箱(推荐的图形化工具)
  • dfu-util / QMK中将构建目标设为 :dfu-util(推荐的命令行工具)

刷写过程:

  1. 使用如下任一方式进入bootloader模式
    • 点击 QK_BOOT 键码有可能只能进入到“安全”bootloader模式参见这里
    • 如果PCB上有 RESET 键,点击之
  2. 等待操作系统识别到设备
  3. 将.bin文件刷写进去
  4. 重置设备进入应用模式(可能会自动进行)

tinyuf2

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

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

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

# 选择Bootloader
BOOTLOADER = tinyuf2

兼容的刷写工具:

  • 任何具备文件拷贝能力的程序,如 macOS FinderWindows Explorer *。

刷写过程:

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