Gamepad & Joystick Drift Tester: Code Examples

How to Test a Controller on Windows 11

Windows prepares gamepad input through the OS driver layer before a browser can read it. The Web Gamepad API lets a page read buttons and axes from gamepads the user agent exposes, and the browser decides whether a controller matches the standard gamepad layout.¹ On Windows, Xbox-style XUSB controllers use the XINPUT path and can also expose a DirectInput HID mapping for legacy software.² DirectInput remains the path for many legacy devices such as steering wheels, fight sticks, and some HOTAS hardware. If a controller is DirectInput-only, the browser may not detect it, or it may expose a mapping that does not match the standard layout.¹²

Using joy.cpl as your first diagnostic step

Joy.cpl is the DirectInput Game Controller control panel. Microsoft describes it as the single control panel you can open to configure and test game controllers, with a default Test page that shows whether the device responds properly.³ Open it by pressing Win+R, typing joy.cpl, and pressing Enter. If your controller appears in the Game Controllers list, Windows has a driver-level view of the hardware and you can move to browser testing. If it does not appear, troubleshoot the driver or USB connection first because the browser cannot expose a controller Windows does not see.

Why Windows must see it first

To compare mappings, click Properties in joy.cpl and then the Test tab. The Test tab shows axes and buttons in the DirectInput/HID view. For XUSB controllers, Microsoft documents that the HID mapping exposes the left stick, right stick, combined trigger axis, D-pad, and face buttons, and notes that the combined trigger axis cannot show every trigger combination. Compare that view with the browser tester before assuming the browser is wrong.

After Windows recognizes the controller, open the tester in Chrome or Edge and press any button to prompt the browser to expose it before you compare mappings. A controller that shows in joy.cpl but stays hidden on the page usually needs that first button press, so do not assume the browser is misreporting until you have interacted with the device while the tab is open.

Confirming XInput mode before opening the browser

Confirming whether your controller is in XInput or DirectInput mode avoids a common category of detection failures. An XUSB controller can show up through XInput and DirectInput, but the two paths do not report the same control model: Microsoft's XINPUT_GAMEPAD structure exposes separate left and right trigger values, while the DirectInput HID mapping combines the two triggers into one Z axis.⁴ That means joy.cpl axis numbering is useful for OS-level diagnosis, but it is not a promise that the browser will use the same numbering.

How to switch to XInput mode on Windows 11

For Logitech F310 controllers, set the input mode switch on the back to X for XInput mode and D for DirectInput mode; Logitech recommends XInput whenever possible for modern Windows games.⁵ For 8BitDo SN30 Pro controllers, the Windows instructions use X + Start before Bluetooth pairing or wired USB connection.⁶ Other 8BitDo models use different combinations, such as X + Home or B + Home, so check the model manual before connecting. Set the mode before the controller connects so Windows receives the device descriptor for the mode you want to test.

Driver conflicts after Windows Update

After a Windows update, driver state can change for any hardware device. Microsoft says Windows can automatically download recommended drivers through Windows Update and that drivers can also be updated or reinstalled through Device Manager.⁴ If a controller worked before an update and no longer appears in joy.cpl, treat it as a Windows driver problem first, not as a browser problem. Open Device Manager by pressing Win+X and selecting Device Manager, then expand Human Interface Devices and look for the controller name or a device reporting an error code.

Reinstalling the driver path

If Windows reports a driver problem, right-click the entry and choose Update driver or Uninstall device, then replug the controller so Windows can reinstall it. For third-party controllers, use the manufacturer's official driver package when Windows Update does not provide a compatible driver. For controllers using Microsoft-provided drivers, Windows Update is the first place to check before trying third-party utilities.

Notes

Before testing in the browser, confirm Windows itself sees the controller. Open the Run dialog (Win+R), type joy.cpl, and press Enter. If the controller appears in Game Controllers, Windows has a working driver and the device is ready for browser testing. If it does not appear, troubleshoot at the OS level first: try a different USB port, reinstall the manufacturer's driver, or check Device Manager for driver errors.

