Chocofly 60% 人体工学单块键盘QMK 固件从构建、刷写到自定义键位实战指南【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmwareChocofly 是一款开源的人体工学单块monoblock60% 键盘PCB 采用 Pro MicroATmega32U4主控并集成一颗旋转编码器。本指南以 QMK 仓库中的 Chocofly 官方定义为主体系统讲解其硬件配置、固件构建与刷写流程、默认键位逻辑以及基于源码的深度定制方法帮助读者从零开始完成 Chocofly 的固件上手与个性化改造。项目概览与硬件规格键盘定位与开源信息Chocofly 由 Vitaly Volkov 设计并维护定位为开源的、人体工学的单块 60% 键盘。其开源资料与硬件发布信息见 github.com/vlkv/chocofly包含以下核心文件v1/keyboard.jsonQMK 数据驱动配置声明矩阵、引脚、编码器、USB 标识与配列布局v1/keymaps/default/keymap.c默认三层键位映射readme.md官方 README含构建/刷写指引。该目录采用纯数据驱动data-driven方式定义键盘没有独立的config.h/rules.mk所有编译期配置全部收敛于 keyboard.json这正是 QMK 社区近年推荐的新式键盘目录结构。主控与兼容性根据 readme.md键盘维护者Vitaly Volkov硬件支持Chocofly PCB v1Pro Micro 5V/16MHz 及兼容板keyboard.json 中development_board: promicro声明开发板类型。查阅 data/mappings/defaults.hjson 可知promicro默认对应处理器atmega32u4Bootloadercaterina引脚兼容pin_compatible: promicro这意味着凡是与 Pro Micro 引脚兼容的主控如 Elite-C理论上均可使用QMK 会自动依据此映射推导编译与刷写参数。固件构建与刷写构建环境与目录层级Chocofly 存在 v1 修订版本因此完整的目标名包含修订号键盘全名chocofly/v1 默认键位default位于 [v1/keymaps/default](https://link.gitcode.com/i/81b10050389ed149c6f77a960cb7f329)构建命令在完成 QMK 构建环境配置详见 docs/newbs_building_firmware_workflow.md后执行make chocofly/v1:default该命令会基于 keyboard.json 生成矩阵、引脚初始化、USB 描述符等代码再编译出 hex/bin 固件。由于键盘启用了编码器见下文构建时 QMK 会自动启用ENCODER_ENABLE相关代码路径。刷写命令与 Bootloader 进入方式刷写命令make chocofly/v1:default:flash刷写前需将 PCB 置于 bootloader 模式。README 的 Bootloader 章节明确指出短暂按下 PCB 顶缘、微控制器旁边的那颗按钮。该操作会触发 Caterina bootloader对应 Pro Micro 默认 bootloader随后make ...:flash通过 avrdude 完成烧录。初次上手 QMK 的用户建议先阅读 docs/newbs_flashing.md 了解刷写原理。硬件配置深度解读keyboard.json 完整声明了 Chocofly 的电气与功能特性USB 标识usb: { vid: 0xCEE2, pid: 0x1001, device_version: 0.0.1 }功能开关features: { bootmagic: false, encoder: true, extrakey: false, mousekey: false, nkro: false }encoder: true启用旋转编码器支持QMK 编码器子系统bootmagic、nkro等均关闭保证固件精简。矩阵与二极管方向matrix_pins: { cols: [F4, F5, F6, F7, B1, B3, B2, B6], rows: [D1, D0, D4, C6, D7, E6, B4, B5] }, diode_direction: COL2ROW8 行 × 8 列矩阵二极管方向为 COL2ROW列到行这是大多数直列/正交键盘的接法。旋转编码器encoder: { rotary: [ {pin_a: D3, pin_b: D2, resolution: 2} ] }定义了一颗分辨率为 2 的旋转编码器。从 QMK 编码器实现 quantum/encoder.c 可见其处理流程encoder_init()初始化驱动encoder_task()在每轮主循环中轮询最终通过encoder_update_kb()非 ENCODER_MAP 模式或action_exec(MAKE_ENCODER_CW/CCW_EVENT(...))ENCODER_MAP 模式quantum/encoder.c分发事件。测试代码 quantum/encoder/tests/encoder_tests.cpp 也验证了resolution 决定多少脉冲计为一步的语义——例如 resolution 为 4 时需 4 个脉冲才产生一次更新Chocofly 取 2 意味着每 2 个 detent 脉冲触发一次事件。配列布局 LAYOUTlayouts.LAYOUT定义了 60 键位的物理坐标x/y与矩阵位置matrix的映射构成类似 Alice/arisu 的分列式人体工学排布左右手区域分开、中间留出拇指区其中matrix: [1, 3]x6.5, y2.375、[3, 3]/[2, 3]、[2, 4]/[3, 4]、[7, 3]~[4, 4]等即拇指群与中缝按键整张配列共 8×864 个矩阵位置中的 60 个被使用其余留空。默认键位解析默认键位位于 v1/keymaps/default/keymap.c共 3 层_QWERTY、_LOWER、_RAISE。层定义与自定义键码enum layers { _QWERTY, _LOWER, _RAISE, }; #define RS_SPC LT(_RAISE, KC_SPC) // 空格 按住进 RAISE #define LW_LGUI LT(_LOWER, KC_LGUI) // 左 GUI 按住进 LOWER #define RS_LGUI LT(_RAISE, KC_LGUI) #define MT_LALT LALT_T(KC_ESC) // 左 Alt 按住为 Alt单击为 Esc #define MT_RALT RALT_T(KC_ENT) // 右 Alt 按住为 Alt单击为 Enter #define MT_LSFT LSFT_T(KC_EQL) // 左 Shift 按住为 Shift单击为 #define MT_RSFT RSFT_T(KC_MINS) // 右 Shift 按住为 Shift单击为 -QWERTY 主层主层布局体现分列式 拇指区设计F 区KC_F1~KC_F12位于最上行左右两端主字母区TAB/Q/W/E/R/T 与 Y/U/I/O/P/[ 分居左右KC_BSLS与KC_MUTE布局于左/中位置KC_MUTE需系统多媒体键支持中缝与功能键KC_GRV、KC_INS、KC_PSCR、KC_RBRC排布在中间列拇指区LW_LGUI、MT_LSFT、RS_SPC、MT_LALT、MT_RALT、MO(_LOWER)、MT_RSFT、RS_LGUI八个键承担空格、层切换与组合修饰键职能。LOWER 层数字与符号顶层KC_EXLM~KC_CIRC/KC_AMPR~KC_EQL等上档符号数字行KC_0~KC_9含KC_PCMM编辑区KC_HOME/KC_UP/KC_END、KC_LEFT/KC_DOWN/KC_RGHT、KC_PGUP/KC_APP/KC_PGDN配合KC_BSPC/KC_DEL未用键以_______透传与XXXXXXX空键填充便于在自定义键位中保留层结构。RAISE 层括号与符号增强括号区KC_LBRC/KC_RBRC、KC_LPRN/KC_RPRN、KC_LCBR/KC_RCBR三层括号按行分布数字对应上档符号KC_EXLM、KC_AT、KC_HASH、KC_DLR、KC_PERC、KC_CIRC、KC_AMPR、KC_ASTR、KC_PCMM编辑键KC_DEL/KC_BSPC与方向键同 LOWER 层互补。进阶定制键位与编码器扩展自定义键位将default键位目录复制为新的键位名如mykeymap修改keymap.c后执行make chocofly/v1:mykeymap你可以修改enum layers增加新层如_FN调整拇指区LT()/MO()的组合方式例如将RS_SPC改为MT(MOD_LSFT, KC_SPC)实现Shift空格在_LOWER/_RAISE中为编码器预留触发键若需配合 ENCODER_MAP。编码器键位映射由于 keyboard.json 已声明encoder: true且默认键位未使用encoder_map默认固件中编码器事件会走encoder_update_kb()弱符号用户可在 keymap 中覆盖encoder_update_user()。若希望在键位层面为编码器绑定按键可在 keymap 中定义encoder_map需ENCODER_MAP_ENABLEQMK 会通过 quantum/encoder.c 的action_exec(MAKE_ENCODER_CW/CCW_EVENT(...))将其转换为普通按键事件实现旋转调节音量、滚动页面等操作。常见问题排查刷写失败确认已按下 PCB 顶缘 bootloader 按钮且 USB 设备枚举为 Caterina 设备Pro Micro 默认编码器无响应核对 keyboard.json 中pin_a: D3/pin_b: D2与实物接线resolution数值决定手感灵敏度键位错乱检查diode_direction: COL2ROW是否与实物矩阵接法一致构建报错找不到目标确认使用chocofly/v1完整路径且 QMK 固件版本已同步至包含该键盘的版本。总结Chocofly 以数据驱动方式在 keyboards/chocofly 中完整声明了矩阵、编码器、USB 标识与人体工学配列配合make chocofly/v1:default一条命令即可构建make chocofly/v1:default:flash配合顶缘按钮即可刷写。其默认键位通过LT()、MT()等 QMK 高级键码在 60% 布局内实现了完整符号层与拇指区设计结合 quantum/encoder.c 的编码器事件分发机制用户可进一步自定义编码器行为与分层键位获得高度个性化的输入体验。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
