NAME

btsixad — Driver for Sixaxis gamepad connected over Bluetooth

SYNOPSIS

DESCRIPTION

The btsixad daemon allows the PlayStation 3 Sixaxis gamepad to be used wirelessly over Bluetooth. When a gamepad is connected, the daemon creates a virtual USB HID device named btsixa*. This can be symlinked to uhid* and used like an ordinary USB joystick or gamepad by SDL and other programs.

The options are:

-a bdaddr

Listen on a specific Bluetooth address.

-d

Run in the foreground. This will print incoming connection details and Bluetooth HID control messages exchanged. Specify -d twice to also print interrupt messages (current state of controls) and specify -d three times to make the gamepad keep sending interrupt messages even if the device is not in use.

-t timeout

Disconnect the device if it is not accessed for timeout seconds.

SETTING UP

Refer to the FreeBSD handbook for a guide on setting up Bluetooth. The gamepad initiates the connection, so the host has to be connectable, but need not be discoverable. The following options in /etc/defaults/bluetooth.device.conf are appropriate:

authentication_enable="NO"
connectable="YES"
discoverable="NO"
local_name=""

The gamepad uses a nonstandard Bluetooth pairing procedure. When it is plugged in over USB, the Bluetooth address of the host is set with a special USB request. The btsixad rc.d script handles this automatically.

The following options can be set in /etc/rc.conf:

btsixad_enable

Whether the daemon and automatic USB operations are enabled.

btsixad_pair

Whether to pair gamepads connected over USB automatically. All currently connected gamepads can be paired manually with

service btsixad pair

btsixad_bdaddr

The host address used for pairing the gamepad. Set this if you have multiple Bluetooth dongles, otherwise a default address is determined by

hccontrol read_bd_addr

btsixad_flags

Additional flags to pass to the daemon, e.g. -t 3600.

btsixad_uhid_min=0 and btsixad_uhid_max=15

Symlink uhid* devices in this range of unit numbers. SDL 1 only checks uhid0 to uhid3, SDL 2 checks uhid0 to uhid15. If a real uhid device is attached with the same number as a symlink, the real device will be obscured, so it may be useful to increase the minimum unit number.

THE GAMEPAD

The PS button (the round button in the center of the gamepad) initiates a connection. When it is pressed, all four LEDs start blinking while a connection is established. When connected, one of the LEDs corresponding to the device unit number either lights up continuously when the device is in use or flashes briefly when it is not. Holding the PS button for 10 seconds disconnects.

A connection should be established before starting any games because SDL enumerates joysticks on startup.

The daemon presents a custom HID descriptor to applications and slightly alters the input report to make the controller more useful without additional configuration. Buttons are numbered in the sequence: Square, X, Circle, Triangle, R1, L1, R3, L3 (analog stick clicks), Start, Select, PS. The D-pad is reported as a hat switch. The two analog sticks and the R2 and L2 triggers are reported as axes. None of the pressure or motion sensors are mapped.

SECURITY CONSIDERATIONS

Since Bluetooth authentication is not supported, a rogue Bluetooth device pretending to be a gamepad can connect to the daemon and provide inputs.

The inputs do not pass through the USB subsystem in the kernel, so there is no chance of, for instance, the keyboard driver binding to them. Furthermore, the way in which they are interpreted by programs is limited by the hardcoded HID descriptor provided by the daemon (and not by the device) to gaming controls and generic buttons.

Nevertheless, care should be taken with programs that translate such inputs into keyboard or mouse events.

SEE ALSO

bthidd(8), usbhidaction(1), uhid(4), cuse(3)

AUTHORS

btsixad was written by Andrey Zholos ⟨aaz@q-fu.com⟩