If the controller has a mode switch, such as the Logitech F310's D/X switch on the back, confirm it is in XInput mode before opening the browser. XInput is usually the safest mode for browser testing. If a third-party controller needs a driver update, check the manufacturer's website for a Windows 11-compatible package before assuming the hardware is faulty.

Examples

Win+R → type joy.cpl → press Enter → confirm controller appears in Game Controllers

In joy.cpl Properties → Test tab: compare DirectInput/HID axis mapping with the browser tester

Win+X → Device Manager → Human Interface Devices: look for controller name or a device reporting an error code

Try in the tool

How to Test a Controller on macOS

On macOS Ventura and later, Apple supports wireless Xbox, PlayStation, and other Bluetooth game controllers on Mac, and some controller customization settings require macOS Ventura 13 or later.¹ PlayStation DualShock 4, DualSense, and DualSense Edge controllers can connect by USB cable or Bluetooth on Mac, while supported Xbox Wireless Controllers can also pair through Bluetooth settings.²³ USB is usually the simplest first connection method for browser testing because it avoids Bluetooth pairing and firmware-update variables. For the cleanest reading, connect the controller before opening the test page, then press any button once the page loads.

If the controller appears in System Information but not in the browser, compare Safari, Chrome, and Firefox before changing macOS settings. Keep the controller awake during long drift checks by tapping a button between readings, because Bluetooth gamepads can sleep when idle. This small habit prevents a power-saving disconnect from looking like a browser mapping failure.

For drift checks, leave the controller flat on the desk and keep the cable from tugging the body. Press a button between readings so the Bluetooth link stays active, then compare screenshots only after the values settle. This keeps power-saving behavior from looking like a mapping problem.

Verifying controller recognition in macOS System Information

When you connect a controller via USB on macOS, verify that the OS itself sees the device before troubleshooting the browser. Open System Information from the Apple menu by holding Option and selecting System Information, then navigate to Hardware and then USB in the sidebar. If the controller does not appear in the USB device tree, no browser fix will make it visible. Resolve the USB recognition at the OS level first.⁴

Confirm macOS recognition before browser troubleshooting

For Bluetooth controllers, open System Settings and navigate to Bluetooth to check whether the device shows as connected. Apple's Xbox controller guidance says to press the Xbox button, hold the Connect button to enter pairing mode, open Bluetooth settings, and select the controller from nearby devices.³ A controller that shows as paired but not connected needs a reconnect initiated either through the settings panel or by pressing the controller's sync button. Bluetooth controllers must show as connected in the OS before the browser can see them.

After the controller shows as connected, open the tester in Chrome or Firefox and press any button to prompt the browser to expose it before reading the values. A device that remains paired but hidden on the page usually needs that first button press, so do not assume the browser is broken until you have interacted with the controller while the tab is open.

Browser choice for reliable results on macOS

Safari on macOS supports the Gamepad API, and WebKit states that any gamepad that works on macOS without additional drivers will work on a Mac.⁵ For troubleshooting, Chrome or Firefox can still be easier because they are commonly used for browser-based controller tests and Chrome exposes a local diagnostics page at chrome://gamepad-internals/ for raw Gamepad API data.

Choosing the fastest browser path

If the controller appears in gamepad-internals but not in the tester page, the issue is page-specific and not a browser or driver problem. If it does not appear in gamepad-internals either, return to System Settings and confirm the controller remains connected while the page is open. macOS can keep a Bluetooth controller paired without keeping it actively connected, especially after inactivity. Reconnect it from Bluetooth settings, then press a face button before refreshing the tester page.

Xbox controllers on macOS via Bluetooth

On macOS, supported Xbox Wireless Controllers can pair through the same Apple Bluetooth settings flow used for other wireless accessories: first press the controller Xbox button to power it on, then hold the small Connect button on top until the Xbox logo begins flashing rapidly to enter pairing mode, and finally open System Settings, navigate to Bluetooth, and select the controller from the list of nearby discoverable devices.

