dualshock tool github: Which Repo, Which Install, Which Tool (2026)

Search engines return at least four different repositories under "dualshock tool github" depending on intent, and they do different things. The truth most articles skip is that there is no canonical "dualshock-tool"; there is a category of related open-source projects that each own a slice of the protocol surface.

nondebug/dualsense is the reference implementation of the DualSense USB and Bluetooth HID protocol. It is JavaScript and Python and is the cleanest single source for understanding what bytes the controller sends and receives. If you want to learn the protocol, this is where to start.

chrippa/ds4drv is a Linux userspace driver for DualShock 4. It exposes the controller as a uinput joystick so Linux games (including Steam Proton titles) see it as a standard gamepad. It does not work on macOS or Windows.

Ryochan7/DS4Windows is a Windows .NET application that maps DualShock 4 and DualSense to XInput, so Windows games that only support Xbox controllers also accept Sony controllers. It ships several small CLI utilities for vibration testing and battery polling alongside the main GUI.

JibbSmart/JoyShockMapper is a cross-platform C++ project that maps any controller (DualSense, DualShock 4, Switch Pro, Joy-Con) to keyboard and mouse, with gyro aiming and per-game profiles. Not strictly a diagnostic tool, but it shows up in dualshock-tool searches.

Each has merit. None of them is the right answer if your question is "is my left stick drifting".

The four projects overlap on the surface and diverge on the details. Here is what each one is built to do.

A diagnostic question (is the controller's hardware healthy) is answerable on any of them, but only after you have done the install work. The browser-native path skips the install entirely.

This is the canonical "dualshock tool github" install if you want to read raw HID reports and send rumble commands programmatically.

1. Install Python 3.10 or newer. macOS: brew install python@3.11. Linux: sudo apt install python3.11 python3-pip. Windows: download from python.org and tick "Add to PATH".
2. Install hidapi. macOS: brew install hidapi && pip install hid. Linux: sudo apt install libhidapi-libusb0 && pip install hid. Windows: pip install hid (bundles the binary).
3. Clone the repository. git clone https://github.com/nondebug/dualsense.git && cd dualsense.
4. Add a udev rule on Linux so a non-root user can claim the device. Drop a file at /etc/udev/rules.d/50-dualsense.rules containing SUBSYSTEM=="hidraw", ATTRS{idVendor}=="054c", ATTRS{idProduct}=="0ce6", MODE="0666", then sudo udevadm control --reload-rules.
5. Plug in the controller via USB-C. Bluetooth works on some setups but is more brittle.
6. Run python3 read.py to dump the parsed input report at 250 Hz, or python3 vibration.py to send a rumble test pulse.

For ds4drv on Linux, the install is shorter: sudo apt install ds4drv on Debian or Ubuntu, then sudo ds4drv to start the daemon. The controller appears as /dev/input/js0 and Steam treats it like a standard joystick.

For DS4Windows on Windows, download the latest release ZIP, extract, run DS4Windows.exe, and follow the in-app prompts to install the ViGEm bus driver that makes Windows see the controller as an Xbox 360 pad.

Realistically, expect 20 to 60 minutes for first install on any of these if you do not already have the toolchain set up. The browser path takes 30 seconds.

If you came here because your controller is misbehaving in a game and you want to know whether it is the hardware, the browser tool reads exactly the same HID input layer the CLIs read.

JoyCheck binds to the controller through the W3C Gamepad API and reads the four stick axes plus every button at the browser's render rate (60 to 120 Hz). The DualSense polls its sensors at 250 Hz over USB and 125 Hz over Bluetooth per the nondebug/dualsense protocol notes and iFixit teardowns.

For a centring drift readout (let the stick rest, look at the value, see whether it sits inside ±0.03), 60 Hz sampling over five seconds is more than enough. You do not need a CLI for that.

For write operations like rumble tests, JoyCheck uses WebHID on Chrome and Edge. That gives you the same output-report path the Python scripts use, without leaving the browser.

The CLI tools matter for: scripted regression suites, reading vendor-specific feature reports (battery voltage, internal temperature), and protocol research where you want full byte-level control. For everything else, the browser is the faster answer.

These come from the nondebug/dualsense and the DS4 USB HID protocol notes on PSDevWiki, both linked from the GitHub README.

If you are debugging a protocol parser or building a tool of your own, these numbers save you a lot of trial and error. If you are debugging a controller, you do not need them.

Bluetooth is where most "dualshock tool github" installs fall over. The protocol differences between USB and Bluetooth are not cosmetic; they change every output report ID, every input report size, and on DualSense, every checksum requirement.

On USB, the DualSense input report is 64 bytes starting at report ID 0x01, with no checksum. On Bluetooth, the same controller emits a 78-byte report starting at ID 0x31 with a CRC-32 checksum on the last four bytes. A CLI that does not handle both will silently misparse the report and report nonsense stick values.

Rumble has the same split. The USB output report ID 0x02 is 47 bytes; the Bluetooth output report ID 0x31 is 78 bytes and also CRC-32 protected. Send a USB-shaped report over Bluetooth and the controller drops it without warning.

The nondebug/dualsense library handles both, but only after you configure it explicitly. ds4drv handles DualShock 4 Bluetooth but its DualSense support is limited, and DS4Windows handles both but only on Windows. JoyCheck handles both behind a single WebHID call so you do not have to think about it.

The CLIs read and write controller state at the HID layer. They do not:

• Recalibrate the stick. Sony's HID protocol does not have a calibration-offset command for DualShock or DualSense, so no software tool, CLI or browser, can store a calibration adjustment in the controller. The hardware does not accept one.
• Repair worn potentiometer sticks. Drift is mechanical wear on the wiper-and-track assembly inside the stick module. Replacement is the fix; see the iFixit DualSense guide.
• Update controller firmware. Sony ships firmware updates via the PS5 system or the official PC companion. CLI tools do not flash firmware.
• Fix Bluetooth pairing. Re-pair at the OS level per Bluetooth SIG standards; the controller does not own the pairing flow.
• Substitute for a multimeter. If you need to measure motor coil resistance or trace a broken solder joint, the CLI cannot help. You need a probe.

If your goal is to diagnose a controller fault, both the CLIs and JoyCheck will tell you the same thing about stick health, button response, and trigger range. The choice is install time vs runtime, not capability.

1. W3C, "Gamepad API specification": www.w3.org/TR/gamepad
2. Mozilla Developer Network, "Gamepad API reference": developer.mozilla.org/en-US/docs/Web/API/Gamepad_API
3. WICG, "WebHID API specification": wicg.github.io/webhid
4. nondebug, "dualsense (Web example)": github.com/nondebug/dualsense
5. USB Implementers Forum, "HID information": www.usb.org/hid