XWIIMOTE(7)

🎀 XWIIMOTE(7) 🎀

okay bestie, buckle up — this is the manual page for XWiimote, which lives in section 7 of the manual (that's the "miscellaneous" section, iykyk). Nintendo Wii Remote Linux Device Driver. yeah. we're doing Wii Remotes on Linux. it's giving 2006 but make it open source 💅

---

✨ NAME ✨

XWiimote — the Nintendo Wii Remote Linux Device Driver 🎮

---

💖 DESCRIPTION 💖

so the XWiimote driver + utilities are literally your whole kit for connecting a Nintendo Wii Remote to your computer. the ensemble cast is:

• a linux kernel driver
• a BlueZ Bluetooth plugin
• some user-space utilities

and together they replace the old user-space drivers like cwiid or wiiuse. out with the old, in with the slay ✨

Since bluez-4.96 the wiimote plugin is available upstream, which means you should be able to pair your Wii Remote like any other Bluetooth device. iconic. and if pairing fails? no stress, just connect the Wii Remote without pairing/bonding. it's fine. we move.

The linux kernel driver for the Wii Remote has been available since linux-3.1, and full support for Wii Remotes since linux-3.3. it's called hid-wiimote and it requires the HID core drivers to be loaded. no configuration is needed for the driver and plugin — zero. none. nada. she configures herself 💅

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.

---

🦋 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 that your kernel has the hid-wiimote kernel plugin loaded. then just connect your Wii Remote like any other Bluetooth device. the system log (dmesg) should print some messages about the new connected device — that's your little confirmation text, bestie 🫶

You can put the Wii Remote 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! (fr fr, trust the red button.)

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 info 👀

And if that doesn't 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. built different.

---

🌸 User-Space Tools 🌸

If you have a Wii Remote connected to your host, you can test it with the xwiishow(1) application. but if you do not have the xwiimote user-space tools installed, you can still 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

and you can retrieve kernel information about the device by reading the files in this directory. detective mode activated 🔍

---

💜 BlueZ wiimote plugin 💜

Since bluez-4.96 the bluetooth daemon includes a special wiimote plugin which handles wiimote pairing requests. So if you pair a Wii Remote, the plugin will automatically generate the right PIN and pair the device — she does the math for you, periodt ✨

If you are asked for PIN input, then either you 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.

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. like, genuinely. don't be out here running ancient kernels bestie 😭

---

⭐ 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 use special Wii Remote functionality, we developed the libxwiimote(7) library which provides an easy API to manage connected Wii Remotes. she's the friendly wrapper, the emotional support library 🫶

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.

---

💀 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. (not their fault, not your fault, it's just like that.)

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. do your part, bestie 🫡

---

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

careful though — 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. no cap.

---

👑 AUTHOR 👑

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

---

🌈 SEE ALSO 🌈

• libxwiimote(7)
• xwiishow(1)

---

okay that's the whole page!! this one was written by David Herrmann, and the version/date on the tin is August 2013 — so yeah, vintage but still eating. go pair your wiimote, you got this 💖✨🎀🦋🌸