Differences

This shows you the differences between two versions of the page.

--- diy-arcade-controls [2026/03/03 02:23] – Revised Ultimarc section superchooch
+++ diy-arcade-controls [2026/05/29 20:55] (current) – [Gallery] nadenislamarre
@@ Line 14: / Line 14: @@
 Since Batocera v41, two tools help address these common cabinet needs:
-  * ''KeyboardToPads'': Converts specific keyboard-style encoders into one or more **virtual controller** devices by remapping input events (so they behave like standard controllers in emulators).
+  * ''keyboardToPads'': Converts specific keyboard-style encoders into one or more **virtual controller** devices by remapping input events (so they behave like standard controllers in emulators).
   * ''Hotkeygen'': Listens for specific **KEY_/BTN_ events** from input devices and triggers Batocera hotkey actions (Menu/Exit/Pause, etc.) by emitting the configured key sequence (or running a command). This makes **dedicated cabinet buttons** work without requiring a separate hotkey button.
@@ Line 29: / Line 29: @@
 {{::homemadecontrollers2.jpg?350|}}
 {{::homemadecontrollers4.png?200|}}
+{{::homemadecontrollers4players.jpg
+?600|}}
 ===== Arcade Cabinet Retailers and License Compliance =====
@@ Line 35: / Line 37: @@
 The following retailers have been reported to respect licensing requirements:
-- https://iconicarcade.com/
+  * https://iconicarcade.com/
-- https://recroommasters.com/
+  * https://recroommasters.com/
 ===== Hotkeys =====
 Contextual hotkeys are the way Batocera maps hotkeys to actions in emulators.
-For each emulator, the emulator hotkeys are referenced and mapped to Batocera hotkeys.  The following is the list of hotkeys they may be help when configuring ''KeyboardToPads'' and ''Hotkeygen'':
+For each emulator, the emulator hotkeys are referenced and mapped to Batocera hotkeys.  The following is the list of hotkeys they may be help when configuring ''keyboardToPads'' and ''hotkeygen'':
@@ Line 68: / Line 70: @@
 | brightness-cycle  | KEY_BRIGHTNESS_CYCLE     |
-==== Using and Configuring Hotkeygen ====
+===== Using and Configuring hotkeygen =====
-Configuring ''Hotkeygen'' will allow you use dedicated cabinet buttons such Menu, Exit, or Pause without having use it in combination with a hotkey.
+Configuring ''hotkeygen'' will allow you use dedicated cabinet buttons such Menu, Exit, or Pause without having use it in combination with a hotkey.
 <WRAP center round tip>
-TIP: Using and configuring ''Hotkeygen'' and ''KeboardToPads'' assumes you know how to access Batocera at the terminal and access and manipulate files.  If you are unfamiliar with how to do this, consult [[access_the_batocera_via_ssh|Access Batocera Via SSH]]
+TIP: Using and configuring ''Hotkeygen'' and ''keyboardToPads'' assumes you know how to access Batocera at the terminal and access and manipulate files.  If you are unfamiliar with how to do this, consult [[access_the_batocera_via_ssh|Access Batocera Via SSH]]
 </WRAP>
@@ Line 136: / Line 138: @@
 You need to restart the hotkeygen service so that any update on these file is taken.
-===== Using keyboadToPads to Convert Keyboard Controllers to Gampads/Controllers  =====
+===== Using keyboardToPads to Convert Keyboard Controllers to Gamepads/Controllers  =====
 Keyboard-style input isn’t always ideal for emulation, because some systems and configurations expect a gamepad/controller device.  ''keyboardToPads'' can convert these keyboard encoders to one or more virtual gamepads/controllers.
@@ Line 157: / Line 159: @@
 There are some file samples in ''/usr/share/keyboardToPads/inputs''.
-Example :
+Here is an example of a Rec Room Masters Xtension 2 Player Plus controller:
   # Xtension 2 Player Plus
@@ Line 205: / Line 207: @@
         ["key:c", "key:space"]: "key:1" # player 2 select from combination player 1 start+tl, require batocera 43
-In that example, the controller is split into 3 virtual devices: 2 pads and 1 hotkey device.
+Using the example above, we can determine the following information:
+  * The controller is split into 3 virtual devices: 2 pads and 1 hotkey device.
+  * The ''name'' of the first virtual pad is ''Xtension 2P Player 1''. Rename Xtension 2P Player 1 & 2 to the name of your controller.
+  * Its ''type'' is "joystick". Possible types are "joystick" for pads, and "hotkeys" for hotkeys.
+  * ''mapping'' is a key-value association table to convert each key from the real device into the virtual pad.  You can assign two or more physical keys to a single pad button.
 <WRAP center round important>
@@ Line 234: / Line 240: @@
-==== Troubleshooting keboardToPads  ====
+==== Troubleshooting keyboardToPads  ====
 In case of error, you can try to run this command (with the event number corresponding to your setup):
