企业官网建设流程全解析

Akko ACR87 QMK 固件使用指南：80% 键盘的编译、刷写与 Win/Mac 双系统键位定制

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

本指南以 QMK Firmware 仓库中 Akko ACR87 键盘的官方文档（keyboards/akko/acr87/readme.md）为主线，结合该键盘的keyboard.json配置、keymap.c默认键位与驱动源码，系统讲解 ACR87 的固件编译、DFU 刷写、重置操作，并深入剖析其硬件特性与六层 Win/Mac 双系统键位方案。读完本文，你将能够独立完成 ACR87 固件的构建与刷写，并理解如何基于默认键位进行个性化定制。

ACR87 键盘与 QMK 支持概况

根据官方 readme，Akko ACR87 是一把可高度自定义的 80% 配列（87 键）键盘，支持旋钮功能（"A customizable 80% encoder keyboard"）。其键盘维护者（Keyboard Maintainer）为 jonylee@hfd，硬件支持型号为 acr87，硬件由 Akko 提供（keyboards/akko/acr87/readme.md）。

在 QMK 仓库中，ACR87 的完整固件源码位于 keyboards/akko/acr87/，核心文件包括：

构建固件：编译环境与 make 命令

在编译前需要先搭建 QMK 构建环境。全新用户建议从官方新手指南开始（docs/newbs.md），完整构建环境安装说明参见 docs/getting_started_make_guide.md。环境就绪后，在仓库根目录执行：

make akko/acr87:default

该命令将编译默认键位（default）的固件。命令格式遵循 QMK 通用的make <keyboard>:<keymap>规则，其中akko/acr87对应键盘目录 keyboards/akko/acr87，default对应 keymaps/default 下的键位方案。

如需生成并刷写固件，使用带:flash后缀的命令：

make akko/acr87:default:flash

底层刷写流程：wb32-dfu bootloader

ACR87 的 bootloader 配置为wb32-dfu（见 keyboard.json 中"bootloader": "wb32-dfu"）。从刷写脚本 platforms/chibios/flash.mk 可以看到，该流程会调用wb32-dfu-updater_cli工具，并先通过wb32-dfu-updater_cli -l循环检测 "Found DFU" 状态，确认设备进入 DFU 模式后才开始烧录。因此刷写前请确保键盘已进入 DFU 模式（见下文"重置键"章节），并安装好对应的 DFU 驱动与工具。

进入刷写模式：K000 重置键

readme 明确给出了 ACR87 的固件重置方法：

Reset Key: Hold down the key located atK000, which programmed asEscwhile plugging in the keyboard.

即：在插入 USB 的同时，按住 K000 位置（默认映射为 Esc）的按键，键盘即可进入 DFU 刷写模式。这一映射在 keyboard.json 的布局定义中可以得到印证——LAYOUT布局的第一项就是{ "label": "Esc", "matrix": [0, 0], ... }，即矩阵坐标 (0,0) 对应 Esc 键（K000 即 Row 0 / Col 0）。此外keyboard.json中启用了bootmagic特性（"bootmagic": true），也提供了进入 bootloader 的辅助途径。

硬件配置深度解读：keyboard.json

ACR87 的硬件参数全部集中在 keyboard.json，这是 QMK 数据驱动配置（data-driven config）的典型实现。以下逐项解读关键配置：

基本信息与 USB 描述

"keyboard_name": "ACR87", "manufacturer": "Akko", "maintainer": "jonylee@hfd", "usb": { "vid": "0xFFFE", "pid": "0x0010", "device_version": "1.0.1", "suspend_wakeup_delay": 400 },

• VID/PID 为0xFFFE:0x0010，设备版本1.0.1；
• suspend_wakeup_delay: 400表示从睡眠唤醒时的延迟参数（单位 ms 级别），用于保证 USB 枚举稳定。

处理器与功能特性

"processor": "WB32FQ95", "bootloader": "wb32-dfu", "features": { "bootmagic": true, "mousekey": true, "extrakey": true, "nkro": true, "rgb_matrix": true }

• 主控为WB32FQ95（WestBerry 32 位 ARM 处理器），bootloader 为wb32-dfu；
• 启用的特性包括：bootmagic（开机魔术键）、mousekey（鼠标键）、extrakey（多媒体/系统键）、nkro（N 键无冲突）以及 rgb_matrix（RGB 矩阵）；
• 同时在host.default中全局开启了"nkro": true，并将qmk.locking的 Caps Lock 锁定/重同步（enabled+resync）打开。

