Use this guide if you are installing an X-Arcade 3-inch trackball in a Raspberry Pi, Batocera, or arcade cabinet project and are unsure what the extra button labels or connections do.

Useful links:

What the trackball connections do

The X-Arcade 3-inch trackball can provide:

  • Trackball movement.
  • Left mouse click.
  • Right mouse click.
  • Middle mouse click.
  • Horizontal disabler.

The horizontal disabler is not a separate computer command. It is a hardware-level axis lock. When held, it disables left/right movement so the trackball only moves vertically.

Important note about button labels

Some button labels included with arcade parts are generic labels for encoder boards. They may not describe the trackball assembly itself.

For the trackball, think of the button wiring as mouse buttons plus the optional horizontal disabler.

Mouse button mapping on current Tankstick controllers

On current Tankstick with Trackball and Tankstick Max controllers:

  • The red LED button on the top right is mouse middle click, also called mouse M3.
  • The left upper flipper button is mouse left click.
  • The right upper flipper button is mouse right click.

These mouse buttons are not programmable because they are part of the mouse/trackball side of the controller, not the joystick encoder board.

The remaining joystick and push-button controls are programmable in Mode 2 / Programmable Keyboard Mode. Programming only applies to Mode 2. Mode 1, Mode 3, and Mode 4 are not programmable.

For programming steps, use the X-Arcade Programming Guide:

https://support.xgaming.com/support/solutions/articles/12000003090-x-arcade-programming-guide

Current Tankstick with Trackball and Tankstick Max controllers include the latest Tri-Mode PCB and ship with the current firmware installed. There is no newer Tri-Mode PCB firmware available for these units right now, so no firmware update is needed when the controller is purchased.

How to test the trackball before Batocera setup

  1. Connect the trackball to a Windows PC or another computer that supports USB mouse input.
  2. Move the trackball.
  3. Confirm that the mouse cursor moves.
  4. Test left, right, and middle click if you wired those buttons.

If the trackball does not move the cursor on a normal desktop, fix the hardware or wiring first before changing Batocera settings.

If your setup also includes X-Arcade joystick and button controls, test those separately in Mode 1 / Keyboard Mode at https://en.key-test.ru/. The keyboard tester is for joysticks and push buttons; trackball movement should still be tested as normal mouse movement.

Batocera setup

  1. Open the game's advanced settings in Batocera.
  2. Enable Optical Device.
  3. Launch the game.
  4. Open the emulator input menu if the game does not auto-detect the trackball.
  5. Map the trackball movement to the game's trackball, dial, or mouse movement input.
  6. Map a Hot Key button, because Batocera commonly uses Hot Key + Start to exit games.

For games such as Missile Command, map your cabinet buttons to the game's launch/fire points in the emulator settings.

Why does the trackball take a moment to start working?

A short delay can be normal on Linux-based systems while the USB bus detects the device. If the trackball works after a few seconds, that delay alone is usually not a sign of a hardware problem.

Why does left/right movement not work?

Check the horizontal disabler first.

Left/right movement may be disabled if:

  • The horizontal disabler button is being held.
  • A cabinet panel or mounting surface is pressing the disabler.
  • The disabler wiring is shorted.
  • The trackball sensor or reader wheel is loose.

If disconnecting the horizontal disabler wire makes left/right movement return, the disabler switch or wiring is likely the cause.

If the trackball still does not work after these steps

Please include:

  • A photo of the trackball wiring.
  • The system you are using: Raspberry Pi, PC, Batocera version, or other setup.
  • Whether the trackball works as a mouse on a desktop.
  • Whether any connected X-Arcade joysticks or buttons respond at https://en.key-test.ru/.
  • Whether movement is missing on one axis or in all directions.
  • A short video showing the behavior.