从按下 Voice 到生成 UF2，这个项目怎样工作？

这个仓库不是一个传统应用

仓库里没有自己编写的主循环，也没有一套 C/C++ 应用代码。它更像一组交给 ZMK 的声明：选择哪块开发板、按钮接在哪些 GPIO、五个位置分别做什么，以及怎样构建和刷写。

按下一颗按钮以后发生了什么？

运行链路依次经过物理电路、GPIO 扫描、位置顺序、键位绑定和 HID 传输。每层只回答一个问题。

1. 电路：按钮把一个 XIAO GPIO 接到 GND。
2. 扫描：ai_remote.overlay 告诉 ZMK 读取 D0–D4，并启用内部上拉与低电平有效。
3. 位置：同一个 overlay 把五个 GPIO 排成从 0 到 4 的一行五列。
4. 行为：ai_remote.keymap 按相同顺序绑定 F13、↑、Enter、↓ 和 BT_NXT。
5. 输出：ZMK 根据配置通过 USB HID 或 BLE HID 把事件发给电脑。

硬件输入：ai_remote.overlay

input-gpios
    = <&xiao_d 0 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
    , <&xiao_d 1 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
    , <&xiao_d 2 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
    , <&xiao_d 3 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
    , <&xiao_d 4 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>;

GPIO_PULL_UP 让松开状态保持为高电平；GPIO_ACTIVE_LOW 表示按下接地后读到低电平时，才算按钮激活。这样每颗按钮只需要 GPIO 和 GND 两根连接。

位置到行为：ai_remote.keymap

bindings = <
    &kp F13
    &kp UP_ARROW
    &kp RETURN
    &kp DOWN_ARROW
    &bt BT_NXT
>;

&kp 发送普通键盘按键；&bt BT_NXT 不发送字符，而是让 ZMK 切换到下一个 Bluetooth profile。五个 profile 的管理、配对信息保存和 BLE HID 传输由 ZMK 提供。

启用传输与持久设置：ai_remote.conf

CONFIG_ZMK_USB=y
CONFIG_ZMK_BLE=y
CONFIG_SETTINGS=y

USB 和 BLE 在原型期同时可用，便于先验证 USB 按键再排查蓝牙。CONFIG_SETTINGS 让配对等 ZMK 设置能够持久保存。

GitHub 怎样把这些声明变成 UF2？

构建链路的重点不是“执行一个神秘编译命令”，而是让 ZMK 能找到这个仓库作为额外模块，并知道要组合哪块 board 与哪套 shield。

1. .github/workflows/build.yml 在 push、pull request 或手动触发时调用 ZMK 官方可复用工作流。
2. config/west.yml 固定 ZMK v0.3，并导入 ZMK 自己的依赖清单。
3. zephyr/module.yml 告诉 Zephyr：这个仓库根目录可以提供 board/shield 定义。
4. build.yaml 声明两个构建目标：正常遥控器和 settings-reset 恢复固件。
5. ZMK 根据 xiao_ble + ai_remote 找到 boards/shields/ai_remote/ 下的配置。
6. 工具链合并 board、shield、Kconfig、Devicetree 和 keymap，生成 UF2 artifact。

jobs:
  build:
    uses: zmkfirmware/zmk/.github/workflows/
      build-user-config.yml@v0.3

- board: xiao_ble
  shield: ai_remote
  artifact-name: ai-remote
- board: xiao_ble
  shield: settings_reset
  artifact-name: settings-reset

首次可构建原型的完整目录地图

下面展示首次可构建原型使用的历史路径。现有仓库中的 ai_voice_remote 对应这里的 ai_remote，各层职责相同。

.
├── .github/workflows/build.yml       # 云端构建入口
├── boards/shields/ai_remote/         # 五键硬件与行为定义
│   ├── Kconfig.defconfig
│   ├── Kconfig.shield
│   ├── ai_remote.conf
│   ├── ai_remote.keymap
│   ├── ai_remote.overlay
│   └── ai_remote.zmk.yml
├── config/west.yml                   # ZMK 依赖清单
├── zephyr/module.yml                 # 把仓库注册为 Zephyr 模块
├── build.yaml                        # 云端构建矩阵
├── scripts/                          # 检查、构建、刷写
│   ├── check-config.py
│   ├── build-firmware.sh
│   └── flash-firmware.sh
├── docs/                             # 操作与验收文档
│   ├── firmware.md
│   ├── product-spec.md
│   └── wiring.md
├── hardware/README.md                # 接线证据与未来 PCB 边界
├── enclosure/README.md               # 未来外壳工作的进入条件
├── README.md                         # 项目入口
├── .gitignore                        # 排除本地和生成文件
└── LICENSE                           # MIT 许可

每个目录和文件分别负责什么？

这里按职责分组。文件之间真正重要的契约是：build.yaml 选择的 shield 名、目录名、Kconfig 条件和文件前缀必须互相匹配。

哪些东西已经存在，哪些仍然只是计划？

读完后，你应该能解释这些问题

内容依据首次可构建原型的 Git 历史快照 efd0458。这个 SHA 只用于固定证据版本，不是本课的学习目标。