Hack and /

Wiimote Control

Kyle Rankin

Issue #172, August 2008

Why let your Wii have all the fun? Find out how to connect your Wiimote to your computer and use it as a mouse or an input device for any number of popular gaming emulators.

If you think about it, there are almost as many ways to interface with your computer as there are Debian-based distributions—and that's a lot. Besides the trusty keyboard and optical mouse, there are trackpoint mice, touchpads, touchscreens, twiddlers, joysticks, presentation remotes and even devices that measure your brain waves. Although I mostly stick with my tried-and-true keyboard and trackpoint mouse (fingers on home row, thank you), when I started hearing about all the interesting things people were doing with the Wiimote (the main controller from the Nintendo Wii), I knew I had to give it a try.

Now traditionally, connecting a brand-new device to a Linux machine was an investment in Internet research, kernel module hacking, prayer and obscure programming skills I haven't used since college. I figured the mere fact that this was a Bluetooth device meant I was going to have to spend some quality time with hcidump. To my surprise, all the hard work already had been done for me, and I could connect and use a Wiimote on my laptop with only a few basic steps.

Configure udev

First, your kernel needs the uinput module available and loaded. This module is available in modern kernels, and my Ubuntu Gutsy install already had it. If you want to be able to connect to the Wiimote as a regular user, however, you need to add a new udev rule to extend permissions to the uinput device. I created a file called /etc/udev/rules.d/95-uinput.rules that contained the following:

KERNEL=="uinput", GROUP="plugdev"

Then, I made sure my user was a member of the plugdev group. If your system doesn't have a plugdev group, you could choose or create another group to use for this device. Next, run /etc/init.d/udev reload to make sure your changes are seen. Finally, I ran modprobe uinput to make sure the module was loaded, and I also added uinput to /etc/modules to make sure it was loaded at boot.

Install wminput

The next step is to install the wminput software. For me, this was simple, as wminput is packaged for my distribution; otherwise, you can download the source from the official site (www.cwiid.org). Then, make sure the Bluetooth device in your computer is enabled. For my laptop, I had to flip a switch on the side, but if you have an external USB Bluetooth adapter, for instance, now is a good time to plug it in. Finally, run wminput in a console and follow the directions:

greenfly@minimus:~$ wminput
Put Wiimote in discoverable mode now (press 1+2)...
Ready.

When you press buttons 1 and 2 on your Wiimote, it goes into discoverable mode, and the blue LEDs along the bottom start blinking. Sometimes you might not start discoverable mode fast enough, or wminput won't detect it, but as long as the LEDs on the Wiimote are blinking, it is still in that mode. So if wminput times out, just run the program again.

If you continually can't connect, you probably should double-check that your Bluetooth device is working. To do this, press buttons 1 and 2 on the Wiimote and then use hcitool to scan for the Wiimote. A successful scan will look like the following:

greenfly@minimus:~$ hcitool scan
Scanning ...
           00:1B:7A:3E:8C:54    Nintendo RVL-CNT-01

After wminput connects, you also can look in /var/log/dmesg for confirmation that the Wiimote is connected:

[ 1226.247203] usb 3-2: new full speed USB device using 
 ↪uhci_hcd and address 13
[ 1226.288768] usb 3-2: configuration #1 chosen 
 ↪from 1 choice
[ 1227.922403] input: Nintendo Wiimote as 
 ↪/devices/virtual/input/input21

Use the Wiimote as a Mouse

Once the Wiimote is connected, the default bindings use it as a mouse. The accelerometers in the Wiimote are used to move the mouse pointer, so if you point the Wiimote down or up, the mouse will move down or up, respectively, and if you roll the Wiimote to the left or right, the mouse will move left or right, respectively. If you look at /etc/cwiid/wminput/buttons, you can see the default mappings:

