Ubuntu Manpage: XWiimote - Nintendo Wii Remote Linux Device Driver

Provided by: xwiimote_0.3+20120630-5+fakesync_amd64

NAME

       XWiimote - Nintendo Wii Remote Linux Device Driver

DESCRIPTION

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. There are also tools to remap the
peripheral input to arbitrary system input so you can use Wii Remotes as input devices for any
application even if the desired application has no special Wii Remote support.

Connecting 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.

User-Space Tools
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.

If you want to remap the keys of the Wii Remote to other keys, use the xwiikeymap(1) utility. Further
tools are under development.

BlueZ wiimote plugin
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.

Wii Remote kernel driver
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.

libxwiimote
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 does not support
Wii Remotes explicitely you can still use the user-space tools like xwiikeymap(1) to map Wii Remote
buttons to arbitrary keys which then can be access as input device by any application which accepts
keyboard input.

However, if an application wants to use the IR or accelerometer sensors of a Wii Remote or if it requires
more advanced key-maps, then it should use libxwiimote to access connected Wii Remotes.

BUGS

   Connecting the Wii Remote requires PIN input
       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.

   The X-Server reacts weirdly on Wii Remote input
       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.

AUTHOR

       David Herrmann <dh.herrmann@googlemail.com>
       The XWiimote Project: http://github.com/dvdhrm/xwiimote

NAME

DESCRIPTION

BUGS

AUTHOR

SEE ALSO