matiasromero/hyperx-quadcast-colors-utility

# HyperX QuadCast 2 S — macOS RGB 控制工具 一款小型、原生的 macOS 菜单栏应用，用于控制 HyperX QuadCast 2 S 麦克风的 RGB LED 灯效。 HyperX NGENUITY（官方软件）仅限 Windows 使用，因此 Mac 用户一直无法在不双系统启动 或运行 Windows 虚拟机的情况下更改麦克风颜色——这款应用填补了这一空白。 **当前范围：** 支持每个区域（上部/下部）设置纯色，亮度为 0–100%。 不支持动画模式（闪烁、循环、波浪、脉冲）——QuadCast 2 S 上这些模式的协议 尚未被解码。 ## 安装 1. 从 **[Releases 页面](https://github.com/matiasromero/hyperx-quadcast-colors-utility/releases/latest)** 下载最新的 `HyperXRGB-x.y.z.dmg`。 2. 打开 DMG 文件，将 **HyperX RGB** 拖入您的 **应用程序 (Applications)** 文件夹。 3. 启动它 —— 图标将出现在 macOS 菜单栏中。 要求 **macOS 14 (Sonoma) 或更高版本**。该应用使用 Apple Developer ID 签名 并经过 Apple 公证，因此 Gatekeeper 会直接放行，不会出现任何 “身份不明的开发者”警告。 ## 使用说明 点击菜单栏图标打开控制面板： - 为 **上部** 区域、**下部** 区域或两者选择一种颜色。 - 将 **亮度** 从 0 调整到 100%。 当您需要自定义颜色时，该应用必须保持运行——一旦主机停止发送 颜色数据包（大约每 150 毫秒一次），QuadCast 2 S 固件将恢复其内置动画。 退出应用程序会使 LED 灯恢复为默认动画。 要在登录时自动启动 HyperX RGB，请将其拖入 **系统设置 → 通用 → 登录项**。 ## 兼容性 | 设备 | 支持 | |-------------------------------------|-----------| | HyperX QuadCast 2 S (USB ID `03f0:02b5`) | 是 | | HyperX QuadCast S (原版) | 否 | | HyperX DuoCast | 否 | 如果您插入了其他 HyperX 设备并且它能正常工作，请提交一个 issue——我们 或许可以通过微小的改动来扩展支持列表。 ## 开发 ### 仓库结构 | 目标 | 位置 | 功能说明 | |---------------------|-----------------------|-----------------------------------------------------------| | `HyperXProtocol` | `Sources/` (库) | 纯 USB 数据包构建器。无 macOS 依赖。 | | `HyperXCore` | `Sources/` (库) | IOKit HID 封装器 + 刷新循环。仅限 macOS。 | | `ValidateProtocol` | `Sources/` (CLI) | 构建器的离线冒烟测试。无需硬件。 | | `HIDProbe` | `Sources/` (CLI) | 测试 CLI：设置颜色几秒钟。 | | `HyperXRGB` | `App/` (Xcode 应用) | SwiftUI 菜单栏应用（最终的 `.app` 包）。 | ### 从源代码构建 需要 macOS 14+、Xcode 15+ 以及 [xcodegen](https://github.com/yonaskolb/XcodeGen) (`brew install xcodegen`)。 ``` xcodegen generate xcodebuild -project HyperXRGB.xcodeproj -scheme HyperXRGB -configuration Release \ -derivedDataPath build clean build open build/Build/Products/Release/HyperXRGB.app ``` 要永久安装本地构建的 `.app`： ``` cp -R build/Build/Products/Release/HyperXRGB.app /Applications/ ``` `.xcodeproj` 位于 `.gitignore` 中——它是在每次构建时由 `project.yml` 重新生成的。 ### 测试 ``` swift run ValidateProtocol # 40 offline protocol checks swift test # 13 unit tests (Swift Testing) ``` ### 连接真实麦克风进行测试 插入麦克风后： ``` swift run HIDProbe ff0000 # red, ~5s swift run HIDProbe 00ff00 # green swift run HIDProbe 0080ff # cyan ``` 当命令结束时，LED 灯会恢复为默认动画——一旦停止发送数据包， 固件就会重新接管控制权。 ## 协议说明 逆向工程自 [Ors1mer/QuadcastRGB](https://github.com/Ors1mer/QuadcastRGB)。 - **HID 设备**：VID `0x03f0` / PID `0x02b5`（USB 产品名称："HyperX QuadCast 2 S Controller"）。 - **音频**：VID `0x03f0` / PID `0x0d84` — 独立的 USB 设备，互不干扰。 - **纯色** 以 7 个 64 字节的数据包发送： - 1 个报头：`[0x44, 0x01, 0x06, 0, …]` → ACK `rsp[0]=0xff rsp[14]=0x44`。 - 6 个数据包 `[0x44, 0x02, packet_index, …]` + RGB 字节 → ACK `rsp[0]=0x45`。 - **上部区域** 从 `packet[0][4]` 开始，**下部区域** 从 `packet[2][46]` 开始。 - 数据包必须 **持续重新发送**（约每 150 毫秒），否则固件 将恢复为默认颜色。 - 在 IOKit 下，数据包通过 `IOHIDDeviceSetReport` 发送，类型为 `kIOHIDReportTypeOutput`。 ### 不明显的坑（对比参考的 C 库） 1. **按 report size 过滤。** "Controller" 暴露了多个具有 相同 VID/PID 的 HID 集合。您必须只打开满足 `MaxOutputReportSize >= 64` 且 `MaxInputReportSize >= 64` 的那个。其他的 （输出大小为 1）不接受 64 字节的数据包。 2. **在每次 SetReport 之间排空输入响应。** 固件会累积 响应，如果未被读取，将停止接受 OUT 传输。如果在 每次发送前没有调用 `drainPendingResponses()`，第二个循环就已经 会返回 `kIOReturnTimeout`。 3. **使用 `kIOHIDOptionsTypeSeizeDevice` 打开** 以避免访问冲突。 ## 发布 发布版本在推送 `vX.Y.Z` 标签时，由位于 [.github/workflows/release.yml](.github/workflows/release.yml) 的 GitHub Actions 工作流进行构建、签名（Developer ID）、公证并发布。 该工作流将构建委托给 [Scripts/build-release.sh](Scripts/build-release.sh)，该脚本同样可以在 本地运行。 ### 一次性设置 每位维护者的机器和 GitHub 仓库仅需执行一次。跳过任何 已完成的部分。 #### A. 创建 Developer ID Application 证书 1. **在您的 Mac 上生成证书签名请求 (CSR)。** 打开 **钥匙串访问 (Keychain Access)** → 菜单 **钥匙串访问 → 证书助理 (Certificate Assistant) → 从证书颁发机构请求证书 (Request a Certificate from a Certificate Authority)**。填写您的电子邮件 和姓名，将 **CA Email Address (CA 电子邮件地址)** 留空，选择 **保存到磁盘 (Saved to disk)**，然后 将 `.certSigningRequest` 暂时保存到某个位置。 2. **将 CSR 上传至 Apple。** 访问 [developer.apple.com/account/resources/certificates/list](https://developer.apple.com/account/resources/certificates/list) → 点击 **+** → 选择 **Developer ID Application** → **G2 Sub-CA (Xcode 11.4.1 或更高版本)** → **Continue** → 上传 `.certSigningRequest` → **Continue** → **Download**。双击 下载的 `.cer` 文件以将其安装到 `login` 钥匙串中。 3. **验证证书是否已安装并获取其身份字符串：** security find-identity -v -p codesigning 您应该会看到类似这样的一行： 1) ABCDEF1234567890… "Developer ID Application: Your Name (ABCDE12345)" - 完整的带引号的字符串即为 `SIGNING_IDENTITY` 密钥的值。 - 括号内的 10 个字符的代码是您的 `APPLE_TEAM_ID`。 如果 `find-identity` 返回 0 个有效身份，最常见的原因是 缺少 Apple 中间证书。安装它并重试： ``` curl -O https://www.apple.com/certificateauthority/DeveloperIDG2CA.cer security import DeveloperIDG2CA.cer -k ~/Library/Keychains/login.keychain-db ``` #### B. 将证书导出为 `.p12` 1. 在 **钥匙串访问 (Keychain Access)** 中，选择 **login** 钥匙串和 **我的证书 (My Certificates)** 类别。点击 *Developer ID Application: …* 旁边的展开三角形，以确认其下方嵌套有 私钥——如果没有，导出将不起作用，您需要在 生成 CSR 的同一台 Mac 上重新执行步骤 A。 2. 右键点击证书 → **导出 "Developer ID Application: …" (Export "Developer ID Application: …")** → **文件格式: 个人信息交换** → 另存为 `DeveloperID.p12` 并设置一个强密码（这将作为 `P12_PASSWORD`）。 3. 为 GitHub 密钥编码 `.p12` 文件： base64 -i DeveloperID.p12 | pbcopy 您的剪贴板现在保存了 `BUILD_CERTIFICATE_BASE64` 的值。 #### C. 创建 App Store Connect API 密钥（用于公证） 1. 访问 [appstoreconnect.apple.com](https://appstoreconnect.apple.com) → **用户和访问 (Users and Access)** → **Integrations** 标签页 → **Team Keys** 子标签 （而不是 "Individual Keys"）。 2. 点击 **+** → 命名，例如 `Notarization CI` → 权限选择 **Developer** → **Generate**。 3. **立即下载 `.p8` 文件** —— Apple 只允许您执行一次此操作。 将其保存在安全的地方。 4. 在同一页面上，记录： - **Key ID** — 表格行中的 10 字符代码。 - **Issuer ID** — 密钥部分顶部的 UUID 风格字符串。 #### D. 将八个密钥加载到 GitHub 在仓库中：**Settings → Secrets and variables → Actions → New repository secret**。添加以下每一项： | 密钥 | 来源 | |---|---| | `BUILD_CERTIFICATE_BASE64` | 步骤 B.3 中剪贴板的内容 | | `P12_PASSWORD` | 您在步骤 B.2 中设置的密码 | | `KEYCHAIN_PASSWORD` | 任意随机字符串 — 例如 `openssl rand -base64 24` | | `SIGNING_IDENTITY` | 步骤 A.3 中完整的带引号字符串，例如 `Developer ID Application: Your Name (ABCDE12345)` | | `APPLE_TEAM_ID` | 步骤 A.3 中括号内的 10 字符代码 | | `APP_STORE_CONNECT_KEY_ID` | 步骤 C.4 中的 Key ID | | `APP_STORE_CONNECT_ISSUER_ID` | 步骤 C.4 中的 Issuer ID | | `APP_STORE_CONNECT_KEY_P8` | 步骤 C.3 中 `.p8` 文件的完整文本，包括 `-----BEGIN PRIVATE KEY-----` 和 `-----END PRIVATE KEY-----` 行（多行） | ### 首次发布前测试 在打上 `v0.1.0` 标签之前，请在本地进行验证并使用一次性标签测试，以免 CI 失败 记录在您真实的发布历史中。 **1. 本地签名 + 公证演练。** 使用 CI 将使用的完全相同的凭据，在您自己的 Mac 上运行完整流水线： ``` brew install create-dmg export SIGNING_IDENTITY="Developer ID Application: Your Name (TEAMID)" export APPLE_TEAM_ID="TEAMID" export APP_STORE_CONNECT_KEY_ID="KEYID" export APP_STORE_CONNECT_ISSUER_ID="ISSUERID" export APP_STORE_CONNECT_KEY_P8="$(cat ~/Downloads/AuthKey_KEYID.p8)" Scripts/build-release.sh 0.1.0-test ``` 当以 `Built and notarized: dist/HyperXRGB-0.1.0-test.dmg` 结束时， 挂载该 DMG，将应用拖入“应用程序”文件夹，然后打开它。Gatekeeper 应该 会毫无警告地放行。 **2. GitHub Actions 工作流的端到端测试。** 推送一个一次性的 候选发布标签： ``` git tag v0.1.0-rc1 git push origin v0.1.0-rc1 ``` 在 GitHub 上查看 **Actions → Release**。如果它成功执行到 *Create GitHub Release*， 从发布的 Release 中下载 DMG 并安装（最好在 另一台 Mac 上，或者在本地通过 `xattr -d com.apple.quarantine` 剥离 “从互联网下载”标志之后进行）。如果出现任何问题，请进行清理： ``` gh release delete v0.1.0-rc1 -y git push --delete origin v0.1.0-rc1 git tag -d v0.1.0-rc1 ``` 一旦演练通过，您就可以为正式发布打标签了。 ### 发布版本 ``` git tag v0.1.0 git push origin v0.1.0 ``` 该工作流会进行归档、签名、构建 DMG、通过 `notarytool` 公证、 装订票据，并发布附带了 `.dmg` 的 GitHub Release。 自动生成的发布说明基于自上一个标签以来的提交。 要在安装后验证发布是否已正确公证： ``` spctl -a -vv /Applications/HyperXRGB.app # → "source=Notarized Developer ID" xcrun stapler validate /Applications/HyperXRGB.app # → "The validate action worked!" ``` ### 本地演练（无需 Developer ID） 在打标签之前，相同的脚本可以在本地生成一个未签名的 DMG，用于端到端测试打包过程： ``` brew install create-dmg SIGNING_IDENTITY="-" Scripts/build-release.sh 0.1.0-dev # → dist/HyperXRGB-0.1.0-dev.dmg ``` 未签名的 DMG 在另一台 Mac 上打开时会触发 Gatekeeper 警告——这 是预期之内的；请仅在本地测试时使用它们。 ## 超出范围 - 动画模式（需要在 Windows 虚拟机上抓取 NGENUITY 的 USB 数据）。 - 其他 HyperX 麦克风（原版 QuadCast S、DuoCast）。 - 自动更新、遥测。 ## 致谢 协议逆向工程基于 [Ors1mer/QuadRGB](https://github.com/Ors1mer/QuadcastRGB) — 感谢 原作者对数据包结构的记录。 ## 许可证 MIT — 见 [LICENSE](LICENSE)。

标签：Apple Developer ID签名, HyperX, macOS Sonoma, macOS原生应用, QuadCast 2 S, RGB灯效控制, USB设备通信, 二进制发布, 亮度调节, 公证应用, 外设管理, 开源工具, 桌面工具, 硬件协议逆向, 硬件控制, 系统扩展, 菜单栏应用, 跨平台替代品, 音频设备, 麦克风