QMK 固件中的 Swoop 分体键盘从编译、刷写到硬件配置实战指南【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware导读Swoop 是一款基于 Ferris/Sweep 架构的开源分体split键盘其 QMK 固件支持位于本仓库的 keyboards/bluebell/swoop 目录下包含 MX 与 Low ProfileLP两种硬件版本。本指南将带你完整掌握 Swoop 的固件编译、分体左右手刷写handedness、Bootloader 进入方式并深入解读其 keyboard.json 中的矩阵、编码器、RGB 与串口配置让你不仅能刷入默认固件还能在此基础上定制自己的键位与功能。Swoop 键盘与仓库支持概况根据 keyboards/bluebell/swoop/readme.mdSwoop 是一款基于 Ferris/Sweep 的开源分体键盘键盘维护者Jimmerricks硬件支持Swoop MX、Swoop LP主控为 Pro Micro 或同等兼容控制器硬件来源Swoop 开源硬件仓库PCB 文件开源可自行制作仓库中的固件目录结构非常精简仅由 4 个文件构成非常便于理解一个 QMK 键盘的最小工程形态keyboards/bluebell/swoop/ ├── config.h # 编译期宏定义EE_HANDS、OLED 超时等 ├── keyboard.json # 数据驱动的硬件配置矩阵、编码器、RGB、USB 描述符 ├── keymaps/ │ └── default/ │ └── keymap.c # 默认键位 └── readme.md # 键盘说明文档这种“keyboard.jsonconfig.hkeymap.c”的三件套结构正是当前 QMK 数据驱动配置Data-Driven Configuration体系的标准做法硬件描述全部收敛到keyboard.json编译期行为由config.h控制按键映射则放在 keymap 中。构建环境准备与固件编译在编译前需要先完成 QMK 构建环境搭建安装依赖、克隆仓库、初始化qmk setup并确保能够运行make命令。环境就绪后编译 Swoop 默认键位固件的命令为make bluebell/swoop:default这条命令会读取 keyboards/bluebell/swoop/keyboard.json 中的硬件定义结合keymaps/default/keymap.c的键位映射为 Pro MicroAVR主控产出可刷写的固件镜像。其中bluebell/swoop是键盘在仓库中的路径标识vendor/keyboarddefault是键位名对应 keymaps/default 目录。刷写固件与分体左右手设置EE_HANDSSwoop 是分体键盘左右两个半区各有一颗 Pro Micro 控制器因此刷写时必须为每一半指定左右手身份。官方示例命令为make bluebell/swoop:default:avrdude-split-right这里的关键在于:avrdude-split-right目标。从仓库文档 docs/flashing.md 可以看到说明:avrdude-split-left和:avrdude-split-right以:avrdude方式刷写固件同时将 handedness左右手设置写入 EEPROM适用于基于 Pro Micro 的分体键盘。这一机制与 config.h 中的这行宏定义直接相关#define EE_HANDSEE_HANDS是 QMK 分体键盘的“由 EEPROM 判定左右手”方案。根据 docs/features/split_keyboard.md 的说明固件在控制器启动时读取 EEPROM 中的 handedness 标志从而确定当前半区是左还是右以及布局如何翻转映射。对于带 Caterina Bootloader 的 AVR 控制器如常见的 Pro Micro需要使用以下参数区分左右主控类型Bootloader 参数Caterina Bootloader 的 AVR如 Pro Microavrdude-split-left/avrdude-split-rightDFU 兼容 Bootloader 的 AVR如 Elite-Cdfu-split-left/dfu-split-rightDFU 兼容 Bootloader 的 ARM如 Proton-Cdfu-util-split-left/dfu-util-split-rightUF2 兼容 Bootloader 的 ARM如 RP2040uf2-split-left/uf2-split-right实操流程以左侧为例将左侧控制器置于 Bootloader 模式执行make bluebell/swoop:default:avrdude-split-left对右侧控制器重复以上步骤改用avrdude-split-right。需要注意该 handedness 设置不会被EE_CLR键或eeconfig_init()清除但如果用外部工具整体覆写 EEPROM例如 QMK Toolbox 的 Reset EEPROM 功能则必须重新刷写对应侧的 EEPROM 文件以恢复左右手身份。硬件配置深度解析keyboard.json 以数据驱动方式完整描述了 Swoop 的硬件。理解这份文件是进一步定制固件如增加键位、调整 RGB、更换主控的基础。USB 描述符与基本信息{ keyboard_name: Swoop, manufacturer: jmnw, maintainer: jmnw, usb: { vid: 0x1804, pid: 0x3046, device_version: 1.0.0 } }vid/pid0x1804 / 0x3046是操作系统识别该键盘的 USB 标识刷写后设备管理器/系统设置中显示的名称即来自keyboard_name。矩阵与二极管方向matrix_pins: { cols: [B1, F7, F6, F5, F4], rows: [D4, C6, D7, E6] }, diode_direction: COL2ROWSwoop 每半区为 5 列 × 4 行的矩阵COL2ROW表示二极管阳极接列、阴极接行扫描时列输出、行读取。左右两半的矩阵共同构成完整的 8 行 × 5 列矩阵与下方LAYOUT_split_3x5_3布局中的matrix坐标一一对应左半 0–3 行右半 4–7 行。分体串口与编码器split: { enabled: true, serial: { pin: D2 }, encoder: { right: { rotary: [ {pin_a: B5, pin_b: B4} ] } } }, encoder: { rotary: [ {pin_a: B4, pin_b: B5} ] }split.enabled: true启用分体模式两半之间通过D2引脚上的串口通信交换矩阵与编码器数据左右各配置一个旋转编码器左半接B4/B5右半split.encoder.right接B5/B4引脚对调以匹配 PCB 布局这也是 QMK 分体编码器的标准做法。RGB 灯效RGBLIGHT WS2812features: { bootmagic: true, mousekey: true, extrakey: true, rgblight: true }, ws2812: { pin: D3 }, rgblight: { hue_steps: 10, led_count: 36, max_brightness: 150, sleep: true, split_count: [18, 18], animations: { breathing: true, rainbow_mood: true, rainbow_swirl: true, static_gradient: true } }Swoop 每半区 18 颗 WS2812 灯珠、共 36 颗由D3引脚驱动split_count: [18, 18]告诉固件左右各 18 颗灯max_brightness: 150限制最高亮度sleep: true允许键盘休眠时熄灭 RGB。启用的动画包括呼吸、彩虹情绪、彩虹漩涡和静态渐变。主控与社区布局development_board: promicro, community_layouts: [split_3x5_3]development_board: promicro声明使用 Pro Micro 开发板定义引脚数、Bootloader、布局宏等均从 QMK 的 promicro 板级定义继承community_layouts: [split_3x5_3]声明 Swoop 属于社区通用的split_3x5_33 行 × 5 列 每侧 3 个拇指键分体布局族对应仓库 layouts/community/split_3x5_3 中的LAYOUT_split_3x5_3宏意味着该键位可直接在其他同布局键盘间共享。默认键位与布局矩阵Swoop 的默认键位在 keymaps/default/keymap.c 中是一个纯 QWERTY 布局单层* ,---------------------------------. ,----------------------------------. * | Q | W | E | R | T | | Y | U | I | O | P | * |-----------------------------| |------------------------------| * | A | S | D | F | G | | H | J | K | L | ; | * |-----------------------------| ,------------------------------| * | Z | X | C | V | B | | N | M | , | . | / | * ------------------------------| |------------------------------------- * | LCTL | BSpc | Esc | | Ent | Spc | LAlt |对应的代码实现为enum layers { _QWERTY }; const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] { [_QWERTY] LAYOUT_split_3x5_3( KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Y, KC_U, KC_I, KC_O, KC_P, KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, KC_LCTL, KC_BSPC, KC_ESC, KC_ENT, KC_SPC, KC_LALT ) };LAYOUT_split_3x5_3宏在 keyboard.json 的layouts节点中定义了完整的物理坐标x/y 值并给出了每个按键与矩阵位置的对应关系。例如拇指键区左半[3,2]LCTLx2.875、[3,3]BSpc、[3,4]Esc右半[7,4]Ent、[7,3]Spc、[7,2]LAlt。自定义键位时只需复制该宏并替换按键码即可保持物理位置与矩阵映射完全一致。Bootloader 进入方式根据 keyboards/bluebell/swoop/readme.mdSwoop 推荐的进入 Bootloader 方式是物理复位按钮短暂按下 PCB 内侧的小按钮部分批次可能没有焊接按钮需要短接预留的触点pad。这是 Pro Micro 分体键盘最常见的进入刷写模式方式按住复位键的同时上电或短接GND与RST控制器即进入 Caterina Bootloader随后执行make bluebell/swoop:default:avrdude-split-left/right即可完成刷写。值得说明的是仓库中还注释掉了另外两种常见方式Bootmagic 复位、QK_BOOT键码Swoop 官方并未默认启用它们因此在keyboard.json中features.bootmagic: true虽然开启但实际操作仍以物理复位键为准。如果你希望在键位中加入一键进 Bootloader 的功能可在 keymap 中引入QK_BOOT键码并自行验证。编译期扩展OLED 支持config.h 还包含一段条件编译的 OLED 配置// OLED driver #ifdef OLED_DRIVER_ENABLE #define OLED_TIMEOUT 30000 #endif当在构建时启用 OLED 驱动例如通过make bluebell/swoop:default:oled或在 rules.mk / keyboard.json 中开启对应 feature时OLED 将在无操作 30 秒后自动关闭以延长续航并保护屏幕。这展示了 QMK 条件编译的典型用法硬件能力与用户可选项分离按需启用。总结与进阶方向Swoop 是一个麻雀虽小、五脏俱全的 QMK 分体键盘示例。通过本指南你应已掌握使用make bluebell/swoop:default编译默认固件使用:avrdude-split-left/right配合EE_HANDS完成左右手刷写通过 keyboard.json 理解矩阵、编码器、RGB 与分体串口配置基于LAYOUT_split_3x5_3修改默认 QWERTY 键位或直接复用社区split_3x5_3布局。进一步的进阶路线包括为 Swoop 添加多层键位与 Mod-Tap / Home Row Mods参考 docs/features/layers.md 与 docs/mod_tap.md、按需启用 OLED、或参照 keyboards/ferris/sweep/readme.md 中 Ferris/Sweep 的引脚交换技巧DIRECT_PINS重定义来适配自己打样的 PCB 变体。深入阅读 docs/features/split_keyboard.md 还能进一步掌握分体键盘的矩阵判定、串口通信等底层机制。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 QMK 固件中的 Swoop 分体键盘：从编译、刷写到硬件配置实战指南
QMK 固件中的 Swoop 分体键盘从编译、刷写到硬件配置实战指南【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware导读Swoop 是一款基于 Ferris/Sweep 架构的开源分体split键盘其 QMK 固件支持位于本仓库的 keyboards/bluebell/swoop 目录下包含 MX 与 Low ProfileLP两种硬件版本。本指南将带你完整掌握 Swoop 的固件编译、分体左右手刷写handedness、Bootloader 进入方式并深入解读其 keyboard.json 中的矩阵、编码器、RGB 与串口配置让你不仅能刷入默认固件还能在此基础上定制自己的键位与功能。Swoop 键盘与仓库支持概况根据 keyboards/bluebell/swoop/readme.mdSwoop 是一款基于 Ferris/Sweep 的开源分体键盘键盘维护者Jimmerricks硬件支持Swoop MX、Swoop LP主控为 Pro Micro 或同等兼容控制器硬件来源Swoop 开源硬件仓库PCB 文件开源可自行制作仓库中的固件目录结构非常精简仅由 4 个文件构成非常便于理解一个 QMK 键盘的最小工程形态keyboards/bluebell/swoop/ ├── config.h # 编译期宏定义EE_HANDS、OLED 超时等 ├── keyboard.json # 数据驱动的硬件配置矩阵、编码器、RGB、USB 描述符 ├── keymaps/ │ └── default/ │ └── keymap.c # 默认键位 └── readme.md # 键盘说明文档这种“keyboard.jsonconfig.hkeymap.c”的三件套结构正是当前 QMK 数据驱动配置Data-Driven Configuration体系的标准做法硬件描述全部收敛到keyboard.json编译期行为由config.h控制按键映射则放在 keymap 中。构建环境准备与固件编译在编译前需要先完成 QMK 构建环境搭建安装依赖、克隆仓库、初始化qmk setup并确保能够运行make命令。环境就绪后编译 Swoop 默认键位固件的命令为make bluebell/swoop:default这条命令会读取 keyboards/bluebell/swoop/keyboard.json 中的硬件定义结合keymaps/default/keymap.c的键位映射为 Pro MicroAVR主控产出可刷写的固件镜像。其中bluebell/swoop是键盘在仓库中的路径标识vendor/keyboarddefault是键位名对应 keymaps/default 目录。刷写固件与分体左右手设置EE_HANDSSwoop 是分体键盘左右两个半区各有一颗 Pro Micro 控制器因此刷写时必须为每一半指定左右手身份。官方示例命令为make bluebell/swoop:default:avrdude-split-right这里的关键在于:avrdude-split-right目标。从仓库文档 docs/flashing.md 可以看到说明:avrdude-split-left和:avrdude-split-right以:avrdude方式刷写固件同时将 handedness左右手设置写入 EEPROM适用于基于 Pro Micro 的分体键盘。这一机制与 config.h 中的这行宏定义直接相关#define EE_HANDSEE_HANDS是 QMK 分体键盘的“由 EEPROM 判定左右手”方案。根据 docs/features/split_keyboard.md 的说明固件在控制器启动时读取 EEPROM 中的 handedness 标志从而确定当前半区是左还是右以及布局如何翻转映射。对于带 Caterina Bootloader 的 AVR 控制器如常见的 Pro Micro需要使用以下参数区分左右主控类型Bootloader 参数Caterina Bootloader 的 AVR如 Pro Microavrdude-split-left/avrdude-split-rightDFU 兼容 Bootloader 的 AVR如 Elite-Cdfu-split-left/dfu-split-rightDFU 兼容 Bootloader 的 ARM如 Proton-Cdfu-util-split-left/dfu-util-split-rightUF2 兼容 Bootloader 的 ARM如 RP2040uf2-split-left/uf2-split-right实操流程以左侧为例将左侧控制器置于 Bootloader 模式执行make bluebell/swoop:default:avrdude-split-left对右侧控制器重复以上步骤改用avrdude-split-right。需要注意该 handedness 设置不会被EE_CLR键或eeconfig_init()清除但如果用外部工具整体覆写 EEPROM例如 QMK Toolbox 的 Reset EEPROM 功能则必须重新刷写对应侧的 EEPROM 文件以恢复左右手身份。硬件配置深度解析keyboard.json 以数据驱动方式完整描述了 Swoop 的硬件。理解这份文件是进一步定制固件如增加键位、调整 RGB、更换主控的基础。USB 描述符与基本信息{ keyboard_name: Swoop, manufacturer: jmnw, maintainer: jmnw, usb: { vid: 0x1804, pid: 0x3046, device_version: 1.0.0 } }vid/pid0x1804 / 0x3046是操作系统识别该键盘的 USB 标识刷写后设备管理器/系统设置中显示的名称即来自keyboard_name。矩阵与二极管方向matrix_pins: { cols: [B1, F7, F6, F5, F4], rows: [D4, C6, D7, E6] }, diode_direction: COL2ROWSwoop 每半区为 5 列 × 4 行的矩阵COL2ROW表示二极管阳极接列、阴极接行扫描时列输出、行读取。左右两半的矩阵共同构成完整的 8 行 × 5 列矩阵与下方LAYOUT_split_3x5_3布局中的matrix坐标一一对应左半 0–3 行右半 4–7 行。分体串口与编码器split: { enabled: true, serial: { pin: D2 }, encoder: { right: { rotary: [ {pin_a: B5, pin_b: B4} ] } } }, encoder: { rotary: [ {pin_a: B4, pin_b: B5} ] }split.enabled: true启用分体模式两半之间通过D2引脚上的串口通信交换矩阵与编码器数据左右各配置一个旋转编码器左半接B4/B5右半split.encoder.right接B5/B4引脚对调以匹配 PCB 布局这也是 QMK 分体编码器的标准做法。RGB 灯效RGBLIGHT WS2812features: { bootmagic: true, mousekey: true, extrakey: true, rgblight: true }, ws2812: { pin: D3 }, rgblight: { hue_steps: 10, led_count: 36, max_brightness: 150, sleep: true, split_count: [18, 18], animations: { breathing: true, rainbow_mood: true, rainbow_swirl: true, static_gradient: true } }Swoop 每半区 18 颗 WS2812 灯珠、共 36 颗由D3引脚驱动split_count: [18, 18]告诉固件左右各 18 颗灯max_brightness: 150限制最高亮度sleep: true允许键盘休眠时熄灭 RGB。启用的动画包括呼吸、彩虹情绪、彩虹漩涡和静态渐变。主控与社区布局development_board: promicro, community_layouts: [split_3x5_3]development_board: promicro声明使用 Pro Micro 开发板定义引脚数、Bootloader、布局宏等均从 QMK 的 promicro 板级定义继承community_layouts: [split_3x5_3]声明 Swoop 属于社区通用的split_3x5_33 行 × 5 列 每侧 3 个拇指键分体布局族对应仓库 layouts/community/split_3x5_3 中的LAYOUT_split_3x5_3宏意味着该键位可直接在其他同布局键盘间共享。默认键位与布局矩阵Swoop 的默认键位在 keymaps/default/keymap.c 中是一个纯 QWERTY 布局单层* ,---------------------------------. ,----------------------------------. * | Q | W | E | R | T | | Y | U | I | O | P | * |-----------------------------| |------------------------------| * | A | S | D | F | G | | H | J | K | L | ; | * |-----------------------------| ,------------------------------| * | Z | X | C | V | B | | N | M | , | . | / | * ------------------------------| |------------------------------------- * | LCTL | BSpc | Esc | | Ent | Spc | LAlt |对应的代码实现为enum layers { _QWERTY }; const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] { [_QWERTY] LAYOUT_split_3x5_3( KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Y, KC_U, KC_I, KC_O, KC_P, KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, KC_LCTL, KC_BSPC, KC_ESC, KC_ENT, KC_SPC, KC_LALT ) };LAYOUT_split_3x5_3宏在 keyboard.json 的layouts节点中定义了完整的物理坐标x/y 值并给出了每个按键与矩阵位置的对应关系。例如拇指键区左半[3,2]LCTLx2.875、[3,3]BSpc、[3,4]Esc右半[7,4]Ent、[7,3]Spc、[7,2]LAlt。自定义键位时只需复制该宏并替换按键码即可保持物理位置与矩阵映射完全一致。Bootloader 进入方式根据 keyboards/bluebell/swoop/readme.mdSwoop 推荐的进入 Bootloader 方式是物理复位按钮短暂按下 PCB 内侧的小按钮部分批次可能没有焊接按钮需要短接预留的触点pad。这是 Pro Micro 分体键盘最常见的进入刷写模式方式按住复位键的同时上电或短接GND与RST控制器即进入 Caterina Bootloader随后执行make bluebell/swoop:default:avrdude-split-left/right即可完成刷写。值得说明的是仓库中还注释掉了另外两种常见方式Bootmagic 复位、QK_BOOT键码Swoop 官方并未默认启用它们因此在keyboard.json中features.bootmagic: true虽然开启但实际操作仍以物理复位键为准。如果你希望在键位中加入一键进 Bootloader 的功能可在 keymap 中引入QK_BOOT键码并自行验证。编译期扩展OLED 支持config.h 还包含一段条件编译的 OLED 配置// OLED driver #ifdef OLED_DRIVER_ENABLE #define OLED_TIMEOUT 30000 #endif当在构建时启用 OLED 驱动例如通过make bluebell/swoop:default:oled或在 rules.mk / keyboard.json 中开启对应 feature时OLED 将在无操作 30 秒后自动关闭以延长续航并保护屏幕。这展示了 QMK 条件编译的典型用法硬件能力与用户可选项分离按需启用。总结与进阶方向Swoop 是一个麻雀虽小、五脏俱全的 QMK 分体键盘示例。通过本指南你应已掌握使用make bluebell/swoop:default编译默认固件使用:avrdude-split-left/right配合EE_HANDS完成左右手刷写通过 keyboard.json 理解矩阵、编码器、RGB 与分体串口配置基于LAYOUT_split_3x5_3修改默认 QWERTY 键位或直接复用社区split_3x5_3布局。进一步的进阶路线包括为 Swoop 添加多层键位与 Mod-Tap / Home Row Mods参考 docs/features/layers.md 与 docs/mod_tap.md、按需启用 OLED、或参照 keyboards/ferris/sweep/readme.md 中 Ferris/Sweep 的引脚交换技巧DIRECT_PINS重定义来适配自己打样的 PCB 变体。深入阅读 docs/features/split_keyboard.md 还能进一步掌握分体键盘的矩阵判定、串口通信等底层机制。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考