矩阵扫描配置

"matrix_pins": { "cols": [ "C1", "C2", "C3", "A0", "A1", "A2", "A3", "A4", "A5", "A6", "A7", "C4", "C5", "B0", "B1", "B2", "B10"], "rows": [ "B15", "C6", "C7", "C8", "C9", "A8"] }, "diode_direction": "ROW2COL"

矩阵为6 行 × 17 列，二极管方向ROW2COL（行接二极管、列扫描）。这与布局中 87 键 + 指示灯区域的矩阵坐标一一对应。

动态键映射（Dynamic Keymap）与 EEPROM

"dynamic_keymap": { "layer_count": 6 }, "eeprom": { "driver": "wear_leveling", "wear_leveling": { "driver": "spi_flash", "backing_size": 8192 } }

• 支持6 层动态键映射，允许在设备运行时通过 VIA 等工具在线改键并保存；
• EEPROM 采用wear_leveling（磨损均衡）驱动，底层为SPI Flash，后备存储大小 8192 字节。这一设计大幅提升了反复擦写配置时的 Flash 寿命。对应地，config.h 中配置了 SPI 引脚（SPI_SCK_PIN B3、SPI_MOSI_PIN B5、SPI_MISO_PIN B4）与片选引脚EXTERNAL_FLASH_SPI_SLAVE_SELECT_PIN C12，并通过 halconf.h 与 mcuconf.h 分别开启 SPI、启用 QSPI。

RGB 矩阵配置

ACR87 的 RGB 矩阵驱动为snled27351（对应驱动源码 drivers/led/snled27351.c），配置要点：

"rgb_matrix": { "driver": "snled27351", "max_brightness": 180, "animations": { "breathing": true, "cycle_all": true, "cycle_left_right": true, "cycle_up_down": true, "rainbow_moving_chevron": true, "cycle_out_in": true, "cycle_out_in_dual": true, "cycle_pinwheel": true, "cycle_spiral": true, "dual_beacon": true, "rainbow_beacon": true, "raindrops": true, "typing_heatmap": true, "solid_reactive_simple": true, "solid_reactive": true, "solid_reactive_cross": true, "multisplash": true }, "react_on_keyup": true, "sleep": true }

• 最大亮度上限为180（0-255 范围）；
• 内置17 种 RGB 动画：呼吸、全彩循环、左右/上下渐变、雨滴、输入热力图、各类按击反应（reactive）与多重涟漪（multisplash）等；
• react_on_keyup: true表示按键抬起时触发反应效果；sleep: true表示键盘空闲时自动关闭 RGB 以省电；
• layout数组定义了每颗 LED 的物理坐标（x/y）、所属矩阵位置与 flags，与 acr87.c 中g_snled27351_leds的通道映射配合，共同决定灯效渲染的位置。

SNLED27351 硬件接线（config.h）

config.h 进一步给出 LED 驱动芯片的 I2C 地址方案：

#define SNLED27351_I2C_ADDRESS_1 SNLED27351_I2C_ADDRESS_GND #define SNLED27351_I2C_ADDRESS_2 SNLED27351_I2C_ADDRESS_VDDIO #define SNLED27351_I2C_ADDRESS_3 SNLED27351_I2C_ADDRESS_SDA

板载多颗 SNLED27351 驱动芯片分别通过 GND / VDDIO / SDA 引脚设定地址；I2C1 时钟频率配置为400000（400 kHz），工作模式OPMODE_I2C。此外定义了RGB_TRIGGER_ON_KEYDOWN，让灯效在按键按下而非抬起时触发。这些宏与rgb_matrix的react_on_keyup相互配合，决定反应式灯效的触发时机。

指示灯实现：Caps Lock 与 GUI 禁用指示

在 acr87.c 中实现了rgb_matrix_indicators_advanced_kb函数（属于 QMK 的 advanced indicators 回调），利用 RGB 矩阵做按键状态指示灯：

• 第 50 号 LED：当host_keyboard_led_state().caps_lock为真（Caps Lock 开启）时点亮为白色（RGB_MATRIX_INDICATOR_SET_COLOR(50, 255, 255, 255)），否则熄灭；
• 第 77 号 LED：当keymap_config.no_gui（GUI 键被禁用）时点亮为白色，用于提示当前 Win 键处于禁用状态；
• 两种指示在 RGB 灯效被关闭（rgb_matrix_get_flags()为空）时也会熄灭对应 LED，保证状态指示与用户开关一致。