@@ Line 245: / Line 251: @@
-Ultimarc is major brand of [interface controllers](https://www.ultimarc.com/control-interfaces/) including I-PAC, J-PAC, A-PAC, Mini-PAC, Opti-PAC, U-HID and more.
+Ultimarc is major brand of [[https://www.ultimarc.com/control-interfaces/|interface controllers]] including I-PAC, J-PAC, A-PAC, Mini-PAC, Opti-PAC, U-HID and more.
 <WRAP center round tip>
-TL;DR: If your encoder is any model of I-PAC or Mini-PAC and your build doesn't have any dedicated buttons (Menu, Exit, Pause) press and hold the buttons corresponding to `[Start1]+[P1SW2]` for ten seconds. If you're lucky, your controller is now a plug 'n play USB controller you can [[https://wiki.batocera.org/configure_a_controller|configure like any other controller]] in batocera. That's it. You're done. Go play some games! 8-)
+TL;DR: If your encoder is any model of I-PAC or Mini-PAC and your build doesn't have any dedicated buttons (e.g. Menu, Exit, Pause), press and hold the buttons corresponding to ''[Start1]+[P1SW2]'' for ten seconds. If you're lucky, your controller is now a plug 'n play USB controller you can [[https://wiki.batocera.org/configure_a_controller|configure like any other controller]] in batocera. That's it. You're done. Go play some games! 8-)
 </WRAP>
@@ Line 261: / Line 267: @@
 </WRAP>
-If you are using Batocera 41 or greater and your Ultimarc encoder with dedicated buttons (Menu, Pause, Exit), it doesn't offer this functionality, or you don't want to upgrade the firmware see [keyboardToPads]().  The Rec Room Master Controllers discussed in that section are based on Ultimarc encoders. If you set them to keyboard mode, (`[Start1]+[P1SW1]`) you can configure the encoder in the same way as a Rec Room Master controller.  It might wind up having a different name and require its own yml config file.  You can use the command  `keyboardToPads --search` to find out the name and the required config file name and then follow the remaining instructions.
+If you are using Batocera 41 or greater and your Ultimarc encoder has dedicated buttons (e.g. Menu, Pause, Exit), it doesn't offer this functionality, or you don't want to upgrade the firmware see [[#Using_keyboardToPads_to_Convert_Keyboard_Controllers_to_Gamepads/Controllers|keyboardToPads]].  The Rec Room Master Controllers discussed in that section are based on Ultimarc encoders. If you set them to keyboard mode, (`[Start1]+[P1SW1]`) you can configure the encoder in the same way as a Rec Room Master controller.  It might wind up having a different name and require its own yml config file.  You can use the command  `keyboardToPads --search` to find out the name and the required config file name and then follow the remaining instructions.
 ==== Ultimarc Control Interfaces for Batocera v40 or Less ====
@@ Line 273: / Line 279: @@
 Follow these steps :
-- login to your Batocera box locally or through SSH
+  * login to your Batocera box locally or through SSH
-- find your encoder's device name with `ls /dev/input/by-id`. Usually, there is a trailing kbd in the event name. For example : `usb-Ultimarc_IPAC_2_Ultimarc_IPAC_2_9-if01-event-kbd`
+  * find your encoder's device name with ''ls /dev/input/by-id''. Usually, there is a trailing kbd in the event name. For example : ''usb-Ultimarc_IPAC_2_Ultimarc_IPAC_2_9-if01-event-kbd''
 **PLEASE NOTE:** a single encoder can have multiple possible names, so try all of them
-For example: `usb-Cypress_I-PAC_Arcade_Control_Interface-event-kbd` → works
+For example: ''usb-Cypress_I-PAC_Arcade_Control_Interface-event-kbd'' → works
-`usb-Cypress_I-PAC_Arcade_Control_Interface-if01-event-kbd` → doesn't work
+''usb-Cypress_I-PAC_Arcade_Control_Interface-if01-event-kbd'' → doesn't work
-- Now remount / as read-write `mount -o remount,rw /`
+  *  Now remount / as read-write ''mount -o remount,rw /''
-- Create an empty file that has the same name of your keyboard device found 2 steps above `touch /usr/share/batocera/datainit/system/configs/xarcade2jstick/devicename`. With the previous example : `touch /usr/share/batocera/datainit/system/configs/xarcade2jstick/usb-Ultimarc_IPAC_2_Ultimarc_IPAC_2_9-if01-event-kbd`
+  * Create an empty file that has the same name of your keyboard device found 2 steps above ''touch /usr/share/batocera/datainit/system/configs/xarcade2jstick/devicename''. With the previous example : ''touch /usr/share/batocera/datainit/system/configs/xarcade2jstick/usb-Ultimarc_IPAC_2_Ultimarc_IPAC_2_9-if01-event-kbd''
-- Edit `batocera.conf` and set `controllers.xarcade.enabled=1` (it should already be set by default but check it)
+  * Edit ''batocera.conf'' and set ''controllers.xarcade.enabled=1'' (it should already be set by default but check it)
-- Save your modifications through SSH `batocera-save-overlay`
+  * Save your modifications through SSH ''batocera-save-overlay''
-- Reboot by typing `reboot`
+  * Reboot by typing ''reboot''
 Now all your keys should be usable, that is for each player : 4 directions joystick, select, start, hotkey, A, B, X, Y, L1 and R1.
@@ Line 291: / Line 297: @@
 You must now configure both the controllers in the Controller Configuration menu and also associate the right controller to player 1 and 2.
-Since Batocera **v34**, [Ultimarc](https://github.com/katie-snow/Ultimarc-linux) has been included. [Read more here.](https://github.com/katie-snow/Ultimarc-linux/blob/master/README.cfg)
+Since Batocera **v34**, [[https://github.com/katie-snow/Ultimarc-linux|Ultimarc]] has been included. [[https://github.com/katie-snow/Ultimarc-linux/blob/master/README.cfg|Read more here.]]
@@ Line 325: / Line 331: @@
 <code>Note: With this tip, it's possible now to have START P1 + A to credit your arcade games ^^</code>
-===== Ultimarc =====
-This instructions are for Batocera 5.24 or later, they are dedicated to [[https://www.ultimarc.com/control-interfaces/|Ultimarc's line of control interfaces]] (including I-PAC, J-PAC, A-PAC, Mini-PAC, Opti-PAC, U-HID and more) and X-Arcade USB Controllers.
+===== Troubleshooting =====
-<WRAP center round tip>
+The entire article is under construction but this part is //especially// under construction.
-TL;DR: If your encoder is any model of I-PAC or Mini-PAC, press and hold the buttons corresponding to Start1+P1SW2 for ten seconds. If you're lucky, your controller is now a plug 'n play USB controller you can [[configure_a_controller|configure like any other controller]] in batocera. That's it. You're done. Go play some games 8-)
-</WRAP>
-If nothing happens or you want to know more, keep reading.
+Quick index:
+  * [[#Issue_1:_Dragonrise_encoders_Player_1_and_Player_2_swapped|Dragonrise encoders Player 1 and Player 2 swapped]]
+  * [[#Issue_2:_I_have_a_trackball_and_spinner_and_sometimes_they_stop_working|I have a trackball and spinner and sometimes they stop working]]
-<WRAP center round info>
-The above will only work with Ultimarc's encoders (they call them control interfaces) made from 2015 on and equipped with Firmware version 50 or higher. You can check what you have with the software they offer [[https://www.ultimarc.com/control-interfaces/i-pacs/i-pac2/|on their website]]. **This is important as flashing your pre-2015 encoder with the new firmware will brick it!** If your board is new enough, but your firmware isn't, you can update with the same tool. Read the information on their page under **"Multi-Mode"** to learn about the different modes and what you can do with them. The instructions above will make your controller run in Mode 2, which should be fine for most users. What this means is that instead or being recognised as a USB keyboard, your controller will now be recognized as a D-input game controller and you won't need to do any of the steps below.
-</WRAP>
-If your Ultimarc encoder doesn't offer this functionality, you don't want to upgrade the firmware or you are using an X-Arcade controller, read on.
+----
-Xarcade2jstick has been patched to support keyboard encoders. You may have to reconfigure a few keys of your encoder as, sadly, x-gaming X-Arcade devices didn't map as usual mame controllers.
+===== Issue 1: Dragonrise encoders Player 1 and Player 2 swapped =====
-Do not change the key mappings of your I-PAC or Mini-PAC as it is unnecessary, but the following procedure only applies if your encoder is in keyboard mode, which is the default mode when they leave the factory.
+**Symptoms:** I use Dragonrise encoders and player 1 and player 2’s inputs are swapped
-**Configuring your keyboard encoder**
+**Cause:** - <What’s actually happening>
-Follow these steps :
-  * login to your Batocera box locally or through SSH
-  * find your encoder's device name with ''ls /dev/input/by-id''. Usually, there is a trailing kbd in the event name. For example : ''usb-Ultimarc_IPAC_2_Ultimarc_IPAC_2_9-if01-event-kbd''
-**PLEASE NOTE:** a single encoder can have multiple possible names, so try all of them\\
-For exemple:
-''usb-Cypress_I-PAC_Arcade_Control_Interface-event-kbd'' -> works\\
-''usb-Cypress_I-PAC_Arcade_Control_Interface-if01-event-kbd'' -> doesn't work
-  * Now remount / as read-write ''mount -o remount,rw /''
-  * Create an empty file that has the same name of your keyboard device found 2 steps above ''touch /usr/share/batocera/datainit/system/configs/xarcade2jstick/devicename''. With the previous example : ''touch /usr/share/batocera/datainit/system/configs/xarcade2jstick/usb-Ultimarc_IPAC_2_Ultimarc_IPAC_2_9-if01-event-kbd''
-  * Edit ''batocera.conf'' and set ''controllers.xarcade.enabled=1'' (it should already be set by default but check it)
-  * Save your modifications through SSH ''batocera-save-overlay''
-  * Reboot by typing ''reboot''
-Now all your keys should be usable, that is for each player : 4 directions joystick, select, start, hotkey, A, B, X, Y, L1 and R1.\\ For now it is not possible to attribute more buttons like L2, R2, L3 or R3
-You must now configure both the controllers in the Controller Configuration menu and also associate the right controller to player 1 and 2.
-Since Batocera **v34**, [[https://github.com/katie-snow/Ultimarc-linux|Ultimarc]] has been included. [[https://github.com/katie-snow/Ultimarc-linux/blob/master/README.cfg|Read more here.]]
-===== Troubleshooting =====
-<WRAP center round todo>
-The entire article is under construction but this part is //especially// under construction.
-</WRAP>
-==== I use Dragonrise encoders and player 1 and player 2's inputs are swapped ====
+**Fix:**
 For Batocera 40 and newer, the fix has been reported as not being necessary any longer, but this was an issue in previous versions.
@@ Line 380: / Line 355: @@
 Make sure they are all wired exactly the same, each button going to the same USB encoder.
-If that's not working or is impossible to do due to your setup's requirements, it's possible to work around by using a USB quirk. Add the following onto the end of your boot line (on Raspberry Pi images, this is at ''/boot/uEnv.txt'', x86_64 users can refer to [[:troubleshooting#boot_issues|here]]):
+If that’s not working or is impossible to do due to your setup’s requirements, it’s possible to work around by using a USB quirk. Add the following onto the end of your boot line (on Raspberry Pi images, this is at ''%%/boot/uEnv.txt%%'', x86_64 users can refer to [[https://wiki.batocera.org/troubleshooting#boot_issues|here]]):
 <code>
@@ Line 386: / Line 361: @@
 </code>
-It's added onto the end of the line, not on a new line. For instance, your boot line might end up looking like this:
+It’s added onto the end of the line, not on a new line. For instance, your boot line might end up looking like this:
 <code>
@@ Line 392: / Line 367: @@
 </code>
-==== I have a two devices that are recognized as mice and I have to reconfigure them every launch ====
+**Notes** -
+----
+===== Issue 2: I have a trackball and spinner and sometimes they stop working =====
+**Symptoms:** When you have both trackball and spinner plugged into Batocera, they may occasionally be read in a different than the last time the devices was booted and, as a result, they will be assigned a different ''%%Index%%'' number and stop working.
+**Cause:**
 Arcade trackballs and spinners are handled as mouse devices.
 The problem comes from the way newer versions of RetroArch recognize mouse devices, by ID instead of name. The ID that they can have is thus unpredictable, resulting in configs (such as ''%%retroarchConfig[‘input_player1_mouse_index’] = “Barcode Reader Mouse”%%'') no longer working.
+**Fix:**
 For now, this can be worked around using a script to automatically log and change the ID as appropriate. Save it to ''/userdata/system/configs/emulationstation/scripts/game-start/mouse-fix.sh'' and mark it as executable with ''chmod +x /userdata/system/configs/emulationstation/scripts/game-start/mouse-fix.sh'':
@@ Line 422: / Line 408: @@
 batocera-settings-set global.retroarch.input_player1_mouse_index $mouse_index
 </file>
 You may need to launch a game twice in order for it to have an effect.
@@ Line 427: / Line 414: @@
 Keep updated by watching this space: [[https://github.com/libretro/RetroArch/issues/7638]]. Original forum post describing this issue and its workaround: [[https://forum.batocera.org/d/6652-being-able-to-use-trackball-and-spinner-using-per-mouse-index]]
-Batocera may make the workaround process easier in the future by the inclusion of ''evsieve''.
+Batocera may make the workaround process easier in the future by the inclusion of ''%%evsieve%%''.
 <WRAP center round tip 100%>
-Standalone MAME has its own mechanism for enabling spinner, trackball, and other mouse devices.  In **ADVANCED GAME OPTIONS**, select **MAME** as the emulator, then choose **ENABLE MOUSE** > **ENABLED**.
+Standalone MAME has its own mechanism for enabling spinner, trackball, and other mouse devices. In **ADVANCED GAME OPTIONS**, select **MAME** as the emulator, then choose **ENABLE MOUSE** > **ENABLED**.
 </WRAP>