QMK 固件中的 ASH-1800 键盘支持:硬件配置、矩阵映射与固件构建实战

原创2026-09-16 15:27:361,997 阅读
文章标签:嵌入式固件硬件开发驱动开发系统编程

QMK 固件中的 ASH-1800 键盘支持:硬件配置、矩阵映射与固件构建实战

ASH-1800 是 QMK Firmware 仓库中一款以低成本 G80/G81 克隆为目标的机械键盘。本文以 keyboards/ash1800/readme.md 为主线,结合该键盘目录下的数据驱动配置、矩阵图与默认键位源码,完整讲解它的硬件配置(USB 标识、矩阵引脚、指示灯)、五种 PCB 布局的差异,以及从编译到刷写的完整操作流程。读完本文,你将掌握如何定位一款 QMK 键盘的配置入口、读懂 keyboard.json 与默认键位文件,并自行编译出可刷写的固件。

ASH-1800 键盘概况

ASH-1800 的定位十分明确:它是“一次尝试制作廉价 g80/g81 克隆”的产物——也就是试图以更低的成本复刻 Cherry G80/G81 系列全尺寸(1800 配列)键盘的布局与手感,核心信息记录在 keyboards/ash1800/readme.md 中:

  • 键盘维护者(Maintainer):angelbirth
  • 硬件支持(Hardware Supported):ASH-1800,主控为 ATMega32u4
  • 硬件可用性(Hardware Availability):private GB(私人团购),即该键盘并非公开零售,主要通过团购渠道获取

对于这类非公开发售的键盘,QMK 仓库中保留完整的支持代码,意味着拿到 PCB 的玩家可以直接使用官方固件与默认键位,也可以自行裁剪、定制。

数据驱动配置:读懂 keyboard.json

ASH-1800 采用 QMK 的“数据驱动配置”方案,即所有硬件元数据集中在 keyboards/ash1800/keyboard.json 中,编译时 QMK 会依据 data/schemas/keyboard.jsonschema 中定义的规则,结合 config.h 与 rules.mk 动态生成配置(详见 docs/data_driven_config.md 与 docs/reference_info_json.md)。该文件的几组关键配置如下。

USB 标识与基础信息

{
    "keyboard_name": "ASH-1800",
    "manufacturer": "Hasyim Ashari",
    "maintainer": "angelbirth",
    "usb": {
        "vid": "0xFEED",
        "pid": "0x1800",
        "device_version": "0.0.1"
    }
}
  • keyboard_name 会作为 USB 产品字符串显示在主机端;
  • manufacturer(制造商)会作为 USB 厂商字符串,此处为 Hasyim Ashari;
  • usb.vid 使用 QMK 社区常见的厂商 ID 0xFEED,pid 为 0x1800(与键盘型号对应),device_version 为 0.0.1;
  • processor 为 atmega32u4,bootloader 为 atmel-dfu——这是 AVR 平台最经典的组合之一,刷写时使用 DFU 协议(对应 :flash 目标)。

功能开关

"features": {
    "bootmagic": true,
    "console": true,
    "extrakey": true,
    "mousekey": false,
    "nkro": true
}

这些布尔开关对应传统 rules.mk 中的 *_ENABLE 选项(参见 docs/getting_started_make_guide.md 中关于 rules.mk Options 的说明):

配置项 含义 ASH-1800 取值
bootmagic 允许通过按住指定键(默认 Esc)上电来复位 EEPROM 并进入刷写就绪状态 true
console 允许通过 hid_listen 等工具输出调试打印信息 true
extrakey 启用系统与多媒体控制键码(如音量、计算器等) true
mousekey 通过键码控制鼠标光标移动与点击 false(未启用,节省固件体积)
nkro 全键无冲(N-Key Rollover) true

此外,qmk.locking 开启了锁定开关支持(enabled: true)并启用状态重同步(resync: true),后者会让开关状态与键盘 LED 状态保持一致(默认均为关闭,详见 docs/reference_info_json.md 的 qmk.locking 小节)。结合 indicators 配置的 Caps/Num/Scroll 三个锁定指示灯,这一组设置保证了锁定键按下后指示灯能够正确反映状态。