Verifying the Bluetooth connection works for browser testing

If the controller appears to connect but does not respond as expected in the browser tester, Apple recommends installing the latest available software updates for both the Mac and the controller firmware, then forgetting the device in Bluetooth settings and re-pairing it from scratch. After successfully re-pairing, open the gamepad tester page and press any button on the controller to register it with the Gamepad API, because macOS may show the controller as paired in Bluetooth settings without actually exposing it to the browser until that first physical button press triggers the HID enumeration.¹ For DualSense and DualShock 4 controllers, PlayStation support pages cover USB and Bluetooth pairing on Mac directly, so no Xbox Accessories app download is involved or required.²⁶

Notes

Safari on macOS supports the Gamepad API, but Chrome and Firefox are useful alternatives when you need browser-specific troubleshooting or Chrome's chrome://gamepad-internals/ diagnostics page.

DualShock 4, DualSense, and DualSense Edge can connect to Mac by USB or Bluetooth through Apple's pairing flow. Supported Xbox Wireless Controllers also pair through Bluetooth settings; there is no Xbox Accessories app requirement on Mac.

Examples

Apple menu → About This Mac → System Report → USB, find controller in the device tree

Open chrome://gamepad-internals/ in Chrome to view raw Gamepad API data before running any test page

Hold PS + Create buttons simultaneously until the LED pulses white → macOS Bluetooth settings → select DualSense Wireless Controller

Try in the tool

How to Test a Controller on Linux

Linux exposes gamepad devices through kernel input handlers: evdev for /dev/input/event* devices and the legacy joydev interface for /dev/input/js* devices.¹ Chromium's Linux gamepad code reads axis and button state from joydev and reads special button events from evdev, so browser visibility depends on both the kernel nodes and the browser's own input backend.² The Web Gamepad API then reports the browser-exposed gamepad as buttons and axes with normalized values.³ If a controller appears in jstest-gtk but not in the browser, compare the evdev permissions for the relevant /dev/input/event* device before assuming the browser is broken.

Understanding evdev versus joydev on Linux

Understanding the difference between the two Linux kernel input interfaces is the key to resolving browser detection failures. The joydev interface exposes controllers as /dev/input/js* devices and is the legacy joystick API; the kernel documentation says newer clients are encouraged to use the generic evdev interface.¹ The evdev interface exposes devices as /dev/input/event* files and is the generic input event interface for userspace.

Chromium's Linux backend reads button and axis events from the joydev node, then reads special button events from the evdev node when needed.² That is why jstest-gtk can show a controller while a browser still misses part of the device: the two tools are not reading the same set of Linux input nodes.

Finding the correct event device for your controller

To identify which event* device corresponds to your controller, run cat /proc/bus/input/devices in a terminal. Find your controller name in the output and look at the adjacent Handlers line: it shows the event number, for example event5, that maps to /dev/input/event5. Once you have identified the event device, check whether your current user has read permission on that specific file before diagnosing any browser-level issues.

Adding a udev rule for permanent evdev access

For a permanent permission fix that does not rely solely on temporary group membership changes, you can write a custom udev rule that grants access to your specific controller based on its unique USB vendor and product ID pair. Create a new rules file at /etc/udev/rules.d/99-gamepad.rules using sudo, then add a rule line that specifies the vendor ID, product ID, GROUP="input", and MODE="0664" for your controller hardware. After saving the file, run sudo udevadm control with the reload-rules option followed by sudo udevadm trigger in a terminal, then physically unplug and replug the controller so the new rule is applied to the device node on reconnect.

Checking browser access after the rule takes effect

After reconnecting the controller, refresh the browser tester page and press a button to register the device with the Gamepad API. If the browser still cannot see the controller, re-check the specific /dev/input/event* device permissions with ls -l and confirm the current user account is a member of the input group by running id in a terminal.

