QMK 键盘 Aplx6 rev2 固件指南：编码器旋钮、OLED 分层显示与媒体宏键配置
【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware
Aplx6 rev2 是 Aplyard 推出的 2×3 六键 MediaPad 的升级版，本文以其在 QMK 固件仓库中的官方文档 keyboards/aplyard/aplx6/rev2/readme.md 为主线，结合仓库内真实存在的 keyboard.json 与 默认键位 keymap.c 源码，完整讲解该键盘的硬件结构、固件编译方法、三层键位设计与编码器/OLED 的自定义开发方式。读完本文，你将能够自行编译刷写 Aplx6 rev2 固件，并按需修改旋钮功能、层切换逻辑与 OLED 显示内容。
一、硬件概览：从 2×3 媒体板到带旋钮的升级版
Aplx6 rev2 是一块 2 行 × 3 列的六键小键盘，核心定位是音乐、浏览器与文档快捷键控制。与原版 Aplx6（rev1，见 rev1/readme.md）相比，rev2 是"更新了编码器的版本"：
- 新增旋转编码器：附带按压开关，按压用于循环切换层（cycling layers）；
- 新增 OLED 显示屏：用于显示一些装饰性 Logo；
- 更多层（More layers）：默认固件内置了三层功能层。
整机采用"三明治（sandwich）"装配结构：PCB 与空白底板之间通过 M2.5 螺丝和铜柱（spacers）固定；轴体支持MX 或 Alps 兼容轴二选一；二极管使用1N4148，属于典型的低成本手焊开源项目。
硬件支持清单（来自文档）
| 项目 | 内容 |
|---|---|
| 键盘维护者（Maintainer） | Aplyard |
| 支持的硬件 | Aplx6 PCB + Pro Micro（ATmega32U4） |
| 固件入口 | keyboards/aplyard/aplx6/rev2/ |
| 默认键位 | keyboards/aplyard/aplx6/rev2/keymaps/default/ |
二、固件编译：一条 make 命令搞定
编译该键盘的默认键位，命令与 rev1 相同但路径带rev2：
make aplyard/aplx6/rev2:default前置条件是按 QMK 官方流程搭建好编译环境。若你是 QMK 新手，仓库内提供了完整的入门资料：构建环境搭建、make 编译说明 以及 全新入门指南（Complete Newbs Guide）。
硬件配置与引脚定义
固件采用>#define KC_COPY LCTL(KC_C) // Mac 系统请改为 LGUI(KC_C) #define KC_CUT LCTL(KC_X) // Mac 系统请改为 LGUI(KC_X) #define KC_PASTE LCTL(KC_V) // Mac 系统请改为 LGUI(KC_V) //#define KC_MY_COMPUTER LGUI(KC_SPC) // 取消注释可让该键在 Mac 上触发 Spotlight 搜索
从源码注释可见：默认按 Windows/Linux 的Ctrl+C/X/V实现复制剪切粘贴；若在 macOS 上使用，需将三处LCTL替换为LGUI；若希望"我的电脑"键在 Mac 上变成 Spotlight 搜索，可取消最后一行的注释。这是一个很好的、面向跨平台使用者的定制示例。
四、旋转编码器：按层执行不同动作
Aplx6 rev2 的核心卖点是编码器。在 QMK 中，用户只需在键位文件中实现弱函数encoder_update_user，即可接管旋钮行为。该回调由量子层 quantum/encoder.c 在编码器事件发生时自动调用，其声明位于 quantum/encoder.h。默认键位中的实现如下（节选关键逻辑）：
bool encoder_update_user(uint8_t index, bool clockwise) { if (index == 0) { switch (get_highest_layer(layer_state)) { case 1: // _DOC 层：左右翻页/移动光标 clockwise ? tap_code(KC_RIGHT) : tap_code(KC_LEFT); break; case 2: // _POWER 层：调节屏幕亮度 clockwise ? tap_code(KC_BRIU) : tap_code(KC_BRID); break; default: // _MEDIA 层：调节系统音量 clockwise ? tap_code(KC_VOLU) : tap_code(KC_VOLD); } } return true; }这套设计很有参考价值：旋钮功能与当前所在层联动——媒体层调音量、文档层左右移动光标、效率层调亮度，源码中每一处都留有//edit here your ... encoder keycode注释，方便你改成KC_MEDIA_NEXT_TRACK、KC_PGDN等任意键码。由于键盘只有一个旋钮，index == 0的判断也展示了多旋钮设备下的标准分支写法。
编码器的物理配置在 rev2/keyboard.json 中声明：
"encoder": { "rotary": [ {"pin_a": "F5", "pin_b": "F4"} ] }层状态读取使用get_highest_layer(layer_state)，与 OLED 的 Logo 切换逻辑（见下节）保持一致，确保"屏幕显示的 Logo"与"旋钮触发的动作"始终对应同一层。
五、OLED 显示：随层切换的位图 Logo
文档提到 rev2 新增了 OLED 用于显示"一些好看的 Logo（some fancy logos）"。默认键位在#if defined(OLED_ENABLE)条件编译块内实现了完整的渲染逻辑：
render_logo()中内置三张 128×32 像素级位图数组logo1 / logo2 / logo3（以PROGMEM存放，节省 RAM），分别对应_MEDIA、_DOC、_POWER三个层；- 通过
switch (get_highest_layer(layer_state))判断当前层，用oled_write_raw_P()将对应位图直接写入显示缓冲； - 用户回调
oled_task_user()每帧调用render_logo()并返回false，表示完全接管屏幕、不再绘制默认文本。
switch (get_highest_layer(layer_state)) { case 1: oled_write_raw_P(logo2, sizeof(logo2)); break; case 2: oled_write_raw_P(logo3, sizeof(logo3)); break; default: oled_write_raw_P(logo1, sizeof(logo1)); }这套"层 → 位图"的映射模式可直接复用：比如为自定义层新增一张位图，只需仿照logo1的结构再声明一个数组，并在switch中增加case分支。位图数据来源于真实按键图案，属于开源硬件社区常用的"像素画转数组"工作流。
六、与 rev1 的对比：升级了什么
结合仓库中 rev1 与 rev2 的源码，可以精确归纳两版差异：
| 维度 | Aplx6 rev1 | Aplx6 rev2 |
|---|---|---|
| 矩阵引脚 | colsF7/B6/F4，rowsE6/B3 | colsC6/D7/E6，rowsB4/B5 |
| 编码器 | 无 | 有（F5/F4，含按压键） |
| OLED | 无 | 有（三层位图 Logo） |
| 层数 | 2 层（MO(1)临时层） | 3 层（TO(n)循环切换） |
| 功能开关 | 无 encoder/oled | 增加encoder、oled，新增tap_keycode_delay |
升级的核心思路是：rev1 靠 Fn 临时层做媒体+系统快捷键，rev2 则用"旋钮按压 → 切层 → 旋钮旋转 → 执行层内动作"的交互闭环替代按键切层，配合 OLED 视觉反馈，交互效率更高。
七、二次开发建议与资料索引
如果你打算基于 Aplx6 rev2 做自己的键位，可按以下路径修改（仓库为只读，请先克隆到本地再进行开发）：
- 改键位：复制
keymaps/default/为自定义目录，编辑keymap.c中三个LAYOUT(...)块，参考 keymap.md 与 feature_layers.md； - 改旋钮动作：在
encoder_update_user中替换tap_code()的键码，键码全集见 keycodes.md； - 改 OLED：在
render_logo()中新增/替换位图数组，位图绘制 API 详见 feature_oled_driver.md； - 改硬件配置：如需调整引脚或功能开关，编辑
keyboard.json，可对照 reference_info_json.md 的 schema 说明； - 编译刷写：重新执行
make aplyard/aplx6/rev2:<你的键位名>，刷写步骤见 newbs_flashing.md。
本项目设计阶段使用的工具链也记录在 rev2 文档中：PCB 用 [KiCad] 设计，元件封装库包括 MX_Alps_Hybrid（同时兼容 MX 与 Alps 轴体）、keebs.pretty、keyboard_parts.pretty 与 ProMicro KiCad；辅助设计可借助 QMK Online Configurator 在线配置、Keyboard Layout Editor 编辑配列、Keyboard Plate & Case Builder 生成定位板与外壳。这些工具均为键盘 DIY 社区的标准流程，与本文讲解的固件配置相辅相成。
【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
