<h3>注意：本项目因个人原因未完工，仅分享QMK相关内容，硬件内容见后续吧。</h3> <p>其实是主控不慎烧掉了，后面在校有事又没时间...</p> <h2>1、项目功能介绍</h2> <p>基于 QMK 固件的、支持 VIA 软件改键的 DIY 热插拔小键盘。</p> <h2>2、项目属性</h2> <p>本项目为原创，首次公开。</p> <h2>3、开源协议</h2> <p>GPL 3.0</p> <h2>4、软件部分</h2> <p>以下内容为一个 QMK 新手在尝试过程中的一些经验和记录，如有错误望指正。</p> <p>此部分内容仅记录Rev1设计过程，截图等不代表最终成品！内容仅供参考。</p> <h3>0、QMK简介</h3> <p>QMK (Quantum Mechanical Keyboard) 是一个社区维护的开源软件，包括 QMK 固件，QMK 工具箱，qmk.fm 网站，和这些文档。QMK 固件是一个基于 tmk_keyboard 的键盘固件，它在 Atmel AVR 微控制器实现一些有用的功能。它被移植到使用 ChibiOS 的 ARM 芯片上. 它可以在飞线键盘或定制 PCB 键盘中发挥功能。</p> <h3>1、安装编译环境</h3> <p>本项目采用Windows系统下 <code>QMK MSYS</code> 软件配置编译环境，安装方便简洁。下面介绍安装流程。</p> <p>如果使用其它系统，请参照官网文档进行相应的环境搭建工作。</p> <p>首先，进入 <a href="https://github.com/qmk/qmk_distro_msys" target="_blank">QMK MSYS</a> 项目页面，于 Release 中下载最新版软件并安装。</p> <p>打开，运行 <code>qmk setup</code> 命令，此步骤需要较长时间 会魔法的兄弟忽略这句话就好。直到显示 <code>QMK is ready to go</code>。</p> <p><img src="//image.lceda.cn/pullimage/fCtV1tQNHkFIkiqXxVvnNy8DbXdp8SMYfUk3gnMx.png" alt="image-20210824161154918.png"></p> <h3>2、初编译</h3> <p><code>qmk setup</code>后，尝试初次编译键盘固件以确认环境搭建成功。（防止丢包、缺失文件导致后面编译出错）</p> <p>可输入</p> <pre><code>qmk compile -kb dz60 -km default</code></pre> <p>以尝试编译 dz60 键盘在默认布局下的固件。（随便选的一个键盘，当然可以选其他的来测试）</p> <p>如果出现一串 OK 并在最后显示 <code>The firmware size is fine</code>，恭喜你，环境搭建完成，且你已经第一次成功编译了一个QMK键盘固件。</p> <p>如果报错，请检查命令是否有误，并检查报错信息，补全文件，再次尝试编译。</p> <p>成功示例（不是第一次编译故 OK 的数量很少）：</p> <p><img src="//image.lceda.cn/pullimage/JTobV8juqgCX2MCtOxTDz1bLwstyAOADCPpk8ZCm.png" alt="image-20210824161941066.png"></p> <h3>3、构建自己的键盘固件</h3> <p>下面来构建自己的键盘固件。</p> <h4>0、了解QMK文件夹的文件结构</h4> <ul> <li>用户空间结构 在users文件夹里面的目录是每个用户的目录。这个文件夹里面放的是用户们在不同键盘都能用到的代码。</li> <li>键盘项目结构 在 keyboards 文件夹和他的子文件夹 handwired 中就是各个键盘的项目了，比如qmk_firmware/keyboards/clueboard。内部结构与如下: <ul> <li>keymaps/ : 可以构建的不同布局</li> <li>rules.mk : 用来设置 “make” 命令默认选项的文件。</li> <li>config.h : 用于设置默认编译选项的文件。</li> <li>在各个布局的文件夹，你能找到以下文件。只有 keymap.c 是必要的, 如果其他文件找不到就会直接选择默认选项。 <ul> <li>config.h: 配置布局的选项</li> <li>keymap.c: 布局的全部代码, 必要文件</li> <li>rules.mk: 使能的QMK特性</li> <li>readme.md:介绍你的布局,告诉别人怎么使用，附上功能说明。</li> <li>config.h 文件</li> </ul></li> </ul></li> </ul> <p>有三个重要的config.h 位置:</p> <p>键盘 <code>/keyboards//config.h</code></p> <p>用户空间 <code>/users//config.h</code></p> <p>布局 <code>/keyboards//keymaps//config.h</code></p> <p>了解完毕！虽然自己的工程不必按照官方要求来建立文件。</p> <h4>1、设计键盘布局</h4> <p>进入<a href="http://www.keyboard-layout-editor.com/#/" target="_blank">Keyboard Layout Editor</a> 网站。这是一个可视化键盘布局编辑网站，通过增减键和调整键的位置和定义来生成键盘布局。设计自己的键盘布局后，下载 json 文件。</p> <p><img src="//image.lceda.cn/pullimage/AYnXYPdKZABwCUGkIzzE2L8ODKvS8GjxszYAvDCS.png" alt="Snipaste_2021-08-24_13-31-26.png"></p> <p>设置键名如上是为了方便后面添加 VIA 支持，如果不需要可以直接命名成自己所需键的名称，以方便检查。</p> <h4>2、初步生成QMK固件</h4> <p>进入 <a href="https://kbfirmware.com/" target="_blank">Keyboard Firmware Builder</a> 网页，将前面的 json文件复制进来。</p> <p>Wiring界面：编辑键盘连线。</p> <p><img src="//image.lceda.cn/pullimage/t4kTGFgardU0vQriR3BsATKZYZOdKsuwNKC3CiAZ.png" alt="Snipaste_2021-08-24_13-31-44.png"></p> <p>Rows 表示行数，Columns 表示列数，同时可以选中某一个键，调整其行、列号，使其连线确定，同时可以美化走线。</p> <p>Pins界面：设置行列对应的主控引脚。</p> <p><img src="//" alt="Snipaste_2021-08-24_13-46-54"></p> <p>注意！本文仅作步骤解释，图示并不完全为正确操作！（如上图，引脚是不同的）</p> <p>Keymap界面：选择某个键，编辑它在某一层（layer）时的功能。</p> <img src="//" alt="image-20210824165202976"> <p>键码的具体含义请前往 QMK 文档<a href="https://docs.qmk.fm/#/keycodes" target="_blank">Keycodes</a>部分进行查看。</p> <p>需要注意的是：当使用到不止一层时，需要添加切层键，具体设置请参照官方文档。</p> <p>Macros界面：键盘宏相关，作者尚不了解，请参照官方文档。</p> <p>Quantum界面：大大的警告，不建议更改。</p> <p><img src="//image.lceda.cn/pullimage/L6XtqTzjkJk8deU6KHWRBsMwnPQKSFQ8jNUjGX7V.png" alt="image-20210824165655964.png"></p> <p>Settings界面：修改键盘名称、容量、WS2812数量、背光亮度等设置。</p> <p>Compile界面：完成全部设置并下载固件的界面</p> <p>如果所需功能较简单，经过以上步骤可以直接配置完成的，可以选择直接下载 .hex 文件，烧录之。</p> <p>如果需要复杂功能（如oled，编码器等），请下载 .zip 文件，里面是该网页自动生成的、未进行编译的 QMK 固件，我们将在其基础上进行修改以满足自己的需求。</p> <h4>3、生成定位板</h4> <p>进入 <a href="http://builder.swillkb.com/" target="_blank">Plate & Case Builder - swillkb</a>，上传键盘配列的 json 文件，网站将自动生成适用于 CherryMX 系列机械键盘轴体和钢板卫星轴的定位板，下载 dxf 文件即可。此文件可以用于制作各种材质的定位板 你要无钢就当我没说</p> <p><img src="//" alt="image-20210824170513233"></p> <h4>4、代码部分</h4> <p>以我自己的代码为例。</p> <p>首先看 <code>rules.mk</code> 文件。</p> <p><img src="//" alt="rules.mk"></p> <p>在最下方添加</p> <pre><code>ENCODER_ENABLE ?= yes VIA_ENABLE ?= yes</code></pre> <p>以实现编码器支持和 VIA 支持。（如不需要 VIA 改键请不要开启）</p> <p>如需其他功能请依照 QMK 官方文档自行添加开启。</p> <p>其次，<code>nk01.h</code> 文件。如果是由网页生成的初始固件，该文件名为 <code>kb.h</code>。建议将其修改为自己的键盘名称。注意：需要同步修改 kb.c 和 kb.h 文件，并修改各文件中头文件名称。</p> <p><img src="//" alt="nk01.h"></p> <p>这个文件定义的是键盘各键的行列序号。理论上无需修改，但请确认与设计稿无出入。</p> <p>然后是 <code>keymap.c</code> 文件。这个文件定义的是键盘的功能。</p> <p><img src="//" alt="keymap.c"></p> <p>5 - 8 行定义的是各层的名称。</p> <p>10 - 26 行定义的是各层键值，可依据 <a href="https://docs.qmk.fm/#/keycodes" target="_blank">QMK Keycodes</a> 列表进行自行修改。</p> <p>29 - 46 行定义的是编码器功能。QMK 文档中有更深解析，如有需求可前往查看。</p> <p>各种切层方法：</p> <p>MO(layer) 按下触发层， 可以把 MO(layer) ， 理解成 Fn。 当松开这个键， layer 层会释放并恢复到上一层。若把 MO(layer)设置到一个键位， layer 层中的同一键位必须设置为 KC_TRNS，否则在松开这个按键的时候不会回到上一层。 若把第 0 层的 ESC 设置为 MO(1)， 则在第一层 ESC 的位置只能设置成 KC_TRNS。同时只能把 MO(layer) 这个键设置到 layer 上面的层， 比如可以在第 0 层设置 MO(1)，但是不能在第 1 层设置 M0(0)。</p> <p>OSL(layer) 临时触发层， 如果把一个键位设置为 OSL(1) ， 点击这个按键后， 只有下一个点击的按键会从层 1 触发。 之后的点击回立即回到层 0 触发。</p> <p>LT(layer, kc) 可以把 LT(layer, kc) 理解成 MO(layer)+kc 一键两用。 当长按这个键， 键位的功能就是 MO(layer) ，点击这个键， 键位的功能就是 kc。经大佬测试， 这里的 kc 不能设置为 mod(Ctrl，Alt，GUI，Shift 等键)</p> <p>LM(layer,mod) 可以把 LM(layer, mod) 理解成 MO(layer)+mod 一键两用。 当你长按这个键， 键位的功能就是MO(layer)+ mod 同时生效。这样可以把 mod 键一键两用。</p> <p>TO(layer) 一键切换到 layer。可以在任意层中设置。例如在层 0 设置了 TO(2) ， 但是要记得最后在层 2 中设置 TO(0)来恢复到默认层。</p> <p>TG(layer) 类似于 TG(layer)，但是只能在某两层中来回切换。例如在层 0 中 ESC 的位置设置了 TG(5)，按下后会立即跳转到层 5 中， 在层 5 中 ESC 的位置只能设置为 KC_TRNS。 只能把 TG(layer) 这个键设置到 layer 上面的层，比如可以在第 0 层设置 TG(5)，但是不能在第 5 层设置 TG(0) 。</p> <p>DF(layer) 键盘的默认层是层 0， 此键位的功能是设置默认层为 layer ， 非必要不用改动默认层。</p> <p>最后来到最复杂的 <code>config.h</code> 文件。</p> <p><img src="//" alt="config.h"></p> <p>其中主要部分不要改动。</p> <p>7 - 12 行可自行更改。（如果计划使用VIA请查看VIA部分并修改）</p> <p>15、16行为行列数量。</p> <p>19、20行定义行列对应引脚号。</p> <p>24行定义二极管方向。</p> <p>50、51、52分别定义编码器分辨率和 A、B 引脚连线。</p> <h4>*5、VIA支持</h4> <p>此部分请自行考虑是否进行，因为大多数使用者并不会频繁出现改键需求。如有需求请前往官网下载VIA软件。（安装包太大了发不上来）</p> <p>VIA 官网链接：<a href="https://caniusevia.com/" target="_blank">VIA</a></p> <ol> <li><code>rules.mk</code> 添加</li> </ol> <pre><code>VIA_ENABLE ?= yes</code></pre> <p>语句，即开启 VIA 支持。 2. 依照 <code>config.h</code> 文件编写 <code>via.json</code> 文件。 以我的项目为例： <img src="//" alt="via.json"> 格式需完全一致。 保存文档。</p> <ul> <li><code>"name"</code>：键盘名，将显示在 VIA 中。</li> <li><code>"vendorId"</code>：即 <code>config.h</code> 文件中的 VENDOR_ID。</li> <li><code>"productId"</code>：即 <code>config.h</code> 文件中的 PRODUCT_ID。</li> <li><code>"lighting"</code>：灯光，因为个人爱好无光键盘故选择 none，若有需求请参照 VIA 官方文档。</li> <li><code>"matrix"</code>：分别输入行、列数量。</li> <li><code>"layouts"</code>：对于固定配列的键盘（即不能更改键长宽位置的），将 KLE 网站下载的 RawData 复制并修改为正确格式即可。若是可变配列型，请参照 VIA 官方文档。</li> </ul> <p>3. 测试 json 文件可行性。 - 打开 VIA 软件，进入 Settings，开启 Design。 - 进入 Design，上传编辑好的 via.json。 - 若成功，将出现如下（或类似）界面。</p> <ul> <li><img src="//" alt="Snipaste_2021-08-25_15-52-08"> * 若不成功或键盘配列怪怪的（键重叠等等），依照报错内容修改 json 文件。 * 硬件制作完成后可测试改键功能。如下图。 <img src="//" alt="image-20210828102704149"></li> </ul> <p>以上部分均基于 Rev1。基础功能其实在烧主控之前已经验证了。</p> <h4>6、生成hex文件</h4> <p>打开 QMK MSYS，初始化后，输入</p> <pre><code>qmk compile -kb nk01 -km default</code></pre> <p>如果是其他键盘或其他配列请自行更改。</p> <p>如果顺利，将出现类似界面。</p> <p><img src="//" alt="image-20210825100023963"></p> <p>恭喜！键盘固件顺利完成！</p> <h2>5、硬件部分</h2> <p>硬件部分包含 Type-C 输入、USB拓展、MCU主控、控制元件四部分组成。请参照附件查看。</p> <p>设计选用 ATmega32U4 作键盘主控 废话固件都写好了。轴体采用热插拔轴座固定方式，方便更换轴体。编码器选用EC11。FE8.1 作USB拓展芯片（问就是SL2.1A烧了好多次了）。Rev 1 版本分别在前后侧引出1、2USB接口，其中靠近Type C 接口侧是用来与主键盘连接 这难道不是分体键盘？，如果使用有线鼠标的可以上方2USB下方1USB以方便放线。Rev 2 版本因插件元件受限，只能将剩余两个usb接口放在右侧（但是我是左手小键盘啊喂）。</p> <h2>6、其他工作</h2> <h3>焊接</h3> <p>（主控烧了导致无法按时完工）</p> <p><img src="//image.lceda.cn/pullimage/zByEcBHQrQZJhEpT8a7DRWml6VE4xltMTce4wTgt.png" alt="image-20210916162727024.png"></p> <h3>烧录</h3> <ol> <li>烧录 Bootloader。 选用 Arduino IDE 烧录。方法如下： <ul> <li>打开 Arduino IDE，版型选择为 Leonardo，烧录方法选择为 USBasp。</li> <li>通过 USBasp 和测试针连接主控，压紧，选择烧录引导程序。</li> <li>烧写完成。</li> </ul></li> <li>烧录键盘固件。 若选用 QMK Toolbox，方法如下： <ol> <li>打开 QMK Toolbox，选中固件，MCU选择为 ATmega32U4。</li> <li>选择键盘和布局，打开自动烧录。</li> <li>连接键盘，reset，开始烧录。</li> <li>烧录完成。</li> </ol></li> <li>若选用 avrdudess，方法如下： <ol> <li>打开 avrdudess，编程器选择为 USBasp，MCU 选择为 ATmega32U4。</li> <li>测试针连接主控，尝试连接芯片。</li> <li>选择键盘固件，烧录。</li> <li>烧录完成。</li> </ol></li> <li>测试键盘。 VIA 软件内 KeyTester 一条龙服务。</li> </ol> <h2>7、BOM清单</h2> <p>因时间原因未按时完工，截止比赛结束仅分享QMK软件部分，故不包含BOM表。</p> <h2>8、大赛LOGO验证</h2> <p>请上传包含大赛logo的项目图片，logo以丝印形式印刷在PCB上面。</p> <p><img src="//image.lceda.cn/pullimage/zByEcBHQrQZJhEpT8a7DRWml6VE4xltMTce4wTgt.png" alt="image-20210916162727024.png"></p>