jameslockman/Griffin-PowerMate-Driver 来源：https://github.com/jameslockman/Griffin-PowerMate-Driver # 适用于现代 macOS 的 Griffin PowerMate 驱动程序

这个小型驱动程序让经典的 Griffin PowerMate 得以在现代系统上使用。PowerMate 能做什么？它是一个可以旋转或按压的旋钮。仅此而已。它的底座还带有一个蓝色 LED，亮度会根据你的操作而变化。发布之初，它的目的是通过为桌面添加一个可滚动的旋钮来辅助视频和音频制作。当然，如今已有功能更丰富、支持更多花哨特性的现代控制器，但这款早期设备却有一种……复古……的独特韵味。

安装时，打开 DMG 文件并将 PowerMate Agent 拖入应用程序文件夹。然后启动 PowerMate Agent。当然，没有 PowerMate 硬件它什么都做不了，所以快去你的 USB 杂物抽屉里把它翻出来擦擦灰吧！顶部菜单栏会出现一个新图标，用于控制 PowerMate 的行为。

PowerMate 充当滚动控制设备。因此，如果当前活动窗口或控件支持滚动，旋转旋钮即可滚动窗口或增减选定值。如果不喜欢默认的滚动方向，也可以进行反转。

PowerMate 同时也可作为鼠标按键使用。短按按钮模拟鼠标单击，长按则模拟右键单击。你也可以修改设置，让长按模拟双击。非常简单，对吧？

技术细节

这是一款小型 macOS 驱动程序，通过 USB HID 打开 Griffin PowerMate（VID 0x077d，PID 0x0410），读取其 6 字节报告，并公开 按钮 和 旋转 事件，以便你将其映射到具体操作（例如滚动、单击、媒体按键）。该设备会在总线上上报数据，但在 macOS 上默认不执行任何操作；此库会**接管（seize）**该设备并将事件传递给你的应用。

报告格式（来自设备）

• 第 0 字节：按钮状态 — 0 = 释放，1 = 按下
• 第 1 字节：旋转增量 — 有符号整数；正数 = 顺时针，负数 = 逆时针（通常每次报告为 ±1 到 ±7）。设备不会直接上报速度；驱动程序会根据两次报告之间的时间间隔推算出旋转速率（每秒增量数）。

构建与运行

cd /path/to/USB
swift build
swift run PowerMateDemo

将 PowerMate 插入电脑后，旋转旋钮或按下按钮，演示程序将打印相应事件。按 Ctrl+C 停止。

系统级驱动（PowerMate Agent）

PowerMateAgent 将旋钮和按钮操作转换为键盘/滚动事件，供任何应用程序接收（浏览器、编辑器等）：

• 旋转 → 垂直滚动，或在菜单（或子菜单）聚焦时发送 上/下方向键。
• 单击（短按）→ 模拟 鼠标左键（光标处），或在菜单聚焦时发送 Return 键（选择高亮项目）。
• 长按 → 模拟 鼠标右键（光标处）。

菜单和子菜单的检测依赖于 辅助功能（Accessibility） API：当聚焦的 UI 元素为菜单（含子菜单）时，旋转会发送方向键，单击发送 Return 键。请在“系统设置 → 隐私与安全性”中授予辅助功能权限，以确保子菜单能正常工作而不会“卡”在滚动模式。如果未启用辅助功能，长按仍会进入备用的“菜单模式”（持续发送方向键直到单击或 5 秒超时）。

旋转时 LED 会呼吸闪烁，闲置时变暗；按住按钮时保持常亮。

swift run PowerMateAgent

首次运行时，macOS 会请求**输入监控（Input Monitoring）**权限。请在“系统设置 → 隐私与安全性 → 输入监控”中授予权限，并添加（或启用）终端或编译后的可执行文件，然后再次运行 Agent。

要在后台运行：执行 swift run PowerMateAgent & 或直接运行编译好的二进制文件 ./.build/debug/PowerMateAgent。若希望开机自启，可将其添加到登录项中。

若要创建经过签名和公证的应用（或安装包），以便他人使用时不会弹出安全警告，请参阅 DISTRIBUTION.md。你需要一个 Apple Developer 账号；用户首次使用旋钮时仍需手动授予一次输入监控（或辅助功能）权限。

