Moltengamepad

Table of Contents generated with DocToc

• About
• Use Cases
  • WiiMote
  • Steam controller
  • JoyCon
  • Your own concoction
• How to install
• How to run

About

This page details installation and usage of Moltengamepad on SteamOS

Moltengamepad (MG) is an input remapper that can create virtual input devices that forwards events from one or more source input devices (gamepads). In that sense, it is not unlike Steam's controller mapping.

Moltengamepad currently supports the following physical source input devices:

• WiiMotes (incl. accessories)
• Steam controllers
• JoyCons (rudimentary)
• Any generic input device via custom gendevice mappings

Moltengamepad currently supports mapping events from these source input devices to the following virtual input devices:

• Generic Gamepad
• Xbox controller
• Keyboard

These virtual devices (number configurable) are created as soon as MG starts, so you can connect and disconnect some or all of your physical controllers on the fly. This also means, that there will be virtual input devices present even if you have no physical controller connected as long as MG is running.

The Moltengamepad documentation can be found at https://github.com/jgeumlek/MoltenGamepad

Use Cases

WiiMote

WiiMotes are modular and in reality a bunch of devices with different capabilities connected together. MG handles WiiMotes so that you can connect accessories like the Nunchuck or the Classic Controller on the fly, without the need to restart anything.

By default, a WiiMote (incl. all accessories) shows up as a generic gamepad and works pretty much as expected out of the box. The WiiMote core piece will always be in horizontal input mode. If you connect a Classic Controller, both the core piece and the Classic Controller will react to button presses.

To use a WiiMote you need to first pair it using the normal Bluetooth tools (Steam BPM's Bluetooth pairing tool or Gnome's Bluetooth control panel).

Steam controller

If you want to use your Steam controller to control keyboard/gamepad events just like you can do in Steam; but in a situation where the controller mapping of the Steam client is not available.

By default, a Steam Controller shows up as a generic gamepad and works pretty much like an Xbox controller out of the box. You will of course need the Steam Controller dongle connected in your machine for the Steam Controller to connect.

JoyCon

JoyCon support is rudimentary, but should be somewhat usable to utilise your JoyCon as a generic gamepad.

Your own concoction

You want to build your own "monster controller" from several physical controllers that MG supports. Moltengamepad could combine them together into one virtual "monster controller" to be consumable by games and other software.

To accomplish this, you will need to write a custom mapping profile, check out the documentation at https://github.com/jgeumlek/MoltenGamepad

There is also an MG-Files repo with examples for profiles and gendevice mappings: https://github.com/jgeumlek/MG-Files

How to install

Install the moltengamepad package from the SteamOS Tools brewmaster main repository.

How to run

Run manually

To start moltengamepad, execute this as the steam user:

moltengamepad --daemon --load-plugins --num-gamepads 1

Flags:

• --daemon: runs the process it in the background
• --load-plugins loads controller plugins, when not supplied, no non-generic controllers are detected
• --num-gamepads number of virtual gamepad devices (slots) that are created when MG starts, change this to your needs

Other interesting flags:

• --no-make-keys prevents MG from creating a virtual keyboard device, if you want to map your controllers to keyboard events, leave out this option
• --mimic-xpad expose virtual controllers as Xbox controllers instead of as generic controllers

Run as a systemd service

MG has a systemd service file upstream at: https://github.com/jgeumlek/MoltenGamepad/blob/master/installation/systemuser/systemd.service

However, that one is specific to the system user installation method. The moltengamepad package in the SteamOS-Tools repo is package the simpler single user installation method.

Using this single user installation method, a simpler service file suffices for our use case:

[Unit]
Description=MoltenGamepad
After=network.target
After=bluetooth.target

[Service]
User=steam
Type=forking
ExecStart=/usr/bin/moltengamepad --daemon --load-plugins --num-gamepads 1

[Install]
WantedBy=default.target

To enable this service:

• Put the above into /etc/systemd/system/moltengamepad.service
• Run systemctl daemon-reload to have systemd pick up the new service file
• Run systemctl start moltengamepad to start the service
• Run systemctl enable moltengamepad to enable the service to start automatically on boot

More systemd operations:

• Run systemctl status moltengamepad to check the service status
• Run journalctl -u moltengamepad to show the service's logs
• Run systemctl stop moltengamepad to stop the service

How to configure

Configuration files

The configuration folder of MG is at /etc/xdg/moltengamepad

There's documentation about the configuration files in the MG repo: https://github.com/jgeumlek/MoltenGamepad/tree/master/documentation

Configure what plugins to load

By default, the moltengamepad package in the SteamOS-Tools repo loads all available gamepad drivers. They reside as separate files in the /usr/lib/moltengamepad folder:

example.so
joycon.so
steamcontroller.so
wiimote.so

Depending on your use case, you might want to disable some of these. For example, when you have a WiiMote and a Steam controller connected and run MG with support for both, MG will hide your Steam controller from the Steam client and will instead expose it as a generic gamepad. If you would rather like to have the Steam client handle the Steam controller and MG only handle the WiiMote, you need to disable the Steam controller support in MG.

To control what plugins to load:

• rm /etc/xdg/moltengamepad/plugins to delete the link referring to all available plugins
• ln -s /usr/lib/moltengamepad/wiimote.so /etc/xdg/moltengamepad/plugins/ to link a specific plugin library into the plugin configuration folder (exemplified here by the WiiMote plugin)
• Restart moltengamepad

Known probems

[June 2017] Recent versions of the Steam client have introduced regressions in multi-controller handling. Sometimes generic controllers will hide the Steam controller in games (but not in the Big Picture Mode interface). The nature of MG constantly exposing a generic gamepad to the system can lead to your Steam controller being unavailable to certain games, especially if they do not have multi-gamepad support. To work around this problem if you encounter it, turn off the moltengamepad service to restore normal Stream Controller operation.