From 0b9a52bd89a3646bc83693f43a131217fcb77187 Mon Sep 17 00:00:00 2001 From: k4i Date: Mon, 10 Aug 2026 23:12:50 +0800 Subject: [PATCH] Add Codex Micro support to Sweep Pro --- .github/workflows/build.yml | 19 +++++++++-- build.yaml | 4 +-- config/sweep.keymap | 31 ++++++++++++++++-- config/west.yml | 5 ++- docs/en/local-build.md | 64 +++++++++++++++++++++++++++++++++++-- docs/zh_CN/local-build.md | 61 +++++++++++++++++++++++++++++++++-- 6 files changed, 172 insertions(+), 12 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index ed0ba37..48a1b12 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -1,6 +1,19 @@ -name: Build ZMK firmware -on: [push, pull_request, workflow_dispatch] +name: Build firmware + +on: + push: + branches: [main] + pull_request: + workflow_dispatch: + +permissions: + contents: read jobs: build: - uses: zmkfirmware/zmk/.github/workflows/build-user-config.yml@cb615aee9a7c427e251f2ab62080c1a44a165da9 + # The module-owned workflow applies its version-matched ZMK compatibility + # patch before building. Pinning it keeps the module and build procedure in sync. + uses: nxtkb/zmk-feature-codex-micro/.github/workflows/build-user-config.yml@034050c6cac7834b5004aad510863e7c999f6307 + with: + build_matrix_path: build.yaml + archive_name: sweep-pro-firmware diff --git a/build.yaml b/build.yaml index fc2ccd5..c500d2b 100644 --- a/build.yaml +++ b/build.yaml @@ -9,11 +9,11 @@ include: - board: nice_nano//zmk shield: sweep_left - snippet: studio-rpc-usb-uart + snippet: studio-rpc-usb-uart nxtkb-codex-micro-usb nxtkb-codex-micro-ble artifact-name: sweep_left - board: nice_nano//zmk shield: sweep_left sweep_left_display_hw sweep_display - snippet: studio-rpc-usb-uart + snippet: studio-rpc-usb-uart nxtkb-codex-micro-usb nxtkb-codex-micro-ble artifact-name: sweep_left_display - board: nice_nano//zmk shield: sweep_right diff --git a/config/sweep.keymap b/config/sweep.keymap index d1657e4..cf3d152 100644 --- a/config/sweep.keymap +++ b/config/sweep.keymap @@ -10,6 +10,10 @@ #include #include #include +#if defined(NXTKB_CODEX_MICRO) +#include +#include +#endif #include "behaviors/character_map.dtsi" #include "behaviors/report.dtsi" @@ -21,6 +25,17 @@ #define LEF 3 #define TRI 4 #define MOUSE 5 +#define CODEX 6 + +#if defined(NXTKB_CODEX_MICRO) +#define CODEX_ENTRY &tog CODEX +#define CODEX_EXIT &tog CODEX +#define CODEX_KEY(n) &codex_key n +#else +#define CODEX_ENTRY &trans +#define CODEX_EXIT &trans +#define CODEX_KEY(n) &trans +#endif #define SPEED_POINTER 0 #define SPEED_SCROLL 1 @@ -33,7 +48,6 @@ #define CIRQUE_MODE_ABSOLUTE 1 #define CIRQUE_MODE_TOGGLE 2 - &sensors { left_encoder { triggers-per-rotation = <15>; @@ -251,7 +265,7 @@ tri_layer { display-name = "FUN"; bindings = < - &kp F1 &kp F2 &kp F3 &kp F4 &bt BT_SEL 0 &bt BT_SEL 2 &out OUT_TOG &tog WIN &kp C_MUTE &kp C_PREV + &kp F1 &kp F2 &kp F3 &kp F4 &bt BT_SEL 0 &bt BT_SEL 2 &out OUT_TOG CODEX_ENTRY &kp C_MUTE &kp C_PREV &kp F5 &kp F6 &kp F7 &kp F8 &bt BT_SEL 1 &bt BT_SEL 3 &kp C_BRI_UP &studio_unlock &kp C_VOL_UP &kp C_PP &kp F9 &kp F10 &kp F11 &kp F12 &bt BT_CLR &bt BT_SEL 4 &kp C_BRI_DEC &soft_off &kp C_VOL_DN &kp C_NEXT &kp C_MUTE &trans &trans &trans &trans &studio_unlock @@ -269,5 +283,18 @@ >; sensor-bindings = <&enc_ptr_spd &enc_scrl_spd>; }; + +#if defined(NXTKB_CODEX_MICRO) + codex { + display-name = "CODEX"; + bindings = < + CODEX_KEY(CODEX_AGENT_0) CODEX_KEY(CODEX_AGENT_1) CODEX_KEY(CODEX_AGENT_2) CODEX_KEY(CODEX_AGENT_3) CODEX_KEY(CODEX_AGENT_4) CODEX_KEY(CODEX_AGENT_5) &trans &trans &trans CODEX_EXIT + CODEX_KEY(CODEX_APPROVE) CODEX_KEY(CODEX_SPLIT) CODEX_KEY(CODEX_DECLINE) CODEX_KEY(CODEX_FAST) &trans CODEX_KEY(CODEX_MIC) CODEX_KEY(CODEX_SEND) &trans &trans &trans + &trans &trans &trans &trans &trans &trans &trans &trans &trans &trans + &trans &trans &trans &trans &trans &studio_unlock + >; + sensor-bindings = <&inc_dec_kp C_VOL_DN C_VOL_UP &inc_dec_kp C_BRI_DEC C_BRI_UP>; + }; +#endif }; }; diff --git a/config/west.yml b/config/west.yml index 8d800b1..0808fd7 100644 --- a/config/west.yml +++ b/config/west.yml @@ -13,7 +13,10 @@ manifest: import: app/west.yml - name: zmk-vfx-sweep-pro-display remote: nxtkb - revision: 88809b0ba9f8af51e937c90d3c34edb9480e5455 + revision: afae3dcf7d94113dfbeb19fb4e4fbd08d6564008 + - name: zmk-feature-codex-micro + remote: nxtkb + revision: 034050c6cac7834b5004aad510863e7c999f6307 - name: zmk-behavior-report remote: nxtkb revision: 476f43da1f98b4a6150c9c0e499a257bd64a29a0 diff --git a/docs/en/local-build.md b/docs/en/local-build.md index 6d46779..78c2196 100644 --- a/docs/en/local-build.md +++ b/docs/en/local-build.md @@ -30,11 +30,18 @@ Install the Zephyr SDK from AUR, or install it manually by following the ZMK/Zep paru -S zephyr-sdk ``` -If the SDK is not detected automatically, set these variables in the current shell: +On Apple Silicon macOS, install the host tools with Homebrew and install the Zephyr SDK version +required by the ZMK revision pinned in `config/west.yml` (currently 0.17.0): + +```shell +brew install cmake ninja ccache dtc wget xz protobuf +``` + +If the SDK is not detected automatically, point Zephyr at your installation in the current shell: ```shell export ZEPHYR_TOOLCHAIN_VARIANT=zephyr -export ZEPHYR_SDK_INSTALL_DIR="$HOME/zephyr-sdk-0.17.0" +export ZEPHYR_SDK_INSTALL_DIR="/path/to/zephyr-sdk-0.17.0" ``` ## Initialize Python @@ -158,6 +165,59 @@ west build -d build/sweep_right_trackpad If you change the shield, extra modules, snippets, or `ZMK_CONFIG`, rerun the full command with `-p` to regenerate the build directory. +## Codex Micro USB and Bluetooth build + +This build adds a second vendor-defined USB HID interface and an encrypted vendor-defined +HID-over-GATT report while preserving the normal ZMK USB/Bluetooth HID and Studio USB UART +interfaces. Codex RPC follows ZMK's selected output endpoint, including the active Bluetooth +profile. Inactive USB and Bluetooth hosts cannot take over the Codex session by retrying. + +The repository's default GitHub Actions workflow builds Codex-enabled central firmware and applies +the required official-ZMK compatibility patch automatically. For a local checkout in which the +Codex module is a west project, apply the same declared patch once before building: + +```shell +west patch -sm zmk-feature-codex-micro apply +``` + +If the module is instead a sibling directory outside the west workspace, apply its patch to ZMK +once with `git apply`, then add the module to the local module list: + +```shell +git -C "$NXTKB_ROOT/zmkfirmware/zmk" apply --check \ + "$NXTKB_ROOT/zmk-feature-codex-micro/zephyr/patches/zmk/zmk-usb-hid-interrupt-out.patch" +git -C "$NXTKB_ROOT/zmkfirmware/zmk" apply \ + "$NXTKB_ROOT/zmk-feature-codex-micro/zephyr/patches/zmk/zmk-usb-hid-interrupt-out.patch" +CODEX_EXTRA_MODULES="$EXTRA_MODULES;$NXTKB_ROOT/zmk-feature-codex-micro" +``` + +Build the left half with display and both Codex transports: + +```shell +west build -s app -p -d build/sweep_left_display_codex -b nice_nano//zmk \ + -S studio-rpc-usb-uart \ + -S nxtkb-codex-micro-usb \ + -S nxtkb-codex-micro-ble -- \ + -DSHIELD="sweep_left sweep_left_display_hw sweep_display" \ + -DZMK_EXTRA_MODULES="$CODEX_EXTRA_MODULES" \ + -DZMK_CONFIG="$ZMK_CONFIG_DIR" +``` + +NXTKB development checkouts may also contain a gitignored +`nxtkb-codex-micro-lab-identity` snippet for local interoperability testing against the current +ChatGPT desktop detection. It changes both the USB VID/PID and Bluetooth Device Information +identity and is intentionally not part of the module repository. Never publish or ship firmware +built with that identity. External integrations must use an identity they are authorized to ship. +The right half continues to use the normal `sweep_right` or `sweep_right_trackpad` firmware. + +After first flashing a BLE-enabled build, forget the old keyboard in the host Bluetooth settings, +clear the selected ZMK Bluetooth profile, and pair with `NXTKB Codex Lab` again. HID report maps are +cached in the bond. Use the existing output-toggle key to prefer Bluetooth; a connected USB cable +may still be used for charging. USB and Bluetooth keyboard connections remain active instead of +disconnecting each other. Every connected computer keeps an independent Codex protocol and Agent +state session; Codex keys and the display follow only the currently selected ZMK output. Switching +back restores the last Agent state reported by that computer. + ## Troubleshooting If you see: diff --git a/docs/zh_CN/local-build.md b/docs/zh_CN/local-build.md index 3cb317d..f6ea126 100644 --- a/docs/zh_CN/local-build.md +++ b/docs/zh_CN/local-build.md @@ -30,11 +30,18 @@ Zephyr SDK 可以通过 AUR 安装，或按 ZMK/Zephyr 官方文档手动安装 paru -S zephyr-sdk ``` -如果 SDK 没有被自动识别，可以在当前 shell 里指定： +macOS（Apple Silicon）建议使用 Homebrew 安装宿主工具，并安装 `config/west.yml` 中固定的 +ZMK revision 所要求的 Zephyr SDK 版本（当前为 0.17.0）： + +```shell +brew install cmake ninja ccache dtc wget xz protobuf +``` + +如果 SDK 没有被自动识别，请在当前 shell 里指向你自己的安装目录： ```shell export ZEPHYR_TOOLCHAIN_VARIANT=zephyr -export ZEPHYR_SDK_INSTALL_DIR="$HOME/zephyr-sdk-0.17.0" +export ZEPHYR_SDK_INSTALL_DIR="/path/to/zephyr-sdk-0.17.0" ``` ## 初始化 Python 环境 @@ -158,6 +165,56 @@ west build -d build/sweep_right_trackpad 修改了 shield、extra modules、snippets 或 `ZMK_CONFIG` 后，建议继续使用带 `-p` 的完整命令重新生成构建目录。 +## Codex Micro USB 与蓝牙构建 + +该构建会增加第二个 vendor-defined USB HID interface，以及加密的 vendor-defined +HID-over-GATT report，同时保留 ZMK 普通 USB/蓝牙 HID 和 Studio USB UART。Codex RPC +响应发起请求的传输通道。 + +仓库的默认 GitHub Actions workflow 会构建启用 Codex 的 central 固件，并自动应用所需的 +官方 ZMK 兼容补丁。本地构建时，如果 Codex 模块是 west workspace 中的 project，请先 +应用模块声明的补丁： + +```shell +west patch -sm zmk-feature-codex-micro apply +``` + +如果模块位于 west workspace 外部的同级目录，则先用 `git apply` 向 ZMK 应用一次补丁， +再把 Codex 模块加入本地模块列表： + +```shell +git -C "$NXTKB_ROOT/zmkfirmware/zmk" apply --check \ + "$NXTKB_ROOT/zmk-feature-codex-micro/zephyr/patches/zmk/zmk-usb-hid-interrupt-out.patch" +git -C "$NXTKB_ROOT/zmkfirmware/zmk" apply \ + "$NXTKB_ROOT/zmk-feature-codex-micro/zephyr/patches/zmk/zmk-usb-hid-interrupt-out.patch" +CODEX_EXTRA_MODULES="$EXTRA_MODULES;$NXTKB_ROOT/zmk-feature-codex-micro" +``` + +编译同时支持 USB 和蓝牙 Codex 通道的左手墨水屏固件： + +```shell +west build -s app -p -d build/sweep_left_display_codex -b nice_nano//zmk \ + -S studio-rpc-usb-uart \ + -S nxtkb-codex-micro-usb \ + -S nxtkb-codex-micro-ble -- \ + -DSHIELD="sweep_left sweep_left_display_hw sweep_display" \ + -DZMK_EXTRA_MODULES="$CODEX_EXTRA_MODULES" \ + -DZMK_CONFIG="$ZMK_CONFIG_DIR" +``` + +NXTKB 的开发 checkout 中可能还会包含一个被 gitignore 排除的 +`nxtkb-codex-micro-lab-identity` snippet，仅用于本地测试当前 ChatGPT 桌面端的发现行为。 +它会同时修改 USB VID/PID 和蓝牙 Device Information identity，且有意不放入模块仓库； +禁止发布或交付使用该身份生成的固件。外部集成必须使用自己有权发布的设备身份。右手继续 +使用原有 `sweep_right` 或 `sweep_right_trackpad` 固件。 + +首次刷入带 BLE 支持的固件后，需要先在主机蓝牙设置中忽略旧键盘、清除所选 ZMK +蓝牙 profile，再重新配对 `NXTKB Codex Lab`。HID report map 会被缓存在旧 bond 中，普通 +断开重连不会刷新。使用现有的 output toggle 键切换到蓝牙优先；USB 线仍可保留用于充电。 +USB 和蓝牙键盘连接不会互斥或彼此断开。每个连接的电脑维持独立的 Codex 协议与 Agent +状态；Codex 按键和墨水屏状态只跟随当前 ZMK output。切换回来后会恢复该电脑最后上报的 +Agent 状态。 + ## 常见问题 如果看到：