Configurare e calibrare un gamepad su Linux: xboxdrv, jstest-gtk e qjoypad

Se il modulo xpad del kernel dà problemi (LED che lampeggiano, mapping errato), disabilitalo e usa xboxdrv o ubuntu-xboxdrv. Calibra con jstest-gtk e mappa tasti/assi con qjoypad. Questa guida mostra comandi, servizio systemd, risoluzione dei problemi, checklist e suggerimenti pratici per far funzionare il gamepad su distribuzioni Debian/Ubuntu.

Perché questo articolo

Linux offre oggi un buon supporto per controller, ma il modulo kernel xpad può presentare bug o limitazioni di configurazione. Qui trovi una procedura pratica per sostituirlo, calibrare il dispositivo e creare profili di mapping persistenti.

Sommario rapido

• Disabilitare temporaneamente o permanentemente xpad
• Installare e avviare xboxdrv (o ubuntu-xboxdrv)
• Calibrare con jstest-gtk
• Creare profili e mappare input con qjoypad
• Troubleshooting e checklist di controllo

Requisiti base

• Accesso amministratore (sudo)
• Distribuzione basata su Debian/Ubuntu (comandi apt mostrati)
• Pacchetti: xboxdrv, jstest-gtk, qjoypad (o relativi backport/ppa)

Usare un driver alternativo

Il primo passo è installare un driver più configurabile rispetto al modulo kernel generico. Apri un terminale e installa xboxdrv:

sudo apt-get update
sudo apt-get install xboxdrv

Se preferisci una versione mantenuta da terze parti che estende la compatibilità, puoi cercare ubuntu-xboxdrv nei PPA (procedura mostrata più avanti). Dopo l’installazione, avvia xboxdrv con il parametro che sfila il driver kernel:

sudo xboxdrv --detach-kernel-driver

L’opzione --detach-kernel-driver evita il conflitto con xpad. In alternativa puoi rimuovere manualmente il modulo xpad dalla sessione corrente:

sudo rmmod xpad
sudo xboxdrv

Quando il driver è attivo, il terminale inizierà a stampare eventi relativi a pulsanti e assi.

Per eseguire xboxdrv in background senza output verboso:

sudo xboxdrv --silent

Se xboxdrv standard non funziona con il tuo dispositivo, puoi provare ubuntu-xboxdrv tramite PPA (valuta i rischi di sicurezza prima di aggiungere repository esterni):

sudo apt-add-repository -y ppa:rael-gc/ubuntu-xboxdrv
sudo apt-get update
sudo apt-get install ubuntu-xboxdrv

Importante: alcuni controller moderni sono già gestiti molto meglio dal kernel; valuta prima se il problema è davvero xpad.

Disabilitare permanentemente xpad

Per evitare che il modulo xpad venga caricato all’avvio, crea un file di blacklist per modprobe:

echo "blacklist xpad" | sudo tee /etc/modprobe.d/blacklist-xpad.conf
sudo update-initramfs -u

Dopo il reboot il modulo non verrà più caricato automaticamente. Questa è la soluzione consigliata se intendi usare sempre xboxdrv.

Avviare xboxdrv automaticamente con systemd (esempio)

Per avere xboxdrv avviato come servizio e con un profilo stabile, crea un’unità systemd minima:

sudo tee /etc/systemd/system/xboxdrv.service > /dev/null <<'UNIT'
[Unit]
Description=Daemon xboxdrv per controller
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/xboxdrv --daemon --silent --detach-kernel-driver
Restart=on-failure

[Install]
WantedBy=multi-user.target
UNIT

sudo systemctl daemon-reload
sudo systemctl enable --now xboxdrv.service

Modifica ExecStart con le opzioni desiderate (mappa personalizzata, file di configurazione, ecc.). Se la tua versione di xboxdrv non supporta --daemon, rimuovi quell’opzione e usa --silent.

Calibrare il gamepad

Per controllare e calibrare assi e pulsanti usa jstest-gtk. Installa ed esegui:

sudo apt-get install jstest-gtk
jstest-gtk

Apri lo strumento, seleziona il tuo dispositivo e clicca Properties. Vedrai indicatori per assi e pulsanti.

Se noti offset o drift, clicca Calibration e poi Start Calibration, quindi segui le istruzioni sullo schermo per impostare i punti di centro e fine corsa degli assi.

Con Mapping puoi rimappare l’ordine dei pulsanti. Le modifiche applicate qui influiscono su tutte le applicazioni che leggono il dispositivo a basso livello.

Mappare input verso tastiera o mouse con qjoypad

Se vuoi che le pressioni del gamepad simulino tasti o movimenti del mouse, qjoypad è una buona soluzione:

sudo apt-get install qjoypad
qjoypad --notray

Crea nuovi layout con Add, assegna azioni ad assi e pulsanti. Usa Quick Set per associare rapidamente un pulsante fisico a un tasto virtuale.

