do4k/LogiTux

# LogiTux 一个用于控制 Logitech 设备的原生 GUI —— 相当于 Linux 优先的 Logitech G HUB。使用 Go 编写。它也可以在 Windows 和 macOS 上构建和运行（但存在设备支持方面的限制 —— 参见[预编译包](#prebuilt-packages)）。 在 Linux 上，LogiTux 通过 `hidraw` 接口直接与硬件通信（不依赖 `libhidapi`，设备 I/O 也不使用 cgo），因此安装时只需要 Go 工具链和 Fyne 常用的 GUI 构建依赖。     ## 状态 v1 支持： - **Litra Glow / Litra Beam** 补光灯 —— 电源、亮度、色温。 - **G Pro Wireless, PRO X Superlight 和 PRO X Superlight 2** 鼠标（直连或通过 Lightspeed 接收器）—— 始终支持 DPI 和回报率（轮询率）；对于带有 Logo 灯的型号支持 Logo 颜色（Superlight 系列没有此功能）；对于固件暴露了相应 HID++ feature 的设备，支持电池电量和按键重映射（参见[用法](#usage) —— 在测试过的两台 G Pro Wireless 中，有一台没有暴露这两种功能，显然是通过接收器自身的协议层处理了它们，因此这两项功能均作为可选项实现，并在不支持时优雅降级，而非保证绝对可用）。较新的鼠标通过不同于 G Pro Wireless 的 HID++ feature 上报 DPI 和回报率（最高 8000 Hz，且 DPI 范围从设备读取，而非硬编码）；LogiTux 会根据连接的鼠标实现的功能进行适配，并在设备自报名称时显示该名称。**注意事项：** Superlight 系列的支持（包括两项扩展功能和两个新的产品 ID）是基于第三方参考实现的协议解析实现的，尚未像原始的 G Pro Wireless 路径那样在物理 Superlight 硬件上进行验证。 - **PRO X Wireless Gaming Headset** —— 电池电量、侧音、完整的分段均衡器（段数/频率/dB 范围均从设备读取，非预设），以及硬件麦克风波噪开关（仅在固件支持时显示，通过读取进行探测；否则隐藏）。 - **C920 / C920 HD Pro / C922 Pro Stream / C930e** 网络摄像头 —— 缩放、平移/倾斜位置、自动对焦和手动对焦、自动和手动曝光，以及图像微调（亮度、对比度、饱和度、锐度）。网络摄像头不是 HID 设备，因此通过轻量级的纯 Go V4L2 层而非 hidraw 进行通信；具体存在哪些控制项是从每个设备的驱动程序中查询的，而非假设。仅支持控制项 —— 尚无视频预览。**注意事项：** 基于文档化的 V4L2 UVC 控制 API 实现，并包含经过单元测试的 ioctl 封装，但尚未像上述其他功能那样在物理硬件上验证过。 UI 仿照 Logitech 自家的 G HUB 设计，包括导航方式：**Dashboard** —— 一个带有青蓝色点缀的接近纯黑的首页 —— 将每个连接的设备显示为可点击的卡片（产品渲染图、名称、电池电量（如果有） —— 闪电标志表示正在充电，以及一个设置按钮）；点击卡片会打开该设备的页面，显示其完整的控制选项，而页面左上角的后退箭头可返回 Dashboard。设备页面仅在实际连接时存在 —— 拔下设备会让你直接返回 Dashboard。设备页面的布局类似于 G HUB：左侧的图标栏将设备的设置分组到不同的部分 —— Sensitivity（DPI、回报率）、Assignments（按键重映射）、Lighting（电源、亮度、色温、RGB Logo 颜色）和 Sound（侧音、麦克风波噪、均衡器） —— 并且仅显示设备实际支持的部分。图标栏旁边的面板包含所选部分的控制项，页面的其余部分显示电池电量和特定于该部分的展示区。在鼠标的 Sensitivity 部分，DPI 以 G HUB 的 **DPI 阶段**呈现：一排预设按钮（当前激活的会高亮显示；点击可切换鼠标到该 DPI），并在展示区通过一条 *DPI Speeds* 轨迹以圆点的形式沿非线性坐标轴标出每个阶段。在耳机的页面上，展示区是垂直的 ADVANCED EQ；在补光灯的页面上，产品渲染图会真正发光，就像 G HUB 的 Litra 页面一样 —— 背后的光环会跟随电源胶囊开关，并且色温和亮度渐变滑块是实时联动的。所选部分在 LogiTux 定期重新轮询设备时会保持不变，而不是每隔几秒就跳回第一项。系统托盘图标提供针对特定设备的快捷操作（电源、DPI 预设），无需打开窗口。 设备层采用插件架构（参见下文的[架构](#architecture)），因此对其他 Logitech 硬件 —— 其他鼠标、键盘、耳机、网络摄像头 —— 的支持可以逐步添加，而无需更改 GUI 或核心应用程序。 ## 快速开始 ``` git clone cd LogiTux ./install.sh ``` 在基于 Debian/Ubuntu 的发行版（包括 Linux Mint）上，`install.sh` 将执行以下操作： 1. 安装 Go 工具链（`golang-go`）（如果缺失）。 2. 安装 Fyne 的构建依赖（`gcc`, `libgl1-mesa-dev`, `xorg-dev`）。 3. 构建 LogiTux 并将其安装到 `~/.local/bin/logitux`。 4. 安装 udev 规则，授予用户访问受支持设备的 `hidraw` 节点的权限（以及 `/dev/uinput`，仅在重映射鼠标按键时使用），并创建 `.desktop` 启动器条目。 在其他发行版上，请自行安装 Go 1.22+ 和 Fyne 的构建依赖（参见 [Fyne 入门指南](https://docs.fyne.io/started/)），然后运行 `./install.sh` —— 它将跳过特定于 apt 的步骤。 安装完成后，**拔下并重新插上你的设备**以使新的 udev 规则生效，然后从你的应用程序菜单启动 LogiTux 或运行 `~/.local/bin/logitux`。 要移除 `install.sh` 设置的所有内容，请运行 `./uninstall.sh`。 ### 预编译包 每次推送都会在 CI 中为所有三个平台构建可安装的包（参见 `.github/workflows/build.yml`），并且打上发布标签（`vX.Y.Z`）后，它们会被附加到 GitHub Release 中： - **Debian/Ubuntu** —— 一个 `.deb` 包（`sudo apt install ./logitux_*_amd64.deb`），它会将二进制文件放入 `/usr/bin`，安装 udev 规则和桌面条目，并为你重新加载 udev。此外还提供了一个普通的二进制压缩包。 - **Windows** —— 一个压缩的 `logitux.exe`。 - **macOS** —— 一个压缩的 `LogiTux.app`。它是未签名的，因此首次启动需要右键点击 → **打开** 以绕过 Gatekeeper。 ## 用法 LogiTux 每隔几秒轮询一次受支持的设备。每个连接的设备都有自己的页面（在设备拔出后页面会消失），可从其 Dashboard 卡片打开，其中包含它支持的所有控制项 —— 电源复选框、滑块、下拉菜单、颜色选择器。更改会立即应用。 关闭窗口会将 LogiTux 最小化到系统托盘，而不是退出；请使用托盘菜单中的“退出”项来真正退出。托盘中还为每个连接的设备提供了一个子菜单，用于一键操作（例如灯光的“打开”/“关闭”，或鼠标的 DPI 预设），无需打开窗口。 无法通过 USB 回报自身状态的设备（Litra 补光灯；而 G Pro Wireless 的 DPI/回报率/电池电量/颜色通常*可以*实时读取，并且实际上也是如此）会回退到 LogiTux 发送的最后数值，并保存在 `$XDG_CONFIG_HOME/logitux/state.json`（通常是 `~/.config/logitux/state.json`）中。大多数设置仅在你与它们交互时才会被*应用* —— 例如，打开 LogiTux 永远不会将陈旧的数值推送到当前关闭的补光灯上。按键重映射是唯一的例外（见下文）：每当鼠标重新连接时，它们会自动重新应用，因为每次应用重启时都静默失效的重映射将违背该功能的初衷。 ### 自定义产品图片 每个受支持的产品都随附专为 LogiTux 绘制的原创渲染图（Logitech 自家的产品照片受版权保护，因此 MIT 许可证的项目无法重新分发它们）。如果你更希望看到官方图片，你可以提供自己的图片：将文件放入 `$XDG_CONFIG_HOME/logitux/images/`（通常是 `~/.config/logitux/images/`），以该产品命名 —— 全小写，空格替换为短横线 —— 扩展名为 `.png`、`.jpg`、`.jpeg` 或 `.svg`，例如 `g-pro-wireless.png`，`litra-glow.png` 或 `pro-x-wireless-gaming-headset.png`。LogiTux 会在启动时加载它们，并在内置渲染图出现的所有地方使用它们。此类图片仅供你本地使用；请勿将它们提交到公开的分支中。 ### 按键重映射 如果鼠标的固件暴露了 `REPROG_CONTROLS` 功能（从 0x1B00 到 0x1B04）—— 并非普遍支持；参见[状态](#status)）—— 其可重映射的按键将各自获得一个下拉菜单，以将它们重新映射到另一个鼠标按键或键盘按键，或恢复为“默认”。如果不存在该功能，此部分将不会出现；鼠标的其他控制项不受影响。 其工作原理是告诉鼠标停止发送该按键的正常点击，并将按下动作作为原始事件上报，然后 LogiTux 通过虚拟输入设备（`/dev/uinput`）将其转换为合成的按键/按钮按下事件。这意味着**重映射的按键仅在 LogiTux 运行时才有效** —— 如果 LogiTux 没有运行（尚未启动、崩溃或在没有机会清理的情况下被杀死），该按键将完全不起作用，这与这里的所有其他设置不同，后者停止运行后仅仅是无法再进行调整，而不会破坏按键本身。当 LogiTux 正常退出（包括通过托盘的“退出”）时，它会恢复所有处于活动状态的重映射，因此正常的关闭操作总是会恢复正常的点击功能。 ## 架构 ``` cmd/logitux/ GUI entry point (Fyne): window, dashboard, device pages, systray internal/hid/ HID Backend interface (hid.go) + Linux hidraw impl (hidraw_linux.go) and a no-op stub for other OSes (hid_stub.go) internal/hidpp/ HID++ 2.0 transport: feature calls, notifications, shared battery logic, device self-naming (DEVICE_TYPE_AND_NAME) internal/uinput/ Virtual input device for button remapping (Linux; stub elsewhere) internal/device/ Plugin registry and capability interfaces internal/device/litra/ Litra Glow/Beam plugin (simple vendor HID protocol) internal/device/gpro/ G Pro Wireless / PRO X Superlight (1 & 2) plugin (HID++ 2.0 protocol) internal/device/prox/ PRO X Wireless Gaming Headset plugin (HID++ 2.0 protocol) internal/device/webcam/ C920/C922/C930e webcam plugin (V4L2 controls, not HID; Linux only) internal/v4l2/ Pure-Go V4L2 control ioctls: query/get/set on /dev/videoN internal/config/ JSON-backed last-known-state store packaging/ nfpm .deb config, Debian postinstall, macOS Info.plist template install/ udev rules and .desktop launcher entry .github/workflows/ CI: vet/test + per-OS builds (.deb, .exe, .app) and tag releases ``` **跨平台结构。** 面向 HID 的类型（`Info`, `Handle`, `Backend`, `Default`）位于没有构建标签的 `internal/hid/hid.go` 中，因此每个设备插件都可以在所有三种操作系统上编译。`hidraw_linux.go` 提供了真正的 Linux 后端；`hid_stub.go`（`//go:build !linux`）提供了一个空操作（no-op）的后端，使得 Windows/macOS 构建版本能够运行，但在编写原生后端之前无法找到设备。`uinput` 包也以同样的方式拆分（真正的 Linux `/dev/uinput` 设备对比一个会报告重映射不可用的空操作 `Open`），并且仅限 Linux 的网络摄像头插件是从 `cmd/logitux/plugins_linux.go` 导入的，而不是从共享的导入块中导入。 设备支持以插件形式添加：一个包在 `init()` 函数中使用 `internal/device.Register` 注册它处理的供应商/产品 ID（参见 `internal/device/litra/litra.go`，`internal/device/gpro/gpro.go` 或 `internal/device/prox/prox.go`），并实现硬件支持的任何能力接口（`PowerControl`, `DPIControl`, `ButtonRemapControl`, `EqualizerControl` 等）。GUI 永远不会引用特定的产品 —— 它根据能力接口对每个发现的 `device.Device` 进行类型断言，并渲染适用的任何控制项。添加新设备意味着编写一个新的插件包，并从 `cmd/logitux/main.go` 导入它（利用其 `init()` 副作用）；其他文件无需更改。完全不位于 hidraw 背后的硬件可以改为使用 `device.RegisterDiscoverer` 注册一个完整的发现函数 —— 这就是网络摄像头插件扫描 `/sys/class/video4linux` 以查找 V4L2 设备的方式，而其他所有设备都通过 hid 后端进行通信。 大多数超出简单灯光范围的 Logitech 外设（鼠标、键盘、耳机）都使用 Logitech 的 **HID++ 2.0** 协议：这是一个请求/响应（request/response）的功能调用系统，而不是像 Litra 那样使用固定的字节序列。`internal/hidpp` 实现了该传输层（通过 Root feature 进行 feature 发现、请求/响应匹配、主动通知），因此一个新的 HID++ 设备插件只需要知道它使用哪些 feature ID 及其字节布局 —— 参见 `internal/device/gpro` 查看涵盖 DPI、回报率、RGB 和按键重映射的完整示例，以及 `internal/device/prox` 查看分段均衡器的示例。电池支持（一个四级的 feature-ID 回退机制，因为不同的设备实现的方式不同 —— 这是在实际硬件上艰难验证的，需要用到每一级回退）仅存在于 `internal/hidpp/battery.go` 中，两个设备插件都直接调用它，而不是各自拥有一个副本。 ## 开发 ``` make build # -> bin/logitux make test # go vet + go test ./... make run # build and run ``` ## 许可证 MIT —— 参见 [LICENSE](LICENSE)。

标签：EVTX分析, Go, GUI, Logitech, Ruby工具, 外设管理, 日志审计, 桌面应用, 硬件控制