DIY街机控制器-一起DIY吧

📖 本文由 Batocera 官方 Wiki 翻译整理，内容可能随版本更新而变化。

街机控制面板自建指南（Do-It-Yourself Arcade Controls）

【提示】本章节内容正在建设中。

使用控制器接口（Using Controller Interfaces）

许多玩家在亲手打造街机柜（Arcade cabinet）、鸡尾酒台式机或小型桌面街机（Bartop）时，都会用到编码器或控制板（Encoder/Controller board）。它的作用是把摇杆和按钮的物理信号传给运行 Batocera 的系统（常见的如 Ultimarc I-PAC 设备或 JAMMASD 板卡）。

这些板子通常会将自己伪装成一个键盘（Keyboard），也就是说，当你按下一个街机按钮时，电脑收到的其实是一个键盘按键事件（KEY_ events）。

生活化类比： 这就像是你给电脑接了一个只有几个按键的“异形键盘”。虽然能用，但很多游戏模拟器更习惯和“手柄”打交道，面对“键盘信号”时可能会有点反应迟钝或配置困难。

此外，街机柜往往还有些特殊的“功能键”，比如专门的菜单、退出和暂停按钮。在 Batocera 的常规操作中，这些功能需要通过“热键（HOTKEY）+ 其他按键”的组合方案来完成。如果你已经有了独立的功能按钮，再要求按组合键就显得多此一举了。

进阶利器：让街机柜更“聪明”

从 Batocera v41 版本开始，系统内置了两个强大的工具来解决上述难题：

1. 键盘转手柄工具（keyboardToPads）

这个工具能把那些“键盘型”编码器的信号，重新映射并转换成一个或多个虚拟控制器（Virtual controller）。
* 效果： 模拟器会认为你插上的是标准游戏手柄，兼容性更好。

2. 热键生成器（Hotkeygen）

它会像一个“监听员”，时刻盯着输入设备发出的特定按键信号。一旦你按下了街机柜上的专用按钮（如“退出”键），它就会自动触发对应的系统指令。
* 效果： 你的街机专用按钮可以实现一键直达，不再需要额外按住热键按钮了。

配置建议步骤

第一步：检查板卡模式
首先确认你的控制板（如某些 Ultimarc 型号）是否可以切换模式。如果能直接切换到 DInput 或 XInput 模式，系统会更容易将其识别为标准手柄。

第二步：使用转换工具
如果板卡只能作为键盘识别，请启用 keyboardToPads 映射功能，将键盘事件转换为模拟器熟悉的“手柄语言”。

第三步：配置专用按钮
利用 Hotkeygen 关联你柜子上的独立功能键。这样不管是想暂停还是想退回菜单，点一下专用按钮就能搞定，操作感直接拉满。

街机柜进阶配置：强强联手

在 Batocera 中，你可以让两个强大的工具“联手办公”：键盘转手柄工具（keyboardToPads） 负责把杂乱的按键信号梳理成整洁的控制器信号，而 热键生成器（hotkeygen） 则负责把特定的按键动作翻译成系统指令。

生活化类比： 这就像是一场完美的演出，keyboardToPads 是后台的化妆师，把所有按键都打扮成标准的手柄模样；而 hotkeygen 则是现场导演，看到你按下特定的按钮，就立刻指挥系统做出相应的动作（比如退出或保存）。

街机控制面板参考展示

下面是一些预制或自制的街机控制器图片，可以作为你 DIY 的参考灵感：

（此处可查看 X-Arcade、Rec Room Masters 以及各种自制控制器的外观示例图）

购买建议与开源授权合规说明

有些街机柜零售商在预装 Batocera 及相关软件时，并没有严格遵守开源授权（Licensing）和归属声明的义务。为了保护开源社区的健康发展，以下是目前已知并尊重授权要求的零售商：

Iconic Arcade: https://iconicarcade.com/
Rec Room Masters: https://recroommasters.com/

