Troubleshooting and FAQ

🔧 Troubleshooting & FAQ

🎮 The app doesn't see my controller (but the system does)

This is the most common issue, and it's almost always BlueZ's input plugin: vds needs raw ownership of the controller's Bluetooth HID channels, and with the plugin active the system claims the DualSense as a plain gamepad first — the app never sees it.

Check whether the override is active:

systemctl show -p ExecStart bluetooth | grep -o 'noplugin=input'

Nothing printed? Apply it (installs since v1.8.x do this automatically; older installs may be missing it):

sudo /usr/share/opends5/override-bluetoothd.sh disable-input --restart

(NixOS: services.opends5.disableBluetoothInputPlugin = true; — the default — see NixOS.)

Then disconnect and reconnect the controller.

⌨️ My Bluetooth keyboard/mouse stopped working

The flip side of the fix above — with the input plugin disabled, other Bluetooth input devices can't connect (audio devices are fine). This is an upstream vds limitation; a BlueZ userspace patch is being explored upstream. Your options:

• use USB/2.4GHz-dongle input devices while OpenDS5's driver stack is active, or
• revert the override and connect the controller by USB cable instead:

  sudo /usr/share/opends5/override-bluetoothd.sh enable-input --restart

🔐 The module won't load after install (Secure Boot)

If the wizard asked you to enroll a MOK key, the module can't load until you reboot and complete enrollment in the blue MOK Manager screen (choose Enroll MOK, enter the one-time password you set during install). Check enrollment with mokutil --test-key /var/lib/dkms/mok.pub.

⚡ Reactive trigger effects don't respond

Position-reactive modifiers need to read the controller's input device — add yourself to the input group and relogin:

sudo usermod -aG input $USER

The base effect works without this; only the reactive parts are skipped.

🧪 Newer trigger modes do nothing

Multi Feedback / Slope / Multi Vibration / frequency-controlled Vibration need a current vdsd (V2 trigger command). Update the app (Updates); from a source checkout, ./update-vdsd.sh.

🚫 /dev/vds* missing

lsmod | grep vds_hcd          # loaded at all?
sudo modprobe vds_hcd         # try loading
dkms status                   # built for this kernel?
journalctl -b | grep vds      # kernel messages

After a kernel update DKMS should rebuild automatically; if the build failed, /var/lib/dkms/vds_hcd/…/build/make.log has the compiler output.

🔒 Permission denied on /dev/vds*

You must be in the vds group (groups | grep vds); the installer adds you but it only takes effect after logging out and back in.

📜 Where are the logs?

What	Where
Install (privileged steps, full output)	/var/log/opends5/install.log
Install (plan)	~/.local/state/opends5/install.log
Daemon	journalctl -u vdsd

The setup wizard's failure screen can copy a ready-to-paste diagnostics bundle.

❓ FAQ

Does this work with games that have native DualSense support? Yes — that's the main point. Games see a wired DualSense, which is what most of them require to enable adaptive triggers/haptics/audio. Don't stack custom trigger profiles on those games.

Do I need any extra hardware? No. The original DS5Dongle approach needed a Raspberry Pi Pico 2 W; OpenDS5 uses vds, which does the same job entirely in software.

Which app version do I have? Settings → About. Driver: modinfo -F version vds_hcd (may lag the app version when releases didn't touch the driver — normal).

Is my distro supported? See the table in Installation. Anything with DKMS and systemd is likely portable — docs/PORTING.md.

Where do I report bugs? GitHub Issues — attach the diagnostics bundle or log paths above.