Skip to content

readme.md

Latest commit

 

History

History
292 lines (194 loc) · 16.1 KB

readme.md

File metadata and controls

292 lines (194 loc) · 16.1 KB

RhythKey Pro 使用手册

控制器外壳的 3D 打印

请前往 Releases 下载外壳的 .3mf 模型文件，
或者自行使用喜欢的 3D 建模软件打开 /case 目录下的 .step 文件进行修改。
可以联系拥有 3D 打印机的朋友或者互联网上的付费 3D 模型打印服务进行打印。

带有 with Text 后缀的上盖 3mf 文件是有整活文字的版本，如果您选择的 3D 打印服务提供商支持多颜色材料混合打印，推荐使用此模型文件，并在提交打印请求时充分告知提供商所使用的颜色配置。

PCB 的打印

您可以使用 嘉立创EDA Pro 登录账号并导入位于 /pcb 目录中的 .epro2 格式文件，并进行 Gerber 文件的导出，然后前往嘉立创在线 PCB 下单服务进行 PCB 的打印。

或者如果您不需要对 PCB 进行审阅或修改，也可以直接前往 Releases 进行 Gerber 文件的下载。

推荐选择白色的 PCB 以使电路板正面的丝印更加美观。

注意：由于我在绘制 PCB 的时候使用了一些没有电气信息的封装，所以 EDA 中的电气原理图功能不具备参考价值。

BOM 配件采购

首先，您需要购买用于 BOM 的电子元件，这些元件的清单如下，大概分为两类，一类是 必购配件，一类是 可选配件，但是推荐所有的配件全部都购买并组装。