这段实现展示了一个通用模式：rgb_matrix_indicators_advanced_kb会先调用rgb_matrix_indicators_advanced_user，供用户层（user space / keymap）扩展，随后叠加板级指示逻辑。

默认键位：Win/Mac 双系统六层方案

ACR87 默认键位（keymaps/default/keymap.c）设计了 6 个层，覆盖 Windows 与 macOS 两套系统的操作习惯：

enum __layers { WIN_B, // Windows 基础层 WIN_W, // Windows WASD 方向键层 WIN_FN, // Windows 功能层 MAC_B, // macOS 基础层 MAC_W, // macOS WASD 方向键层 MAC_FN // macOS 功能层 };

Windows 基础层（WIN_B）

标准 87 键布局：F1-F12、PrintScreen/ScrollLock/Pause、数字区、编辑区与方向区齐全。底部一行从KC_LCTL、KC_LGUI、KC_LALT到KC_RALT、KC_RGUI，并在KC_RGUI之后放置MO(WIN_FN)（按住进入功能层），最右侧是方向键与右 Ctrl。空间过长，默认被KC_SPC的 6.25u 宽度吸收（对应 keyboard.json 中 Space 的"w": 6.25）。

WASD 方向键层（WIN_W / MAC_W）

通过TG(WIN_W)（Toggle）切换到该层后，原本的 WASD 键被映射为方向键：

• W→KC_UP，A/S/D→KC_LEFT/KC_DOWN/KC_RGHT；
• 同时功能层内W、A、S、D位置也被保留为方向键，方便在按住 FN 时直接使用方向键。

这一设计让无独立方向键需求的用户也能随时切换出完整方向键区。

功能层（WIN_FN / MAC_FN）

FN 层（MO(WIN_FN)/MO(MAC_FN)临时激活）集中了媒体键与 RGB 控制：

• 媒体键：KC_MYCM（我的电脑）、KC_MAIL、KC_WSCH（搜索）、KC_WHOM、KC_MSEL、KC_MPLY、KC_MPRV、KC_MNXT、KC_MUTE、KC_VOLD、KC_VOLU、KC_CALC；
• RGB 控制：RM_TOGG（开关）、RM_NEXT（切换模式）、RM_SPDD/RM_SPDU（减速/加速）、RM_HUEU（色相+）、RM_SATD/RM_SATU（饱和度-/+）、RM_VALD/RM_VALU（亮度-/+）；
• 系统切换：DF(WIN_B)/DF(MAC_B)用于在 Windows 与 macOS 基础层之间切换默认层；TG(WIN_W)/TG(MAC_W)切换 WASD 方向层；
• Windows 功能层还包含GU_TOGG（切换 GUI/Win 键锁定），其状态会同步到 acr87.c 中的第 77 号 LED 指示灯。

macOS 层（MAC_B / MAC_W / MAC_FN）

macOS 基础层（MAC_B）与 Windows 层的主要差异：

• 功能键区映射为 macOS 系统键：KC_BRID/KC_BRIU（亮度-/+）、KC_MCTL（Mission Control）、KC_LPAD（Launchpad）、KC_MPRV/KC_MPLY/KC_MNXT（上一曲/播放/下一曲）、KC_MUTE/KC_VOLD/KC_VOLU（音量控制）；
• 底部修饰键顺序调整为 macOS 习惯：KC_LCTL、KC_LALT、KC_LGUI（Cmd）与右侧KC_RGUI、KC_RALT，FN 层入口为MO(MAC_FN)；
• MAC_FN 层则把 F1-F4 保留为普通功能键，其余键位与 Win 功能层保持一致。

小结与进一步定制

Akko ACR87 在 QMK 中的支持相当完整：从 keyboard.json 的数据驱动配置，到 acr87.c 的 SNLED27351 LED 映射与状态指示灯，再到六层 Win/Mac 双系统默认键位，体现了 QMK 对量产键盘"可玩性"与"开箱即用"的兼顾。

日常使用只需记住三件事：

1. 编译：make akko/acr87:default；
2. 刷写：make akko/acr87:default:flash（需先进入 DFU 模式）；
3. 进 DFU：插入 USB 时按住 K000（Esc）键。

若想进一步定制键位，可以基于 keymaps/default 复制出新的 keymap 目录进行修改，层切换、动态键映射与 RGB 动画的具体用法可参考仓库中的 docs/feature_layers.md 与 docs/newbs_flashing.md 等文档。

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