QMK 固件之 Atreyu 键盘完全指南：Lily58 与 Sofle 的“非分体”混血儿编译、刷写与键位定制-平芜编程栈

QMK 固件之 Atreyu 键盘完全指南：Lily58 与 Sofle 的“非分体”混血儿编译、刷写与键位定制

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

Atreyu 是 QMK Firmware 仓库中一款基于 Atmel AVR 架构的客制化机械键盘固件支持项目，其定位是“一款未分体（unsplit）的、Lily58 与 Sofle 结合体”键盘。本文以 keyboards/atreyu/readme.md 为骨架，结合仓库内 info.json、rev1/keyboard.json、rev2/keyboard.json 以及默认键位图源码，完整讲解该键盘的硬件特征、编译与刷写命令、Bootloader 三种进入方式、分层键位设计与源码级实现细节，帮助你从零开始为 Atreyu 编译、烧录并定制属于自己的固件。

一、Atreyu 键盘概述：Lily58 与 Sofle 的混血设计

根据官方 readme，Atreyu 被定义为"An unsplit, modified version of a Lily58 having a baby with a Sofle keyboard"——即一款移植并修改自 Lily58、同时又吸收了 Sofle 设计思路的**单块 PCB（unsplit）**键盘。它保留了这两款知名分体键盘的人体工学错落配列（各排按键带阶梯式 y 坐标偏移），但去掉了左右分体结构，整体为一块完整的 PCB。

键盘维护者（Maintainer）：Jesus Climent
支持的硬件：AtreyuKeyboard PCB、ProMicro 主控
硬件资料：PCB 与外壳数据由维护者在个人仓库中开源提供

从仓库目录结构看，Atreyu 存在两个硬件版本：

版本	目录	说明
Rev1	keyboards/atreyu/rev1/	初版 PCB
Rev2	keyboards/atreyu/rev2/	修订版 PCB

两个版本共享同一套键位图目录keymaps/与顶层 info.json，各自通过keyboard.json描述硬件差异（详见下文“硬件配置解析”一节）。

二、构建环境准备与编译命令

1. 环境搭建

编译前需要先搭建 QMK 构建环境。仓库中的官方文档提供了完整指引，建议按以下顺序阅读：

初次接触 QMK 的完整新手教程：Complete Newbs Guide（docs/newbs.md）与 docs/newbs_getting_started.md
构建环境安装：docs/getting_started_introduction.md 中关于工具链安装的部分
Make 编译说明：docs/getting_started_make_guide.md

在完成环境安装后，即可在仓库根目录执行编译。

2. 编译默认键位

Atreyu 的编译命令为：

make atreyu:default

该命令会以keyboards/atreyu为键盘目标、keymaps/default为键位目标进行构建。default键位图的完整源码位于 keyboards/atreyu/keymaps/default/keymap.c，同时包含 config.h 与 rules.mk。

3. 编译并刷写

刷写固件使用:flash目标：

make atreyu:default:flash

执行后 QMK 会先完成编译，再调用对应烧录工具将固件写入主控。由于 Atreyu 使用 ProMicro 主控、atmega32u4处理器与atmel-dfu引导程序（见 rev1/keyboard.json 中的"processor"与"bootloader"字段），刷写前请确认系统已正确安装对应驱动与烧录工具，详细刷写方法可参考 docs/flashing.md。

三、进入 Bootloader 的三种方式

Atreyu 的 readme 明确指出有3 种进入 Bootloader（引导程序）的方法，适用于刷写固件前的准备：

Bootmagic 复位（Bootmagic reset）：按住矩阵中(0,0)位置对应的按键（通常是左上角第一颗键或 Esc 键），然后插入 USB 供电。该功能依赖顶层 info.json 中启用的"bootmagic": true特性，QMK 会在上电时检测该按键是否被按住。
PCB 物理复位按钮：短按 PCB 背面的复位按钮；部分批次没有按钮，而是需要短接标出的焊盘（pads）。
键位中的复位键码：如果当前键位图将某个按键映射为QK_BOOT，直接按下该键即可进入引导程序。

四、硬件配置解析：Rev1 与 Rev2 的差异

Atreyu 采用 QMK 的“数据驱动配置”（data-driven configuration）方式，硬件描述全部集中在keyboard.json中，无需手写config.h引脚定义。对比两个版本可清晰看到演进差异。

1. USB 标识与固件版本

字段	Rev1	Rev2
keyboard_name	Atreyu	Atreyu
manufacturer	Heyzeus	Heyzeus
VID	0xFEED	0xFEED
PID	0x0001	0x0001
device_version	0.0.1	0.0.2

