ds3-bluetooth-linux

Hacer funcionar un mando DualShock 3 / Sixaxis (PS3) de forma inalámbrica por Bluetooth en Linux moderno, cuando el plugin sixaxis de BlueZ ya no funciona.

Probado en CachyOS / Arch con BlueZ 5.86 y un adaptador Intel AX201, pero el método es genérico para cualquier distro con BlueZ 5.x.

---

El problema

Conectar un DS3 por Bluetooth en Linux debería ser automático: conectas el mando por USB una vez, el plugin sixaxis de BlueZ hace el emparejamiento por cable, y luego el mando conecta solo por Bluetooth.

En la práctica, en sistemas actuales esto falla por dos razones que se combinan:

1. El plugin sixaxis de BlueZ está efectivamente muerto. Carga, pero no reacciona a la conexión USB del mando, así que nunca hace el cable-pairing ni provee el registro HID que BlueZ necesita.

2. El DS3 no publica su registro SDP/HID por Bluetooth. La conexión L2CAP llega (PSM 17/19), pero muere con el clásico error:

   hidp_add_connection() Could not parse HID SDP record
   

Resultado: el mando intenta conectar, BlueZ no sabe qué es, y la conexión se cae.

La solución (3 piezas)

Este repo automatiza el arreglo persistente (no se pierde al reiniciar):

1. ClassicBondedOnly=false en /etc/bluetooth/input.conf. El DS3 no soporta el bonding/cifrado que BlueZ exige por defecto en perfiles de entrada.

2. Inyectar a mano el registro HID en el cache de BlueZ. Como el DS3 no lo publica, lo generamos nosotros: un programa en C (ds3-mkhidrec, usa libbluetooth) construye el registro SDP del perfil HID (UUID 0x1124) embebiendo el HID report descriptor real que el kernel expone para el mando, y lo escribimos en:

   /var/lib/bluetooth/<adaptador>/cache/<mac-del-control>
   [ServiceRecords]
   0x00010000=<blob hex>
   

   Más una entrada confiable en .../<mac-del-control>/info (Trusted=true, servicio HID 0x1124).

3. Grabar la "MAC maestra" en el mando con ds3-pair (un sixpair portado a libusb-1.0). El DS3 solo conecta por Bluetooth al último adaptador cuya MAC tenga grabada dentro. Por eso, para alternar el mando entre el PC y la consola, hay que reescribir esa MAC por cable cada vez (el kernel hid-sony de equipos actuales no lo hace solo).

Requisitos

Arch / CachyOS:

sudo pacman -S --needed base-devel bluez bluez-libs bluez-utils libusb

Debian / Ubuntu:

sudo apt install build-essential libbluetooth-dev libusb-1.0-0-dev bluez

Instalación

git clone https://github.com/DJhonnyRM/ds3-bluetooth-linux.git
cd ds3-bluetooth-linux
sudo ./install.sh

El instalador compila los dos binarios, instala todo en /usr/local/bin, deja ClassicBondedOnly=false en input.conf y reinicia Bluetooth.

¿Prefieres a mano? make && sudo make install, y edita input.conf tú mismo.

Uso

Primera vez con un mando (configurarlo)

1. Conecta el control PS3 al PC por USB.
2. Ejecuta:

   sudo ds3-setup

3. Desconecta el cable y pulsa el botón PS. Cuando el LED 1 quede fijo, está conectado.

ds3-setup auto-detecta la MAC del adaptador y la del mando: no tienes que escribir nada.

Alternar un mando ya configurado

La MAC maestra vive dentro del mando (recuerda un solo aparato), así que para cambiar de destino hay que reescribirla por cable:

Volver al PC:

# conecta el mando por USB y:
sudo ds3-pc
# desconecta el cable y pulsa PS

Volver a la PS3:

# conecta el mando por USB y:
sudo ds3-ps3 AA:BB:CC:DD:EE:FF      # MAC Bluetooth de tu consola
# desconecta el cable y pulsa PS cerca de la consola

