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_firmware

This 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` | 只执行处理流程、不把数据写入磁盘（"Don't 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_copy，api.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），脚本会枚举该键盘的所有 keymap（list_keymaps(keyboard_name, c=False, fullpath=True)），并做如下处理：
- 跳过不在 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），仅供参考

企业官网建设流程全解析