QMK 固件中 Morgan65 的完整移植解析：USB/蓝牙双模 65% 键盘的构建、矩阵与自定义蓝牙驱动-北京尧图网络

QMK 固件中 Morgan65 的完整移植解析USB/蓝牙双模 65% 键盘的构建、矩阵与自定义蓝牙驱动【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmwareMorgan65 是 DT Studio 出品的 65% 自定义键盘其 PCB 由 Basic I/O InstrumentsBIOI设计支持 USB 与蓝牙双模连接。本文以 QMK 仓库中 keyboards/bioi/morgan65/readme.md 为骨架结合该键盘目录下的实际固件源码完整讲解这款键盘在 QMK 中的构建方式、矩阵引脚定义、默认键位布局、Magic Key 锁定机制以及其通过 UART AT 指令实现的自定义蓝牙驱动原理帮助开发者理解一颗双模键盘在 QMK 中的全链路实现。键盘概况与维护信息按 readme 的原始描述Morgan65 是一款 65% 布局的自定义键盘由 Basic I/O Instruments 提供的 USB/蓝牙双模 PCB 驱动。其维护者为 Basic I/O Instruments 的 Scott Wei仓库 maintainer 字段为scottywei支持的硬件为 Morgan65 PCB。从 keyboard.json 可以看到该键盘的完整设备身份与硬件能力声明处理器atmega32u4引导加载器qmk-dfu可通过qmk dfu或 Bootmagic 进入 DFU 模式刷写USB 描述符VID0x8101BIOI 厂商 ID、PID0x6581、设备版本0.0.1启用的功能bootmagic、extrakey、command、backlight、rgblight、bluetoothmousekey 明确关闭构建选项开启lto链接时优化QMK 锁定状态同步qmk.locking.enabled true且resync true用于在重连时同步锁定键状态。这组配置说明 Morgan65 在 QMK 中是一个全功能键盘既有传统白光灯又有 WS2812 RGB 灯效还有蓝牙连接能力因此下文会分别展开这些子系统。构建固件在配置好 QMK 构建环境后编译该键盘的命令为继承自 readme 原文make bioi/morgan65:default其中default指 keymaps/default/keymap.c 中的默认键位。产物为可直接写入 ATmega32u4 的.hex固件配合qmk-dfu引导加载器刷写。该键盘目录下的 rules.mk 只有三行关键配置却揭示了它作为蓝牙键盘的两个核心特征# Processor frequency F_CPU 8000000 UART_DRIVER_REQUIRED yes SRC bluetooth_custom.cF_CPU 8000000将 CPU 主频设为 8 MHzATmega32u4 标称支持 16 MHz从源码结构看这是蓝牙键盘常见的低功耗折中UART_DRIVER_REQUIRED yes开启 UART 驱动——这正是自定义蓝牙方案的数据通道ATmega32u4 通过串口与蓝牙模块通信SRC bluetooth_custom.c将位于上级bioi目录的 bluetooth_custom.c 编入固件。注意该文件被 bioi 家族的多块键盘如 g60ble 等共享Morgan65 的蓝牙能力即来自这份共享实现。键盘矩阵与引脚分配Morgan65 的行列矩阵完全由 keyboard.json 中的matrix_pins字段声明采用COL2ROW列到行二极管方向14 列colsF5, F6, F7, C7, B0, B7, B5, D5, B4, D7, D6, D1, D0, B35 行rowsE6, C6, F4, B2, D4矩阵示意图见 matrix_diagram.md其要点是标准 5×14 的块状 65% 键阵第 0~3 行为完整 14 键列区第 4 行的布局与外观行不同40 41 42是左 Ctrl/GUI/Alt 三个 1.25u 键45是横跨 6.25u 的空格46是右 Alt4A 4B 4C是右 Ctrl/下/左右方向键区而43 44 47 48 49分散承担 F 区与退格键例如43对应 1u 的 F1/Home、49对应退格右侧的 Delete/Grave 位置图中标注了 2u 退格2u Backspace与 Tsangan 空格条40/41/42/45/4A 拼成的整条底行两种物理布局形态对应后面community_layouts中的标准版与 Tsangan 版键位宏。除键阵外其余外设引脚同样声明在keyboard.json中外设配置说明背光pin: B6levels: 1212 级白光灯可用BL_TOGG/BL_STEP控制RGBws2812.pin: B1led_count: 88 颗 WS2812饱和度与亮度各 8 档启用 breathing、rainbow_mood、rainbow_swirl、snake、knight、christmas、static_gradient、rgb_test、alternating、twinkle 共 10 种动画指示灯caps_lock: F0on_state: 0Caps Lock 指示灯接 F0低电平点亮默认键位布局默认 keymap 定义了 4 个 layerkeymap.c布局宏为LAYOUT_all其 5×14 参数顺序与矩阵示意图一一对应Layer 0基本层标准 ANSI 65% 布局。值得注意的是两个非直观映射——\Grave键实际位于矩阵[4, 9]退格右侧的窄键位而 F1~F4 被放在右侧竖列的[4, 3] [4, 4] [4, 7] [4, 8]UP方向键位于[3, 13]。底行是 Ctrl/GUI/Alt 6.25u 空格 Alt/Ctrl 三个方向键。Layer 1功能层数字键位变为 F1~F12Tab键位[1, 0]映射为QK_BOOT——按住可进入 bootloader 刷写固件这与bootmagic: true的 Bootmagic按住 Esc 进入 DFU形成两种刷写入口Q W E变为方向键上/左/下R为右配合构成方向键区底行集中了灯光与音量控制UG_TOGG切换 RGB 模式、UG_NEXT下一个动画、BL_TOGG白光灯开关、BL_STEP白光灯亮度步进、KC_MUTE、KC_VOLD、KC_VOLU。Layer 2 / Layer 3全部为_______无操作占位层为扩展保留。Magic Key 锁定功能Morgan65 的 config.h 启用了 QMK 的 Magic Key 键盘锁定功能/* key combination for magic key command */ #define KEYBOARD_LOCK_ENABLE #define MAGIC_KEY_LOCK LKEYBOARD_LOCK_ENABLE打开锁定键盘这一 Magic Key 能力MAGIC_KEY_LOCK L指定触发组合中包含字母L即按住 CtrlAlt 等修饰键后按 L具体组合由 QMK 的 Magic Key 约定决定。该功能的实现位于 quantum/command.ccommand.c会响应MAGIC_KC(MAGIC_KEY_LOCK)事件并在命令帮助中显示 Lock Keyboard而 quantum/command.h 提供了默认值——若未定义则回退为CAPS#ifndef MAGIC_KEY_LOCK # define MAGIC_KEY_LOCK CAPS #endif也就是说Morgan65 通过 config.h 覆盖默认值把锁定键盘的组合键从 Caps Lock 改到了 L 键上避免用户误触 Caps Lock 时意外锁定整个键盘。自定义蓝牙驱动UART AT 指令keyboard.json中bluetooth: { driver: custom }声明本键盘不走 QMK 内置的 Bluefruit 二进制驱动而是使用自定义实现。结合rules.mk中的UART_DRIVER_REQUIRED yes与 bluetooth_custom.c 可以还原完整链路ATmega32u4 主芯片以 76800 波特率通过 UART 连接一颗蓝牙模块将 HID 报告以 AT 指令文本形式发送出去从代码中ATBLEKEYBOARD*指令名可推断该模块为 Nordic Bluefruit LE 系列。关键实现有四处初始化bluetooth_inituart_init(76800)建立串口wait_ms(250)等待模块就绪后发送三组\r\n唤醒/清空缓冲区bluetooth_task为空实现说明该模块是单向透传、无需主芯片轮询回包键盘报告发送bluetooth_send_keyboard将标准 HID 键盘报告编码为一条 AT 指令——ATBLEKEYBOARDCODEmods-00-key1-key2-...-key6其中mods为修饰键字节随后按KEYBOARD_REPORT_KEYS循环追加 6 个键位码全部以两位十六进制文本send_bytes中的%02X格式化传输末尾以\r\n终止多媒体/消费者键bluetooth_send_consumer用CONSUMER2BLUEFRUIT宏把 QMK 的 HID Usage ID 一一映射到 Bluefruit 私有 bitmap例如AUDIO_MUTE → 0x00e2、AUDIO_VOL_UP → 0x00e9、TRANSPORT_PLAY_PAUSE → 0x00b1、AC_HOME → 0x0223再以ATBLEHIDCONTROLKEY0xhilo发出。代码中附有一张消费者键与 bit map 的对照表注释可作为协议参照调试支持定义BLUEFRUIT_TRACE_SERIAL后每次发送都会打印带边框的 HID 报告十六进制转储bluefruit_trace_header/footer便于排查蓝牙侧丢包或编码问题serial_send中的dprintf(Sending: %u\n, data)同样依赖 QMK 的 debug 输出。此外还有bluetooth_send_mouse会透传鼠标报告0xFD 0x00 0x03前缀按键/坐标/滚轮但由于keyboard.json中mousekey被设为false默认固件并不会产生鼠标报告——这段代码是共享文件中为同系列其他键盘保留的能力。这种AT 指令文本协议的方案优点是完全不依赖 QMK 蓝牙驱动对特定芯片库的绑定任何带 UART 的 MCU 均可复用代价是每次按键都发送一条约 30 字节的 ASCII 指令带宽与延迟表现不如二进制协议这也是蓝牙模式下典型可接受的取舍。社区布局与扩展keyboard.json的community_layouts列出 8 个社区版布局宏覆盖 ANSI/ISO × 标准底行/Tsangan 底行 × 常规退格/分体退格65_ansi_blocker、65_ansi_blocker_split_bs、65_ansi_blocker_tsangan、65_ansi_blocker_tsangan_split_bs及对应 ISO 版本。这些宏同时定义了每个键位的外观坐标x/y/w/h与矩阵坐标matrix可被 QMK 工具链如 keymap 编辑器直接消费其中LAYOUT_all即上文 keymap 所用的默认宏。小结Morgan65 在 QMK 仓库中是一个麻雀虽小、五脏俱全的移植范例keyboard.json以声明式方式集中了矩阵引脚、背光、RGB、USB 描述符与锁定同步等全部硬件事实rules.mk用三行完成蓝牙构建配置config.h微调 Magic Key 组合而真正的蓝牙能力由 BIOI 家族共享的 bluetooth_custom.c 通过 UART AT 指令实现。执行make bioi/morgan65:default即可得到完整固件理解上述各文件分工后也便于将其移植模式套用到其他带 UART 蓝牙模块的键盘上。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

QMK 固件中 Morgan65 的完整移植解析：USB/蓝牙双模 65% 键盘的构建、矩阵与自定义蓝牙驱动

相关推荐

SEO优化实战：关键词研究与内容创作全攻略

E2B生产级架构：预热池、MinIO分层存储与AI运维实践

rust-libp2p 的 Kademlia 协议栈演进史：从 0.20 到 0.49 的 API 变迁与配置实践

更多资讯

React Native在OpenHarmony中的列表性能优化实践

Python爬虫实战：网页数据抓取与Excel存储教程

行星齿轮内啮合副时变啮合刚度MATLAB计算解析

Flutter+OpenHarmony打造智慧井盖管理系统

AI Agent工程师：百万年薪背后的技术栈与职业路径

自部署CRM实战：从选型到上线，打造永久在线的客户管理系统

今日更新

AWS无服务器应用开发指南：从Lambda到SAM的架构与实践

SpringBoot+Vue人事系统实战：解决HR数据断点与事务一致性

MATLAB手写紧束缚模型计算石墨烯能带结构

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？