企业官网建设流程全解析

QMK 键盘 Vector Macropad 固件指南：1×4 旋钮宏键盘的构建、刷写与编码器映射

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

The Vector 是 Array Peripherals 出品的一款小型 1×4 宏键盘（Macropad），在四颗按键之外还集成了一颗旋转编码器（rotary encoder），属于 QMK 固件仓库keyboards/arrayperipherals/vector目录下的官方支持键盘。本篇指南将以该键盘的官方 readme 为主体，结合仓库内的 keyboard.json、默认键位 以及 QMK 编码器特性文档（docs/features/encoders.md）与底层实现（quantum/encoder.h），带你完整掌握 Vector 的硬件定义、编译烧录流程、两种进入 Bootloader 的方式，以及如何利用编码器映射（Encoder Map）在分层键位中自由分配旋钮功能。

硬件概览：1×4 按键加一颗旋钮

根据 readme.md 与 keyboard.json，Vector 的硬件规格如下：

• 主控芯片：Atmel ATmega32u4（8-bit AVR 系列）
• 按键矩阵：4 颗按键 + 1 个编码器按键位（可按下），采用直连矩阵（direct matrix）
• 旋转编码器：1 颗，接在 F0 / F1 两个引脚上
• Bootloader：atmel-dfu（Atmel 官方 DFU 协议）
• 维护者：David Doan（GitHub 用户名daviddoan）

仓库中的keyboard.json精确记录了这套硬件的电气连接：

{ "manufacturer": "Array Peripherals", "keyboard_name": "The Vector", "maintainer": "daviddoan", "bootloader": "atmel-dfu", "encoder": { "rotary": [ {"pin_a": "F0", "pin_b": "F1"} ] }, "features": { "bootmagic": true, "encoder": true, "extrakey": true, "mousekey": true }, "matrix_pins": { "direct": [ ["D4", "C6", "D7", "E6", "F7"] ] }, "processor": "atmega32u4", "usb": { "device_version": "1.0.0", "pid": "0x4F47", "vid": "0x4152" }, "layouts": { "LAYOUT": { "layout": [ {"label": "k01", "matrix": [0, 0], "x": 0, "y": 0}, {"label": "k02", "matrix": [0, 1], "x": 1, "y": 0}, {"label": "k03", "matrix": [0, 2], "x": 2, "y": 0}, {"label": "k04", "matrix": [0, 3], "x": 3, "y": 0}, {"label": "k05", "matrix": [0, 4], "x": 4.25, "y": 0} ] } } }

值得注意的细节：

• 从"features"中可以看到 Vector 在固件层面默认启用了bootmagic、encoder、extrakey与mousekey四个特性，前两者分别服务于“免工具进入 Bootloader”与“旋转编码器”两个核心功能。
• 布局LAYOUT中定义了 5 个键位：k01～k04 对应四颗普通按键（x 坐标 0～3），而 k05 位于 x=4.25 处，它是编码器自带的按压开关。也就是说，旋钮本身还具备一个可编程的按下动作，与四个按键加起来一共可定义 5 个输入点，这与默认键位中LAYOUT(...)传入 5 个键码的事实完全吻合。

编译与烧录：两条命令搞定

在搭建好 QMK 构建环境后，Vector 的编译和烧录都非常直接。readme 给出了官方推荐的两条命令：

# 编译默认键位固件 make arrayperipherals/vector:default # 编译并烧录 make arrayperipherals/vector:default:flash

其中arrayperipherals/vector是键盘路径，default是键位名（对应 keymaps/default/ 目录）。make ...:flash会在编译完成后自动调用atmel-dfu烧录流程，把生成的.hex写入芯片。

如果你是 QMK 新手，仓库文档提供了两条标准路线：

• 构建环境搭建指南：负责安装工具链与 QMK CLI；
• make 使用指南：讲解make <keyboard>:<keymap>的完整语法与常用目标。

进入 Bootloader 的两种方式

readme 明确列出了 Vector 的两种复位方式，在烧录固件前必须掌握：

1. Bootmagic reset（免工具复位）：按住矩阵中坐标 (0,0) 的那个键再插入 USB。由于 Vector 采用直连矩阵，matrix_pins.direct数组的第一项是 D4，对应布局中的 k01——也就是从编码器方向看最左边的那颗按键。这一方式得益于keyboard.json中开启的bootmagic特性。
2. 物理复位按钮：短按两下 PCB 背面的复位按钮（briefly double press）。

两种方式最终都会让芯片进入atmel-dfu引导程序，此时即可通过make arrayperipherals/vector:default:flash完成烧录。

默认键位剖析：媒体键 + 旋钮音量 + 分层切换

仓库自带的默认键位在 keymaps/default/keymap.c 中，内容如下（已去除 GPL 许可证头）：

#include QMK_KEYBOARD_H const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { [0] = LAYOUT( KC_MPRV, KC_MPLY, KC_MNXT, KC_MUTE, TG(1) ), [1] = LAYOUT( KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, TG(1) ), }; #if defined(ENCODER_MAP_ENABLE) const uint16_t PROGMEM encoder_map[][NUM_ENCODERS][NUM_DIRECTIONS] = { [0] = {ENCODER_CCW_CW(KC_VOLD, KC_VOLU)}, [1] = {ENCODER_CCW_CW(KC_TRNS, KC_TRNS)}, }; #endif // ENCODER_MAP_ENABLE

逐项解读这份键位：

