Vibe Ring

Vibe Ring 是一款专为 macOS 设计的开源工具，它能让你的 任天堂健身环 (Ring-Con) 化身为一个独特的物理输入设备。通过蓝牙连接 Joy-Con (R)，Vibe Ring 将健身环的挤压和拉伸动作映射为键盘按键，为你的工作流增添一份趣味性和互动性，甚至可以作为某种形式的“微运动”提醒。

核心功能与映射

Vibe Ring 利用健身环内置的压力传感器，将物理动作转化为标准的 macOS 键盘事件：

💡 创意用法：你可以将 Fn 键与其他键组合（如 Fn + C 复制），或者在聊天软件中用“拉环”来发送消息，实现一种充满仪式感的交互体验。

前置条件

• 操作系统：macOS (目前暂不支持 Windows 或 Linux)。
• 硬件：
  • 一台 Mac。
  • 一个 任天堂 Joy-Con (R) 手柄（右红/左蓝中的右侧那个）。
  • 一个 Ring-Con (健身环)，并已牢固安装在 Joy-Con (R) 上。
• 软件环境：
  • Node.js 18+
  • pnpm
  • Xcode 命令行工具 (xcode-select --install)

快速开始

1. 安装依赖

克隆仓库后，在项目根目录运行：

pnpm install

此步骤会自动构建 node-hid 原生绑定，并在首次运行时编译 Swift 键盘辅助程序。

2. 配对 Joy-Con (R)

1. 打开 macOS 系统设置 > 蓝牙。
2. 按住 Joy-Con (R) 侧面的黑色小同步按钮，直到指示灯呈流水灯闪烁。
3. 在 Mac 蓝牙列表中找到 Joy-Con (R) 并点击连接。

3. 授予辅助功能权限

由于 Vibe Ring 需要模拟键盘事件，必须获得 macOS 的辅助功能授权：

1. 前往 系统设置 > 隐私与安全性 > 辅助功能。
2. 点击列表下方的 + 号，添加你打算接收按键的应用（如 Terminal, iTerm2, Ghostty, 或 VS Code 等）。
3. 确保开关已开启。

4. 启动程序

在终端中运行：

pnpm start

程序会自动发现已配对的 Joy-Con (R)，初始化健身环 MCU，并开始监听输入。你会看到类似以下的日志：

Found Joy-Con (R): IOService:/...
Initializing Ring-Con...
  [OK] Enable vibration
  ...
Ring-Con initialized successfully!
Ring-Con ready! Listening for input...
  Squeeze → Fn (hold)
  Pull outward (short) → Enter
  Ctrl+C to quit

参数校准与调节

由于每个健身环的老化程度和使用习惯不同，压力传感器的阈值可能需要微调。你可以在 src/main.ts 中修改以下常量：

校准方法：运行程序后，观察日志中打印的 flex 值。轻轻挤压或拉动，记录触发时的数值，据此调整上述阈值。

常见问题 (FAQ)

Q: 提示 “Joy-Con (R) not found”？

• A: 请确认 Joy-Con (R) 已在 macOS 蓝牙设置中成功配对并处于连接状态。注意：仅支持 Joy-Con (R) (VID 057E, PID 2007)，左侧的 Joy-Con (L) 无法使用。

Q: 健身环初始化失败？

• A: 尝试在蓝牙设置中忽略该设备，重新配对。同时确保健身环已完全推入 Joy-Con 的导轨并听到“咔哒”声。

Q: 挤压/拉动没有反应？

• A: 90% 的情况是辅助功能权限未授予。请检查是否已将你当前使用的终端应用添加到“辅助功能”白名单中，并重启终端应用。