Wiimote.A               = BTN_LEFT
Wiimote.B               = BTN_RIGHT
Wiimote.Up              = KEY_UP
Wiimote.Down    = KEY_DOWN
Wiimote.Left    = KEY_LEFT
Wiimote.Right   = KEY_RIGHT
Wiimote.Minus   = KEY_BACK
Wiimote.Plus    = KEY_FORWARD
Wiimote.Home    = KEY_HOME
Wiimote.1               = KEY_PROG1
Wiimote.2               = KEY_PROG2
...

By default, wminput reads the configuration listed in /etc/cwiid/wminput/default to get its mappings. In this file you will see:

#acc_ptr

include buttons

Plugin.acc.X    = REL_X
Plugin.acc.Y    = REL_Y

Essentially, this file includes the buttons file for keybindings, and it also enables the use of the accelerometers for X and Y movements. The great thing about wminput is that all these mappings are completely configurable. If you look in /etc/cwiid/wminput, you should see a number of other example mappings you can use as inspiration. You also can store custom mappings in your home directory under ~/.cwiid/wminput. The button mappings use standard names for keys and mouse buttons that can be found in /usr/include/linux/input.h, but most of the names are pretty straightforward.

Wiimotes for NES Emulation

One of the first things I wanted to do with my Wiimote after it was connected was to use it as a controller for my various game system emulators. But, before I go any further, if you do use a game system emulator like nestra, fceu, snes9x or MAME, be sure you have full rights to use any ROMs you might have. Make an appointment with your lawyer for details, but essentially, to play a commercial ROM, you should own the corresponding game.

With the legal disclaimers aside, the Wiimote makes a great wireless NES (Nintendo Entertainment System) controller. All the basic buttons are there, and all that's left to do is rearrange the button mappings to work with either nestra or fceu NES emulators. Both programs use slightly different mappings, so I created files called buttons-fceu and buttons-nestra and placed them in ~/.cwiid/wminput. First, buttons-nestra:

Wiimote.A               = KEY_0
Wiimote.B               = KEY_1
Wiimote.Up              = KEY_LEFT
Wiimote.Down    = KEY_RIGHT
Wiimote.Left    = KEY_DOWN
Wiimote.Right   = KEY_UP
Wiimote.Minus   = KEY_TAB
Wiimote.Plus    = KEY_ENTER
Wiimote.Home    = KEY_PAUSE
Wiimote.1               = KEY_Z
Wiimote.2               = KEY_SPACE

After I set the regular NES buttons, I had a few extra to bind, so I bound the A button to pause the emulator, the B button to set nestra to normal speed and the home button to reset the game.

The fceu emulator had completely different keybindings, so here is my buttons-fceu file:

Wiimote.A               = KEY_F7
Wiimote.B               = KEY_F5
Wiimote.Up              = KEY_A
Wiimote.Down    = KEY_S
Wiimote.Left    = KEY_Z
Wiimote.Right   = KEY_W
Wiimote.Minus   = KEY_TAB
Wiimote.Plus    = KEY_ENTER
Wiimote.Home    = KEY_F10
Wiimote.1               = KEY_KP2
Wiimote.2               = KEY_KP3

In addition to the standard buttons, I bound the B button to save a game state, A to restore and home to reset the game.

Now, to use either of these configuration files, all I need to do is tell wminput to load these files instead:

greenfly@minimus:~/$ wminput -c ~/.cwiid/wminput/buttons-nestra 
Put Wiimote in discoverable mode now (press 1+2)...
Ready.

Because wminput sends regular keyboard events, I don't have to do anything special to nestra or fceu.

Wiimotes for SNES Emulation

The Wiimote worked great for NES games, but how about SNES (Super Nintendo) emulation? I actually purchased a few different SNES games for the Wii virtual console, and I also bought a Classic Controller so I would have all the standard SNES buttons. It turns out that wminput also can bind keys to the Nunchuck and Classic Controller attachments, so all I had to do for it to work with snes9x was create a new configuration file that mapped all the keys. Here is my buttons-snes9x file:

Wiimote.A               = KEY_X
Wiimote.B               = KEY_S
Wiimote.Up              = KEY_LEFT
Wiimote.Down    = KEY_RIGHT
Wiimote.Left    = KEY_DOWN
Wiimote.Right   = KEY_UP
Wiimote.Minus   = KEY_TAB
Wiimote.Plus    = KEY_ENTER
Wiimote.Home    = KEY_ESC
Wiimote.1               = KEY_C
Wiimote.2               = KEY_D

Nunchuk.C               = BTN_LEFT
Nunchuk.Z               = BTN_RIGHT

Classic.Up              = KEY_UP
Classic.Down    = KEY_DOWN
Classic.Left    = KEY_LEFT
Classic.Right   = KEY_RIGHT
Classic.Minus   = KEY_SPACE
Classic.Plus    = KEY_ENTER
Classic.Home    = KEY_ESC
Classic.A               = KEY_D
Classic.B               = KEY_C
Classic.X               = KEY_S
Classic.Y               = KEY_X
#Classic.ZL             = 
#Classic.ZR             = 
Classic.L               = KEY_A
Classic.R               = KEY_Z

Even though I planned to use the Classic Controller, I tried to map as many of the regular Wiimote keys to buttons that made sense, so you could potentially play at least some games with the regular Wiimote as well. If you notice, I also left bindings for the special ZL and ZR keys blank, so you could bind them to extra keys.

Wiimote Control for MAME

One of the best game system emulators out there is MAME. MAME emulates classic arcade games, and there are many guides out there (including in Linux Journal itself) on how to use MAME to create your own arcade cabinet. Well, I haven't cleared away the time for that project yet, but I did want to use my Wiimote and Classic Controller attachment for MAME games. MAME has a large number of bindings (press Tab in MAME to see a list), so it was difficult to choose which to bind to the extra keys. Here is a sample buttons-xmame file I created:

Wiimote.A               = KEY_P
Wiimote.B               = KEY_5
Wiimote.Up              = KEY_LEFT
Wiimote.Down    = KEY_RIGHT
Wiimote.Left    = KEY_DOWN
Wiimote.Right   = KEY_UP
Wiimote.Minus   = KEY_2
Wiimote.Plus    = KEY_1
Wiimote.Home    = KEY_F3
Wiimote.1               = KEY_LEFTCTRL
Wiimote.2               = KEY_LEFTALT

Nunchuk.C               = BTN_LEFT
Nunchuk.Z               = BTN_RIGHT

Classic.Up              = KEY_UP
Classic.Down    = KEY_DOWN
Classic.Left    = KEY_LEFT
Classic.Right   = KEY_RIGHT
Classic.Minus   = KEY_2
Classic.Plus    = KEY_1
Classic.Home    = KEY_F3
Classic.A               = KEY_LEFTCTRL
Classic.B               = KEY_LEFTALT
Classic.X               = KEY_SPACE
Classic.Y               = KEY_LEFTSHIFT
Classic.ZL              = KEY_5
Classic.ZR              = KEY_P
Classic.L               = KEY_Z
Classic.R               = KEY_X

In addition to the standard bindings you might expect, the home key resets MAME; the plus key selects single player; minus selects two players; ZL on the Classic Controller and B on the Wiimote insert a coin; and ZR on the Classic Controller and A on the Wiimote pause. These are by no means perfect bindings, so I recommend you experiment with different keys that work better for you.

The possibilities with wminput go much further than what I've presented here. There also are configuration files that use the analog joystick inputs on the Classic Controller, the IR sensors on the Wiimote and the accelerometers on the Nunchuck. Wminput isn't just a handy way to play video games on your laptop or desktop. The fact that the connection to the computer is wireless makes the Wiimote a great gaming input for a MythTV client or other computer connected to your PC. As for me, I think I'll be spending a few more days trying to beat this impossible Super Mario Brothers hack that has been floating around the Internet.

Kyle Rankin is a Senior Systems Administrator in the San Francisco Bay Area and the author of a number of books, including Knoppix Hacks and Ubuntu Hacks for O'Reilly Media. He is currently the president of the North Bay Linux Users' Group.