The XWiimote software stack is an approach to write Linux drivers for the Nintendo Wii Remote. Long time cwiid and wiiuse were the only choices to use Wii Remotes under Linux. However, both tools very badly designed. They require the application that uses the device to perform a Bluetooth inquiry, connect to the device and run a user-space driver instead of adding the device to the Linux input devices and let applications use them with well-defined APIs like linux-input / evdev. An application does not need to connect to keyboards by itself so why should it need to connect to Wii Remotes? Also the libraries provided by both projects either required threads or global objects which is horrible to use in most applications. This is why the XWiimote project was created.

The XWiimote project consists of:

  • hid-wiimote.ko: This is the kernel HID driver for Wii Remotes. It is available upstream since linux-3.1. With linux-3.11 full extension support is also available. Development takes place at linux-input@vger.kernel.org. See the source code for more information. The driver provides generic access to the Wii Remote protocol and needs no configuration. It is available in most distributions by default. Load it with `modprobe hid-wiimote`.
  • BlueZ wiimote plugin: The BlueZ stack is the official Linux Bluetooth stack. It is available in all major distributions. Since bluez-5 it contains a wiimote plugin. It allows pairing with Wii Remotes like with any other Bluetooth device. Wii Remotes do not follow the Bluetooth specification recommendations so this plugin is needed. If you run an older BlueZ version or if your Wii Remote is not detected as a Wii Remote, you can simply connect without Pairing/Bonding and everything should work fine without that plugin.
  • xwiimote tools: The xwiimote-tools are the user-space part of the driver. They are not required but can hide the complex kernel API behind an easy library API (libxwiimote). They also provide handy tools like xwiishow which help testing Wii Remote connections. I includes several man-pages about the software and should be the main entry point if you want more information about the whole XWiimote software stack.
  • xf86-input-xwiimote: Wii Remotes can be used as input devices for all kind of applications. However, most Linux systems use X.Org as desktop environment. Therefore, we wrote an input driver for X.Org. It can provide mouse-emulation and several other handy features based on Wii Remotes. See its man-page (man xorg-xwiimote) for the many configuration options.

The software is extended regularly and all contributions are welcome. Following a collection of useful links about XWiimote:

8 thoughts on “XWiimote

  1. Franz


    I just played around a bit with xwiimote. Do you know, what are the max values for x and y read_ir will return?


    1. David Herrmann Post author

      x=[0-1023] and y=[0-768]. If both are set to 1023, the input is invalid, which means the IR cam wasn’t able to track an IR light. Up to 4 lights can be tracked. Also see ./tools/xwiishow.c which is a small example for all supported peripherals.

  2. jamiemacdo

    I installed xf86-input-xwiimote and xwiimote userspace tools, and I’m using bluez 5.5 and linux 3.9. I’m able to connect to the wiimote and use all the functionality described in the xf86-input-xwiimote man page, but it doesn’t describe mouse emulation based on the IR sensor (it mentions MotionSource=accelerometer or MotionPlus). Is the IR-based mouse feature missing?

    1. David Herrmann Post author

      It’s not implemented. I don’t have any external IR emitters so I hadn’t had any chance to implement+test it. The xwiishow tool does visualize IR input, though. If anyone is willing to implement a state-machine that emulates mouse-positions by IR input, I am more than willing to merge it.

  3. Flavio

    Hi David,

    First of all, thank you very much for your work with xwiimote!
    I installed it from ubuntu software center (Ubuntu 14.04).
    Using jstest-gtk I can see that the buttons (except for directional control) are working.
    However, what I really need is the data from the accelerometer and jstest-gtk gives 0 axes for my wiimote. Also, the leds keep blinking and it is driving me crazy šŸ˜€

    I would appreciate any help.
    Thanks in advance.


    1. David Herrmann Post author

      I’m not sure what I should tell you. Accelerometer data is reported through a separate input device called “Nintendo Wii Remote Accelerometer”. If jstest-gtk doesn’t visualize it, I cannot help you. It’s there, you just have to access it directly.
      Btw., a wiimote is *not* a joystick, so jstest is probably never gonna recognize it properly.

      1. Flavio

        Thank you for the fast reply.

        In ‘configurations’ -> Bluetooth it appears as a joystick, that is why I thought I could test it with jstest.
        When I run xinput –list I can’t see anything related to the wiimote.

        Can I read the accelerometer state from a file (or files), like:
        /sys/devices/pci0000:00/0000:00:14.0/usb2/2-4/2-4:1.0/bluetooth/hci0/hci0:35/0005:057E:0306.0008/input/input28/FILE_NAME ?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s