热键映射指南（Hotkeys）

上下文热键（Contextual hotkeys） 是 Batocera 将模拟器操作与手柄按键联系起来的核心方式。
系统会将每个模拟器自带的热键功能一一对应到 Batocera 的标准指令上。当你配置上文提到的 keyboardToPads 和 hotkeygen 时，下表中的按键对应关系将非常有用：

热键与键盘按键对应表

如何使用与配置 hotkeygen

（后续配置步骤请参阅下文…）

使用热键生成器（Hotkeygen）实现一键直达

通过配置热键生成器（Hotkeygen），你可以让街机柜上的菜单（Menu）、退出（Exit）或暂停（Pause）等专用按钮变成“独立按键”。

生活化类比： 这就像是给你的电视配了一个带“一键直达”功能的遥控器。原本你想看电影得先按“主页”再找“电影库”（组合键操作），现在你只需要按一下那个印着“电影”的专属大按钮（独立按键），就能直接进入画面。

【提示】在使用和配置 hotkeygen 以及 keyboardToPads 之前，你需要掌握如何进入 Batocera 的终端（Terminal）以及如何操作文件。如果你还不熟悉这些，请先参考“通过 SSH 访问 Batocera（Access Batocera Via SSH）”的相关教程。

第一步：查看当前的按键状态

在 EmulationStation 界面运行时，输入命令 hotkeygen --list，你会看到类似下面的信息：

$ hotkeygen --list
Context [EmulationStation]:
exit------------> KEY_ESC
menu------------> KEY_SPACE
files-----------> KEY_F1
# device /dev/input/event5 [Ultimarc I-PAC 4] (no Ultimarc_IPAC_4-d209-430.mapping file found)
KEY_PAUSE-------> pause
# device /dev/input/event3 [AT Translated Set 2 keyboard] (no AT_Translated_Set_2_keyboard-01-01.mapping file found)
KEY_PAUSE-------> pause
# device /dev/input/event23 [Xtension hotkeys] (no Xtension_hotkeys-00-00.mapping file found)
KEY_EXIT--------> exit------------> KEY_ESC
KEY_MENU--------> menu------------> KEY_SPACE
KEY_PAUSE-------> pause

这份清单告诉你了什么？
* 当前环境（Context）： 你目前处于 EmulationStation（系统主界面）。
* 按键映射关系： * 触发“退出（exit）”指令，相当于按下了键盘上的 ESC 键。
* 触发“菜单（menu）”指令，相当于按下了键盘上的空格键。
* 触发“文件（files）”指令，相当于按下了键盘上的 F1 键。
* 识别到的设备： 系统识别到了 3 个可以生成这些事件的设备（例如 Xtension hotkeys）。
* 自定义状态： 提示中显示 no ... mapping file found，意味着系统目前没有找到针对这些设备的自定义映射文件，正处于使用“系统标准热键”的状态。

第二步：理解不同模拟器下的环境变化

由于每个模拟器的快捷键可能不同，当你运行特定模拟器时，hotkeygen 的反馈也会随之改变。例如，当你运行索尼 PSP 模拟器（ppsspp）时：

$ hotkeygen --list
Context [ppsspp]:
exit------------> ['KEY_LEFTALT', 'KEY_F4']
save_state------> KEY_F3
restore_state---> KEY_F4

从这里你可以看出：
1. 环境已切换： 现在变成了 ppsspp 环境。
2. 组合键映射： 此时执行“退出”指令，系统实际上是帮你按下了键盘上的 Alt + F4。
3. 功能调整： 出现了针对该模拟器的“保存存档（save_state）”和“读取存档（restore_state）”的对应按键（F3 和 F4）。

在掌握了 hotkeygen 的基本概念后，我们来聊聊如何进阶操作，以及如何处理那些“伪装成键盘”的控制板。

第一步：在命令行中测试热键

