brookesdjb/macropad-configurator

# MacroPad Configurator [](https://github.com/brookesdjb/macropad-configurator/releases/latest) [](https://github.com/brookesdjb/macropad-configurator/actions/workflows/ci.yml) [](LICENSE) 一款小巧、快速的 macOS 原生应用，用于配置受支持的兼容 Sayo 的 macro pad。它使用 SwiftUI 编写，通过 USB 直接与 pad 通信，并且不需要 仅支持 Windows 的厂商配置器。 该项目还收集了逆向工程笔记和恢复工作， 为未来的开源固件做准备。 MacroPad Configurator 是一个独立的社区项目。它不隶属于 SayoDevice，也未获得其认可。 ## 下载 从 [GitHub Releases](https://github.com/brookesdjb/macropad-configurator/releases/latest) 下载最新的 Mac 构建版本。 当前的二进制文件需要： - Apple silicon Mac - macOS 13 Ventura 或更新版本 - 受支持的 USB `1189:8890` pad 首个公开版本为临时签名 (ad-hoc signed)，而非 Developer ID 签名和 公证。因此 macOS 可能会对其进行隔离。请先尝试 **按住 Control 点击 → 打开**。 如果 macOS 仍然阻止此开发构建版本，请在检查 已发布的 SHA-256 校验和后移除隔离： ``` xattr -dr com.apple.quarantine "/Applications/MacroPadConfigurator.app" ``` 配置器本身不需要任何辅助功能、键盘监控或后台权限。 ## 支持的硬件 | 主板 | USB 标识 | 控件 | 灯光 | 状态 | |---|---|---|---|---| | 通用 CH552 三键 pad | `1189:8890` | 3 个按键；编码器左旋、右旋和按下 | 3 个按键 LED | 已测试 | 经过验证的主板没有 USB 制造商、产品或序列号字符串。因此， 在允许写入之前，应用程序除了检查 VID/PID 外，还会检查其 配置接口和端点。 一些廉价的主板没有直接进行 USB-C 到 USB-C 连接所需的 USB-C 配置通道电阻。如果使用 C 转 C 线缆时 pad 看起来完全 没反应，请使用 USB-A 转 USB-C 数据线，如有必要，可在 Mac 端 使用 A 转 C 适配器。 ## 功能 - 清晰的已连接/已断开反馈 - 可视化选择所有三个按键和所有三个编码器动作 - 键盘快捷键以及最多包含五次击键的序列 - 媒体控制、鼠标按键和滚动 - 存储在 Mac 本地的三个命名配置文件 - 一键将完整的配置文件应用到 pad - 响应式和彩虹追逐 LED 模式 - 安全的 `F13`–`F18` 初始配置文件 - 沙盒化的 USB 访问，没有固件刷新或任意的原始 USB 控件 配置文件保存在本地，因为目前未知此原厂固件是否有配置读取命令。 **应用到 Pad** 会执行持久化写入；应用程序绝不会将成功的写入 假装为是从设备闪存中读取的回读。 ## 构建和运行 要求为 macOS 13 或更高版本、Xcode 命令行工具、`curl` 和 `make`。首次构建将在本地下载并构建 libusb 1.0.30。 ``` git clone https://github.com/brookesdjb/macropad-configurator.git cd macropad-configurator make app-run ``` 使用以下命令运行测试： ``` make test ``` 要求检测已连接的物理主板： ``` SAYO_HARDWARE_TEST=1 \ PKG_CONFIG_PATH="$PWD/.build/dependencies/libusb/lib/pkgconfig" \ swift test --filter testAttachedHardwareCanBeDetectedWhenRequested ``` 详细的构建、签名和公证说明请参见 [APP.md](APP.md)。 ## 添加其他主板 欢迎为其他 pad 做出贡献，但配置写入必须保持 基于已验证型号可选开启。请从 [ADDING_BOARDS.md](ADDING_BOARDS.md) 开始。它 描述了： - 提议的目录驱动主板模型； - 安全的自动检测和模糊布局处理； - 添加硬件定义所需的证据； - 需要动态化的代码边界； - 测试和配置文件迁移期望。 有用的贡献包括 USB/HID 描述符捕获、清晰的 PCB 照片、 控制/动作 ID 映射、协议跟踪、测试以及 SwiftUI 相关工作。请勿 在未知设备上测试猜测的写入数据包。 ## 固件研究 该主板使用 WCH `CH552G`。**尚未**刷新自定义固件。 在此之前，项目正在建立恢复路线，并尽可能保留受保护的原厂设备 允许我们读取的所有内容。 - [HANDOFF.md](HANDOFF.md) — 当前证据、未知项和调查计划 - [RECOVERY.md](RECOVERY.md) — ISP 进入、备份限制和禁止操作门槛 - [`captures/`](captures/) — 已校验校验和的只读原厂设备证据 - [`tools/pad_monitor.swift`](tools/pad_monitor.swift) — 只读 HID 监视器 在未阅读 `RECOVERY.md` 的情况下，请勿尝试首次刷新固件。原厂 程序闪存可能受代码保护，并且可能无法恢复。 ## 仓库布局 ``` Sources/MacroPadConfigurator/ SwiftUI application and protocol encoder Sources/CSayoUSB/ Narrow libusb transport for the verified board Tests/ Byte-exact protocol and profile tests Resources/ App metadata and sandbox entitlements scripts/ Build, packaging, capture and recovery helpers captures/ Checksummed stock-device observations ``` ## 许可证 项目代码和文档基于 [MIT licence](LICENSE) 提供。 打包后的应用程序包含基于 LGPL-2.1-or-later 的 libusb；其许可证已捆绑 在应用程序内部。产品名称和商标归其各自的 所有者所有。

标签：macOS应用, SwiftUI, USB通信, 固件研究, 硬件工具, 配置工具