QMK Toolbox全攻略：从入门到精通⌨️🔧

准备篇：初识QMK Toolbox

核心组件解析

QMK Toolbox是一款集成多种固件刷新工具的应用程序，专为键盘爱好者设计。它的核心组件包括：

• 公共资源模块：common文件夹存放跨平台共享的配置文件和资源，如avrdude.conf配置文件和各种reset.eep重置文件。
• 平台适配代码：windows和macos文件夹分别包含对应操作系统的实现代码，确保在不同平台上都能正常工作。
• 固件刷新工具集：在各平台的Resources目录下，你可以找到如dfu-util、avrdude等多种固件刷新工具。

[!TIP] 如果你是开发者，可以通过修改这些核心组件来自定义QMK Toolbox的行为，但建议先备份原始文件。

系统安装对比

安装方式	Windows系统	macOS系统
独立程序	下载standalone版本，直接运行	下载standalone版本，解压后拖入应用程序文件夹
安装程序	下载installer，双击运行安装向导	下载installer，按照提示完成安装
包管理器	不适用	使用Homebrew：brew install qmk-toolbox

[!TIP] 首次运行QMK Toolbox时，Windows系统会提示安装必要的驱动程序，建议点击"安装"以确保设备正常识别。

操作篇：固件刷新实战

3步完成固件刷新

1. 准备工作：确保你的键盘已连接到电脑，并处于bootloader（引导加载程序）模式。不同键盘进入bootloader的方式可能不同，通常是按住特定按键组合后插拔键盘。

2. 选择固件：打开QMK Toolbox，点击"Open"按钮，浏览并选择你要刷写的固件文件（通常是.hex或.bin格式）。

3. 开始刷新：点击"Flash"按钮开始刷写过程。你可以在日志窗口中查看刷新进度和状态信息。

[!TIP] 刷写过程中，请勿断开键盘与电脑的连接或关闭QMK Toolbox，否则可能导致设备无法正常工作。

支持的bootloader类型

QMK Toolbox支持多种bootloader，包括：

• ARM DFU：适用于APM32、STM32等ARM架构的微控制器，使用dfu-util工具。
• Atmel DFU：适用于Atmel系列微控制器，使用dfu-programmer工具。
• Caterina：适用于Arduino、Pro Micro等设备，使用avrdude工具。
• HalfKay：适用于Teensy系列控制器，使用Teensy Loader工具。

[!TIP] 如果你的键盘使用的bootloader不在列表中，可以尝试在QMK Toolbox的设置中启用"显示所有设备"选项，或者查看官方文档了解是否有其他解决方案。

进阶篇：解决常见问题

新手常见配置问题Q&A

Q: 为什么QMK Toolbox无法识别我的键盘？
A: 可能是驱动程序未正确安装。Windows用户可以尝试使用Zadig工具重新安装驱动；macOS用户通常不需要额外安装驱动，但需要确保键盘已正确进入bootloader模式。

Q: 刷新固件时提示"Device not found"怎么办？
A: 首先检查键盘是否已进入bootloader模式，然后尝试更换USB端口或重启电脑。如果问题仍然存在，可以尝试使用Zadig工具更新USB驱动。

Q: 如何自定义QMK Toolbox的设置？
A: QMK Toolbox的设置通常是内在的，适应不同类型的键盘和bootloader。对于高级用户，可以通过修改源代码来自定义工具的行为。

[!TIP] 如果你遇到其他问题，可以查看QMK Toolbox的日志文件获取更多信息，日志文件通常保存在应用程序的数据目录中。

跨平台兼容性对照表

功能	Windows	macOS
自动驱动安装	支持	不适用
固件拖放功能	支持	支持
HID控制台	支持	支持
命令行界面	支持	支持

[!TIP] 在不同操作系统上，QMK Toolbox的界面可能略有差异，但核心功能和操作流程基本一致。

你在使用QMK Toolbox时有什么独特的配置技巧或遇到过哪些有趣的问题？欢迎在评论区分享你的经验！

相关资源：

• 官方文档：docs/official.md
• 社区论坛：community/forum.md
• FAQ页面：docs/faq.md