
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 支持概况根据官方 readmeAkko ACR87 是一把可高度自定义的 80% 配列87 键键盘支持旋钮功能A customizable 80% encoder keyboard。其键盘维护者Keyboard Maintainer为 jonyleehfd硬件支持型号为 acr87硬件由 Akko 提供keyboards/akko/acr87/readme.md。在 QMK 仓库中ACR87 的完整固件源码位于 keyboards/akko/acr87/核心文件包括文件作用keyboard.json数据驱动配置定义处理器、USB 描述、矩阵、RGB、EEPROM 等全部硬件参数acr87.c板级实现包含 SNLED27351 LED 位置映射与 Caps Lock / GUI 指示灯逻辑config.hSPI / I2C 底层外设配置halconf.hChibiOS HAL 外设开关I2C、SPImcuconf.hMCU 外设配置QSPI、I2C1keymaps/default/keymap.c默认六层键位映射构建固件编译环境与 make 命令在编译前需要先搭建 QMK 构建环境。全新用户建议从官方新手指南开始docs/newbs.md完整构建环境安装说明参见 docs/getting_started_make_guide.md。环境就绪后在仓库根目录执行make akko/acr87:default该命令将编译默认键位default的固件。命令格式遵循 QMK 通用的make keyboard:keymap规则其中akko/acr87对应键盘目录 keyboards/akko/acr87default对应 keymaps/default 下的键位方案。如需生成并刷写固件使用带:flash后缀的命令make akko/acr87:default:flash底层刷写流程wb32-dfu bootloaderACR87 的 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.jsonACR87 的硬件参数全部集中在 keyboard.json这是 QMK 数据驱动配置data-driven config的典型实现。以下逐项解读关键配置基本信息与 USB 描述keyboard_name: ACR87, manufacturer: Akko, maintainer: jonyleehfd, usb: { vid: 0xFFFE, pid: 0x0010, device_version: 1.0.1, suspend_wakeup_delay: 400 },VID/PID 为0xFFFE:0x0010设备版本1.0.1suspend_wakeup_delay: 400表示从睡眠唤醒时的延迟参数单位 ms 级别用于保证 USB 枚举稳定。处理器与功能特性processor: WB32FQ95, bootloader: wb32-dfu, features: { bootmagic: true, mousekey: true, extrakey: true, nkro: true, rgb_matrix: true }主控为WB32FQ95WestBerry 32 位 ARM 处理器bootloader 为wb32-dfu启用的特性包括bootmagic开机魔术键、mousekey鼠标键、extrakey多媒体/系统键、nkroN 键无冲突以及 rgb_matrixRGB 矩阵同时在host.default中全局开启了nkro: true并将qmk.locking的 Caps Lock 锁定/重同步enabledresync打开。矩阵扫描配置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与 EEPROMdynamic_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 }最大亮度上限为1800-255 范围内置17 种 RGB 动画呼吸、全彩循环、左右/上下渐变、雨滴、输入热力图、各类按击反应reactive与多重涟漪multisplash等react_on_keyup: true表示按键抬起时触发反应效果sleep: true表示键盘空闲时自动关闭 RGB 以省电layout数组定义了每颗 LED 的物理坐标x/y、所属矩阵位置与 flags与 acr87.c 中g_snled27351_leds的通道映射配合共同决定灯效渲染的位置。SNLED27351 硬件接线config.hconfig.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 时钟频率配置为400000400 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_guiGUI 键被禁用时点亮为白色用于提示当前 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_UPA/S/D→KC_LEFT/KC_DOWN/KC_RGHT同时功能层内W、A、S、D位置也被保留为方向键方便在按住 FN 时直接使用方向键。这一设计让无独立方向键需求的用户也能随时切换出完整方向键区。功能层WIN_FN / MAC_FNFN 层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_CALCRGB 控制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_FNmacOS 基础层MAC_B与 Windows 层的主要差异功能键区映射为 macOS 系统键KC_BRID/KC_BRIU亮度-/、KC_MCTLMission Control、KC_LPADLaunchpad、KC_MPRV/KC_MPLY/KC_MNXT上一曲/播放/下一曲、KC_MUTE/KC_VOLD/KC_VOLU音量控制底部修饰键顺序调整为 macOS 习惯KC_LCTL、KC_LALT、KC_LGUICmd与右侧KC_RGUI、KC_RALTFN 层入口为MO(MAC_FN)MAC_FN 层则把 F1-F4 保留为普通功能键其余键位与 Win 功能层保持一致。小结与进一步定制Akko ACR87 在 QMK 中的支持相当完整从 keyboard.json 的数据驱动配置到 acr87.c 的 SNLED27351 LED 映射与状态指示灯再到六层 Win/Mac 双系统默认键位体现了 QMK 对量产键盘可玩性与开箱即用的兼顾。日常使用只需记住三件事编译make akko/acr87:default刷写make akko/acr87:default:flash需先进入 DFU 模式进 DFU插入 USB 时按住 K000Esc键。若想进一步定制键位可以基于 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创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考