矩阵引脚与指示灯

ASH-1800 使用 12 行 × 10 列的标准矩阵,二极管方向为 COL2ROW(列输出、行读取,二极管负极朝行):

"matrix_pins": {
    "cols": ["F1", "F4", "F5", "F6", "B0", "B2", "B1", "B3", "B7", "C7"],
    "rows": ["C6", "B6", "B5", "B4", "D7", "D0", "D1", "D2", "D3", "D5", "D4", "D6"]
}

指示灯(锁定状态 LED)同样以数据驱动方式定义:

"indicators": {
    "caps_lock": "F0",
    "num_lock": "E6",
    "scroll_lock": "F7",
    "on_state": 0
}
  • caps_lock 接 F0、num_lock 接 E6、scroll_lock 接 F7;
  • on_state 为 0,表示这三个指示灯的“点亮”对应低电平状态(即 LED 低电平有效),这是从配置取值可以推断出的电平约定。

对应的完整矩阵接线关系可参考仓库内的 keyboards/ash1800/matrix_diagram.md,其中用 ASCII 图表标注了每个物理键位对应的矩阵坐标(如 00 表示第 0 行第 0 列),并特别标注了 40 为 2.25u 左 Shift、底排 WKL 变体的 50 / 51 / 53 / B4 / B7 位置,方便焊接与排障时对照。

五种布局:从 ANSI 到 ISO 再到 WKL

全尺寸 1800 配列的最大特点是“紧凑但五脏俱全”,且同一块 PCB 往往要兼容多种按键排列。ASH-1800 的 keyboard.json 一次性定义了五种布局宏:

布局宏 说明
LAYOUT_all 全兼容布局,覆盖所有物理键位(包括 ISO Enter、2.25u 左 Shift 等变体)
LAYOUT_ansi 标准 ANSI 配列,左 Shift 为 2.25u,底排含 1.25u×3 + 6.25u 空格
LAYOUT_ansi_wkl ANSI + WKL 底排(Win 键去掉,左 Shift 加宽为 1.5u,空格加宽为 7u)
LAYOUT_iso 标准 ISO 配列,含回车的额外键位与 1.25u 左 Shift
LAYOUT_iso_wkl ISO + WKL 底排组合

以 LAYOUT_ansi 的底排为例:

{"matrix": [5, 0], "x": 0, "y": 6, "w": 1.25},
{"matrix": [5, 1], "x": 1.25, "y": 6, "w": 1.25},
{"matrix": [5, 2], "x": 2.5, "y": 6, "w": 1.25},
{"matrix": [5, 3], "x": 3.75, "y": 6, "w": 6.25},
{"matrix": [11, 4], "x": 10, "y": 6, "w": 1.5},
{"matrix": [11, 7], "x": 11.5, "y": 6, "w": 1.5}

这里每个条目用 matrix 指定矩阵坐标(行、列),用 x/y 描述在配列图上的相对位置,用 w/h 描述键帽宽度/高度(以 1u 为基准)。对比 LAYOUT_ansi 与 LAYOUT_ansi_wkl 可以看出:WKL 版本把底排的 1.25u×3 换成 1.5u×2,并将空格加宽到 7u,同时删去 Win 键位。ISO 版本则在主键区右侧用 "w": 1.25, "h": 2 定义加高的 ISO 回车,并用 [2, 9] 补上 \ 键。

这些布局宏的完整定义覆盖了行 0~11、列 0~9 的全部矩阵交叉点,既能满足默认键位使用 LAYOUT_all,也能让玩家针对自己的键帽套件选用更精确的 ANSI / ISO / WKL 变体,避免布局宏中出现“幽灵键”。

默认键位:全尺寸配列的完整映射

默认键位位于 keyboards/ash1800/keymaps/default/keymap.c,使用 LAYOUT_all 布局宏,共定义了两个图层。

第 0 层:基础键位

函数行完整映射了 KC_ESC、KC_F1~KC_F12,并在其右侧依次放置 KC_INS、KC_HOME、KC_PGUP、KC_PSCR,下一行继续 KC_DEL、KC_END、KC_PGDN、KC_SCRL——这是 1800 配列“功能键区并入主键区上方”的典型表现。

