---
myst:
  html_meta:
    "description lang=en": "Kasm Workspaces Gamepad pass-through setup and usage. Use a real Gamepad from any Web Browser on a Kasm Workspace."
    "keywords": "Kasm, Gamepad, Game-pad,Controller, Joystick, Setup"
    "property=og:locale": "en_US"
---
```{title} Gamepad Pass-through
```

# Gamepad Pass-through

Workspaces supports passing through up to 4 gamepads into the Kasm sessions. Participants in shared sessions may
also pass through gamepads.


```{raw} html
<div class='embed-container'>
   <iframe src='https://5856039.fs1.hubspotusercontent-na1.net/hubfs/5856039/docs_resources/videos/Gamepad-Demo.mp4' frameborder='0' allowfullscreen></iframe>
</div>
</br>
```


## Configuration
To enable this feature:

1. Set the `allow_kasm_gamepad` {doc}`Group Setting <groups>` to `true` prior to launching the session.

2. Launch a Kasm session.

    ```{tip}
       The `kasmweb/ubuntu-focal-desktop` and `kasmweb/ubuntu-jammy-desktop` images have several gamepad
       testing utilities included that may help with troubleshooting. The `:develop` tag or versioned tags
       \>= to `:1.12.0` may be used.
       
       - Use `jstest-gtk` to test the `udev` interface.
       
       - Use `gamepadtool` to test the `sdl2` interface. Available on amd64 images only.
    ```
    
    
3. Open the control panel on the left side of the session, and select **Gamepads**.

4. Press any button on the connected Bluetooth or USB gamepad(s). If the browser detects the gamepad(s), an entry will
   be listed for each device. A dropdown will be visible next to each device representing the virtual device port/index
   ( 0 - 3 ) mapped within the session. These can be changed as desired.
    
    
    ```{figure} /images/gamepad/new_connection.webp
    :align: center
    **Gamepad Connection**
    ```

    ```{tip}
     Gamepads may not be visible if they are in use by another program, browser, or tab. It may be necessary
     to close those programs then re-open the current browser. It may be helpful to verify the gamepads can be seen
     using other [browser-based gamepad testing utilities](https://greggman.github.io/html5-gamepad-test)
    ```

## More Details

This feature works by connecting to the local USB or Bluetooth gamepads via the browser's GamepadAPI, then passing the
gamepad events (button presses) into virtual devices mapped inside the container. The virtual gamepads should be
accessible by programs within the session container supporting `udev` or `sdl2` interfaces.

A default `sld2` mapping environment variable is defined within the  Workspaces Images and may be overridden if desired
either by creating a {doc}`Custom Image <../how_to/building_images>`, or by updating the variable
via {ref}`docker-run-config`.

```
SDL_GAMECONTROLLERCONFIG="030000005e040000be02000014010000,XInput Controller,platform:Linux,a:b0,b:b1,x:b2,y:b3,back:b8,guide:b16,start:b9,leftstick:b10,rightstick:b11,leftshoulder:b4,rightshoulder:b5,dpup:b12,dpdown:b13,dpleft:b14,dpright:b15,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7"
```

The virtual gamepad devices are exposed inside the sessions using Xbox controller attributes and use a standard mapping
in line with the [GamepadAPI Standard Mapping Spec](https://www.w3.org/TR/gamepad/#dfn-standard-gamepad).



Known Issues
------------

- Chromium based browsers running inside the Kasm sessions will only pick up a single gamepad running on port/index 3.

- L2 and R2 triggers are mapped as buttons that support being pressed/not pressed instead of an analog axis.

- Rumble/Haptic feedback is not supported.

- The feature is not supported on Docker in Docker (DinD) installs including TrueNAS and Unraid integrations.

- The feature is not supported on older linux distros/kernels such as those provided by CentOS 7.