QMK Firmware 实战：Ishi 80 Mk 0 键盘的 Elite-C 扩展版固件（mk0_avr_extra）编译、刷写与定制指南

QMK Firmware 实战：Ishi 80 Mk 0 键盘的 Elite-C 扩展版固件（mk0_avr_extra）编译、刷写与定制指南

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

Ishi 80 Mk 0 是一款配备 SouthPaw（左手方向键位）与镜像小键盘（Mirrored Numpad）的 60% 布局客制化键盘。本指南围绕 QMK Firmware 仓库中该键盘的mk0_avr_extra固件变体展开，讲解其硬件兼容性前提、构建与刷写命令、Bootloader 进入方式，并结合仓库内的keyboard.json、默认键位与编码器映射源码，深入解析矩阵定义、功能开关、旋钮与 OLED 扩展的底层实现。读完本文，你将掌握如何为本键盘编译、刷写固件，并能按需定制键位层、编码器动作与开机 Logo。

硬件与固件变体背景

Ishi 80 Mk 0 在 QMK 仓库中以argo_works/ishi/80为键盘目录，包含两个固件变体：

• mk0_avr：面向标准 Pro Micro 引脚兼容子板，不支持编码器与 OLED 功能；
• mk0_avr_extra（本文主题）：面向拥有底部 5 个额外引脚的 ATMega32U4 子板（如 Elite-C），额外支持旋转编码器与 OLED 显示屏。

mk0_avr_extra的 readme.md 中明确给出了关键兼容性警告：本固件仅适用于基于 ATMega32U4 且底部带 5 个额外引脚的子板（如 Elite-C），与标准 Pro Micro 引脚布局的子板不兼容。选购或改装子板时务必核对引脚定义，避免烧录后按键矩阵或扩展功能失效。

其余基础信息：

• 键盘维护者（Maintainer）：Jason Devadoss（jasonj2232），该信息同时写入 keyboard.json 的maintainer字段；
• 硬件支持：Ishi 80 Mk 0 + Elite-C 引脚布局子板；
• 硬件购买渠道：官方文档标注为未公开（Hardware Availability:-）。

编译与刷写

在搭建好 QMK 构建环境后，编译默认键位固件：

make argo_works/ishi/80/mk0_avr_extra:default

刷写固件到子板：

make argo_works/ishi/80/mk0_avr_extra:default:flash

其中argo_works/ishi/80/mk0_avr_extra是键盘在仓库中的完整路径，default是目标键位（keymap）名称，对应仓库中的 keymaps/default。构建时 QMK 会依据该键盘目录下的 keyboard.json 自动生成矩阵扫描、USB 描述符与功能开关配置，无需手写config.h与rules.mk（除默认键位目录下的个别选项外）。

数据驱动的键盘配置解析

mk0_avr_extra采用 QMK 的数据驱动配置（Data-Driven Configuration）模式，全部硬件参数集中在 keyboard.json 中：

USB 标识与开发板

"development_board": "elite_c", "pin_compatible": "elite_c", "usb": { "device_version": "0.0.1", "pid": "0x4930", "vid": "0x4157" }

• development_board/pin_compatible声明使用 Elite-C 引脚映射，这也是本变体与 Pro Micro 版 mk0_avr（development_board: "promicro"）在配置层最直观的差异；
• USB VID/PID 为0x4157/0x4930，设备版本0.0.1，编译后固件以此标识枚举为键盘设备。

矩阵引脚与二极管方向

"diode_direction": "COL2ROW", "matrix_pins": { "cols": ["D3", "F4", "F5", "F6", "F7", "D7", "C6", "D4", "D2"], "rows": ["B3", "B1", "B6", "B2", "F0", "F1", "B5", "B4", "E6"] }

矩阵为 9 列 × 9 行，采用 COL2ROW（列扫描、行读入）二极管方向。对比标准版 mk0_avr 的矩阵配置可以发现：扩展版将第 4、5 行的引脚从D1/D0调整为F0/F1——这正对应 Elite-C 与 Pro Micro 在底部额外引脚上的差异，也是两个固件变体必须分开维护的直接原因。

功能开关（features）

"features": { "bootmagic": true, "extrakey": true, "mousekey": true, "nkro": true, "encoder": true, "oled": true, "wpm": true }

相比标准版，mk0_avr_extra额外启用了encoder（旋转编码器）、oled（OLED 显示屏）与wpm（打字速度统计）三项功能；extrakey与mousekey分别提供多媒体键与鼠标键能力，nkro启用无冲（N-Key Rollover）。这些功能开关决定了最终固件中会链接哪些量子模块（quantum/）与驱动代码。

Bootmagic 矩阵位置

"bootmagic": { "matrix": [1, 0] }

本键盘将 Bootmagic 触发键设置在矩阵坐标[1, 0]（即键位布局中左上角第一颗键，位于 x=0,y=0，默认键位下为小键盘的KC_PMNS键），与 keyboard.json 中LAYOUT布局第一条记录{"matrix": [1, 0], "x": 0, "y": 0}完全对应。文档中所述“Bootmagic reset 需按住矩阵 (0,0) 处的键”是基于通用说明的近似描述，实际以本键盘配置的[1, 0]为准。

旋转编码器定义

"encoder": { "rotary": [ {"pin_a": "B7", "pin_b": "D5"} ] }

编码器 A/B 相分别接在B7与D5引脚上。编码器的行为映射并不在此定义，而是由键位目录中的编码器映射（Encoder Map）决定，详见下文。

默认键位与层结构

默认键位源码位于 keymaps/default/keymap.c，定义了BL（Base Layer，基础层）与UL（Upper Layer，上层）两个自定义层：

基础层（BL）：SouthPaw + 镜像小键盘

• 左侧小键盘区：KC_PMNS、KC_PAST、KC_PSLS、KC_NUM、KC_PPLS、KC_P9~KC_P1、KC_PENT、KC_PDOT、KC_P0等完整小键盘键位，镜像排布在键盘左侧；
• 主键区：KC_ESC与数字行KC_1~KC_0、KC_MINS、KC_EQL、KC_BSPC；字母区KC_Q~KC_P、KC_A~KC_QUOT、KC_Z~KC_SLSH；
• 修饰与特殊键：KC_CAPS_LOCK、KC_LSFT/KC_RSFT、KC_LCTL、KC_LGUI、KC_RALT、KC_RGUI、KC_APP、KC_RCTL；
• 层切换键：空格左侧使用LT(1, KC_LALT)——按住进入 UL 层并透传左 Alt，单击则仍输出 Alt，实现层切换与按键复用；
• 多媒体键：最右侧为KC_AUDIO_MUTE（静音）。

上层（UL）：功能键层

[UL] = LAYOUT( KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_GRAVE, KC_F1, KC_F2, ... KC_TRNS, ..., KC_PSCR, KC_SCRL, KC_PAUS, ... ... KC_TRNS, ..., KC_UP, KC_TRNS, ..., KC_TRNS, KC_LEFT, KC_DOWN, KC_RIGHT, KC_MPLY ),

• 主键区与字母区全部为KC_TRNS（透传，沿用基础层行为）；
• 数字行映射为KC_F1~KC_F12，配合KC_GRAVE（反引号）与KC_DEL提供笔记本式功能键体验；
• 右侧小键盘区补全KC_PSCR、KC_SCRL、KC_PAUS；
• 方向键集中在右下角：KC_UP、KC_LEFT、KC_DOWN、KC_RIGHT；
• 最右侧为KC_MPLY（播放/暂停）。

编码器映射（Encoder Map）

默认键位目录下的 rules.mk 仅一行，用于开启编码器映射：

ENCODER_MAP_ENABLE = yes

开启后，keymap.c 中通过ENCODER_MAP_ENABLE条件编译块按层定义旋钮行为：

const uint16_t PROGMEM encoder_map[][NUM_ENCODERS][NUM_DIRECTIONS] = { [BL] = { ENCODER_CCW_CW(KC_VOLD, KC_VOLU) }, [UL] = { ENCODER_CCW_CW(KC_BRID, KC_BRIU) }, };

• 基础层（BL）：逆时针旋转减小音量（KC_VOLD），顺时针增大音量（KC_VOLU）；
• 上层（UL）：逆时针降低屏幕亮度（KC_BRID），顺时针提高亮度（KC_BRIU）。

通过这种“按键复用层切换 + 按层切换编码器行为”的组合，单个旋钮即可在不同层中承担音量与亮度两种职责，是 60% 小配列键盘常见的扩展思路。

OLED 开机 Logo 的实现

mk0_avr_extra目录下的 mk0_avr_extra.c 是键盘级（keyboard-level）C 代码，在OLED_ENABLE条件下实现开机 Logo 渲染：

• 使用static const char PROGMEM raw_logo[]存放预生成的位图数据，通过oled_write_raw_P(raw_logo, sizeof(raw_logo))直接写入显存，避免逐像素绘图带来的性能开销；
• 重写oled_task_kb()键盘级任务钩子：先调用oled_task_user()（键位级用户钩子），在其返回false时立即退出（表示用户层已接管渲染），否则渲染 Logo 并返回true。

这种“kb 钩子委托 user 钩子”的写法是 QMK OLED 扩展的标准协作模式，用户可在自己的 keymap 中覆盖oled_task_user()增加自定义内容，而无需改动键盘级代码。

进入 Bootloader 的三种方式

mk0_avr_extra的 readme.md 提供了三种进入刷写模式（Bootloader）的方法：

1. Bootmagic 复位：按住矩阵坐标[1, 0]处的按键（布局左上角第一颗键）的同时插入 USB 线供电。注意本键盘的 Bootmagic 矩阵位置在 keyboard.json 中被显式配置为[1, 0]；
2. 物理复位按键：短按 PCB 背面的复位按钮；部分 PCB 没有实体按钮，需要用镊子短接对应焊盘；
3. 键位中的复位键码：在键位中放置QK_BOOT（旧称RESET）键码并按下。默认键位未包含该键码，可在自定义 keymap 中自行加入。

刷写固件时使用前文给出的make argo_works/ishi/80/mk0_avr_extra:default:flash，配合 QMK 的自动复位流程即可完成烧录。

拓展与定制建议

• 更换键位：复制keymaps/default目录创建自己的 keymap，修改层定义与编码器映射后，以make argo_works/ishi/80/mk0_avr_extra:你的键位名编译；
• 旋钮行为：如需新增功能（如KC_MUTE、翻页、缩放等），保持ENCODER_MAP_ENABLE = yes，在encoder_map中替换ENCODER_CCW_CW(...)的参数即可；
• OLED 内容：在个人 keymap 中实现oled_task_user()自定义显示内容（键位状态、WPM 等），mk0_avr_extra.c中的键盘级实现会自动让位于用户级渲染；
• 子板选型：务必使用 Elite-C 引脚兼容的 ATMega32U4 子板，若使用标准 Pro Micro 引脚子板，请改用同目录下的 mk0_avr 固件变体，并注意该变体不支持编码器与 OLED。

以上所有配置与代码均可直接在仓库中查看：keyboard.json、keymaps/default/keymap.c、keymaps/default/rules.mk 与 mk0_avr_extra.c，可作为理解 QMK 数据驱动配置、Elite-C 扩展引脚利用、编码器映射与 OLED 键盘级渲染的完整参考案例。

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