ultimatecontroller

Open source Linux tool for configuring 8BitDo Ultimate controllers. Provides full feature parity with the official Windows/Android apps — profile management, button remapping, stick/trigger tuning, macros, and more.

The protocol was reverse-engineered from the official 8BitDo Ultimate Software (Windows) and Android app. See docs/protocol.md for the full protocol documentation.

Features

• Read/write controller configuration — all 3 profile slots
• Button remapping — remap any of 20 buttons including back paddles (P1/P2), with turbo toggle
• Stick deadzone/range — per-stick inner deadzone and outer range with validation
• Trigger range — per-trigger start/end range
• Rumble intensity — per-motor intensity with test rumble button
• Macro editor — 4 macros per profile, up to 18 steps each
• Special features — stick inversion, stick/trigger swap, 4-way mode
• Gamepad mode — switch between XInput, Switch Pro, DirectInput, Mac
• Profile management — rename, copy between slots, set active profile
• Stick calibration — center-point calibration
• Xbox mode switching — automatic xpad driver handling and config mode switch
• BLE connection — Bluetooth Low Energy support (optional feature)

Supported Controllers

Controller	USB	BLE	Notes
Ultimate 2.4G	Yes	—
Ultimate BT	Yes	Yes	Bluetooth + USB
Ultimate PC	Yes	—	Wired USB
Pro2	Yes	Experimental

Other 8BitDo controllers with the config protocol may also work.

Building

CLI only

cargo build --release

GUI

cargo build --release --features gui

GUI + BLE

cargo build --release --features gui,ble

Setup

udev rules (non-root access)

sudo cp udev/99-8bitdo.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules

Then replug the controller. Without this, you'll need to run as root.

xpad driver

The xpad kernel driver is handled automatically. The tool detaches xpad from the specific device via detach_kernel_driver — no rmmod required.

Usage

CLI

# Detect connected controllers
ultimatecontroller detect

# Read config and display summary
ultimatecontroller read

# Read config and save as JSON
ultimatecontroller read --output config.json

# Write config from JSON
ultimatecontroller write config.json

# Show firmware version
ultimatecontroller version

# Hex dump of raw config
ultimatecontroller dump

# Any command works over BLE with the --ble flag (requires ble feature)
ultimatecontroller --ble read
ultimatecontroller --ble read --output config.json
ultimatecontroller --ble write config.json
ultimatecontroller --ble dump

GUI

ultimatecontroller-gui

The GUI auto-connects on launch. Use RUST_LOG=debug for verbose logging:

RUST_LOG=debug ultimatecontroller-gui

Firmware Downloads

A Python script can download firmware from the official 8BitDo server:

# List all device types
python3 scripts/download_firmware.py --list

# Download firmware for Ultimate 2.4G
python3 scripts/download_firmware.py --type 43

# Download all firmware
python3 scripts/download_firmware.py

Note: Firmware files are Jieli SoC encrypted and cannot be flashed by this tool. Use the official 8BitDo Firmware Updater.

Project Structure

src/
  bin/
    cli.rs              CLI entry point (clap)
    gui.rs              GUI entry point (eframe)
  protocol/
    structs.rs          ControllerConfig and data types (1652-byte config)
    commands.rs         High-level protocol commands (read/write/calibrate/rumble)
    hid.rs              HID packet construction and parsing
    constants.rs        PIDs, button bitmasks, command IDs
    crc.rs              CRC-16/KERMIT
  devices/
    detection.rs        Device enumeration and mode switching (CLI)
    usb.rs              Shared USB operations (HID scan, Xbox switch, xpad)
    ble.rs              BLE transport (btleplug, optional)
  gui/
    mod.rs              App struct, eframe impl, status handling
    state.rs            AppState, ConnectionState, dirty tracking
    device_thread.rs    Background thread for device I/O
    panels/
      top_bar.rs        Connection status, read/write/revert buttons
      sidebar.rs        Profiles, gamepad mode, profile copy
      sticks.rs         Stick deadzone sliders + calibration
      triggers.rs       Trigger range sliders
      rumble.rs         Motor intensity sliders + test button
      special.rs        Special feature toggles (invert, swap, etc.)
      mapping.rs        Button remapping table with turbo
      macros.rs         Macro editor (4 slots, 18 steps)
      buttons.rs        Shared button definitions and lookup
docs/
  protocol.md           Full protocol documentation
scripts/
  download_firmware.py  Firmware download tool
udev/
  99-8bitdo.rules       udev rules for non-root access

License

MIT