必购配件

  • 1x Sparkfun Arduino Pro Micro 5V/16MHz
    也可以是其他厂商生产的兼容版本，只要是搭载 ATMega32U4 主控芯片且工作电压是 5V 工作频率是 16MHz 的模块就可以了。
    切勿购买使用 Mini-USB 接口的版本，其 PCB 尺寸和我们的 PCB 不符，而且我相信您应该很难在2026年找到一根那样的数据线
    切勿购买 3.3v / 8MHz 的版本，其工作电压不兼容 PCB 上的其他元器件，工作频率也只有 5V 版本的一半，会影响模块的性能。
    推荐购买预先焊接好插针的版本，使用方便快捷。

  • 12x 您喜欢的五脚机械键盘轴体
    我在改良设计这款音游控制器的时候，有朋友询问过我能不能使用光轴或者静电容轴来提升其在音游场景下的绝对游玩体验。
    遗憾的是，答案是不能，光轴或静电容轴的触发力度 / 键程调节功能不是一位在校学生可以在不借助任何专业调校设备的帮助下使用基于 Arduino 的主控方案实现的。

  • 12x 凯华机械键盘轴座

  • 8x 1U 尺寸的机械键盘键帽和 4x 2.75U 尺寸的机械键盘键帽

  • 4x 2U 尺寸的机械键盘卫星轴
    在大多数时候您应该会被店家捆绑销售一根适用于机械键盘空格键的 6.5U 或者 7U 长度的卫星轴，这是正常现象。

  • 2x EC11 旋转编码器及配套旋钮帽

    ⚠️ 注意： 本项目 SOUND VOLTEX 旋钮部分使用的是旋转编码器（Rotary Encoder），输出数字脉冲信号。请勿将其与输出模拟信号的传统电位器（Potentiometer）混淆。

    在编码器的选型上，存在两种主要的装配方案。综合游玩手感与装配成本，本项目强烈推荐采用方案 A（第三方编码器去段落改造）。

    方案 A：第三方 EC11 编码器 + 物理改造（作者推荐）
    由于 ALPS 进口编码器成本高昂（是国产编码器的7.5倍左右），使用常规的第三方/国产 EC11 编码器是极佳的替代方案。

    • 采购： 选购市面常见的低成本 EC11 编码器即可（通常均带有物理段落感）。
    • 改造： 带有刻度的编码器在旋转时会产生明显的阻滞感，极大地影响 SDVX 的游玩体验。建议在焊接前进行物理改造：使用工具拆开编码器的金属外壳，将内部与齿轮接触的弹性金属弹片完全压平，以消除物理段落感。
    • 体验： 改造后的编码器由于内部缺乏高粘度阻尼脂，会处于极低摩擦力的状态。这种轻盈且带有惯性的顺滑感，反而非常贴近街机原厂光电编码器的游玩体验。缺点是机械触点寿命相对有限，高强度使用数月后如出现信号抖动，直接更换即可。

    方案 B：ALPS 原装 EC11 编码器（无级版）
    如果您不希望进行任何物理改造，可以采购由日本 ALPS 原装进口的 EC11 编码器。

    • 采购： ALPS 原厂提供带段落的 EC11E09244BS 和无段落平滑的 EC11E1834403 两个版本。请务必选择无段落平滑版（EC11E1834403）。
    • 体验： ALPS 原厂无级编码器内部注有高品质的阻尼脂以提升旋转精度。这导致其旋转阻力显著大于常规件，在 SDVX 需要快速、高频搓盘的应用场景下，会产生明显的粘滞感与疲劳感。因此，从实际游玩体验出发，并不将其作为首选推荐。

    旋钮帽选购提示： EC11 编码器的金属转轴通常分为**半圆轴（D型轴）与梅花轴（齿形轴）**两种规格。购买配套的金属旋钮帽时，请务必确认旋钮帽内部的孔型与您采购的编码器轴体形状完全一致，否则将无法正常安装。

  • 1x ALPS B10K 60/75mm 双联滑动电位器以及1个滑动电位器推子帽
    国产双联电位器和 ALPS 进口电位器我也都购买过，国产方案的手感和性能完全不逊色于进口件，所以推荐使用国产方案，同样能省下7.5倍的钱。
    不过要注意的是，国产的单联滑动电位器不但和双联电位器的规格不一致，而且品控远差于双联电位器，购买时请注意区分型号，如果商家发错货需要及时申请售后。

    电位器和编码器的配套帽建议在购买电位器编码器的同一店铺购买，通常可节省运费。

  • 7x 6mm*6mm 贴片按键式轻触开关，按键高度 7.5mm

  • 4x R0805 10KΩ 贴片电阻

  • 16x R0805 100nF 贴片电容

  • 1x R0805 330Ω 贴片电阻

  • 12x R0805 1Ω 贴片电阻

  • 12x WS2812 3528 封装反贴 RGB LED 灯珠
    注意搜索关键词： SK6812MINI-E 才是封装正确的反贴版本灯珠。
    WS2812 本来是 WorldSemi 的产品，但其原生封装是正贴 5050 尺寸的，而自制键盘圈子里最常用的反贴 RGB 灯珠就是 SK6812MINI-E 了。

  • 18x R1206 1N4148 反冲二极管

  • 6x M2*8 自攻螺丝

  • 5x M2*16 自攻螺丝

  • 可以调整温度的电烙铁，焊锡丝，焊油，松香，以及一把弯头尖嘴镊子
    或者如果您拥有热风枪的话，也许可以试试回流焊？

可选配件

  • 2x 2.54mm 直插单排母排针母座
    如果您不考虑模块的可插拔特性，可以直接将模块焊死在主板上。
  • 6x 6mm 厚度的橡胶脚垫
    在使用排针插座连接 Arduino 模块时，模块的高度会超出 3D 打印件的厚度，所以需要几个脚垫将其垫高，旋钮侧垫高 12mm ，用户侧垫高 6mm 即可。
  • 12x 机械轴的轴下垫
    主要是我真不觉得几片泡沫能改变以 3D 打印的材料为外壳的音游控制器的按键听感到什么地步，那么还不如什么都不贴。但因为您可以选择贴上，所以在这里提一嘴。

焊接

除了位于主板正面的 6 个贴片轻触开关以外，所有的贴片电子元件全部都被设计在了主板的背面，丝印直接指示元器件型号，对号入座即可。
先完成背面的贴片元件焊接之后，再焊接电位器、正面的贴片开关、排针母座等部件。
完成的电路板应该如下图所示，虽然图中的 PCB 是曾经的 Prototype 版本，和仓库中的 PCB 不一致：