Esempio pratico: assegnare H alla direzione sinistra dell’analogico e O alla destra, così da simulare tastiera in giochi non nativi.

Quando chiudi l’app, avvia qjoypad dal menu per inviarlo nell’area di notifica e passare tra i profili.

Controlli e comandi utili per diagnostica

• Verifica moduli caricati:

lsmod | grep xpad

• Vedere eventi kernel/reazione USB:

dmesg | tail -n 50

• Trovare device event (evdev) per test:

ls /dev/input/
sudo evtest

• Controllare se xboxdrv ha aperto device:

ps aux | grep xboxdrv

Casi in cui potrebbe non funzionare

• Controller molto recente o non standard potrebbe essere già gestito da driver proprietari o richiedere firmware specifico.
• Alcune distribuzioni più conservative potrebbero non avere pacchetti aggiornati; in quel caso compila da sorgente o usa container/flatpak se disponibili.
• Controller Bluetooth: la gestione Bluetooth (pairing, profili) può interferire; assicurati che il dispositivo sia associato correttamente e che non esista un altro processo che lo gestisca.

Suggerimenti pratici e modelli mentali

• Mental model: tre livelli di gestione

  1. Kernel (xpad) — basso livello, supporto nativo ma meno configurabile
  2. Driver userland (xboxdrv) — più flessibile, mapping e profili
  3. Wrapper/applicazioni (qjoypad, Steam Input) — mappatura per singole applicazioni

• Procedura rapida che funziona nella maggior parte dei casi:

  1. Rimuovi xpad temporaneamente (rmmod) e verifica comportamento
  2. Installa xboxdrv e testa in terminale
  3. Calibra con jstest-gtk
  4. Crea profili qjoypad o configura Steam Input per singoli giochi

Checklist per ruolo

Gamer

• [ ] Disabilitare xpad se causa problemi
• [ ] Installare xboxdrv e avviare in modalità --silent
• [ ] Calibrare con jstest-gtk
• [ ] Creare profili con qjoypad o usare Steam Input

Sviluppatore/Streamer

• [ ] Creare servizio systemd per avviare xboxdrv automaticamente
• [ ] Testare mapping con evtest e jstest-gtk
• Fornire un profilo condivisibile (file di configurazione o script di avvio)

Tecnico di laboratorio

• [ ] Verificare lsmod, dmesg e permessi su /dev/input/*
• Documentare procedure di rollback (rimuovere blacklist, riavviare)

Snippet e cheat sheet dei comandi più usati

# Installare strumenti
sudo apt-get update
sudo apt-get install xboxdrv jstest-gtk qjoypad

# Avviare xboxdrv temporaneamente
sudo xboxdrv --detach-kernel-driver --silent

# Rimuovere modulo xpad per sessione
sudo rmmod xpad

# Bloccare xpad permanentemente
echo "blacklist xpad" | sudo tee /etc/modprobe.d/blacklist-xpad.conf
sudo update-initramfs -u

# Avviare jstest-gtk
jstest-gtk

# Avviare qjoypad senza tray
qjoypad --notray

Casi limite e come gestirli

• LED che lampeggiano ciclicamente: tipico segno di conflitto tra xpad e xboxdrv. Rimuovere xpad (rmmod) o creare blacklist.
• Input non lineare o drift dopo la calibrazione: ripetere la calibrazione e verificare usura meccanica del controller.
• Controller che funziona in alcune applicazioni ma non in altre: controllare se l’applicazione usa API diverse (SDL, XInput, evdev). In molti casi Steam Input sovrascrive il comportamento.

Note su compatibilità e migrazione

• Se passi da xpad a xboxdrv, verifica che le applicazioni leggano dallo stesso device (evdev). Alcune app potrebbero preferire il mapping kernel.
• Per distribuzioni non-Debian, usa il gestore pacchetti nativo oppure compila xboxdrv dal sorgente.

Riepilogo e azioni consigliate

• Prima prova: esegui rmmod xpad e sudo xboxdrv --silent per vedere se il problema sparisce.
• Se funziona, crea la blacklist e un servizio systemd per automatizzare l’avvio.
• Calibra sempre con jstest-gtk e crea profili qjoypad se hai bisogno di mappare input su tastiera/mouse.

Importante: non tutti i controller richiedono xboxdrv. Se tutto funziona correttamente con xpad, potresti non aver bisogno di cambiare nulla.

Riassunto finale

Con pochi comandi puoi ottenere un controllo molto più preciso su come il tuo gamepad interagisce con Linux. Disabilita xpad solo se necessario, usa xboxdrv per configurazioni avanzate, calibra con jstest-gtk e crea profili con qjoypad. Le pratiche descritte riducono i problemi più comuni e rendono il controller utilizzabile con giochi non nativi.