两个版本使用相同的 VID/PID，仅通过device_version（0.0.1 → 0.0.2）区分硬件修订。

2. 矩阵与二极管方向

两版本均为10 行 × 6 列的矩阵、COL2ROW二极管方向，但列引脚有调整：

Rev1：cols =C6, D4, D0, D1, D2, D3；rows =D7, E6, B4, B5, F6, F7, B1, B3, B6, B2
Rev2：cols =F4, F5, C6, D4, D2, D3；rows 与 Rev1 完全一致

3. 旋转编码器（Rotary Encoder）

两版本在编码器配置上差异显著：

Rev1：板载1 个编码器，引脚F5/F4；同时声明了 split 配置中的右侧编码器（F4/F5，左右对称），为后续分体扩展预留。
Rev2：板载2 个编码器，引脚分别为D5/B7与D5/C7。

不过需要注意，默认键位图的 rules.mk 中明确写入ENCODER_ENABLE = no，即默认键位未启用编码器功能；若需要使用编码器，需在自建键位图中启用该特性。

4. 配列信息（LAYOUT）

顶层 rev1/keyboard.json 中定义了名为LAYOUT的配列，共 60 个键位（每行 6 键 × 10 行，含左右两半与拇指区）。每个键位通过matrix: [row, col]与x/y坐标（支持h高度扩展）描述物理位置。以拇指区为例：

{"matrix": [8, 4], "x": 6, "y": 4.25, "h": 1.25}, {"matrix": [9, 4], "x": 9.5, "y": 4.25, "h": 1.25}

这两颗 1.25 倍高的键位正是 Lily58/Sofle 风格的拇指簇设计。Rev2 的LAYOUT定义与 Rev1 完全一致，仅矩阵引脚与编码器不同。

五、默认键位图源码解析

默认键位图 keymaps/default/keymap.c 完整展示了 Atreyu 的出厂键位逻辑，也是学习如何为该键盘定制键位的范例。

1. 层结构：四层 + 自定义键码

键位图定义了 4 个层和 4 个自定义键码：