如果你想验证某个热键是否生效，不一定非要按手柄。你可以直接在命令行中模拟按键操作。

模拟退出游戏： 无论你正在玩什么，输入以下命令即可强行退出：
hotkeygen --send exit
模拟暂停： 输入以下命令可以暂停模拟器。在大多数模拟器中，“菜单”和“暂停”的功能是一样的：
hotkeygen --send pause

【提示】如果你想看到更多背后的技术细节，可以在命令后面加上 --debug 参数。例如，输入 hotkeygen --list --debug，系统会告诉你它是从哪些路径读取配置文件的，这在你想要自定义设置时非常有用。

第二步：扩展热键配置

Batocera 的默认配置存放在 /etc/hotkeygen 文件夹中。但如果你想打造自己的专属方案，建议在 /userdata/system/configs/hotkeygen 目录下创建新文件，系统会自动将它们与默认设置合并。

生活化类比： 这就像去餐厅点餐。默认配置是“主厨推荐套餐”（不可更改），而你在自定义文件夹里创建的文件就是你的“加菜需求”。服务员（系统）会把加菜和套餐一起端给你。

通用配置（common_context.conf）： 在这里定义那些无论何时都生效的热键，比如截图功能。
默认映射（default_mapping.conf）： 用于定义哪些按键对应哪些动作。理论上，普通用户不需要改动这个文件。

【注意】每当你修改了这些配置文件，必须重启 hotkeygen 服务才能让改动生效。

第三步：使用 keyboardToPads 将键盘编码器转换为手柄

有些街机控制板是以“键盘”模式工作的，但这在玩某些游戏时并不好用，因为模拟器更希望识别到一个标准的“手柄”。keyboardToPads 就像是一个翻译官，它能把键盘编码器发出的信号实时转换成一个或多个虚拟手柄（Virtual gamepads）。

Batocera 已经为市面上一些常见的键盘编码器预装了配置文件。

如何检查你的设备是否已有现成的配置？
请在终端输入以下命令：
keyboardToPads --search

输入后，你将看到类似下面的搜索结果：

$ keyboardToPads --search
# 这里会列出系统支持的预设列表

识别与自定义你的街机控制器

当你运行查询命令后，系统会显示类似下面的设备信息。这能帮你确认系统是否已经认出了你的硬件，以及你应该在哪里进行“魔改”。

device /dev/input/event3 : "Ultimarc I-PAC 4"
config file name : UltimarcIPAC4.vd209.p0430.yml
system config found at /usr/share/keyboardToPads/inputs/UltimarcIPAC4.vd209.p0430.yml
you can create a custom config at /userdata/system/configs/keyboardToPads/inputs/UltimarcIPAC4.vd209.p0430.yml

配置步骤：定制属于你的映射

第一步：确定文件路径
系统会告诉你当前正在使用的配置文件路径。如果你想进行自定义，不要直接修改系统文件，而是在 /userdata/system/configs/keyboardToPads/inputs/ 目录下创建一个同名的 YAML 格式文件。

第二步：参考范例编写
如果你不知道怎么写，可以参考 /usr/share/keyboardToPads/inputs 里的现成范例。

生活化类比： 这就像是装修样板房。系统自带的配置是“基础装修”，而你在自定义文件夹里创建的文件就是你的“个性化软装”。系统会优先按照你的装修风格（自定义文件）来布置按键。

实例解析：以 Xtension 二人位控制器为例

下面是一个经典的 Rec Room Masters Xtension 2 Player Plus 控制器的配置示例。它将一个键盘编码器拆分成了两个独立的游戏手柄和一个热键控制区：