systemd's default input subsystem rules automatically assign the input device class to the input group, and they set file mode 0664 for js device nodes so group members can read them.⁴ systemd also automatically tags joystick input devices with the uaccess tag when they carry the ID_INPUT_JOYSTICK property, which grants the currently logged-in user transparent access through logind without manual group changes.⁵ For controllers that lack a fixed USB ID or for a quick general fix, the simpler approach is adding your user to the input group: run sudo usermod -aG input $USER and then fully log out of the desktop session and log back in.⁶ Simply closing and reopening a terminal window is not sufficient, because the group membership change requires a complete session restart to propagate to all processes.

Wayland versus X11 for browser controller testing on Linux

Wayland and X11 can affect how pointer and keyboard focus behave in desktop applications, but controller visibility in the browser fundamentally starts at the kernel input layer below either display server, so the choice of compositor is rarely the root cause of a gamepad detection failure. If the same physical controller works correctly in one desktop session but fails to appear in another session on the exact same Linux system, compare the evdev device permissions between the two sessions rather than immediately assuming the display server protocol is responsible.

Comparing permissions between sessions to isolate the cause

Run ls -l /dev/input/event* in each session to compare the file ownership and permission bits directly side by side. Different ownership or mode values between two sessions on the same machine point to a session-specific udev rule or a logind access policy as the more likely cause of the discrepancy. Always log out of the desktop session completely and log back in after making any group membership changes, because simply closing and reopening a terminal window does not apply the new group permissions to already-running desktop processes.

Notes

First check that the OS sees the controller: run ls /dev/input/js* in a terminal and verify a js0 or similar device exists. Install jstest-gtk, available as the package jstest-gtk or joystick on many distributions, and verify the controller shows full axis and button movement before testing in the browser.

If jstest-gtk works but the browser does not detect the controller, compare evdev permissions. Run ls -l /dev/input/event* and check that the current user can read the relevant event device. A targeted udev rule can set GROUP="input" and MODE="0664" for the controller, then run sudo udevadm control with the reload-rules option and unplug and replug the controller.

Alternatively, add the user to the input group with sudo usermod -aG input $USER and log out and back in. The group change requires a full session restart; closing and reopening the terminal is not enough.

Examples

ls /dev/input/js* : should return /dev/input/js0 or similar

ls -l /dev/input/event* : look for crw-rw---- root input; confirm current user is in the input group

sudo udevadm control --reload-rules && sudo udevadm trigger : then unplug and replug the controller

Try in the tool

How to Test a Controller on Steam Deck

The Steam Deck runs SteamOS, a Linux-based operating system, with two distinct modes. Gaming Mode is the default game-launching interface; Desktop Mode provides a PC-style desktop for running desktop applications. Valve describes SteamOS as the operating system on Steam Deck and says you can head out to the desktop when you want a more hands-on PC experience.¹ Browser controller testing belongs in Desktop Mode, where you can open a browser and run desktop applications. To switch, hold the Steam button and select Power, then Switch to Desktop. For wired external controllers, remember that the Deck has a single multi-purpose USB-C jack, so a hub or dock is needed for USB-A peripherals.

For drift checks, keep the Deck flat and press a button between readings so the built-in controller stays active while the browser samples the axes.²

Switching to Desktop Mode for browser testing

To run any browser-based gamepad test on the Steam Deck, you must first switch the device into Desktop Mode, because the default Gaming Mode interface does not provide access to a standard web browser. Valve describes Desktop Mode as the hands-on PC-style desktop experience built into SteamOS, and it allows you to install and run desktop applications independently from the Steam game library.¹

Why the browser needs Desktop Mode rather than Gaming Mode

The gamepad tester requires a normal browser tab with a fully visible page and direct access to the Gamepad API, none of which are available inside the Gaming Mode fullscreen launcher interface. Gaming Mode is designed exclusively for launching and playing Steam games through Valve custom frontend, so it cannot host a standard web page with JavaScript API access.