enum custom_layers { _QWERTY, // 默认输入层 _LOWER, // 下层 _RAISE, // 上层 _ADJUST // 调整层（LOWER+RAISE 同时按下触发） }; enum custom_keycodes { QWERTY = SAFE_RANGE, // 自定义键码从 SAFE_RANGE 之后开始 LWR, // LOWER 层开关 RSE, // RAISE 层开关 ADJ };

_QWERTY层为标准的 QWERTY 输入布局，字母区两侧各 6 键，拇指区布置了LWR（左侧）、RSE（右侧）等。
_RAISE层提供导航与符号：如KC_HOME/KC_END、方向键KC_LEFT/KC_DOWN/KC_RGHT/KC_UP、KC_LCBR/KC_RCBR、KC_PIPE等，且大量使用_______（透明）继承下层按键。
_LOWER层提供 F 区功能键KC_F1~KC_F10、音量控制KC_VOLU/KC_VOLD、KC_CAPS，以及TG(_RAISE)（切换 RAISE 层）和AG_TOGG（切换 GUI/Cmd 与 Ctrl 位置）。
_ADJUST层当前全部填充XXXXXXX（屏蔽）与透明键，作为预留的调整层。

2. 三层层叠（Tri-Layer）逻辑

LWR与RSE键通过process_record_user()实现按下/释放时的层开关，并在同时按下两者时自动进入_ADJUST层：

case LWR: if (record->event.pressed) { layer_on(_LOWER); update_tri_layer(_LOWER, _RAISE, _ADJUST); } else { layer_off(_LOWER); update_tri_layer(_LOWER, _RAISE, _ADJUST); } return false;

update_tri_layer(_LOWER, _RAISE, _ADJUST)是 QMK 提供的标准函数：当_LOWER与_RAISE同时处于开启状态时自动激活_ADJUST层，释放任意一个则自动退出。

3. 组合键技巧：GUI + Esc 输出反引号

在process_record_user()中还有一个巧妙的处理：当按住左 GUI（Cmd/Win）键时按下KC_ESC，会改为输出反引号`（KC_GRV）：

case KC_ESC: if ((get_mods() & MOD_BIT(KC_LGUI)) == MOD_BIT(KC_LGUI)) { if (record->event.pressed) { register_code(KC_GRV); } else { unregister_code(KC_GRV); } return false; } return true;

这模拟了 macOS 键盘上“GUI 键被占用后 Esc 位置改放 `”的常见习惯，属于典型的 QMK 用户态按键重映射范例。

4. 键位图级配置：config.h 与 rules.mk

keymaps/default/config.h 覆盖了两项行为：

#ifdef TAPPING_TERM #undef TAPPING_TERM #define TAPPING_TERM 150 #endif #define RETRO_TAPPING

TAPPING_TERM 150：将敲击判定窗口缩短为 150ms，适用于快速键入场景（默认通常为 200ms）。
RETRO_TAPPING：启用“回溯敲击”，当按键被按住超过 TAPPING_TERM 后才释放时，仍会按“先敲击后按住”的逻辑处理，改善 Mod-Tap 类按键的输入体验。

而 rules.mk 中ENCODER_ENABLE = no则表明默认键位未启用编码器。

六、编码器底层实现：rev1.c 与 rev2.c

虽然默认键位未启用编码器，但两个版本目录下的 rev1.c 与 rev2.c 均已实现键盘级（_kb）的编码器处理回调，代码完全一致：

#ifdef ENCODER_ENABLE bool encoder_update_kb(uint8_t index, bool clockwise) { if (!encoder_update_user(index, clockwise)) { return false; } if (index == 1) { if (clockwise) { tap_code(KC_VOLU); // 编码器 1 顺时针 → 音量加 } else { tap_code(KC_VOLD); // 编码器 1 逆时针 → 音量减 } } if (index == 0) { if (clockwise) { tap_code(MS_WHLU); // 编码器 0 顺时针 → 鼠标滚轮上 } else { tap_code(MS_WHLD); // 编码器 0 逆时针 → 鼠标滚轮下 } } return true; } #endif

从源码结构可以推断：

该实现同时兼容 Rev1（1 个编码器）与 Rev2（2 个编码器）：index == 0的编码器控制鼠标滚轮（配合顶层 info.json 中启用的mousekey特性），index == 1的编码器控制系统音量。
回调首先调用encoder_update_user()，这是 QMK 提供给用户态（键位图）的钩子：如果用户在键位图中定义了同名函数并返回false，键盘级处理会被跳过，从而允许用户完全接管编码器行为。这是标准的 QMK 钩子分层机制。
整体逻辑由ENCODER_ENABLE宏保护，只有在键位图/规则文件中启用编码器特性时才会编译进固件。

七、顶层特性配置：info.json

Atreyu 顶层的 info.json 声明了固件默认编译进哪些 QMK 特性：

{ "features": { "bootmagic": true, "mousekey": true, "extrakey": true, "nkro": true } }

特性	作用
`bootmagic`	支持上电按住 (0,0) 键进入引导程序（对应上文 Bootloader 方式一）
`mousekey`	启用鼠标键功能，供编码器滚轮（`MS_WHLU/MS_WHLD`）与鼠标键键码使用
`extrakey`	启用系统/媒体键（如音量`KC_VOLU/KC_VOLD`），供编码器与`_LOWER`层使用
`nkro`	启用 N 键无冲突（N-Key Rollover），支持多键同时按下

这四个特性与默认键位图及编码器实现形成了完整的依赖闭环：extrakey与mousekey支撑了 rev1/rev2.c 中的音量/滚轮键码，bootmagic支撑了刷写流程中的 Bootmagic 复位方式。

八、从零定制 Atreyu 键位图

在了解上述源码结构后，你可以基于仓库现有材料快速创建自己的键位图：

复制默认键位目录：以 keyboards/atreyu/keymaps/default/ 为模板，在keymaps/下新建一个命名字目录（如keymaps/mykeymap/），包含keymap.c、config.h、rules.mk。
修改键位层：参照 keymap.c 中的LAYOUT(...)宏填充自己的按键映射，可用_______透明键继承下层，用XXXXXXX屏蔽按键。
调整行为参数：在config.h中按需覆盖TAPPING_TERM、启用RETRO_TAPPING等。
启用编码器：如需使用编码器，在rules.mk中设置ENCODER_ENABLE = yes；可在keymap.c中实现encoder_update_user()覆盖键盘级的默认音量/滚轮逻辑。
编译与刷写：执行make atreyu:mykeymap编译，make atreyu:mykeymap:flash刷写；若需更换引导方式，可参考上文三种 Bootloader 进入方式。

九、总结

Atreyu 作为一款 Lily58 与 Sofle 的“非分体”混血键盘，其 QMK 支持完整展示了现代 QMK 数据驱动配置的典型形态：硬件差异通过 rev1/keyboard.json 与 rev2/keyboard.json 描述、特性开关集中在 info.json、键位逻辑沉淀在 keymaps/default/keymap.c，而编码器这类硬件功能则在 rev1.c / rev2.c 中以标准_kb/_user钩子分层实现。掌握make atreyu:default:flash的编译刷写流程、三种 Bootloader 进入方式以及四层键位与 tri-layer 逻辑，即可完整驾驭这款键盘的固件定制。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考