# Xtension 2 Player Plus 配置文件
target_devices:
- name: Xtension 2P Player 1  # 定义 1 号玩家虚拟手柄
  type: joystick
  mapping:
    "key:up":        "abs:hat0y:-1"  # 键盘上键映射为摇杆上
    "key:down":      "abs:hat0y:1"
    "key:left":      "abs:hat0x:-1"
    "key:right":     "abs:hat0x:1"
    "key:leftshift": "btn:south"     # 键盘 Shift 映射为手柄南键(B)
    "key:enter":     "btn:south"
    "key:z":         "btn:east"
    "key:leftctrl":  "btn:west"
    "key:leftalt":   "btn:north"
    "key:space":     "btn:tl"
    "key:x":         "btn:tr"
    "key:c":         "btn:start"
    "key:1":         "btn:start"
    "key:v":         "btn:select"
    "key:5":         "btn:select"

- name: Xtension 2P Player 2  # 定义 2 号玩家虚拟手柄
  type: joystick
  mapping:
    "key:r": "abs:hat0y:-1"          # 使用不同的按键模拟第二个手柄
    "key:f": "abs:hat0y:1"
    "key:d": "abs:hat0x:-1"
    "key:g": "abs:hat0x:1"
    "key:w": "btn:south"
    "key:i": "btn:east"
    "key:a": "btn:west"
    "key:s": "btn:north"
    "key:q": "btn:tl"
    "key:k": "btn:tr"
    "key:j": "btn:start"
    "key:2": "btn:start"
    "key:1": "btn:select"
    "key:6": "btn:select"

- name: Xtension hotkeys       # 定义专用热键区
  type: hotkeys
  mapping:
    "key:tab": "key:menu"            # 按 Tab 键直接弹出菜单
    "key:p":   "key:pause"           # 按 P 键直接暂停
    "key:esc": "key:exit"            # 按 Esc 键直接退出
    ["key:1", "key:v"]: "key:exit"   # 组合键退出：同时按 1号Player开始 + 2号Player选择

【提示】上述代码中最后的“组合键退出”功能（即同时按下 1 和 v）需要 Batocera v43 或更高版本才支持。

深入理解与进阶配置：打造你的虚拟手柄

通过上一节的 YAML 配置文件示例，我们可以拆解出以下核心信息，帮助你更好地理解系统是如何工作的：

设备拆分：一个真实的物理编码器被“分身”成了 3 个虚拟设备：2 个手柄（Pads）和 1 个专门的热键设备（Hotkey device）。
命名规则：示例中的虚拟手柄名为 Xtension 2P Player 1。在实际操作中，你应该根据自己的手柄型号来重新命名。
设备类型（Type）：配置中定义了设备类型，通常 joystick 代表普通手柄，而 hotkeys 则专门处理快捷键指令。
映射表（Mapping）：这本质上是一张“按键转换表”。它把真实设备发出的每一个键盘信号（Key），翻译成虚拟手柄上的对应动作。

生活化类比： 这就像是找了一个“同声传译”。当街机按钮发出“我按下了键盘 C 键”的信号时，这位翻译官立刻告诉系统：“他按下了 2 号玩家的选择键”。

操作指南：自定义你的控制方案

第一步：确定物理按键名称
如果你不知道手柄上的某个按钮对应键盘的哪个键位，请在终端输入以下命令进行实时检测：
evsieve --input /dev/input/event3 --print
（注：其中的 event3 请根据你设备的实际编号进行修改）

第二步：编写映射逻辑
在 YAML 映射表中，你可以发挥高度的灵活性。比如，你可以将两个或多个物理按键同时指向同一个虚拟手柄按钮。

【提示】根据你的使用场景，你可能还会用到 btn:tl2 和 btn:tr2（即左侧和右侧的第二对触发键/L2 R2）。

第三步：生效配置
【注意】完成文件编写后，你不需要重启整个系统。只需拔掉手柄并重新插入，新的配置就会被系统自动加载。

重要提示与警告

【警告】在为你的虚拟设备命名时，请务必不要在名称中包含“PAC”字样。否则，系统可能会产生冲突，导致配置失效。