In Desktop Mode, open a web browser from the taskbar or the application menu. Navigate to the gamepad tester page in whichever browser you prefer, such as Chromium or Firefox. When you finish testing, use the Return to Gaming Mode shortcut icon on the desktop to switch back to the standard Steam game launcher interface.

Built-in Steam Deck controls in Desktop Mode

The Steam Deck's built-in thumbsticks, face buttons, bumpers, triggers, and paddles have a defined controller mapping in SDL's Steam Deck HID driver. That driver sends the sticks, triggers, buttons, and paddles through gamepad axis/button paths, while the trackpads are sent through SDL's joystick touchpad API rather than as ordinary gamepad axes.³ The browser Gamepad API then exposes the browser-visible gamepad as normalized buttons and axes.⁴

What the browser can see

Press any button on the Deck to register the device, then test each axis and button. The touchpads may still be usable as pointer controls in Desktop Mode, but they should not be treated as standard thumbstick axes in this browser tester. The trackpads report movement through a separate pointer-style API rather than through the Gamepad API axis array, so the tester cannot display trackpad position even though the rest of the Deck controls are visible.

Testing external controllers connected to the Steam Deck

Connecting an external controller to the Steam Deck requires a USB-C hub with a USB-A port for wired connections, since Valve describes the Deck as having a single multi-purpose USB-C jack for charging, peripherals, and display output.² Connect the hub, plug the controller into the hub's USB-A port, and press a button to register the external controller in the browser. The browser can expose multiple connected gamepads, so the external controller appears as a separate gamepad entry from the Deck's built-in controls.⁴

When Steam has taken exclusive input ownership

Steam Input can emulate an Xbox controller for games. Steamworks documentation says that on macOS and Linux, emulated controller input is provided by a driver, and the controller appears in games as an Xbox controller.⁵ On Linux desktops, Steam Input can also use EVIOCGRAB on the raw evdev device on X11 so games see the virtual controller instead of the raw one; this is why the same physical controller can appear differently depending on Steam Input and compositor behavior.⁶ If an external controller appears when Steam is not running but not when Steam is open in the background, close Steam from the Desktop Mode taskbar and reload the browser page before testing again.

Notes

The Steam Deck's built-in controls, including thumbsticks, trackpads, and buttons, are available to apps and games in Desktop Mode when Steam is running. In Desktop Mode, the built-in sticks should appear as a browser-visible gamepad after pressing a button on the Deck itself. The trackpads are pointer-style inputs and should not be treated as standard thumbstick axes in this browser tester.

For external controllers connected via USB-C with a hub or via Bluetooth, the behavior follows standard browser Gamepad API rules. If an external controller is recognized by Steam in Gaming Mode but not by the browser in Desktop Mode, check Steam Input configuration and the /dev/input/event* permissions described in the Linux controller guide. The Steam Deck runs SteamOS, so the same evdev permission rules apply.

Examples

Hold Steam button → Power → Switch to Desktop

Open Discover app store → search Chromium → install → launch and navigate to the gamepad tester

In Desktop Mode with Chromium open, move the left thumbstick: the axis canvas responds after pressing any button on the Deck

Try in the tool

Gamepad Testing on Linux with Steam and Proton

Steam on Linux uses a software layer called Steam Input that intercepts controller input before it reaches any application.¹ When Steam is running, your controller's raw hardware signals may be processed, remapped, and re-emitted as a virtual gamepad rather than passed through directly.² Testing in a browser before launching Steam gives you the unmodified hardware reading that reveals whether a problem is in the hardware itself or in Steam Input's configuration. For Proton troubleshooting, record both the closed-Steam value and the in-game value so the comparison is easy to explain.³⁴

How Steam Input intercepts controller data on Linux

On Linux, the Steam client reads raw input events directly from the kernel evdev interface and then creates a virtual gamepad device that it presents to applications whenever a game window is focused or Big Picture Mode is active.¹ Applications running on the system, including your web browser, may then receive controller data from this Steam-generated virtual device rather than from the actual physical hardware, which means the values you see can differ from what the controller truly outputs.

