agarat/openpodgo

# openpodgo openpodgo 通过 Helix/HX 系列的 USB **vendor protocol** 与踏板进行通信 （bulk transfers + MessagePack 格式的 presets），该协议由社区进行逆向工程， 并适配至 POD Go (`0e41:4247`)。它可以在官方编辑器无法运行的平台上运行：Linux。 ## 功能 - **USB protocol layer**，已针对真实的 POD Go (`0e41:4247`) 进行验证： device open、session handshake、所有 128 个 presets 的流式传输与解析 （MessagePack）、读取 active preset，以及通过 vendor protocol 将 parameter / block 重排序写回踏板。 - **Preset librarian** — 浏览 Factory 和 User setlists；一键召回 preset。 - **可视化 chain 编辑器**（PySide6，暗色主题） — signal-flow 视图、block 检查器、model 替换、parameter 编辑、bypass/controller 分配、 snapshots 以及双向 live-sync（踏板上的更改会同步至 UI）。 - **`.pgp` 导入/导出**，兼容 POD Go Edit / CustomTone 格式。 - 基于 ALSA (`amidi`) 的 **MIDI** 辅助功能：program change、setlist 选择、 snapshots、footswitches、tap。 ## 尚未实现（或存在的限制） - **该项目是非官方的且基于逆向工程。** Firmware 更新可能会更改 protocol 并导致故障。目前的开发已跟进至 POD Go firmware **v2.01**；其他版本未经测试。 - **未捆绑任何专有资源。** 开箱即用时，UI 使用中性的 占位图标。要获取真实的图标素材，您需要自行将其复制进来 — 请参阅 [图标与素材](#icons--artwork)。 - **以 Linux 为主。** 在其他支持 `libusb` 的平台上可能也能运行，但仅对 Linux 进行了测试。 - 部分功能仍在开发中；请参阅 [`docs/specs/00-roadmap.md`](docs/specs/00-roadmap.md)。 - **请备份您的 presets。** 写入硬件始终存在风险。 ## 环境要求 - Linux，Python **3.10+** - 通过 USB 连接的 POD Go - UI 方面：支持 Qt 的桌面环境（通过 `ui` extra 安装 PySide6） ## 安装 ``` git clone https://github.com/agarat/openpodgo.git cd openpodgo python3 -m venv .venv && . .venv/bin/activate pip install -e '.[dev,ui]' # library + tests + UI ``` ### 免 sudo 进行 USB 访问 ``` sudo cp 99-podgo.rules /etc/udev/rules.d/99-podgo.rules sudo udevadm control --reload-rules && sudo udevadm trigger # 然后重新连接 POD Go ``` ## 运行 ``` python -m openpodgo.app # or: openpodgo (launches the UI) ``` ## 图标与素材 openpodgo **不**提供任何 Line 6 / POD Go Edit 素材。在没有这些素材的情况下，UI 会 回退至中性的占位图标（完全可用）。要获取真实的 model 缩略图、分类图标和 logo，请将现有 **POD Go Edit** 安装目录下的 `res/` 文件夹复制到 repository 根目录： | 操作系统 | POD Go Edit 资源文件夹 | |-----------|------------------------------| | Windows | `C:\Program Files (x86)\Line6\POD Go Edit\res` | | macOS | 位于 `POD Go Edit.app` bundle 内部 (`.../Contents/.../res`) | ``` # 从 repo 根目录开始，其中 = 上面的 res 文件夹 cp -r "" ./res ``` 应用程序会在下次启动时自动识别它们 — 真实图标将替换 占位符。`res/` 已被 git 忽略，且该项目**绝不会**对其进行再分发； 它仅保留在您的本地计算机上。 ## 关于 model catalog 的说明 应用程序内置了 `src/openpodgo/data/{models,controls,icon_map}.json`：这是解析 presets 所需的客观 id → name → parameter-range 映射数据。它们是 从官方 POD Go Edit 资源中*派生*而来的（属于数据，而非素材或 代码）。它们使得 openpodgo 能够开箱即用；`tools/build_catalog.py` 可以 根据您自己的 POD Go Edit 安装重新生成它们。 ## 开发 ``` python -m pytest # offline test suite (no pedal needed) ``` 测试套件完全离线运行，针对位于 `tests/fixtures/` 下的小型、已脱敏的 fixtures。在一个全新的 clone 中（不存在任何专有资源），它会运行 **315 个测试**；另外有 28 个测试被跳过，因为它们需要官方的 POD Go Edit 资源或您本地的 USB 抓包数据。 RE / 硬件工具位于 `tools/` 目录（它们会与真实的踏板通信 — 请先关闭 应用程序，因为只有一个进程能占用 vendor interface）： ``` python tools/probe.py # open, handshake, list presets python tools/capture.py --label "..." # labeled capture for RE ``` ## 项目结构 - `src/openpodgo/` — 库文件：`usb_transport`、`session`、`packets`、 `preset`、`l6helix`、`catalog`、`device`、`editor`、`midi` 以及 `ui/`。 - `tools/` — 逆向工程 / 验证脚本（针对真实的踏板运行）。 - `docs/` — `protocol.md` 以及带有编号的 RE `specs/`。 - `tests/` — 离线测试套件和脱敏后的 fixtures。 ## 致谢 - [**openhx**](https://github.com/allansomensi/openhx) (MIT) — protocol 模板移植自其 HX Stomp XL 文档，并已适配至 POD Go。 - [**helix_usb**](https://github.com/kempline/helix_usb) (MIT) — 早期 Helix/HX USB 逆向工程。 详情请参阅 [`NOTICE`](NOTICE)。此处不分发上述项目的任何代码或文档。 ## 免责声明 这是一个独立的非官方项目。它不隶属于、也未受 Yamaha Guitar Group / Line 6 认可或支持。“Line 6”、“POD Go”、“POD Go Edit” 和 “Helix” 均为其各自所有者的商标，此处仅用于 描述互操作性。不分发任何官方素材、手册或 字体。与您的硬件进行交互的风险需由您自行承担。 ## 许可证 [MIT](LICENSE) © 2026 Arnaldo Garat

标签：MIDI, PySide6, USB通信, 硬件交互, 逆向工具, 音频设备编辑器, 预设管理