企业官网建设流程全解析

QMK 固件中的 AKB Vero：HHKB 配列机械键盘的构建、刷写与配置指南

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

AKB 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 中提供的硬件信息：

提示：本文中的硬件购买信息仅来源于仓库 readme，购买前请以官方渠道为准。

从零构建固件

QMK 采用"键盘路径 + 键位名"的方式定位目标。设置好构建环境后，为 AKB Vero 编译默认键位的固件只需一条命令：

make antipode/vero:default

这里antipode/vero是键盘在 QMK 仓库中的完整路径（keyboards/akb/vero），default是对应键位目录名。编译产物通常是.bin或.hex文件，位于 QMK 的构建输出目录中。

如果你刚接触 QMK，建议先按官方流程准备环境：

• 首次使用 QMK 的用户，先阅读 Complete Newbs Guide 完成环境搭建；
• 构建环境的详细配置见 Getting Started - Build Tools 与 Getting Started - Make Guide（这两个链接在原文档中指向外部站点，本仓库的对应文档如上所示）。

一次构建、多重目标

QMK 的 make 目标支持叠加多种后缀，常用的组合有：

对于 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 的方式，这是刷机成败的关键：

1. Bootmagic 重置：按住矩阵 (0,0) 位置的按键（通常是左上角第一个键或 Esc 键）同时插入 USB 线。这是 QMK 的 Bootmagic 功能，默认在 keyboard.json 中通过"bootmagic": true启用。
2. 物理重置按钮：短按 PCB 背面的重置按钮；部分版本可能没有按钮，而是需要短接对应的焊盘。
3. 键位中的 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_pins：15 根列线（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: "B1"：Caps Lock 状态指示灯接在 B1 引脚，QMK 会自动管理该灯。
• usb：VID 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重定义为16000000U；
• mcuconf.h 将 PLL 的 M 分频系数从 F411 通用默认值 4 改为 8（注释明确说明原因：板载 16 MHz 晶振）。

这两处改动保证了主控能正确从 16 MHz 晶振倍频出系统时钟，刷写官方固件后即可正常运行，无需用户额外干预。

五套官方键位：从标准到真 HHKB

keymaps/目录下提供了 5 套官方键位，覆盖了 Vero 的所有配列变体：

不同配列对应 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

官方默认键位示例

以default（LAYOUT_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 与 3U+3U 分体），官方键位代码注释中的 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