QMK 固件实战：Cipulot OK-1 低矮键盘的构建、烧录与 Bootloader 使用指南

QMK 固件实战：Cipulot OK-1 低矮键盘的构建、烧录与 Bootloader 使用指南

【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware

OK-1 是 Cipulot 推出的一款低矮（low profile）键盘，其 QMK 支持以 keyboards/cipulot/ok_1/ 目录形式维护在当前 QMK 固件仓库中。本文以该键盘的官方 readme.md 为主线，结合仓库内keyboard.json、config.h、rules.mk、halconf.h、mcuconf.h及默认键映射源码，系统讲解 OK-1 固件的构建与烧录命令、STM32 DFU 引导程序的三类进入方式，以及数据驱动配置背后的硬件细节，帮助你从零完成编译、刷写与按键定制。

OK-1 硬件与仓库文件概览

OK-1 由键盘维护者 cipulot 提交到 QMK，硬件支持型号为 OK-1。在仓库中，其固件工程由以下文件构成：

• keyboard.json：数据驱动配置主文件，集中声明 MCU、矩阵、特性与布局（QMK 数据驱动配置机制的说明参见 docs/data_driven_config.md）；
• keymaps/default/keymap.c：默认键映射，包含 Mac/Windows 双平台四层布局与自定义按键处理；
• config.h：RGB LED（WS2812 PWM + DMA）底层参数；
• rules.mk：DFU 后缀参数；
• halconf.h 与 mcuconf.h：ChibiOS 外设（PAL、PWM/TIM1）使能配置。

构建与烧录：核心命令速查

根据官方 readme，在搭建好 QMK 构建环境（qmk setup，参见仓库 docs/newbs_getting_started.md 与 docs/newbs_building_firmware.md）后，编译默认键映射的固件：

make cipulot/ok_1:default

一键编译并烧录：

make cipulot/ok_1:default:flash

这两条命令是 QMK 键盘工程的通用模式：make <键盘路径>:<键映射名>编译指定键映射，追加:flash目标则会在编译完成后进入烧录流程。若使用 QMK CLI，等价操作是qmk compile -kb cipulot/ok_1 -km default与qmk flash -kb cipulot/ok_1 -km default。完整编译命令说明可参考 docs/getting_started_make_guide.md，刷写流程见 docs/flashing.md 与 docs/newbs_flashing.md。

编译器优化：默认启用 LTO

在 keyboard.json 的build段中声明了"lto": true，即构建默认开启链接时优化（Link-Time Optimization）。LTO 能显著压缩固件体积，对于同时开启 RGB Matrix、鼠标键等特性的固件尤其重要。仓库 builddefs/build_keyboard.mk 中定义了 LTO 标志向编译器的传递逻辑，你可以在编译时通过make cipulot/ok_1:default的终端输出中看到LTO_ENABLE=yes相关的处理。

DFU 后缀的宽容配置

rules.mk 中只有一行特殊配置：

DFU_SUFFIX_ARGS = -v FFFF -p FFFF

该参数配合stm32-dfu引导程序使用，将 DFU 文件后缀中的 VID/PID 设为通配符 FFFF，从而允许为兼容芯片（如 APM32 系列替代型号）生成的固件也能通过标准 STM32 DFU 工具刷入，扩展了固件文件的可烧录性。

Bootloader：三种进入方式详解

官方 readme 明确列出了进入 OK-1 引导程序的三种方式，这与 docs/feature_bootmagic.md 描述的机制一一对应：

1. 布局中的键码（Keycode in layout）：按下映射了QK_BOOT的按键即可软重启进入 DFU 模式。OK-1 的默认键映射将QK_BOOT保留给用户自定义（默认键映射中未直接占用），你可以在自己的键映射中将其放到任意按键上，例如在LAYOUT数组里填入QK_BOOT，这是最方便的刷写前操作方式；
2. 物理复位按钮（Physical reset button）：长按 PCB 上焊接的复位按键进入引导程序，适合固件刷写失败、键盘无响应时的硬复位场景；
3. Bootmagic 复位（Bootmagic reset）：按住左上角按键的同时插入 USB 线缆，触发 Bootmagic 复位。这一机制由 QMK 核心的 Bootmagic 功能提供，其实现位于 quantum/ 下的 bootmagic 相关源码中。左上角按键即键盘物理矩阵[0,0]位置，对应 keyboard.jsonlayouts.LAYOUT.layout中第一个键位。

进入 DFU 模式后，主机会枚举出 STM32 DFU 设备（VID0x6369、PID0x6BCA对应的固件应用，引导时使用 DFU 默认 VID/PID），此时即可执行make cipulot/ok_1:default:flash完成烧录。

数据驱动配置：键盘硬件全貌

OK-1 的所有硬件参数都集中在 keyboard.json，这是 QMK 数据驱动配置（Data Driven Configuration）的典型实践：config.h与rules.mk中的大部分值由 JSON 生成，keyboard.json成为单一事实来源。

主控与 USB 标识

• 处理器："processor": "STM32F072"，属于 STM32F0 系列，具备 USB 设备控制器，支持stm32-dfu引导；
• USB 标识：vid为0x6369，pid为0x6BCA，device_version为0.0.1，manufacturer与keyboard_name分别为Cipulot与OK-1；
• USB 共享端点："shared_endpoint": {"keyboard": true}，允许键盘与鼠标/媒体键共享一个 USB 端点，减少端点占用，这解释了features中同时开启mousekey、extrakey的可行性。