组装

  • 将卫星轴嵌入到上盖当中
  • 将 PCB 放置在底壳中，拧上 M2*8 的自攻螺丝
  • 将顶壳放置在底壳上，拧上 M2*16 的自攻螺丝
  • 安装机械轴、旋钮帽、电位器帽、键帽
    如果觉得电位器帽在电位器上面很松动，可以在电位器帽里面塞一张小纸片，这会增大电位器帽与电位器的摩擦力。

完成组装的产品如图所示：

固件烧录

第一次刷入

首先下载并安装 Arduino IDE，打开 Preferences 选项卡。

在 Additional Boards Manager URLs 中填入 https://raw.githubusercontent.com/dmadison/ArduinoXInput_Boards/master/package_dmadison_xinput_index.json ，如图所示。如果这一行里已经有其他的内容了，就追加到后面，以分号间隔开。

然后打开 Boards Manager ，搜索并安装 XInput SparkFun Boards 。

接下来再打开 Library Manager ，搜索并安装 XInput 库和 FastLED 库。

然后，将装配好的 RhythKey Pro 的 USB-C 接口连接到电脑。
第一次刷入固件时不需要 RESET 按钮便可识别到暴露的 COM 端口，点击识别到串口旁边的笔图标，搜索并选中 SparkFun Pro Micro w/ XInput ，选中右侧对应的端口再选择 OK 。

接下来（非常重要！）点击 Tools 选项卡，其中有一个 Processor: ATMega32U4 的选项，点击它，务必在弹出的菜单中选择 ATMega32U4 (5V, 16 MHz) 这一项，否则刷入固件后模块将无法被识别。

然后打开仓库中的 rhythkeyoro_fw.ino 文件，点击左上角的 Upload 按钮，等待固件烧录完成。

固件升级

由于在刷入 XInput 固件之后 Pro Micro 模块会变成一个 XInput 设备，所以 Arduino IDE 将无法识别到它，此时需要按下 Pro Micro 模块的 RESET 按钮，使其重新进入 Bootloader 模式，再进行后续的固件升级。

这个 Bootloader 模式仅会持续 8 秒钟的时间，所以会很考验用户对电脑操作的熟练度。

先打开 Arduino IDE ，按下 RESET 键一次，使模块进入 Bootloader 模式。
您需要在这 8 秒钟之内完成对模块端口和开发板类型的绑定设置（点击笔图标，选择端口，选择开发板类型）。
然后在模块不在 Bootloader 模式的情况下，点击 Upload 按钮，烧录固件。
在 Arduino IDE 完成固件编译后（如下图所示），显示 Uploading 时，立刻按一下 RESET 按钮，使其重新进入 Bootloader 模式，新固件才能被成功刷入。

功能介绍

按键映射

本控制器的机械轴按键被映射到 XInput 的按键，具体映射如下：

机械轴按键 XInput 按键
左右侧键 左右肩键
左右菜单键 左右菜单键
左侧3个主键 D-PAD的左/上/右
右侧3个主键 X/Y/B
左侧地键 D-PAD的下
右侧地键 A
左旋钮按下 LS
右旋钮按下 RS

附加功能键定义

本控制器的下部有一排贴片按钮，从左到右分别是：

  • RGB LED 亮度降低
  • RGB LED 亮度增加
    （注：系统具有非易失性存储的掉电记忆功能。在您完成亮度调节后闲置约 3 秒，系统会自动防抖并将设定值平滑保存至内部 EEPROM 中，避免频繁写入损耗芯片寿命，且下次上电时会自动恢复该亮度）
  • LS 键
    （注：和左旋钮按下从电路层面上并联，软件层面不可更改）
  • RESET 键
  • 未定义
  • 模式切换

本控制器定义了两个模式，分别为 ONGEKI 模式和 VARIOUS 模式。两种模式的灯光效果和行为都不同。

