我最近买了一个便宜的宏键（当然，还写了些文章）。它出奇地好用，而且价格也不贵。但我买的时候有点后悔。这种东西自己做应该很容易。现在人们经常自己做键盘，而且按键数量少，你甚至不用扫描矩阵。每个开关只需要一个 I/O 引脚。
宏键盘上有一些古怪的软件，幸运的是，人们已经用开源替代品替换了它们。但如果我要自己动手，使用像 QMK 这样的软件会比较明智，就像一个大键盘一样。但这让我不禁思考，为一个简单的项目设置 QMK 会有多麻烦。剧透：其实很简单。
硬件
简单的徽章还是原型宏键？为什么不两者兼而有之？
由于我只是想做个实验，所以很想在面包板上装几个开关，再配上一台 Raspberry Pi Pico。但后来我想起了附近架子上放着的那个“简易徽章”项目。它本身就很简单：一个 RP2040-Plus（普通的 Pi Pico 也可以）和一块小型扩展板，上面有一个开关“操纵杆”、四个按钮和一个小显示屏。这个项目其实不需要 Plus，因为与徽章不同，它不需要电池。USB 数据线可以为设备供电，并将键盘（甚至鼠标）命令传输回电脑。
实用吗？不实用。不过，连接任何你喜欢的开关都很容易。我没有用到显示器，所以如果你想复制这个项目，就没必要连接显示器了。
软件
市面上有多种键盘固件可供选择，但 QMK 可能是最常见的。它支持 Pico，并且支持良好。它采用模块化设计，提供丰富的功能。
我做的第一件事就是克隆Git 存储库并开始我自己的分支来工作。有许多源文件，但大多数文件不需要做太多。
有一个名为keyboards的目录。里面包含不同类型的键盘（通常是不同品牌的键盘）的目录。此外，还有一个名为handwired的目录，用于定制键盘，里面包含多个目录。
有一个特别值得关注的目录： onekey 。这有点像 QMK 固件的“Hello World”。里面有不同 CPU 的目录，包括我计划使用的 RP2040。不过，如果你喜欢其他的，还有很多其他选择。
惊喜！
感兴趣文件的快速指南。
那么，该目录中可能有很多文件，对吧？其实不然。它只有五个文件，包括一个 readme 文件，仅此而已。其中，我只打算修改两个： config.h和keyboard.json 。此外，父目录中还有一些可能很重要的文件： config.h 、 onekey.c和info.json 。
我不想干扰股票期权，所以我在~/qmk_firmware/keyboards/handwired/hackaday创建了一个目录。我将onekey的文件以及rp2040和keymap目录（这个很重要）复制到了这个目录。我将onekey.c重命名为hackaday.c 。
乍一看可能有点令人困惑，但这张图或许能帮到你。这份文档也会有所帮助。好消息是，这些文件中的大多数文件你甚至不需要更改。本质上， info.json适用于任何处理器， keyboard.json适用于特定的处理器，而keymap.json则适用于特定的键盘映射。
变化
根目录下hackaday.c config.h 无需任何修改，不过如果你介意的话，可以在这里禁用某些功能。hackaday.c 文件里有一些调试选项设置为 true，但为了简单起见，我把它们全部设置为 false。
info.json文件是最有趣的。你可以在那里设置键盘名称和 USB ID 等。其余部分我没有改动，尽管此文件中的diode_direction键在本项目中不会用到。此外，只有当你有可以锁定的物理按键时才需要locking部分，但我保留了它，因为它不会造成任何影响。
在rp2040目录中，还有更多更改。config.h config.h允许您设置各种设备的引脚编号，我还在其中添加了一些鼠标参数（稍后会详细介绍）。我实际上并没有使用这些东西（SPI 和显示器），所以我可以删除其中的大部分内容。
但最大的变化是在keyboard.json文件中。在这里，您可以设置处理器类型。但最重要的是设置按键和一些功能标志。通常，您需要描述键盘行和列的配置方式，但这个简单的设备只是直接连接。您仍然需要设置虚拟的行和列。在本例中，我选择设置两行，每行五列。第一行是四个按键（以及一个死区）。第二行是摇杆按键。您可以在文件的matrix_pins部分中看到它们。
布局部分非常简单，为每个按键指定了一个名称。我还设置了一些选项，允许使用虚拟鼠标键和媒体键（将mousekey和extrakey设置为 true）。文件内容如下：
{ “键盘名称”：“RP2040_Plus_Pad”， “处理器”：“RP2040”， “引导加载程序”：“rp2040”， “矩阵引脚”：{ “直接的”： [ ["GP15", "GP17", "GP19", "GP21", "NO_PIN"], [“GP2”，“GP18”，“GP16”，“GP20”，“GP3”] ] }， “特征”： { “鼠标键”：true， “extrakey”：是的， “nkro”：错误， “启动魔法”：假 }， “布局”：{ “布局”： { “布局”： [ { “标签”：“K00”， “矩阵”：[0，0]，“x”：0，“y”：0}， { “标签”：“K01”， “矩阵”：[0，1]，“x”：1，“y”：0}， { “标签”：“K02”， “矩阵”：[0，2]，“x”：2，“y”：0}， { “标签”：“K03”， “矩阵”：[0，3]，“x”：3，“y”：0}， { “标签”：“K10”， “矩阵”：[1，0]，“x”：0，“y”：1}， { “标签”：“K11”， “矩阵”：[1，1]，“x”：1，“y”：1}， { “标签”：“K12”， “矩阵”：[1，2]，“x”：2，“y”：1}， { “标签”：“K13”， “矩阵”：[1，3]，“x”：3，“y”：1}， { “标签”：“K14”， “矩阵”：[1，4]，“x”：4，“y”：1} ] } } }
键盘映射
好像还缺了点什么。每个按键对应的键码。它位于../hackaday/keymaps/default目录中。还有一个你不需要修改的 json 文件和一个 C 文件：
#包括 QMK_KEYBOARD_H const uint16_t PROGMEM 键映射[][MATRIX_ROWS][MATRIX_COLS] = { [0] = 布局( // 4 个按钮 音量增加键、静音键、音量减小键、媒体播放暂停键 // 老鼠 QK_MOUSE_CURSOR_UP，QK_MOUSE_CURSOR_DOWN， QK_MOUSE_CURSOR_LEFT，QK_MOUSE_CURSOR_RIGHT， QK_MOUSE_BUTTON_1 ), }; ...
鼠标移动
我后来才添加了鼠标命令。添加之后，它们似乎不起作用。当然，我必须启用鼠标命令，但仍然不起作用。让我困扰了好几次的是，QMK Flash 脚本（见下文）不会等待 Pi Pico 下载完成。所以有时你以为下载完成了，但实际上并没有。有几种方法可以解决这个问题，正如你将看到的。
杂项和建筑
安装 QMK 很简单，但具体方法取决于您的电脑类型。文档会是您的好帮手。同时，我保留了官方固件的 fork 版本供您使用。请务必切换到rp2040分支，否则您将看不到与官方 repo 的任何差异。
您可以在不同目录中的rules.mk文件中添加一些构建选项。如果您想使用显示屏等功能，QMK 内置了大量 API。您还可以将代码添加到keymap.c （以及其他地方）中，以便在启动时运行代码。您可以在文档中了解更多可能性。例如，如果您想尝试 OLED 显示屏，这里有现成的驱动程序可供使用。
第一次刷机时，您需要将 Pico 置于引导加载程序模式，然后尝试以下操作：
qmk flash -kb handwired/hackaday/rp2040 -km 默认
如果您尚未准备flash ，请尝试compile命令。您也可以使用clean清除所有二进制文件。这些二进制文件最终位于qmk_firmware/.build中。
首次安装引导加载程序后（假设您未更改设置），您可以通过双击重置按钮返回引导加载程序模式。板载 LED 将亮起，表示您已处于引导加载程序模式。
务必等待树莓派断开连接，否则可能无法完成编程。在烧写命令末尾添加sync命令是个不错的选择。或者，耐心等待树莓派自动断开连接。
通常情况下，设备会自动重置并变成键盘。如果没有，请自行重置，或拔掉电源再重新插入。这样您就可以使用四个按钮来调节音量和静音。摇杆会伪装成鼠标。不喜欢这样？请在keymap.c.
当然还有很多内容，但这能帮你入门。一开始可能有点混乱，但一旦你完成了一次，你就会发现其实不需要做太多改动。如果你浏览一下文档，你会发现它对不同类型的硬件提供了丰富的支持。
那调试呢？运行一些用户代码？我留到下次再说。
现在，您可以打造您梦想中的宏键或键盘，甚至可以用它来制作模拟键盘设备，从用户输入以外的其他来源获取数据。记得给我们留言，告诉我们您的作品。
原文： https://hackaday.com/2025/08/20/instant-macropad-just-add-qmk/