【注意】最后一步至关重要！
虽然你已经通过配置文件创建了虚拟手柄，但因为它目前还不在系统的默认数据库中，你必须像设置一个全新的手柄一样，在图形界面中手动完成最后的“身份登记”：
1. 进入 主菜单（Main Menu）
2. 选择 控制器与蓝牙设置（CONTROLLER & BLUETOOTH SETTINGS）
3. 选择 控制器映射（CONTROLLER MAPPING）

如果你跳过这一步，模拟器将无法识别你的手柄，游戏也将无法操作。

keyboardToPads 故障排查与 Ultimarc 控制接口配置

故障排查（Troubleshooting）

如果你在配置转换工具时遇到了麻烦，可以尝试手动运行启动命令来排查错误。

操作步骤：
请打开终端并输入以下命令（注意：请将 event3 替换为你自己设备的实际编号）：
keyboardToPadsLauncher /dev/input/event3 run

关于 Ultimarc 控制接口（Ultimarc Control Interfaces）

Ultimarc 是街机控制器接口的主要品牌，旗下产品包括 I-PAC、J-PAC、A-PAC、Mini-PAC、Opti-PAC、U-HID 等。

核心攻略（太长不看版）：

如果你的编码器是 I-PAC 或 Mini-PAC 的任何型号，且你的街机柜上没有专门的功能按键（如“菜单”、“退出”、“暂停”），请尝试以下操作：
* 第一步： 同时按住对应 [Start1] + [P1SW2] 的按钮。
* 第二步： 保持按住状态 10 秒钟。

如果运气好的话，你的控制器现在已经变身为一个“即插即用（Plug ‘n Play）”的 USB 手柄了！你只需像配置普通手柄一样在 Batocera 里设置一下即可。大功告成，快去享受游戏吧！

深入了解与固件说明

如果上述方法不起作用，或者你想了解更多技术细节，请继续阅读：

生活化类比： 这就像是给你的老旧设备做一次“大脑升级”。升级后，它不再只会像打字机一样发字母（键盘模式），而是学会了像专业运动员一样用手柄信号进行沟通。

关于兼容性：
上述“快捷转换”的方法仅适用于 2015 年之后生产且配备了 50 或更高版本固件（Firmware）的 Ultimarc 编码器。

【注意】非常重要！ * 绝对不要尝试给 2015 年之前生产的老款编码器刷新固件，否则会导致设备“变砖（Brick）”损坏！
* 如果你的板子生产日期足够新，但固件版本较低，可以使用 Ultimarc 官网提供的工具进行升级。

关于“多模式（Multi-Mode）”：
建议阅读官网页面中关于“多模式”的部分。按照上文“快捷转换”操作后，你的控制器将运行在 Mode 2（模式 2） 下。

【提示】在这种模式下，系统不会再把你识别为“USB 键盘”，而是识别为一个或多个 D-input 游戏控制器。这意味着你不再需要执行复杂的键盘转手柄配置，系统认出手柄后一切都会变得简单。

Ultimarc 控制器进阶配置指南

针对不同版本的 Batocera 系统和不同型号的 Ultimarc 编码器，配置方法略有差异。请根据你的实际情况选择以下方案。

针对 Batocera v41 或更高版本

如果你的机柜配有专门的菜单、暂停或退出按钮，或者你的编码器不支持自动切换到手柄模式，那么 keyboardToPads 工具将是你的救星。

第一步：切换至键盘模式
按住 [Start1] + [P1SW1] 组合键，将编码器强制设定为键盘模式。著名的 Rec Room Master 控制器本质上也是基于 Ultimarc 编码器的，所以操作逻辑完全一致。

第二步：查找设备信息
由于不同型号的名称可能不同，你需要通过命令行来确认身份。在终端输入：
keyboardToPads --search
系统会反馈你的设备名称以及所需的配置文件（.yml）名称。

第三步：完成映射
获取名称后，请参考前文提到的 keyboardToPads 教程，编写对应的映射文件即可。

针对 Batocera v40 或更低版本

