Xbox Linux Utility (XLU)

A powerful Java 21 utility for Linux that gives you control over your Xbox Series X/S controller's LED brightness while maintaining full input functionality.

The Problem & Solution

The standard Linux kernel driver (xpad) resets the controller's LED brightness every time it initializes. This makes it impossible to simply "set it and forget it." XLU solves this by acting as a userspace driver replacement.

When running in Service Mode, XLU:

1. Detaches the kernel driver (xpad).
2. Sets your desired LED brightness (which persists because xpad is gone).
3. Creates a virtual Xbox controller (via uinput) so your games and OS still receive all button presses and joystick movements.
4. Restores the original driver automatically when you exit.

Prerequisites

• Java 21 (JDK 21+)
• Maven (3.6.3+)
• Root Privileges (Required for --service mode to create virtual input devices).

Installation & Build

1. Clone the repository:

   git clone https://github.com/your-repo/XboxLinuxUtility.git
   cd XboxLinuxUtility

2. Build with Maven:

   mvn clean package -DskipTests

   This generates an executable JAR in the target/ directory: xbox-linux-utility-1.0-SNAPSHOT-jar-with-dependencies.jar.

Usage

Service Mode (Recommended)

This mode sets the brightness and keeps the utility running as a driver, ensuring inputs continue to work.

sudo java -jar target/xbox-linux-utility-1.0-SNAPSHOT-jar-with-dependencies.jar --service --brightness 10

• --service: Activates the driver emulation.
• --brightness <0-100>: Sets the LED brightness percentage.

To stop, simply press Ctrl+C. The utility will attempt to hand the device back to the standard kernel driver automatically.

Test Modes (Debugging)

XLU includes several test modes to verify system compatibility:

• Virtual Device Test: Checks if uinput is accessible and can create a joystick.

  sudo java -jar ... --test-virtual

• Raw Input Test: Reads raw USB data from the controller (requires xpad detach).

  sudo java -jar ... --test-inputs

• JNA Test: Verifies native library loading.

  java -jar ... --test-jna

Architecture

See ARCHITECTURE.md and PROJECT_GUIDE.md for a deep dive into how the code works.

Troubleshooting

• "Pipe is still busy": This can happen on exit. The utility includes logic to forcefully abort connections, but if it persists, simply unplug and replug the controller.
• "Permission Denied": Service mode requires access to /dev/uinput and raw USB devices. Always run with sudo.
• Input Latency: The Java userspace loop runs at high frequency, but is theoretically slower than a kernel driver. In practice, it is indistinguishable for most users.