QMK 中的 BINEPAD PIXIE：一块 RP2040 双旋钮 2x2 Macropad 的完整解析

QMK 中的 BINEPAD PIXIE：一块 RP2040 双旋钮 2x2 Macropad 的完整解析

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

BINEPAD PIXIE 是一款极简的 2x2 宏小键盘（macropad），配备两颗旋转编码器（rotary encoder），采用 RP2040 处理器并运行 QMK 固件。本篇技术文章基于 QMK 仓库中该键盘的端口文档与配置源码，带你完整理解它的矩阵与编码器引脚规划、keyboard.json

数据驱动配置、默认键位映射的实现方式，以及如何构建与烧录固件、进入 RP2040 引导加载器。

一、硬件定位与端口概览

根据 keyboards/binepad/pixie/readme.md 的描述，PIXIE 的核心规格是：2x2 键位矩阵 + 2 个旋转编码器

，由 binepad 团队设计维护，硬件可在其官网获取。

从仓库中的 keyboard.json 可以确认其完整硬件画像：

可以看出这是一个典型的数据驱动配置（data-driven config）：QMK 的构建系统会解析keyboard.json生成keyboard_c.h、pins等文件，config.h中不再需要手工声明MATRIX_ROWS、MATRIX_COLS

和编码器引脚。仓库中 data_driven_config.md 对这套机制有系统性说明，PIXIE 正是该机制下的标准实践。

二、config.h：只有一行有效宏

整个端口的 config.h 非常简洁，仅包含一行有效定义：

#define ENCODER_DEFAULT_POS 0x3 // enable 1:1 resolution

ENCODER_DEFAULT_POS用于设置旋转编码器的默认解析粒度（resolution）。PIXIE 将其设为0x3，按源码注释开启1:1 分辨率

——即编码器的每一个物理 detent（一格咔哒声）都产生一次事件，保证旋钮操作的手感与响应一一对应，不会丢格。对于媒体控制类旋钮，这是推荐的设置。

三、默认键位：媒体键 + 编码器映射

默认键位位于 keymaps/default/keymap.c，配合 rules.mk 一起工作：

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { [0] = LAYOUT( KC_MUTE, KC_MPLY, KC_MPRV, KC_MNXT ) };

2x2 四个键映射为四个媒体控制键：静音（KC_MUTE）、播放/暂停（KC_MPLY）、上一曲（KC_MPRV）、下一曲（KC_MNXT）。LAYOUT宏对应的键位坐标在keyboard.json的layouts.LAYOUT.layout

中定义（4 个键，行列坐标 0/1.25，1.25 的 x 偏移对应键距留白），QMK Configurator 等工具依赖它做可视化。

编码器映射

rules.mk

中只需一行：

ENCODER_MAP_ENABLE = yes

开启后，键位文件中即可定义encoder_map

：

#if defined(ENCODER_MAP_ENABLE) const uint16_t PROGMEM encoder_map[][NUM_ENCODERS][NUM_DIRECTIONS] = { [0] = { ENCODER_CCW_CW(KC_VOLD, KC_VOLU), ENCODER_CCW_CW(MS_WHLU, MS_WHLD) } }; #endif

• 第一颗旋钮（索引 0）：逆时针KC_VOLD音量减，顺时针KC_VOLU音量加；
• 第二颗旋钮（索引 1）：逆时针MS_WHLU鼠标滚轮上滚，顺时针MS_WHLD下滚——这依赖keyboard.json中开启的mousekey特性。

其中ENCODER_CCW_CW(ccw, cw)

是 QMK 提供的方向宏，定义在 quantum/encoder.h：

#define ENCODER_CCW_CW(ccw, cw) {(cw), (ccw)}

值得注意的是该宏内部把参数对调存放：encoder_map数组的每行[NUM_ENCODERS][NUM_DIRECTIONS]中索引 0 存顺时针、索引 1 存逆时针，因此宏写成ENCODER_CCW_CW(逆时针键, 顺时针键)

的调用形式。理解这一点可以避免自定义映射时方向接反。

四、构建与烧录

在配置好 QMK 构建环境后（见 getting_started_build_tools.md），构建命令为：

make binepad/pixie:default

烧录命令：

make binepad/pixie:default:flash

构建时，keyboard.json中的processor决定平台为 RP2040（相关平台开发背景可参考 platformdev_rp2040.md），bootloader

字段决定使用 RP2040 原厂 USB 引导 ROM 进行烧录，无需额外刷写 bootloader。

进入 Bootloader 的三种方式

按照 readme 文档，PIXIE 有三种进入 RP2040 引导模式的方法：

1. Bootmagic Reset：按住矩阵坐标 (0,1) 的按键（左下角那颗，即KC_MUTE）不放，然后插入 USB 线缆；
2. 物理 Reset 按键：短按 PCB 背面的按钮；
3. 键位触发：布局中映射了QK_BOOT（或RESET）的按键，按下即重启进 bootloader。

其中 Bootmagic 特性正是keyboard.json中bootmagic: true

所启用，其通用行为在 feature_bootmagic.md 中有说明。

五、自定义建议

• 改键位：直接编辑 keymaps/default/keymap.c 的LAYOUT(...)四个位置，或使用 QMK Configurator（该键盘有layouts数据，支持可视化编辑）。
• 改旋钮行为：修改encoder_map中的键值即可，ENCODER_CCW_CW(逆时针, 顺时针)的顺序不要写反；如需按层区分旋钮功能，encoder_map支持按层数组定义。
• 新增层：keymaps[][]可添加[1]、[2]… 层并配合MO/DF等键码切换，编码器映射同样按层生效。
• 同品牌参考：binepad 目录下还有 bn003、bnk8、knobx1 等其他型号，其中 knobx1 携带了自定义编码器驱动（knobx1.c），可作为深入学习编码器自定义实现的参照。

小结

PIXIE 端口展示了现代 QMK 键盘端口的完整形态：keyboard.json声明处理器、引脚矩阵、编码器与 USB 身份；config.h仅需一行编码器分辨率宏；键位文件专注LAYOUT与encoder_map两块内容。make binepad/pixie:default

一条命令即可产出固件，配合 RP2040 原厂 bootloader 完成烧录，是研究 QMK 数据驱动配置与编码器支持的极佳最小样例。

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