在你的应用中使用

1. 添加依赖包

在你的应用 Package.swift 文件中（或在 Xcode 中：文件 → 添加包依赖）：

dependencies: [
    .package(path: "/path/to/USB"), // or your clone URL
],
targets: [
    .target(name: "YourApp", dependencies: ["PowerMateDriver"]),
]

2. 启动驱动并映射事件

import PowerMateDriver
let driver = PowerMateDriver()
// Optional: use closures for simple mapping
driver.onRotate = { delta, rate in
    // delta > 0 = clockwise, delta < 0 = counter-clockwise
    // rate = deltas per second (nil on first report); use for speed-dependent mapping
    // e.g. scroll: CGEventCreateScrollWheelEvent(..., delta * lineHeight)
}
driver.onButtonDown = { /* e.g. simulate click or toggle */ }
driver.onButtonUp = { }
// Or use the delegate for all events
driver.delegate = self // implement PowerMateDriverDelegate
driver.start()
// Keep run loop running (e.g. main thread in an app)

3. 事件类型

• PowerMateEvent.buttonDown / buttonUp — 旋钮按下 / 释放
• PowerMateEvent.buttonClick — 短按并释放（在 longPressThreshold 阈值内）。
• PowerMateEvent.buttonLongPress — 按住至少 longPressThreshold 时间后释放。
• PowerMateEvent.rotate(delta: Int, rate: Double?) — delta 为有符号步数（例如 +1、-2）；rate 为推导出的旋转速度（每秒增量数，首次报告时为 nil）。

设置 longPressThreshold（默认 0.4 秒）以调整长按的判定阈值。使用 onClick 和 onLongPress（或代理）进行分别处理。使用 driver.isConnected 检查设备当前是否已连接打开。

LED（底座蓝色指示灯）

底座带有一个蓝色 LED，可用于状态反馈。仅在设备已连接时（isConnected == true）对其进行控制。

• setLEDBrightness(_ value: UInt8) — 静态亮度 0–255（0 = 关闭）。
• setLEDPulseAsleep(_ on: Bool) / setLEDPulseAwake(_ on: Bool) — 开启或关闭“睡眠”或“唤醒”状态下的内置呼吸效果。
• setLEDPulseMode(table:op:arg:) — 自定义呼吸模式：table 为 0–2，op 为 0 = 变慢，1 = 正常，2 = 变快；当 op 为 0 或 2 时，arg 取值为 1–255。

LED 命令使用 USB 厂商控制请求（与 Linux 驱动协议相同）。命令发送成功将返回 true。如果 USB 设备被占用（例如其他进程已打开它），LED 相关调用可能会失败。

映射到系统操作

• 滚动：在 onRotate 中创建滚轮 CGEvent（例如 CGEventCreateScrollWheelEvent）并发送，或将增量值传入你自己的滚动逻辑中。
• 单击：在 onButtonDown / onButtonUp 中创建并发送鼠标单击 CGEvent，或调用你自己的单击处理函数。
• 媒体控制 / 其他：将 onRotate 和 onButtonDown 映射到你需要的任何操作（例如音量调节、键盘等效按键）。

发送事件可能需要你的应用在“系统设置 → 隐私与安全性”中获取输入监控（或辅助功能）权限。

如果设备无响应

1. 拔下并重新插入 PowerMate，然后再次运行你的应用。
2. 退出其他可能正在使用 PowerMate 的软件（例如旧版 PowerMate 应用）。
3. 驱动使用了 kIOHIDOptionsTypeSeizeDevice 标志，因此会获取独占访问权限；同一时间只能有一个进程使用它。

系统要求

• macOS 13 或更高版本
• Swift 5.9 或更高版本

参考资料

• Linux PowerMate 驱动 (https://gitlab.eclipse.org/eclipse/oniro-core/linux/-/blob/master/drivers/input/misc/powermate.c)（报告格式：第 0 字节 = 按钮，第 1 字节 = 旋转）
• 在 Linux 上复活 Griffin PowerMate (https://www.gilesorr.com/blog/powermate-on-linux.html)
• Apple IOKit HID：IOHIDManager、IOHIDDeviceOpen、IOHIDDeviceRegisterInputReportCallback