Raw hardware readings versus Steam Input readings

The practical effect of this Steam Input interception layer is that the browser may silently display axis values that have been modified by Steam Input configurable deadzone compensation, custom calibration curves, and per-game response remapping profiles rather than the true unmodified raw hardware values you actually need to evaluate when diagnosing whether your controller has a genuine drift problem.⁵

To obtain a clean, unmodified hardware reading that reflects the true state of your controller sensors, close the Steam client entirely before opening the browser and running the gamepad test. Right-click the Steam icon in the Desktop Mode taskbar and select Exit Steam to ensure no background processes remain active. Once Steam has fully stopped, reload the test page completely, press a button on your controller to register it with the Gamepad API, and then read the raw axis values directly from the kernel evdev interface without any Steam Input processing layer modifying the signal.³

Disabling Steam Input for a single controller

When you need to test controller hardware without closing Steam entirely, you can disable Steam Input for one specific device. Open Steam Settings, navigate to the Controller section, and find the configuration for your controller model. Set the template to No Steam Input. After applying this change, disconnect and reconnect the controller so Steam releases exclusive hold and the kernel evdev data flows directly to the browser.⁵

Testing with Steam running versus closed: interpreting the difference

Compare the browser reading with Steam Input disabled against the value you saw in the game or with Steam running. That comparison separates raw hardware behavior from the software layer that Steam applies before a game receives the controller state. Recording both values side by side makes it easier to explain a support case or decide whether a hardware repair is actually needed.

When the values differ

If the browser shows a different axis value with Steam running than with Steam closed, Steam Input's deadzone or calibration is modifying the hardware signal. The value with Steam closed is the true hardware reading. The difference tells you how much correction Steam Input is applying. A tiny difference can be normal compensation; a larger difference suggests the hardware drift exceeds what Steam Input is filtering. If the values match closely, the hardware is likely fine and the in-game symptom points to a Steam Input configuration issue rather than a worn stick.

SDL gamepad database and its effect on game button layouts

SDL2, the game development library used by most native Linux games and many Proton titles, maintains a gamepad database that maps controller USB vendor and product IDs to named button layouts.⁶² When your controller's IDs appear in the SDL database, the game remaps the raw axis indices to expected names. When your controller is not in the database, the game treats it as a generic joystick, which can produce unexpected button assignments in the title's control mapping screen.⁶

Checking SDL mappings before game launch

Install sdl2-jstest through your distribution's package manager, then run sdl2-jstest with the list option to see how SDL maps your specific controller. If the output does not match your physical controls, the controller is not in the SDL database and you may need to configure button mappings manually in the game's settings. Running sdl2-jstest with the test option while pressing each button and moving each axis shows you exactly which SDL axis index corresponds to each physical control, so you can predict how most native Linux games will see the inputs before launching a title.

Notes

To isolate hardware from software: close Steam entirely before opening the browser and running the gamepad test. With Steam not running, the browser receives raw input from the kernel evdev interface without any Steam Input layer. If drift is present in the browser but not visible in games, Steam Input's deadzone or calibration settings are masking hardware drift. If drift appears in games but not in the browser, Steam Input's configuration may be applying an offset or the game's own input code is the source.

The SDL gamepad database, used by many Linux games via SDL2, also applies its own button remapping based on the controller's USB vendor and product ID. Controllers not in the SDL database may appear with non-standard axis assignments in native Linux games even when they work correctly in the browser. Run sdl2-jstest with the list option to see how SDL maps your controller, which predicts how most native Linux games will see the inputs.

Examples

Quit Steam completely → open browser → run gamepad test → compare axis readings to in-game behavior with Steam running

sdl2-jstest --list (install via libsdl2-dev or sdl2-tools package depending on distribution)

Steam → Settings → Controller → set controller to No Steam Input template → reconnect controller

Try in the tool