矩阵扫描与二极管方向

matrix_pins定义了 6 行 × 14 列的扫描矩阵，行线为B11, A2, B9, B8, B7, B6，列线为B10, B2, B1, B0, A7, A6, A5, A1, A0, F1, F0, C15, A4, A3，diode_direction为COL2ROW（二极管阳极接列线、阴极接行线）。行扫描方向的正确配置由 QMK 核心矩阵扫描代码在 quantum/matrix.c 中消费，决定按键状态读取的正确性。

特性开关

features段开启：

• extrakey：媒体键与系统键支持；
• mousekey：鼠标键模拟；
• nkro：全键无冲（N-Key Rollover）；
• rgb_matrix：RGB 矩阵灯效。

另外qmk.locking设置了enabled: true与resync: true，开启 Caps Lock 等锁定键支持并启用重同步，保证锁定状态指示灯与主机状态一致。

RGB Matrix 与 WS2812 驱动

rgb_matrix段不仅默认开启rainbow_moving_chevron灯效、sleep: true（休眠时自动关闭灯效），还通过layout数组将 65 个 RGB LED 逐一映射到矩阵坐标（flags字段标注 LED 类型，如 1 表示 modifier、4 表示字母区、8 表示可寻址特殊键）。其驱动为ws2812，底层由 keyboards/cipulot/ok_1/config.h 配置：

#define WS2812_PWM_COMPLEMENTARY_OUTPUT #define WS2812_PWM_DRIVER PWMD1 #define WS2812_PWM_CHANNEL 1 #define WS2812_PWM_PAL_MODE 2 #define WS2812_DMA_STREAM STM32_DMA1_STREAM5 #define WS2812_DMA_CHANNEL 6

即使用 TIM1 的 PWM 通道 1（互补输出模式）并配合 DMA1 Stream5 直接搬运数据，实现不占用 CPU 的 LED 时序输出。为使 PWM 外设可用，halconf.h 启用了HAL_USE_PAL与HAL_USE_PWM，mcuconf.h 中开启STM32_PWM_USE_TIM1，WS2812 数据引脚位于B13（keyboard.json 的ws2812.pin）。

默认键映射：双平台四层布局解析

默认键映射 展示了 OK-1 的出厂布局设计，值得作为自定义键映射的起点模板：

• 四个层：_MAC_BASE、_MAC_FN、_WIN_BASE、_WIN_FN，分别对应 macOS 与 Windows 的基础层和功能层；
• 层切换宏：#define MAC PDF(_MAC_BASE)与#define WIN PDF(_WIN_BASE)使用PDF()（点按层切换）让 macOS 基础层上的MAC键可一键切至 Windows 布局；MACFN MO(_MAC_FN)、WINFN MO(_WIN_FN)则用MO()（按住临时层）实现功能层；
• 功能层内容：在 Mac 功能层上，F 行映射了亮度、Mission Control（KC_MCTL）、媒体控制与音量键，并放置SNIP自定义键（见下）；Windows 功能层与此对应，且额外在 Shift 行提供MAC键用于切回 Mac 布局；
• 底部阵列：KC_LOPT/KC_ROPT/KC_LCMD/KC_RCMD（Mac）与KC_LGUI/KC_RGUI/KC_LALT/KC_RALT（Windows）保证了两平台修饰键语义的正确性。

自定义键码 SNIP：跨平台截图

键映射通过process_record_user()实现了一个名为SNIP的自定义键码（自SAFE_RANGE起始），按下时根据当前所在功能层发送不同的系统截图快捷键：

• 在_WIN_FN层：tap_code(KC_PSCR)，触发 Windows 打印屏幕；
• 在_MAC_FN层：tap_code16(LSFT(LGUI(KC_3)))，触发 macOS 的Shift + Command + 3全屏截图。

该实现演示了 QMK 自定义键码的标准写法：在enum custom_keycodes中声明、在LAYOUT()中引用、并在process_record_user()中返回false拦截默认处理。可结合 docs/custom_quantum_functions.md 深入理解这一机制。

自定义你的 OK-1 固件

若要在默认键映射基础上定制，推荐做法是复制默认键映射目录并重命名：

1. 将 keymaps/default/ 复制为keymaps/<你的名字>/；
2. 编辑其中的 keymap.c，修改keymaps[][MATRIX_ROWS][MATRIX_COLS]数组与process_record_user()；
3. 用make cipulot/ok_1:<你的名字>编译验证，make cipulot/ok_1:<你的名字>:flash烧录。

布局宏LAYOUT的键位顺序与 keyboard.json 中layouts.LAYOUT.layout的 65 个条目一一对应：包括 6 行键位、底部2.25u/1.25u/6.25u空格等异形键帽，填写键值时务必保持数量与顺序一致。更多键映射编写方法见 docs/keymap.md，键码参考见 docs/keycodes.md。

小结

通过本文，你可以掌握 OK-1 键盘固件的完整使用链路：使用make cipulot/ok_1:default编译、make cipulot/ok_1:default:flash烧录，熟悉键码、物理复位键、Bootmagic 三种 DFU 引导进入方式；同时理解了其数据驱动配置中 STM32F072 主控、6×14 矩阵、WS2812 PWM+DMA 灯效驱动以及双平台四层键映射的设计细节。无论是直接刷写默认固件，还是基于 keymaps/default/keymap.c 定制个人布局，上述文件与命令都是你的实操起点。

【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware