QMK 固件中的 Kitten Paw 鍵盤移植指南2016 版 Bathroom Epiphanies 控制器的構(gòu)建、刷寫與自定義【免費下載鏈接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families項目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware本指南聚焦 QMK Firmware 倉庫中keyboards/bpiphany/kitten_paw目錄所承載的 Kitten Paw 鍵盤支持。Kitten Paw 是 Bathroom Epiphaniesbpiphany于 2016 年推出的控制器 PCB用于替換成品鍵盤的主控而本目錄下的 readme.md、keyboard.json、matrix.c、config.h 與 rules.mk 共同構(gòu)成了該鍵盤在 QMK 中的完整移植。讀完本文你將掌握Kitten Paw 的硬件與固件背景、倉庫中配置的數(shù)據(jù)結(jié)構(gòu)、其獨特的 8×18 自定義矩陣掃描實現(xiàn)以及如何構(gòu)建、刷寫并自定義屬于你自己的鍵位映射。Kitten Paw 鍵盤與固件背景Bathroom Epiphaniesbpiphany是一家位于瑞典的控制器板設(shè)計者其產(chǎn)品線以可替換成品鍵盤主控著稱bpiphany 目錄說明 指出其控制器板作為現(xiàn)成鍵盤的可替換組件銷售。Kitten Paw 正是這一思路下的產(chǎn)物它是 2016 年修訂版的替換控制器倉庫中明確記錄This is the firmware for the 2016 revision of the Kitten Paw controller by Bathroom Epiphanies. Most of the boilerplate code is the work of BathroomEpiphanies.換言之Kitten Paw 固件的大部分樣板代碼源自 BathroomEpiphanies 本人的工作QMK 社區(qū)在此基礎(chǔ)上完成了移植與維護。從倉庫數(shù)據(jù)可以確認(rèn)該鍵盤的完整身份信息見 keyboard.json項目值鍵盤名稱Kitten Paw廠商bpiphany維護者QMK CommunityVID0xFEEDPID0x6050設(shè)備版本1.0.4主控ATMega32U2引導(dǎo)加載程序atmel-dfu啟用功能鼠標(biāo)鍵、擴展鍵、控制臺、命令行Command禁用功能Bootmagic社區(qū)布局fullsize_ansi值得注意的是readme 中特別注明NKRO 目前無法工作6KRO 已足夠使用這意味著當(dāng)前移植默認(rèn)未啟用 NKROn-key rollover而是依賴標(biāo)準(zhǔn) HID 報文的 6 鍵無沖突能力。這是移植作者在 readme.md 中留下的明確取舍說明屬于當(dāng)前倉庫的既定事實。全尺寸 ANSI 布局與 8×18 矩陣的數(shù)據(jù)結(jié)構(gòu)布局定義LAYOUT 與 LAYOUT_fullsize_ansiKitten Paw 是一塊全尺寸Fullsize鍵盤控制器鍵盤掃描矩陣為 8 行 × 18 列見 config.h 中MATRIX_ROWS 8與MATRIX_COLS 18。keyboard.json 中定義了兩個布局LAYOUT默認(rèn)布局名與LAYOUT_fullsize_ansi社區(qū)標(biāo)準(zhǔn)布局兩者按鍵物理位置完全一致——區(qū)別僅在于空格行與 Shift 行個別鍵帽寬度不同例如LAYOUT中[2,13]為 1.25u 寬、LAYOUT_fullsize_ansi中為 2.25u后者用于與其他全尺寸 ANSI 鍵盤共享鍵位映射文件。每個按鍵條目用matrix坐標(biāo)行、列與x/y物理坐標(biāo)描述例如{matrix: [6, 9], x: 0, y: 0}, // Esc {matrix: [2, 1], x: 13, y: 1.5, w: 2}, // Backspace2u 寬 {matrix: [6, 10], x: 3.75, y: 5.5, w: 6.25} // 空格6.25u 寬w/h字段用于表達(dá)鍵帽寬度/高度這正是 QMK 數(shù)據(jù)驅(qū)動配置data_driven_config.md的標(biāo)準(zhǔn)寫法keyboard.json 本身即數(shù)據(jù)驅(qū)動遷移的產(chǎn)物替代了舊的info.json加keymaps.c頭文件組合。默認(rèn)鍵位映射默認(rèn)鍵位映射位于 keymaps/default/keymap.c定義了單層DEFAULT布局完整覆蓋了 108 鍵全尺寸鍵盤的功能區(qū)、主鍵區(qū)、編輯鍵區(qū)與數(shù)字小鍵盤const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] { [DEFAULT] LAYOUT( KC_ESC, KC_F1, KC_F2, KC_F3, KC_F4, KC_F5, KC_F6, KC_F7, KC_F8, KC_F9, KC_F10, KC_F11, KC_F12, KC_PSCR,KC_SCRL,KC_PAUS, KC_GRV, 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_BSPC, KC_INS,KC_HOME,KC_PGUP, KC_NUM,KC_PSLS,KC_PAST,KC_PMNS, 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_BSLS, KC_DEL, KC_END,KC_PGDN, KC_P7, KC_P8, KC_P9,KC_PPLS, KC_CAPS, KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L,KC_SCLN,KC_QUOT, KC_ENT, KC_P4, KC_P5, KC_P6, 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, KC_UP, KC_P1, KC_P2, KC_P3,KC_PENT, KC_LCTL,KC_LGUI,KC_LALT, KC_SPC, KC_RALT,KC_RGUI, KC_APP,KC_RCTL, KC_LEFT,KC_DOWN,KC_RGHT, KC_P0,KC_PDOT) };鍵位布局采用標(biāo)準(zhǔn) US ANSI 全尺寸排列第一行功能鍵與 Print Screen/Scroll Lock/Pause 鍵第二至四行為字母與數(shù)字主鍵區(qū)含 Backspace、Enter 雙排鍵位第五行為 Shift 行注意KC_NUBS即\反斜杠鍵第六行為 Ctrl/Win/Alt 與空格鍵組成的修飾鍵行右側(cè)依次為 RAlt、RGUI、App、RCtrl。編輯鍵區(qū)Insert/Home/PageUp、Delete/End/PageDown、方向鍵與數(shù)字小鍵盤含 NumLock、小鍵盤 Enter、加減乘除與小數(shù)點均有完整映射。由于該布局頂層僅聲明了DEFAULT一個層鍵位映射非常簡潔適合作為學(xué)習(xí)數(shù)據(jù)驅(qū)動布局文件與自定義矩陣鍵盤如何協(xié)同的范例。若需要加入層切換可在枚舉中追加層名并使用MO(layer)、LT(layer, kc)等層鍵碼QMK 的層功能說明見 feature_layers.md。自定義矩陣掃描硬件原理與源碼解讀Kitten Paw 的獨特之處在于其矩陣掃描并非 QMK 通用 GPIO 掃描而是采用了定制實現(xiàn)。rules.mk 通過如下兩行聲明了這一點CUSTOM_MATRIX yes SRC matrix.cCUSTOM_MATRIX yes告知 QMK 構(gòu)建系統(tǒng)使用鍵盤自帶的矩陣實現(xiàn)而不是默認(rèn)矩陣SRC matrix.c則把 matrix.c 編入固件。這樣做的原因是Kitten Paw 的 18 列并非全部由 MCU 引腳直接驅(qū)動而是借助一枚74HC154 4 線轉(zhuǎn) 16 線低電平有效譯碼器擴展列選通能力。matrix.c 頂部注釋對此有清晰說明These rows uses one 74HC154 4 to 16 bit demultiplexer (low active), together with 2 rows driven directly from the micro controller, to control the 18 rows. The rows are driven from pins B6,5,4,3,2,1,0.引腳分配與初始化從 matrix.c 的注釋與代碼可以還原完整引腳方案行輸入引腳8 行PC7, PD5, PD3, PD1, PC2, PD6, PD4, PD2作為輸入并啟用內(nèi)部上拉PORTC | 0b10000100、PORTD | 0b01111110配合DDR清零read_rows()中低電平表示按鍵按下返回對應(yīng)位 1。列輸出引腳18 列PB0 ~ PB6共 7 位其中高 4 位B6..B3作為 74HC154 譯碼器的選擇輸入、部分低位組合用于直接驅(qū)動。select_col()為每個列號寫入一段特定的 PORTB 位模式case 0 到 case 17例如case 0: PORTB (PORTB ~0b01111111) | 0b01100100;。matrix_init()首先配置 DDR 與上拉電阻隨后將matrix與matrix_debouncing緩沖清零最后調(diào)用弱符號鉤子matrix_init_kb()→matrix_init_user()允許鍵盤級或用戶級代碼在掃描開始前做額外初始化。掃描、去抖動與報告鉤子matrix_scan()實現(xiàn)了完整的逐列掃描 去抖動流程對每一列調(diào)用select_col(col)選通該列_delay_us(3)等待信號穩(wěn)定read_rows()一次性讀回 8 行狀態(tài)逐行與matrix_debouncing緩沖比對若某位發(fā)生變化則翻轉(zhuǎn)緩沖位并把debouncing計數(shù)器重置為DEBOUNCE未定義時默認(rèn) 5即 5 個掃描周期若debouncing計數(shù)器遞減到 0才把去抖動緩沖整體提交到matrix狀態(tài)從而過濾按鍵抖動最后調(diào)用弱符號matrix_scan_kb()→matrix_scan_user()供上層在每次掃描后掛接自定義邏輯。matrix_is_on(row, col)與matrix_get_row(row)分別提供按鍵狀態(tài)查詢與整行讀取接口matrix_print()則以二進制形式打印全部 8 行狀態(tài)用于調(diào)試矩陣接線。這套matrix_init_kb/matrix_scan_kb/matrix_init_user/matrix_scan_user的弱符號鉤子機制是 QMK 鍵盤級與用戶級自定義的標(biāo)準(zhǔn)擴展點官方說明見 custom_matrix.md 與 custom_quantum_functions.md。與之形成對比的是同目錄下其他鍵盤如 ghost_squid、frosty_flake它們同樣針對各自 PCB 布線提供matrix.c可見定制矩陣掃描是 bpiphany 系列控制器的共同特征。指示燈配置與功能開關(guān)keyboard.json 中定義了三個鍵盤指示燈引腳on_state: 0表示低電平點亮常見于共陽極 LED 設(shè)計indicators: { caps_lock: C6, num_lock: B7, scroll_lock: C5, on_state: 0 }同時qmk.locking段啟用了 Caps Lock 等鎖定鍵的軟件重同步enabled: true, resync: true確保鎖定狀態(tài)在多次觸發(fā)間保持一致features段則啟用mousekey鼠標(biāo)鍵、extrakey媒體/系統(tǒng)鍵、console控制臺輸出與commandQMK 命令行調(diào)試功能并顯式關(guān)閉bootmagic。若想縮減固件體積config.h 中還保留了NO_DEBUG、NO_PRINT、NO_ACTION_LAYER、NO_ACTION_TAPPING、NO_ACTION_ONESHOT等注釋掉的開關(guān)可供按需啟用這與 QMK 官方 config_options.md 中關(guān)于功能裁剪的說明一致。構(gòu)建與刷寫構(gòu)建環(huán)境構(gòu)建 Kitten Paw 固件需要先在本地完成 QMK 構(gòu)建環(huán)境搭建。官方推薦流程包括安裝依賴與拉取 qmk_firmware 倉庫具體步驟可參考 getting_started_introduction.md 與 newbs.md新手完整指南。QMK 提供跨平臺環(huán)境配置文檔getting_started_docker.md 覆蓋 Docker 方式構(gòu)建參數(shù)的一般性說明見 getting_started_make_guide.md。編譯命令在完成環(huán)境搭建后使用如下命令編譯默認(rèn)鍵位映射這是 readme.md 給出的標(biāo)準(zhǔn)用法make bpiphany/kitten_paw:default命令格式為make keyboard:keymap其中bpiphany/kitten_paw是鍵盤路徑對應(yīng)keyboards/bpiphany/kitten_paw目錄default是鍵位映射名對應(yīng) keymaps/default。若要編譯并一次性刷寫可在目標(biāo)后追加:flash目標(biāo)make bpiphany/kitten_paw:default:flash進入引導(dǎo)加載程序與刷寫Kitten Paw 采用atmel-dfu引導(dǎo)加載程序見 keyboard.json 的bootloader字段。DFU 引導(dǎo)的常見進入方式包括按下 PCB 上的物理復(fù)位/引導(dǎo)按鈕進入 DFU 模式在鍵位映射中放置QK_BOOT鍵碼按下后復(fù)位進入 DFU。進入 DFU 模式后make ...:flash會調(diào)用 flashing.md 中描述的 DFU 刷寫工具如dfu-programmer寫入固件。刷寫前請確認(rèn)操作系統(tǒng)已正確安裝對應(yīng)驅(qū)動Windows 用戶常需借助 Zadig 安裝 WinUSB 驅(qū)動見 driver_installation_zadig.md。完整的刷寫方法論與排錯建議可參閱 newbs_flashing.md。自定義鍵位映射Kitten Paw 當(dāng)前只內(nèi)置了default一個鍵位映射。你可以參考 keymaps/default/keymap.c 的寫法在keymaps/下新建目錄例如keymaps/mine/放入自己的keymap.c然后以make bpiphany/kitten_paw:mine編譯。鍵碼的完整清單見 keycodes.md 與 keycodes_basic.md層、Tap-Hold、一鍵觸發(fā)等進階能力分別見 feature_layers.md、mod_tap.md、one_shot_keys.md。若你希望以 JSON 方式聲明鍵位映射可參考 newbs_building_firmware_configurator.md 與 reference_info_json.md。倉庫內(nèi)的擴展閱讀路徑鍵盤全部源碼與配置keyboards/bpiphany/kitten_paw含 keyboard.json、matrix.c、config.h、rules.mk同廠商其他控制器移植用于對照定制矩陣寫法keyboards/bpiphany/ghost_squid、keyboards/bpiphany/frosty_flake、keyboards/bpiphany/hid_liber自定義矩陣實現(xiàn)指南custom_matrix.md數(shù)據(jù)驅(qū)動配置規(guī)范data_driven_config.md 與 reference_info_json.md構(gòu)建與刷寫全流程getting_started_make_guide.md、flashing.md、newbs_flashing.md小結(jié)Kitten Paw 移植展示了 QMK 中替換成品鍵盤主控類項目的典型結(jié)構(gòu)一份 keyboard.json 承載鍵盤身份、USB 描述符、指示燈與布局?jǐn)?shù)據(jù)一份 matrix.c 針對 PCB 上 74HC154 譯碼器實現(xiàn) 8×18 定制掃描一份 config.h 與 rules.mk 完成尺寸與構(gòu)建定制。理解這些文件之間的關(guān)系你不僅能順利編譯刷寫 Kitten Paw 固件也能將其模式遷移到自己的自定義矩陣鍵盤項目中。【免費下載鏈接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families項目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考