• 第 0 层（默认层）：四颗按键依次为上一首（KC_MPRV）、播放/暂停（KC_MPLY）、下一首（KC_MNXT）、静音（KC_MUTE），旋钮按下键为TG(1)——单击即可切换到第 1 层，再按一次切回。
• 第 1 层：四颗按键全部为KC_TRNS（透传，沿用上一层行为），旋钮按键同样保留TG(1)用于切回默认层。这是典型的分层宏键盘设计：旋钮按键充当“层开关”，让同一颗旋钮在不同层里担任不同职责。
• 编码器映射：在第 0 层，逆时针旋转（CCW）触发KC_VOLD（音量减），顺时针旋转（CW）触发KC_VOLU（音量加）；在第 1 层则均为透传，避免在媒体控制层之外误触发音量调节。

keymaps/default/rules.mk中只有一行关键配置：

ENCODER_MAP_ENABLE = yes

它开启了编码器映射（Encoder Map）特性，让旋钮行为能够像普通按键一样按层定义。

深入原理：Encoder Map 是如何工作的

与默认回调的区别

如果不启用ENCODER_MAP_ENABLE，QMK 编码器的默认行为是：所有编码器统一映射为顺时针音量加、逆时针音量减，由 quantum/encoder.c 中的encoder_update_kb/encoder_update_user回调链处理。这种做法的局限在于无法区分不同的编码器，也无法按层切换行为。

而 Encoder Map 把编码器纳入了与按键一致的“分层键码”体系。正如 docs/features/encoders.md 所述，启用后需在keymap.c中定义如下结构：

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

这个三维数组的第一维是层号，第二维是编码器序号（NUM_ENCODERS），第三维是旋转方向（NUM_DIRECTIONS，固定为 2）。

宏与数据结构的底层定义

ENCODER_CCW_CW(ccw, cw)与NUM_DIRECTIONS的实际定义位于 quantum/encoder.h：

# ifdef ENCODER_MAP_ENABLE # define NUM_DIRECTIONS 2 # define ENCODER_CCW_CW(ccw, cw) {(cw), (ccw)} extern const uint16_t encoder_map[][NUM_ENCODERS][NUM_DIRECTIONS]; # endif // ENCODER_MAP_ENABLE

注意ENCODER_CCW_CW内部将参数顺序做了对调：展开后{(cw), (ccw)}，即数组第 0 项是顺时针键码、第 1 项是逆时针键码，与宏的语义“CCW 参数在前”相反。这属于实现细节，普通键位作者只需按ENCODER_CCW_CW(逆时针功能, 顺时针功能)的语义书写即可，无需关心内部存储顺序。

对于非分体键盘（如 Vector），NUM_ENCODERS由ENCODER_A_PINS引脚数组的长度推导（quantum/encoder.h）；Vector 通过keyboard.json中的encoder.rotary数据驱动方式生成了该定义，因此只有一个编码器时NUM_ENCODERS恒为 1。

事件处理管线

启用 Encoder Map 后，旋钮事件会以 “keydown / keyup” 的成对形式进入 QMK 常规键码处理管线，经由process_record_xxxxx()等函数处理——这意味着你在按键上能用的层切换、宏、背光/自定义功能等一切特性，对旋钮同样生效。文档还建议：若需调整旋钮“keyup”与“keydown”之间的间隔，可在config.h中配置：

#define ENCODER_MAP_KEY_DELAY 10

默认情况下该延迟等于TAP_CODE_DELAY的值（见 docs/features/encoders.md）。

此外，从源码结构还可以看到，编码器事件在 quantum/encoder.h 中通过环形队列（encoder_event_t+encoder_events_t）进行缓冲，MAX_QUEUED_ENCODER_EVENTS会随每侧编码器数量自动调整；quantum/action_layer.c、quantum/action.c中也对ENCODER_MAP_ENABLE场景下的层缓存与换手（swap hands）处理做了适配。这些机制保证了快速旋转旋钮时事件不会丢失。

自定义你的 Vector：从改键位到换旋钮功能

新建自己的键位目录

在仓库中，每个键位是keyboards/arrayperipherals/vector/keymaps/<名字>/下的一个目录。最简单的做法是复制default目录，然后修改其中的keymap.c：

[0] = LAYOUT( KC_A, KC_B, KC_C, KC_D, MO(1) ), [1] = LAYOUT( KC_1, KC_2, KC_3, KC_4, KC_TRNS ),

例如把四颗键改为字母 A～D，旋钮按下键用MO(1)实现“按住进入第 1 层、松开返回第 0 层”（与默认键位的TG(1)单击切换行为不同，可按使用习惯选用）。

调整旋钮功能

如果不需要按层切换旋钮行为，也可以移除rules.mk中的ENCODER_MAP_ENABLE = yes，改用经典回调方式，在键位的 C 文件中定义：

bool encoder_update_user(uint8_t index, bool clockwise) { if (clockwise) { tap_code(KC_PGDN); } else { tap_code(KC_PGUP); } return false; }

这样无论处于哪一层，旋钮都统一执行翻页功能。两种方式各有适用场景：Encoder Map适合“不同层旋钮不同用途”的复杂配置；回调方式适合“全局统一行为”的简单需求。

关于 keymap 级特性的说明

QMK 官方文档特别提醒：ENCODER_MAP_ENABLE这类特性应当在keymap 层级的rules.mk中开启，而不是键盘根目录——Vector 的默认键位正是遵循了这一规范。自定义键位时也请保持同样的文件组织方式，避免影响其他键位的编译。

快速参考

在此基础上，你可以进一步阅读 docs/features/encoders.md 了解编码器回调、分辨率（resolution）与分体键盘配置的完整细节，或参考 docs/feature_layers.md 设计更多层的功能分配，把 Vector 打造为适合自己工作流的媒体控制与快捷键中枢。

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