在 ONGEKI 模式下：

  • 所有机械轴按键均可用，但两个菜单键需要长按 3 秒钟，才会被触发
  • 滑动电位器被映射到线性扳机，以中间位置为边界，电位器向左偏移时左线性扳机按下，向右偏移时右线性扳机按下
  • 通过震动马达的数据通道改变 RGB LED 颜色效果的特性可用
    （注：得益于固件级别的定向过滤优化，系统主动免疫了由 Windows 焦点丢失、按下 Win 键等系统级事件引发的全局震动重置 (0,0) 信号，从根本上杜绝了游玩过程中灯效出现违和闪烁的现象）
  • 旋转编码器会被直接屏蔽，以防止游戏过程中误触

在 VARIOUS 模式下：

  • 侧键和菜单键会被直接屏蔽，以防止游戏过程中误触，其对应的 LED 灯也会随之熄灭
  • 滑动电位器被映射到右摇杆的 X 轴
  • 通过震动马达的数据通道改变 RGB LED 颜色效果的特性不可用
  • 左右旋转编码器分别被映射到左摇杆的 X 轴和 Y 轴

在两个模式间切换时，所有摇杆和线性扳机的数值都会被清空，以防止游戏过程中出现异常。如果切换模式时滑动电位器的位置不在中心位置，在其没有读取数值变化时，其映射的目标会保持在中心位置，等到读数出现变化时才会将电位器的位置反映到映射目标的数值上。

游戏设置

免责声明：本项目不提供任何游戏的安装文件及游戏自身的使用教程。

音击

首先切换到 ONGEKI 模式。

打开 segatools.ini ，调整好其他设置，滚动到配置文件的末尾。

[io4]
enable=1
; Test button virtual-key code. Default is the F1 key.
test=0x70
; Service button virtual-key code. Default is the F2 key.
service=0x71
; Keyboard button to increment coin counter. Default is the F3 key.
coin=0x72

; Set "1" to enable mouse lever emulation, "0" to use XInput
mouse=0

将 mouse 项更改为 0 ，然后保存配置文件。

然后打开 start.bat ，在 start "AM Daemon" 所在的行后面添加这行内容：

start "LED Sync" /min python "ongeki_led_reader.py"

以及 taskkill /f /im amdaemon.exe 所在的行后面添加这行内容：

taskkill /f /fi "WINDOWTITLE eq LED Sync" > nul 2>&1

保存 start.bat 文件。最后，把 tools/ongeki_led_reader.py 文件复制到 start.bat 所在的目录中。

如果你没有安装 Python ，可以从 python.org 下载安装。

启动游戏，按 F1 进入测试模式，选择 レバー設定 并进入。

先选择 初期設定に戻す ，然后缓慢地移动电位器到最左端，再移动到最右端。
接下来选择 終了 ，然后 保存する ，完成其他需要的设置后退出测试模式，开始享受游戏。

SOUND VOLTEX

首先切换到 VARIOUS 模式。

运行 spicecfg.exe 或者在进入游戏后按 F4 按钮，打开 spicetools 的设置界面。

按照图中的方式逐个点击 Bind 按钮，然后按下控制器上对应的按键进行绑定。
绑定完按键后切换到 Analogs 选项卡。

将两个旋钮分别绑定到控制器的摇杆 X 轴和 Y 轴上，并启用 Smooth Axis。
（注：由于国产 EC11 编码器与 ALPS 原厂件的在 A/B 相输出上可能是相反的，若您在测试中发现旋钮旋转方向与游戏内完全相反，请直接在该界面勾选对应的 Invert Axis 选项进行软件反转，无需重新编译固件或更改硬件接线。）

然后退出设置，开始享受游戏。

DJMAX RESPECT V

切换到 VARIOUS 模式，进入游戏，进入设置 -> 控制 -> 输入设置 -> 编辑。

设置好按键映射之后直接开始享受游戏。

osu!

使用类似 DJMAX 的方式设置按键映射后即可开始享受游戏。

In Falsus Demo

切换到 VARIOUS 模式，然后确保在 Steam 中导入这个布局。

steam://controllerconfig/4355100/3667527437

然后在 Steam 设置 -> 控制器 -> 校准及高级设置 中，关闭右摇杆的死区，然后进入游戏。

注：根据不同显示器尺寸的差异，可能需要自行微调映射摇杆的区域垂直位置和区域大小。