Configure a Linux-supported Gamepad

Configuring a gamepad input controller allows you to use a Linux-supported gamepad as a device to communicate with your machine. Linux supports most standard gamepads, such as PlayStation or Xbox type game controllers, as well as many joysticks, racing wheels, and more.

To be able to test your gamepad as you configure it, physically connect your gamepad to your machine’s computer and turn both on. Then, configure the controller:

Navigate to the CONFIGURE tab of your machine’s page in the Viam app. Click the + icon next to your machine part in the left-hand menu and select Component. Select the input_controller type, then select the gamepad model. Enter a name or use the suggested name for your input controller and click Create.

An example configuration for a linux-based gamepad input controller component in the Viam App config builder

Edit the attributes as applicable to your input controller, according to the table below.

{
  "components": [
    {
      "name":  "<your-gamepad-input-controller>",
      "model": "gamepad",
      "type": "input_controller",
      "namespace": "rdk",
      "attributes": {
        "dev_file": "<string>",
        "auto_reconnect": <boolean>
      }
    }
  ]
}

The following attributes are available for gamepad input controllers:

NameTypeRequired?Description
dev_filestringOptionalIf dev_file is left blank or not included, viam-server will search and use the first gamepad it finds that’s connected to the computer controlling your machine. If you want to specify a device, give the absolute path to the input device event file. For example: /dev/input/event42.
auto_reconnectbooleanOptionalApplies to both remote (gRPC) and local (bluetooth or direct USB connected) devices. If set to true, viam-server tries to (re)connect the device automatically. It waits for a device to connect during a machine’s start-up. If set to false (default) then start-up fails if a device is not already connected.

Test the input controller

After you configure your input controller, open the input controller’s TEST panel on the CONFIGURE or CONTROL tabs. View the current value of each input on your controller.

The input controller component in the test panel of the Viam app.

Work in progress models

Mappings are currently available for a wired XBox 360 controller, and wireless XBox Series X|S, along with the 8bitdo Pro 2 bluetooth gamepad (which works great with the Raspberry Pi).

The XBox controllers emulate an XBox 360 gamepad when in wired mode, as does the 8bitdo.

Because of that, any unknown gamepad is mapped as an XBox 360.

If you have another controller that you want to use to control your machine, feel free to submit a PR on GitHub with new mappings.

Troubleshooting

If your input controller is not working as expected, follow these steps:

  1. Check your machine logs on the LOGS tab to check for errors.
  2. Review this input controller model’s documentation to ensure you have configured all required attributes.
  3. Click on the TEST panel on the CONFIGURE or CONTROL tab and test if you can use the input controller there.

If none of these steps work, reach out to us on the Community Discord and we will be happy to help.

Not able to see a dropdown menu?
If you are not able to see a dropdown menu with the name of your controller appear in the CONTROL tab, try specifying the dev_file attribute to match the exact path to your device. You can also try setting auto_reconnect to True.

Next steps

For more configuration and usage info, see:

Input controller API

Give commands to register callbacks for events, allowing you to use input devices to control your machines.

Configure a machine

Create a machine in a few steps using Viam's modular system of components and services without writing much or any code.

Drive a Rover with a Gamepad

Drive a wheeled rover with a Bluetooth gamepad that has a dongle.

Have questions, or want to meet other people working on robots? Join our Community Discord.

If you notice any issues with the documentation, feel free to file an issue or edit this file.