Home

Awesome

ControllerBuddy

<!--suppress HtmlDeprecatedAttribute --> <img src="icon.svg" alt="ControllerBuddy Logo" align="right" width="128px"/>

ControllerBuddy Release Status

Visit the ControllerBuddy Homepage to get started.
For more support, join the ControllerBuddy Discord.

Description

ControllerBuddy is an advanced gamepad mapping software that supports the creation of input profiles for complex target applications such as flight simulators.

In addition to the simple mapping of buttons and axes of a physical game controller to keyboard and mouse input, ControllerBuddy also supports feeding input commands to a virtual joystick device (vJoy / uinput).

The goal of ControllerBuddy is to allow the user to control target applications exclusively with a gamepad without ever having to reach for a keyboard or mouse.

Download and Installation

Tip: Check out the ControllerBuddy-Install-Script, it automates all the steps below and much more!

Windows x86-64

  1. First download and install vJoy on your system.
  2. Click here and download the latest build of ControllerBuddy for Windows as a ZIP archive.
  3. Extract the ControllerBuddy directory from the archive to any desired location on your hard-drive.
  4. Run ControllerBuddy.exe inside the extracted ControllerBuddy directory.

Linux x86-64

  1. First, make sure you have libsdl2 installed on your system:
    • Debian / Ubuntu: sudo apt-get install libsdl2-2.0
    • Red-Hat-based: sudo yum install SDL2
    • Arch Linux: sudo pacman -S sdl2
    • SUSE Linux: sudo zypper install SDL2
  2. Configure uinput and hidraw:
    1. Create an uinput group: sudo groupadd -f uinput
    2. Add yourself to the group: sudo gpasswd -a "$USER" uinput
    3. As root, create a file /etc/udev/rules.d/99-input.rules with the following content:
      KERNEL=="uinput", SUBSYSTEM=="misc", MODE="0660", GROUP="uinput"
      KERNEL=="hidraw*", SUBSYSTEM=="hidraw", ATTRS{idVendor}=="054c", ATTRS{idProduct}=="05c4", MODE="0666"
      KERNEL=="hidraw*", SUBSYSTEM=="hidraw", ATTRS{idVendor}=="054c", ATTRS{idProduct}=="09cc", MODE="0666"
      KERNEL=="hidraw*", SUBSYSTEM=="hidraw", ATTRS{idVendor}=="054c", ATTRS{idProduct}=="0ba0", MODE="0666"
      KERNEL=="hidraw*", SUBSYSTEM=="hidraw", ATTRS{idVendor}=="054c", ATTRS{idProduct}=="0ce6", MODE="0666"
      
    4. As root, create a file /etc/modules-load.d/uinput.conf with the following content:
      uinput
  3. Reboot
  4. Click here and download the latest build of ControllerBuddy for Linux as a TGZ archive.
  5. Extract the ControllerBuddy directory from the archive to any desired location on your hard-drive.
  6. Run ControllerBuddy inside the extracted ControllerBuddy/bin directory.

Features

Profiles

Profiles are used to configure your gamepad for a specific target application.
The general structure of a profile is as follows:

Profile (.json file)
├── Default Mode
│   ├── X Axis
│   │   ├── some Action
│   │   └── another Action
│   ├── Y Axis
│   │   └── some Action
│   ├── A Button
│   │   ├── some Action
│   │   └── another Action
│   ├── B Button
│   │   └── Switch Mode Action (switches to 'Another Mode' and back)
│   ├── X Button
│   │   └── Switch Mode Action (switches to 'Yet another Mode' and back)
│   └── Y Button
│       └── Cycle Action (performs 'Action 1', when pressed again 'Action 2', then 'Action 3', then starts over)
│           ├── Action 1
│           ├── Action 2
│           └── Action 3
├── Another Mode
│   ├── X Axis
│   │   └── some Action
│   └── A Button
│       └── some Action
└── Yet another Mode
    └── X Axis
        └── some Action

When switching from one Mode to another, all the axes and buttons that are not used by the other mode retain their function from the previous mode. This works across multiple levels of modes.

Mode switching can be configured to work in two different ways:

The ControllerBuddy-Profiles repository contains a number of well-thought-out profiles for many different flight simulators.

Architecture

Local mode:

            Local:

     Physical Controller
              |
              |
              v
       ControllerBuddy
              |
              |
              v
    vJoy + Win32 / uinput
              |
              |
              v
      Target Application

Server-Client mode:

             Server:                                 Client:

       Physical Controller
                |
                |
                v                  UDP
         ControllerBuddy  -------------------->  ControllerBuddy
                                                        |
                                                        |
                                                        v
                                              vJoy + Win32 / uinput
                                                        |
                                                        |
                                                        v
                                                Target Application

Screenshots

Modes Tab

Assignments Tab

Component Editor - Button

Component Editor - Axis

Dark Mode

Visualization Tab

Overlay

VR Overlay

Command Line Parameters

ParameterArgumentsDescriptionAvailable for scripting
-autostartlocal / client / serverstarts the specified mode of operation after launchyes
-exportfile destinationexports a visualization of the current profile to the specified pathyes
-helpprints the help and exitsno
-profilefile sourceloads the specified profile after launchyes
-gamecontrollerdbfile sourceadds the SDL controller mappings from the specified fileyes
-quitquits the applicationyes
-savefile destinationsave the current profile to the specified pathyes
-skipMessageDialogsskips all message dialogsno
-traylaunches the application in the system trayyes
-versionprints the version information and exitsno

If one instance of ControllerBuddy is already running, starting a second instance with the parameters marked as "available for scripting" will trigger the corresponding action in the first instance and shut down the second instance immediately.

This can be used to integrate ControllerBuddy into third party applications.
For more information see ControllerBuddy-DCS-Integration, an exemplary integration of ControllerBuddy into DCS World.

Attribution

ControllerBuddy makes use of these awesome software technologies and libraries:

Building

If you want to build ControllerBuddy from source, this section might be helpful to get you started.
ControllerBuddy uses the Gradle build system, the following Gradle tasks are supported:

TaskCommand
Generate version source filegradlew generateVersion
Run SpotBugs and Spotlessgradlew check
Apply Spotless formattinggradlew spotlessApply
Run ControllerBuddygradlew run
Install a jpackage imagegradlew installDist
Create a ZIP-compressed jpackage imagegradlew distZip
Create a TGZ-compressed jpackage imagegradlew distTar
Delete build and gen directoriesgradlew clean

License

GNU General Public License v3.0