QMK Keyboard Metadata

QMK Keyboard Metadata【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmwareThis directory contains machine parsable data about keyboards supported by QMK. The latest version is always available online at https://keyboards.qmk.fm.Do not edit anything here by hand. It is generated with theqmk generate-apicommand.这份 readme.md 是生成目录的说明书明确了三个关键事实 1. **目录用途**该目录存放关于 QMK 所支持键盘的、可由机器解析machine parsable的数据 2. **线上权威版本**最新数据始终发布在 https://keyboards.qmk.fm仓库中的只是生成模板与产物 3. **生成方式**该目录内容由 qmk generate-api 命令自动生成**严禁手工编辑**。 需要注意的是data/templates/api/ 在当前仓库中仅包含 readme.md 这一份模板文件。真正的生成结果并不落在仓库里而是输出到构建目录 .build/api_data/见下文源码分析。这个模板目录 构建输出的设计让仓库保持整洁同时确保任何人在本地执行同一命令都能得到可复现的结果。 ## qmk generate-api 命令入口与参数 生成命令的完整实现位于 [lib/python/qmk/cli/generate/api.py](https://link.gitcode.com/i/8094d81a555856498d49c7061a5dc85f)。该文件通过 milc 框架注册了一个名为 generate_api 的子命令cli.subcommand(Generate QMK API data, ...)CLI 层面的名称即 qmk generate-api。 ### 命令行参数 从 [api.py](https://link.gitcode.com/i/8094d81a555856498d49c7061a5dc85f#L92-L94) 可以看到该命令支持两个参数 | 参数 | 说明 | | --- | --- | | -n, --dry-run | 只执行处理流程、不把数据写入磁盘Dont write the data to disk.用于验证与调试 | | -f, --filter | 按键盘名称的部分匹配过滤键盘列表Filter the list of keyboards based on partial name matches the supplied value. May be passed multiple times.可多次传递 | 例如测试用例 [lib/python/qmk/tests/test_cli_commands.py](https://link.gitcode.com/i/1298d95b469e97cfeb279f835366d239) 演示了最典型的组合用法 python def test_generate_api(): result check_subcommand(generate-api, --dry-run, --filter, handwired/pytest) check_returncode(result)即用--filter handwired/pytest把键盘列表收缩到测试键盘再配合--dry-run校验整个生成流程能否顺利跑通而不污染构建目录。目录规划与数据流脚本开头api.py定义了三个关键路径常量DATA_PATH Path(data) TEMPLATE_PATH DATA_PATH / templates/api/ BUILD_API_PATH Path(.build/api_data/)生成流程的核心数据流是清空并重建.build/api_data/若存在则先shutil.rmtree把data/templates/api/整体复制为.build/api_data/即把 readme 说明带进产物把整个data/目录constants、mappings、schemas 等复制为.build/api_data/v1/其中.hjson会被转换为.json、.jsonschema会被重新序列化见_filtered_copyapi.py逐一为每个键盘生成info.json与readme.md并把纯>{ keyboard_name: pytest, manufacturer: none, maintainer: qmk, usb: { vid: 0xFEED, pid: 0x6465, device_version: 0.0.1 }, matrix_pins: { cols: [F4], rows: [F5] }, diode_direction: COL2ROW, processor: atmega32u4, bootloader: atmel-dfu, layout_aliases: { LAYOUT: LAYOUT_ortho_1x1 }, layouts: { LAYOUT_ortho_1x1: { layout: [ {matrix: [0, 0], x: 0, y: 0} ] } } }keymap 的解析与发布在逐个键盘处理时api.py脚本会枚举该键盘的所有 keymaplist_keymaps(keyboard_name, cFalse, fullpathTrue)并做如下处理跳过不在 qmk_firmware 仓库内的 keymap跳过存在keymap.c的 keymap只发布纯>{ ranges: { 0x0000/0x00FF: { define: QK_BASIC }, 0x0100/0x1EFF: { define: QK_MODS }, 0x2000/0x1FFF: { define: QK_MOD_TAP }, 0x4000/0x0FFF: { define: QK_LAYER_TAP }, ... } }qmk.keycodes.load_spec会把这份 HJSON 与 data/schemas/keycodes.jsonschema 校验后按版本合并生成 API 消费者可直接引用的锁定版常量文件。消费侧视角keyboards.qmk.fm 与 QMK API生成的元数据在线上以 https://keyboards.qmk.fm 为权威发布点供 QMK Configurator、VIA 以及任何第三方工具消费。与之配合的异步编译服务 QMK API 的用法记录在 docs/api_docs.md提交编译任务向/v1/compilePOST 描述键盘与 keymap 的 JSON含keyboard、keymap、layout、layers等字段获得enqueued: true与job_id查询状态GET/v1/compile/job_id状态可取failed、finished、queued、running、unknown下载结果任务结束后从result中读取firmware_binary_url、firmware_keymap_url、firmware_source_url与编译日志output。对于常量消费docs/api_docs.md 说明了端点格式https://keyboards.qmk.fm/v1/constants_metadata.json https://keyboards.qmk.fm/v1/constants/{subsystem}_{version}.json【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考