QMK 固件中的 AKB VeroHHKB 配列机械键盘的构建、刷写与配置指南【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmwareAKB Vero 是挪威键盘工作室 Antipode 推出的一款 60% HHKB 配列机械键盘官方支持已经合入 QMK Firmware 仓库位于keyboards/akb/vero/。本文以该键盘的官方 readme 文档为骨架结合仓库内的keyboard.json、矩阵示意图与五套官方默认键位系统讲解 AKB Vero 的硬件规格、固件构建与烧写流程、Bootloader 三种进入方式以及如何基于官方键位定制自己的布局帮助你从拿到 PCB 到刷入第一份固件全流程上手。硬件概况与命名由来Vero 在意大利语中意为真实AKB Vero 的设计目标就是把经典的 HHKB 布局原汁原味地带到 MX 轴机械键盘上。其最显著的特征包括真正的 HHKB 配列与传统 60% 键盘不同HHKB 配列将 Ctrl 键放在 A 键左侧即 Caps Lock 位置并以 6U 空格和左右不对称挡块blockers还原 HHKB 的经典外形。6U 空格 不对称挡块底部区域左侧有 Alt、GUI 键位右侧对称放置 GUI、Alt中间是 6U 空格视觉上复刻 HHKB 的对称美感。可选的 2U Backspace 与 Split Space仓库内的矩阵图与键位定义显示PCB 同时支持 2U 退格、6U 空格、分体空格split space以及 ISO 回车等变体覆盖 ANSI 与 ISO 两种主流标准。以下为官方 readme 中提供的硬件信息项目说明Keyboard MaintainerAntipodeQMK 内维护者为arnstadmHardware SupportedAKB Vero PCBHardware Availability见官方产品页https://www.antipode.no/products/akb-vero处理器STM32F411见 keyboard.jsonBootloaderSTM32 DFUstm32-dfu提示本文中的硬件购买信息仅来源于仓库 readme购买前请以官方渠道为准。从零构建固件QMK 采用键盘路径 键位名的方式定位目标。设置好构建环境后为 AKB Vero 编译默认键位的固件只需一条命令make antipode/vero:default这里antipode/vero是键盘在 QMK 仓库中的完整路径keyboards/akb/verodefault是对应键位目录名。编译产物通常是.bin或.hex文件位于 QMK 的构建输出目录中。如果你刚接触 QMK建议先按官方流程准备环境首次使用 QMK 的用户先阅读 Complete Newbs Guide 完成环境搭建构建环境的详细配置见 Getting Started - Build Tools 与 Getting Started - Make Guide这两个链接在原文档中指向外部站点本仓库的对应文档如上所示。一次构建、多重目标QMK 的 make 目标支持叠加多种后缀常用的组合有目标作用make antipode/vero:default只编译不烧录make antipode/vero:default:flash编译并尝试烧录自动进入 DFU 模式make antipode/vero:default:dfu编译并使用 DFU 工具烧录STM32F411 常用make antipode/vero:default:clean清理该目标的构建缓存对于 STM32F411 stm32-dfu的板子flash目标底层会调用 dfu-util 完成下载详见 QMK 文档 Flashing。刷写固件Flashing官方 readme 给出的烧录命令为make antipode/vero:default:flash执行该命令时QMK 会先编译固件然后等待键盘进入 DFU 模式并自动写入。需要特别注意的是烧录前必须先让键盘进入 Bootloader见下文否则工具会一直等待设备出现。部分 PCBA 上的 STM32 需要短接 BOOT0 跳线才能进入 DFU请结合自己的 PCB 版本操作。Bootloader 的三种进入方式官方 readme 明确列出了三种进入 Bootloader 的方式这是刷机成败的关键Bootmagic 重置按住矩阵 (0,0) 位置的按键通常是左上角第一个键或 Esc 键同时插入 USB 线。这是 QMK 的 Bootmagic 功能默认在 keyboard.json 中通过bootmagic: true启用。物理重置按钮短按 PCB 背面的重置按钮部分版本可能没有按钮而是需要短接对应的焊盘。键位中的 RESET 键码如果当前键位把某个键映射为RESET键码按下该键即可软复位进入 Bootloader。Vero 官方键位没有直接放置RESET你可以参考下文在自定义键位中加入。进入 Bootloader 后板子会以 STM32 DFU 设备出现在系统中设备 VID/PID 见 keyboard.json 中的0x4150:0x5645这是键盘正常工作时的 USB 标识DFU 模式下 QMK 会自动识别随后执行make ...:flash即可完成写入。硬件配置与矩阵解析keyboard.json数据驱动的硬件定义AKB Vero 采用 QMK 的数据驱动配置data-driven config方式所有硬件参数集中在 keyboard.json{ manufacturer: AKB, keyboard_name: Vero, maintainer: arnstadm, bootloader: stm32-dfu, diode_direction: COL2ROW, features: { bootmagic: true, extrakey: true, mousekey: true, nkro: true }, matrix_pins: { cols: [A13, B3, A15, A14, B0, A7, A6, A5, A4, A3, A2, A1, B7, B6, B5], rows: [B15, B4, A0, B13, B14] }, indicators: { caps_lock: B1 }, processor: STM32F411, usb: { device_version: 1.0.0, pid: 0x5645, vid: 0x4150 } }关键字段解读diode_direction: COL2ROW二极管方向为列到行即扫描时列驱动、行读取这是矩阵扫描正确工作的前提。matrix_pins15 根列线A13…B5与 5 根行线B15…B14对应一个 5×15 的矩阵最大可承载 75 个开关位Vero 实际使用了其中大部分位置。processor: STM32F411主控为 STM32F411属于 ARM Cortex-M4F 系列配合stm32-dfuBootloader。features默认开启 Bootmagic、多媒体键extrakey、鼠标键mousekey与 N 键无冲突NKRO满足日常办公与轻度游戏需求。indicators.caps_lock: B1Caps Lock 状态指示灯接在 B1 引脚QMK 会自动管理该灯。usbVID 0x4150、PID 0x5645、设备版本 1.0.0是键盘枚举为 USB HID 设备时的标识。矩阵示意图仓库提供了 matrix_diagram.md用 ASCII 图清晰标出了每个物理键位对应的矩阵坐标例如左上角00即矩阵 (0,0)是 Bootmagic 触发键第一行00…0E对应 Esc 到反引号右侧0D标注为 2U Backspace底部41 / 42 / 45 / 47 / 4A / 4B对应 Alt / GUI / 左空格 / 右空格 / GUI / Alt其中45与47配合 6U 空格或分体空格使用2D与2C区域显示 ISO Enter 的可选位置。时钟配置细节Vero 的 PCB 使用 16 MHz 晶振仓库中两处配置对此做了针对性调整board.h 将STM32_HSECLK重定义为16000000Umcuconf.h 将 PLL 的 M 分频系数从 F411 通用默认值 4 改为 8注释明确说明原因板载 16 MHz 晶振。这两处改动保证了主控能正确从 16 MHz 晶振倍频出系统时钟刷写官方固件后即可正常运行无需用户额外干预。五套官方键位从标准到真 HHKBkeymaps/目录下提供了 5 套官方键位覆盖了 Vero 的所有配列变体键位目录配列说明defaultLAYOUT_all全键位ANSI 2U 退格 分体空格功能最全default_true_hhkbLAYOUT_60_true_hhkb真 HHKB6U 空格、ANSI 回车default_true_hhkb_split_spaceLAYOUT_60_true_hhkb_split_space真 HHKB 分体空格两块 3Udefault_true_hhkb_isoLAYOUT_60_true_hhkb_iso真 HHKB ISO 回车default_true_hhkb_iso_split_spaceLAYOUT_60_true_hhkb_iso_split_space真 HHKB ISO 回车 分体空格不同配列对应 keyboard.json 中声明的 5 个 LAYOUT 宏键位文件通过LAYOUT_all/LAYOUT_60_true_hhkb等宏把键码映射到矩阵坐标。编译某个变体只需切换键位名例如make antipode/vero:default_true_hhkb make antipode/vero:default_true_hhkb_iso_split_space官方默认键位示例以defaultLAYOUT_all为例keymaps/default/keymap.c 的第 0 层是标准 HHKB 布局[0] LAYOUT_all( KC_ESC, KC_1, KC_2, KC_3, KC_4, KC_5, KC_6, KC_7, KC_8, KC_9, KC_0, KC_MINS, KC_EQL, KC_BSLS, KC_GRV, KC_TAB, KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Y, KC_U, KC_I, KC_O, KC_P, KC_LBRC, KC_RBRC, KC_BSPC, KC_LCTL, KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_QUOT, KC_NUHS, KC_ENT, KC_LSFT, KC_NUBS, KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, KC_RSFT, MO(1), KC_LALT, KC_LGUI, KC_SPC, KC_SPC, KC_RGUI, KC_RALT ),值得注意的细节Caps Lock 位置是KC_LCTL这正是 HHKB 配列的灵魂——把 Ctrl 移到 A 键左侧长期使用 Vim / Emacs 等编辑器的高强度用户会非常受用第一行末尾是KC_BSLS反斜杠与KC_GRV反引号配合 2U 退格使用空格分为KC_SPC, KC_SPC两块对应矩阵 45、47即分体空格布局右下角MO(1)是临时切换第 1 层的层按键momentary。第 1 层则提供了完整的 F 键区、数字小键盘区KC_PAST、KC_PSLS等、方向键KC_UP、KC_DOWN等以及媒体键KC_VOLD、KC_VOLU、KC_MUTE和KC_PWR电源键实现了 60% 键盘小而全的日常可用性。各变体的第 0 层布局差异仅在于回车键形状ANSI 单行 Enter 与 ISO 倒 L 形 Enter、退格键宽度2U 与 1U反引号以及空格形态6U 与 3U3U 分体官方键位代码注释中的 ASCII 键盘图可以让用户直观地看到每种配列例如 keymaps/default_true_hhkb/keymap.c 中的 6U 空格示意。如何开始自定义键位复制一套官方键位即可开始定制qmk new-keymap -kb antipode/vero或手动把keymaps/default_true_hhkb复制为keymaps/mykeymap然后修改keymap.c。几个高频修改点加入 RESET 键在任意层放一个QK_BOOT即RESET键码例如把default第 1 层的右下角MO(1)位置替换为QK_BOOT之后即可通过按键软进 Bootloader省去拔线操作。调整空格键行为若使用分体空格LAYOUT_60_true_hhkb_split_space可以把两块空格分别映射为KC_SPC与LT(1, KC_SPC)按住进层、点按出空格实现空格兼任层切换。切换配列记得选择与 PCB 焊盘设置一致的 LAYOUT 宏避免矩阵坐标与实际物理键位错位。所有键码的完整列表见 Keycodes层切换与 Mod-Tap 等高级玩法可参考 Layers 与 Mod-Tap。常见问题排查make找不到键盘确认 QMK 仓库完整克隆且keyboards/akb/vero/存在目标名必须写作antipode/vero。flash一直等待设备先按上文三种方式之一进入 Bootloader再执行烧录Windows 用户需先安装 dfu-util 对应的驱动见 Driver Installation with Zadig。某些键无响应检查键位使用的 LAYOUT 宏是否与 PCB 配列一致尤其 ISO 与分体空格必要时对照 matrix_diagram.md 核对矩阵坐标。想恢复出厂重新刷入default键位即可make antipode/vero:default:flash。小结AKB Vero 是 QMK 生态中把 HHKB 配列带入 MX 轴世界的一款代表作品。通过本文你可以完成从环境准备、make antipode/vero:default:flash一键编译烧录到理解keyboard.json中矩阵与 Bootloader 配置、并在五套官方键位标准、真 HHKB、ISO、分体空格基础上定制专属布局的完整流程。所有关键配置与源码都可以在本仓库keyboards/akb/vero/目录下找到随时可以对照查阅。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考