| XWIIMOTE(7) | Wii Remote Driver | XWIIMOTE(7) |
XWiimote - Nintendo Wii Remote Linux Device Driver
The XWiimote driver and utilities can be used to connect a Nintendo Wii Remote to your computer. It consists of a linux kernel driver, a BlueZ Bluetooth plugin and user-space utilities. They replace the old user-space drivers like cwiid or wiiuse.
Since bluez-4.96 the wiimote plugin is available upstream and you should be able to pair your Wii Remote like any other Bluetooth device. If pairing fails, simply connect the Wii Remote without pairing/bonding. The linux kernel driver for the Wii Remote is available since linux-3.1 and full support for Wii Remotes since linux-3.3. It is called hid-wiimote and requires the HID core drivers to be loaded. No configuration is needed for the driver and plugin.
The user-space utilities provide a library that can be used to monitor and access connected Wii Remotes and they provide several applications to manage connected Wii Remotes.
To connect a Wii Remote to your host be sure that the official linux Bluetooth stack (BlueZ) is installed on your system and your kernel has the hid-wiimote kernel plugin loaded. Then connect your Wii Remote like any other Bluetooth device. The system log (dmesg) should print some messages about the new connected device.
The Wii Remote can be put into discoverable mode by pressing the red sync-button behind the battery cover on the back. The Wii Remote will stay in discoverable mode for 20s. You can also hold the 1+2 buttons to put the Wii Remote into discoverable state. However, the first method works more reliably! If you are asked for PIN input while bonding the devices, then your BlueZ bluetoothd daemon does not include the wiimote plugin. See Bugs below for more information. If this does not help, you can still connect to your Wii Remote without pairing/bonding (i.e. not using authentication with a PIN). This should work with any BlueZ version.
If you have a Wii Remote connected to your host you can test it
with the xwiishow(1) application. However, if you do not have the
xwiimote user-space tools installed, you can find Wii Remotes with
ls /sys/module/hid_wiimote/drivers/hid:wiimote/
They are listed there with their device ID inside that directory. For example
/sys/module/hid_wiimote/drivers/hid:wiimote/0005:057E:0306.0001
You can retrieve kernel information about the device by reading the files in
this directory.
Since bluez-4.96 the bluetooth daemon includes a special wiimote plugin which handles wiimote pairing requests. If you pair a Wii Remote, the plugin will automatically generate the right PIN and pair the device. If you are asked for PIN input, you either do not have this plugin installed or your device is not detected. See BUGS for troubleshooting Wii Remote connection problems.
The wiimote kernel driver is available since linux-3.1 in the official linux kernel. Since linux-3.2 the accelerometer and IR sensor are supported. Since linux-3.3 extension support is available. There is no need to configure this driver. All configuration should be done in the user-space utilities. The kernel driver provides a simple abstraction layer which does not need any configuration.
With linux-3.11 the driver was rewritten to support extension hotplugging, device detection and more advanced functionality. It is highly recommended to use a kernel version greater than, or equal to 3.11.
The kernel API for the Wii Remote is quite complex. It is
documented in the xwiimote source repository in doc/INTERFACE
To help application developers to use special Wii Remote functionality, we
developed the libxwiimote(7) library which provides an easy API to
manage connected Wii Remotes.
If an application wants to use the IR or accelerometer sensors of a Wii Remote or if it requires advanced key-maps, it should use libxwiimote to access connected Wii Remotes.
If you are asked for PIN input while connecting your Wii Remote then you either do not have the BlueZ wiimote plugin installed or your device is not detected as a Wii Remote. This might happen with 3rd party Wii Remotes which are not sold by Nintendo. You can still use these devices by connecting them without pairing or bonding. Tools like gnome-bluetooth require you to select "Use no PIN" to connect devices without pairing/bonding.
There are attempts to improve the detection of Wii Remotes in BlueZ. If you are sure that your device is not detected properly, please report a bug upstream.
By default the X-Server opens all input devices that are available
on your machine. The Wii Remote input devices are very useless without a
proper keymap so you should instruct your X-Server to ignore raw Wii Remotes
input devices. The xwiimote source repository contains an xorg-config file
res/50-xorg-disable-wiimote.conf which can be installed into
/etc/X11/xorg.conf.d/ to ignore all raw Wii Remote input devices.
This only ignores raw Wii Remote devices. If you used some of the user-space
utilities to remap the buttons then the new devices will still be detected
by your X-Server.
David Herrmann <dh.herrmann@googlemail.com>
The XWiimote Project: http://dvdhrm.github.io/xwiimote
| August 2013 | David Herrmann |