在旧版系统中，我们主要依靠 Xarcade2jstick 补丁来支持键盘编码器。由于 X-Arcade 设备的按键映射不符合常规 MAME 标准，我们可能需要手动调整。

【提示】如果你的 I-PAC 或 Mini-PAC 处于出厂默认的“键盘模式”，请直接按照以下步骤操作，无需更改编码器内部的按键映射。

配置键盘编码器的具体步骤：

第一步：登录系统
你可以直接在机器上操作，或者通过 SSH 远程连接（Secure Shell） 登录到你的 Batocera 盒子。

第二步：锁定设备身份
我们需要在系统中找到你编码器的“真名”。输入以下命令查看：
ls /dev/input/by-id
通常情况下，键盘设备的名称结尾会带有 kbd 字样。

例如：USB-Ultimarc_IPAC_2_Ultimarc_IPAC_2_9-if01-event-kbd

【注意】请仔细辨别： 一个编码器可能会列出多个相似的名称，你需要逐一尝试。
* 成功案例： USB-Cypress_I-PAC_Arcade_Control_Interface-event-kbd（可用）
* 失败案例： USB-Cypress_I-PAC_Arcade_Control_Interface-if01-event-kbd（不可用）

第三步：解锁系统权限
为了修改系统文件，我们需要把系统分区从“只读”变为“可读写”。请输入：
mount -o remount,rw /

生活化类比： 这就像是给一个带锁的记事本解开密码。平时系统为了安全把记事本锁住了，你只能看不能改；输入这个命令后，你就拿到了修改权，可以往里写新的配置了。

进阶配置：针对 X-Arcade 与 JammASD 控制器

如果你正在使用较旧版本的系统，或者需要手动处理键盘编码器，接下来的步骤将带你完成最后的冲刺。

配置 X-Arcade 驱动适配

当你完成了前文提到的“解锁系统权限”后，请按照以下步骤进行操作：

第一步：创建标识文件
在系统中创建一个与你设备名称完全一致的空文件。
使用命令：touch /usr/share/Batocera/datainit/system/configs/xarcade2jstick/设备名称

操作范例：
touch /usr/share/Batocera/datainit/system/configs/xarcade2jstick/USB-Ultimarc_IPAC_2_Ultimarc_IPAC_2_9-if01-event-kbd

第二步：开启功能开关
编辑配置文件 batocera.conf，确保其中有一行内容为：controllers.xarcade.enabled=1。
（通常系统默认已开启，但最好检查一下，确保开关处于“打开”状态。）

第三步：保存并重启
由于 Batocera 的系统分区结构特殊，你需要运行指令来保存更改：
1. 在终端输入：batocera-save-overlay
2. 待保存完成后，输入：reboot 重启系统。

配置结果：
重启后，你的所有按键（包括每个玩家的 4 方向摇杆、选择、开始、热键，以及 A/B/X/Y、L1/R1）都应该可以正常使用了。
【注意】目前的驱动方案暂不支持 L2/R2、L3/R3 等更多按键。

【提示】最后，你仍需进入系统菜单的“控制器设置”，手动完成一次按键映射，并将对应的控制器分配给玩家 1 和玩家 2。从 Batocera v34 版本开始，系统已原生集成 Ultimarc 支持，配置会更加简便。

使用 JammASD 控制器连接老式街机框体

如果你拥有一台原装的老式街机框体，并希望通过它自带的摇杆和按钮来玩游戏，最简单的方法就是使用 JammASD 控制板（JammASD controller）。

生活化类比： JammASD 就像是一个“多面手翻译”，它不仅能把游戏画面和声音传给街机，还能把街机按键的信号翻译成电脑懂的语言。

目前，Batocera 的主界面（EmulationStation）还不能直接识别这款设备，因为它默认被识别为一套“键盘”。为了让双人对战的配置更简单，我们需要通过“变身术”把它伪装成 X-Arcade 驱动。