数字区则复用主键区的第 2 行到第 4 行:KC_NUM、KC_PSLS、KC_PAST、MO(1) 位于主键区 = / Backspace 之后,KC_P7~KC_P9、KC_PMNS、KC_P4~KC_P6、KC_PPLS、KC_P1~KC_P3、KC_PENT 依次排列,最右侧一行由 KC_UP、KC_P0、KC_PDOT 收尾。方向键以 KC_LEFT、KC_DOWN、KC_RIGHT 出现在数字区下方,与绝大多数 1800 键盘的惯例一致。

主键区为完整的 ANSI 布局:KC_GRV 到 KC_EQL,KC_BSPC;KC_TAB 起首的 QWERTY 行;KC_CAPS 起首的字母行;KC_LSFT、KC_BSLS(ANSI 反斜杠)、KC_Z…KC_SLSH、KC_RSFT 的 Shift 行。底排依次为 KC_LCTL、KC_LGUI、KC_LALT、6.25u KC_SPC、KC_RALT、KC_RCTL。

第 1 层:功能层

第 1 层通过第 2 行的 MO(1) 键按住触发,属于“按住即用”的临时功能层:

[1] = LAYOUT_all(
    QK_BOOT, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______,            _______, _______, _______, _______,
                                                                                                                                      _______, KC_MUTE, _______, _______,
    _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, KC_CALC, _______, _______, _______,
    ...
    _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, KC_VOLU, _______, _______, _______, _______,
    _______, _______, _______,                   KC_MPLY,                                     _______, _______, KC_MPRV, KC_VOLD, KC_MNXT, _______, _______
);

各功能键位分布:

  • QK_BOOT:置于左上角 Esc 位,按下即进入 DFU 刷写模式,无需拆壳按复位键;
  • KC_MUTE:F12 右侧的静音键;
  • KC_CALC:数字区 Num Lock 位的计算器快捷键;
  • KC_VOLU:数字区 7 位的音量加;
  • 多媒体组合:空格位 KC_MPLY(播放/暂停),方向键区域 KC_MPRV(上一曲)、KC_VOLD(音量减)、KC_MNXT(下一曲)。

由于 extrakey 功能已开启,这些多媒体与系统控制键码可直接生效。

构建与刷写

搭建好 QMK 构建环境(参考 docs/newbs_getting_started.md 与 docs/newbs.md)后,编译 ASH-1800 默认键位的命令非常简单:

make ash1800:default

make 的完整语法为 <keyboard>:<keymap>:<target>,其中 <keyboard> 即键盘目录名 ash1800,<keymap> 为键位名 default,更多细节参见 docs/getting_started_make_guide.md。常用的目标与变体:

  • make ash1800:default:flash——编译并直接刷写。由于 bootloader 为 atmel-dfu,刷写时使用 DFU 协议,Windows 下可能需要借助 docs/driver_installation_zadig.md 安装驱动;
  • make ash1800:default:clean——清理该键盘的构建输出,遇到疑难编译问题时先执行一次;
  • make ash1800:<你的键位名>——编译你自己放在 keyboards/ash1800/keymaps/ 下的自定义键位。

若你想基于现有默认键位改造,只需在 keyboards/ash1800/keymaps/ 下新建一个目录(例如 keymaps/mine/),放入自己的 keymap.c 即可,选择 LAYOUT_ansi、LAYOUT_iso 等精确布局宏能更好地匹配你的键帽套件。

总结

ASH-1800 作为 QMK 仓库中一款全尺寸 1800 配列的 AVR 键盘,完整展示了“数据驱动配置”的典型形态:keyboard.json 集中描述 USB 标识、矩阵引脚、指示灯与五种布局宏,默认键位文件负责提供开箱即用的键位与功能层。无论是想刷写原厂固件、定制个人键位,还是理解 QMK 中 1800 配列的矩阵与布局设计,keyboards/ash1800/ 目录下的 readme.md、keyboard.json、matrix_diagram.md 与 keymaps/default/keymap.c 都是可以直接对照研读的完整范例。

登录后查看全文
qmk_firmware