La MAC Bluetooth de la PS3 está en: Ajustes → Ajustes del sistema → Información del sistema → "Dirección MAC Bluetooth". Para no escribirla siempre, guárdala una vez:

echo AA:BB:CC:DD:EE:FF | sudo tee /etc/ds3/console.mac

(luego basta sudo ds3-ps3)

Varios mandos a la vez

Sí funciona: salen como js0, js1, … Cada mando nuevo necesita su sudo ds3-setup una vez (conéctalo SOLO por USB → ds3-setup → desconecta → PS). Las entradas de info/cache son por-MAC; ClassicBondedOnly=false es global.

Mapeo de botones en juegos (SDL / Steam)

El DS3 por Bluetooth a veces reporta los botones/ejes en un orden raro y los juegos los mapean mal. ds3-bt-map te guía botón por botón y genera una cadena SDL_GAMECONTROLLERCONFIG + un lanzador:

ds3-bt-map            # con el mando ya conectado por BT

Te dice cómo usarlo en Steam (Opciones de lanzamiento) o para todas las apps SDL del sistema vía ~/.config/environment.d/.

Herramientas instaladas

Comando	Qué hace
ds3-setup	Configura cualquier DS3 conectado por USB (genera+inyecta su registro HID, lo marca confiable, le graba la MAC del adaptador, reinicia bluetooth). Úsalo para añadir mandos nuevos.
ds3-pc	Apunta un mando ya configurado a este PC (reescribe su MAC maestra).
ds3-ps3 <MAC>	Apunta el mando a tu consola.
ds3-pair <MAC>	Graba una MAC maestra arbitraria en el mando (el sixpair).
ds3-mkhidrec <rdesc>	Genera el blob SDP del registro HID a partir de un report descriptor.
ds3-bt-map	Mapea botones/ejes y genera config SDL para juegos.

Cómo funciona por dentro

ds3-pair (sixpair) — src/sixpair.c

Port a libusb-1.0 del clásico sixpair. Habla con el mando por USB (VID/PID 054c:0268) y, vía petición HID de clase (feature report 0xF5), hace un GET de la MAC maestra actual y un SET con la nueva:

SET_REPORT (0x09), wValue=0x03F5  ->  01 00 AA BB CC DD EE FF

ds3-mkhidrec — src/mkhidrec.c

Construye con libbluetooth (sdp_gen_record_pdu) el registro SDP del perfil HID que BlueZ no logra obtener del mando. Atributos clave del registro:

• ServiceClassIDList → HID (0x1124)
• ProtocolDescriptorList → L2CAP (PSM 0x11) + HIDP
• AdditionalProtocolDescriptorLists → L2CAP (PSM 0x13) + HIDP
• HIDDescriptorList (0x0206) → el report descriptor real del kernel embebido
• atributos HID (subclass gamepad 0x08, virtual cable, reconnect, supervision timeout 0x0C80, …)

El report descriptor se lee de /sys/.../hidrawX/device/report_descriptor mientras el mando está por USB.

Nota: las fuentes C de este repo se reconstruyeron a partir de los binarios originales y se validaron comparando su salida byte a byte contra ellos (ds3-mkhidrec produce un blob SDP idéntico para descriptores de DS3).

Solución de problemas

• El mando parpadea (4 LEDs) y no conecta: la MAC maestra no apunta a este PC. Conéctalo por USB y corre sudo ds3-pc.
• Could not parse HID SDP record en journalctl -u bluetooth: falta el registro HID en el cache. Corre sudo ds3-setup con el mando por USB.
• Conecta y se cae al instante: revisa que ClassicBondedOnly=false esté en /etc/bluetooth/input.conf y reinicia bluetooth.
• No detecta el mando por USB en ds3-setup: prueba otro cable (muchos cables de carga no llevan datos) y comprueba lsusb | grep 054c:0268.
• Ver qué pasa: journalctl -u bluetooth -f mientras pulsas PS.

Créditos

• sixpair original de Pabr (http://www.pabr.org/sixlinux/).
• Construcción del registro SDP HID basada en la API libbluetooth de BlueZ.

Licencia

MIT — ver LICENSE.