QMK固件中keymap.c到JSON转换的层信息处理优化

在QMK固件开发过程中，键盘布局定义通常使用keymap.c文件，其中包含多个按键层(layer)的定义。当需要将这种C语言格式的键盘布局转换为JSON格式时，现有的转换工具在处理层间引用时存在一些不足，这给开发者带来了不便。

现有转换机制的问题

当前QMK提供的c2json转换工具能够将keymap.c文件转换为JSON格式，但在处理层间引用时存在以下局限性：

1. 层引用信息丢失：当使用LT()、MO()等层切换宏时，JSON输出中保留了原始的层名称(如_SETUP)，但没有提供这些名称对应的实际层索引或定义

2. 缺乏层元数据：转换后的JSON仅包含按键代码数组，不包含层的命名信息，使得解析工具无法理解层间的逻辑关系

3. 可读性降低：开发者无法直接从JSON文件中理解各层的用途和相互关系

技术背景

在QMK固件中，键盘布局通过分层系统实现：

• 每个层都是一个完整的按键矩阵布局
• 通过enum定义层名称和索引
• 使用特殊宏实现层间切换：
  • MO(layer)：瞬时切换到指定层
  • LT(layer, kc)：按住时切换到指定层，松开时触发按键
  • TG(layer)：切换层的开关状态
  • DF(layer)：设置默认层

优化方案分析

针对这一问题，提出了两种可行的优化方案：

方案一：结构化层定义

将JSON中的layers字段从数组改为对象，使用层名称作为键：

"layers": {
    "_COLMAK": [...],
    "_SYMBOLS": [...],
    "_NUMPAD": [...]
}

优点：

• 保留了完整的层命名信息
• 直接反映源代码中的组织结构
• 便于工具解析和理解层关系

缺点：

• 可能破坏现有依赖数组顺序的工具
• 需要修改JSON解析逻辑

方案二：层引用索引化

保持数组结构，但将层引用转换为数字索引：

"layers": [
    ["LT(2, KC_ESC)", ...],  // 2表示_SETUP层
    [...],
    [...]
]

优点：

• 保持向后兼容
• 减少文件体积
• 便于程序处理

缺点：

• 可读性降低
• 需要额外文档说明索引对应关系

实现建议

结合两种方案的优点，建议采用混合模式：

1. 保留现有数组结构保证兼容性
2. 添加层元数据字段描述各层信息
3. 提供可选参数控制输出格式

示例实现：

{
    "keyboard": "sofle/rev1",
    "keymap": "default",
    "layer_info": {
        "names": ["_COLMAK", "_SYMBOLS", "_NUMPAD"],
        "descriptions": ["主布局层", "符号层", "数字小键盘层"]
    },
    "layers": [...],
    "layout": "LAYOUT"
}

对开发者的影响

这一优化将显著改善：

1. 工具链集成：IDE和可视化工具可以更好地理解键盘布局结构
2. 文档生成：自动生成更准确的键盘布局文档
3. 调试体验：开发者可以更直观地查看层间关系
4. 协作开发：JSON文件包含更多语义信息，便于团队协作

总结

QMK固件的c2json转换工具在处理层信息方面还有优化空间。通过增强JSON输出中的层元数据，可以提升开发体验和工具链的集成能力。建议采用兼顾兼容性和可读性的混合方案，既保留现有数组结构，又添加描述性的层信息字段。这一改进将使QMK固件的键盘布局定义更加清晰和易于维护。