JammASD 配置步骤：

第一步：远程登录
通过 SSH 远程连接（Secure Shell） 访问你的 Batocera 系统。

第二步：锁定设备 ID
在终端中输入以下命令来查看 JammASD 的设备识别码：
ls /dev/input/by-id

你会看到类似这样的反馈信息：
USB-ASD_JammASD_Interface_ASD275D-if01-event-kbd

（请记好这个名字，我们在接下来的配置中会用到它。）

JammASD 驱动转换与常见问题排查

接续上文，当我们找到了 JammASD 的设备识别码后，就可以通过以下操作让它完美适配双人模式。

第一步：创建驱动标识文件
在指定目录下创建一个以你设备 ID 命名的空文件。请在终端执行以下命令：
touch /userdata/system/configs/xarcade2jstick/USB-ASD_JammASD_Interface_ASD275D-if01-event-kbd

第二步：重启系统
输入 reboot 重启你的 Batocera。

第三步：配置控制面板
重启后，进入 EmulationStation 的菜单进行按键映射。此时，你的街机面板会被系统识别为 Xarcade-to-Gamepad Device 1 和 Xarcade-to-Gamepad Device 2。

【提示】配置完成后，你还可以实现炫酷的组合键操作：比如同时按下 1号玩家开始键（START P1）+ A键 来为街机游戏增加代币（Credit）。

常见故障排查（Troubleshooting）

【提示】本章节内容及以下部分仍在完善中。

问题 1：Dragonrise 编码器的 1 号和 2 号玩家位置反了

症状： 我使用的是 Dragonrise 编码器，但 1 号玩家和 2 号玩家的输入完全调换了。

原因： 系统识别 USB 端口的顺序与你预想的物理顺序不一致。

解决方法：
* 对于 Batocera v40 及更新版本： 根据反馈，系统已优化此问题，通常不再需要手动修复。
* 物理检查： 首先确保两个编码器的接线完全一致，即每个按钮都连接到 USB 编码器上的相同位置。
* 进阶修复（使用 USB 特性参数）： 如果调整接线也无效，可以通过添加“USB 隔离参数（USB quirk）”来绕过此问题。
* 操作步骤： 在你的启动行（Boot line）末尾添加以下代码。
> 文件位置： 树莓派（Raspberry Pi）用户请查看 /boot/uEnv.txt；x86_64（普通 PC）用户请参考相关启动项说明。

```text
usbhid.quirks=0x0079:0x0006:0x040
```
【注意】必须添加在现有内容的**同一行末尾**，不要另起新行。

**生活化类比：** 这就像是在给快递员的地址后面加了一条备注：“请把一号包裹送到左边，二号送到右边，不要搞混了”。

**修改后的示例：**
`APPEND=label=Batocera rootwait quiet ...省略部分内容... usbhid.quirks=0x0079:0x0006:0x040`

问题 2：我的轨迹球（Trackball）和旋钮（Spinner）有时会失效

（该部分内容正在建设中…）

问题 2：我的轨迹球和旋钮为何有时会失效？

症状： 当你同时将轨迹球（Trackball）和旋钮（Spinner）接入 Batocera 系统时，它们偶尔会在开机后产生“身份错位”。虽然物理连接没变，但系统给它们分配的编号变了，导致它们直接罢工。

原因：
在街机模拟中，轨迹球和旋钮其实是被当作鼠标设备（Mouse devices）来处理的。
问题出在新版 RetroArch 模拟器识别鼠标的方式上：它现在根据“ID”而不是“名称”来认人。由于这个 ID 每次开机都可能随机变化，导致原本设置好的配置（比如“让条码扫描器模拟鼠标”）在下一次启动时就失效了。

生活化类比： 这就像你去餐厅吃饭，服务员原本是按照“姓名”叫号（比如“张三的菜好了”），现在改成了按“座位号”叫号。由于你每次去坐的位置都不固定，服务员就总是把菜送错桌。

解决方法：使用自动修正脚本

目前我们可以通过一个自动化脚本来绕过这个难题。这个脚本的作用是在游戏启动前，自动帮你把“座位号”和“姓名”重新对上。

第一步：创建脚本文件
你需要将以下代码保存到这个路径：/userdata/system/configs/EmulationStation/scripts/game-start/mouse-fix.sh

第二步：赋予运行权限
为了让系统能够运行这个脚本，请在终端执行以下命令：
chmod +x /userdata/system/configs/EmulationStation/scripts/game-start/mouse-fix.sh

脚本代码内容（mouse-fix.sh）：

#!/bin/bash

# 设置你想要使用的鼠标输入设备名称
# 你可以通过 RetroArch 的日志文件或运行 'evtest' 命令来找到它
mouse_name="Combined Analog Arcade Controls"

# 必须开启 RetroArch 的日志记录功能，脚本才能生效
batocera-settings-set global.retroarch.log_dir "/userdata/system/logs/retroarch"
batocera-settings-set global.retroarch.log_to_file true
batocera-settings-set global.retroarch.log_to_file_timestamp false

# 脚本逻辑说明：
# 从上一次的 RetroArch 日志文件中读取鼠标索引值（Index），
# 并自动更新配置，确保下一次运行 RetroArch 时索引是正确的。
# 【提示】由于某些设备名称包含斜杠 "/"，脚本使用了 "~" 作为分隔符。
# 【提示】脚本通过 'head -1' 只获取第一个匹配设备的索引，防止多接口设备造成干扰。

【注意】请确保 mouse_name 变量中的名称与你实际设备的名称完全一致，否则脚本将无法准确找到你的轨迹球或旋钮。

自动修正脚本（续）与鼠标设备启用指南

接上文，脚本的核心逻辑如下，它能自动帮你“找回”丢失的设备索引：

# 从日志中提取匹配设备名称的鼠标索引号
mouse_index=$(sed -En "s~.*Mouse.* #(.*): "$mouse_name".*~\1~p" /userdata/system/logs/RetroArch/RetroArch.log | head -1)

# 如果没找到索引，则默认设为 0
if [ -z "$mouse_index" ]; then
    mouse_index=0
fi

# 将获取到的索引写入 Batocera 配置中
batocera-settings-set global.retroarch.input_player1_mouse_index $mouse_index

第三步：生效脚本
完成脚本配置后，你可能需要连续启动两次游戏才能看到效果。这是因为脚本需要先从第一次运行生成的日志中“学习”当前的设备 ID，然后在第二次启动时才能正确应用它。

持续关注与未来展望

这个鼠标索引（Mouse Index）的问题是由于模拟器底层逻辑变动引起的。如果你想了解最新进展，可以关注以下链接：
* RetroArch 官方问题追踪： GitHub 议题 #7638
* 社区讨论与解决方案原文： Batocera 官方论坛帖子

【提示】未来 Batocera 可能会通过引入 evsieve 工具来简化这一复杂的变通操作，让轨迹球和旋钮的配置变得更加“无感”。

在独立版 MAME 中开启设备

如果你使用的是独立版 MAME（Standalone MAME）而非 RetroArch 核心，它有一套自带的机制来处理旋钮、轨迹球和其他鼠标设备。

操作步骤：
1. 在系统中进入游戏高级选项（ADVANCED GAME OPTIONS）。
2. 将模拟器（Emulator）选定为 MAME。
3. 找到开启鼠标（ENABLE MOUSE）选项，将其设置为开启（ENABLED）。

生活化类比： 这就像是给模拟器装上了一个“雷达”。默认情况下它是关闭的，当你手动打开这个开关后，模拟器才会开始搜索并接收来自轨迹球或旋钮的信号。

原文: DIY街机控制器 • 翻译: DIY8 Bot

文章版权归作者所有，未经允许请勿转载。