Nintendo Wiimotes

Background

Wii Homebrew

Nintendo's release of the Wii in 2006 sparked the formation of a homebrew culture to hack the console's hardware. Projects have included "jailbreaking" the Wii to run third-party software, and emulating the Wii environment on a PC. The Wiibrew wiki contains an incredible amount of information about Wii internals, and tutorials on getting started with homebrew development.
For the purposes of this class, we will focus on using the Wii remote as a controller for other devices.

Wiimote Basics

The Wii remote communicates through Bluetooth, making it possible to connect to any Bluetooth-enabled device. The remote has two distinct motion sensing capabilities: a three-dimensional accelerometer to sense orientation and movement, and an infrared receiver to allow the remote to be used as a cursor.
The accelerometer works out-of-the-box; with the appropriate drivers and software, any application can grab accelerometer data.
Infrared tracking, however, requires a "sensor bar." The name is misleading; the bar is actually a signaling device that simply contains five infrared LEDs on opposite sides. The remote's IR receiver can determine the distance from the emitters and triangulates its location relative to the sensor. In the presence of any such infrared source--even candles work!--the remote will send IR data to the console.

Additional Resources

Wikipedia: Wii Remote
Good overview of the design of the Wii Remote and its functionality.
Wiibrew: Wiimote
Incredibly detailed low-level specification of the Wii Remote. Includes specialized Bluetooth protocol and raw accelerometer output information. You'll hopefully never need this much detail; this is entirely abstracted by the Wiiuse library.
Instructables: USB Sensor Bar
A guide to build your own sensor bar. There are many different guides on instructables.



Working with the Wiimote

There is a great variety of frameworks and ways to work with the wiimote. This page covers how to get running in various frameworks, and some of the advantages of working in them.

Getting set up

The first step is to connect a wiimote to your computer via bluetooth. The exact procedure varies based on your hardware and driver provided software. Generally, you'll need to:
  • Install or turn on your bluetooth adapter, and ensure you have proper drivers to use it.
  • Hold down the 1 and 2 buttons on the wiimote. You should see an led flashing at the bottom of the wiimote. Continue to hold them through the next step.
  • Windows: On your computer, choose to add a new bluetooth connection with your driver software.
  • Linux: Simply run a program that will connect to the wiimote.
  • Once the computer establishes the connection, you can let go of the buttons.

Standalone Test Programs

These simply show output from your wiimote, and are an easy way to get familiar with the wiimote's capabilities. Just download and run them after connecting your wiimote.

Here are a few we found:

Libraries

Only a few few libraries are investigated here. A more comprehensive list can be found at http://wiibrew.org/wiki/Wiimote/Library.

Wiiuse, Wiiusecpp, Pywii


Wiiuse is a full featured C library that supports Windows and Linux. Wiiusecpp and Pywii are c++ and python wrappers around wiiuse.
Wiiuse: http://sourceforge.net/projects/wiiuse/files/wiiuse/v0.12/
Wiiusecpp/pywii: http://www.missioncognition.net/software/wiiusecpp.html

Installing on Windows

  1. Download and install Wiiuse.
  2. Download and install Visual Studio. You can get the full product at Dreamspark or just use an express version.
  3. Download and install Python. 2.6 or 2.7 is preferred, since these are also the versions that work with Kinect.
  4. Download WiiuseCpp/Pywii.
  5. You will need two makefiles to compile the library and example. The makefile for WiiuseCpp can be found here, the makefile for Pywii can be found here. Make sure to edit the makefiles with correct paths!
  6. Compile the source. See Compiling with Visual Studio for details. Since the example is a single cpp file, you can just open it in Visual Studio and compile from the IDE. Make sure to include the Wiiuse and Wiiusecpp dependencies if you choose to do this.
  7. Link your wiimote to a computer with Bluetooth. To enable the Wiimote's Bluetooth search mode, hold down the wiimote's 1 and 2 buttons.

You can now run example.exe (compiled from C++) or example.py.

Installing on Linux

You will have to build all the libraries from source.
  1. Download Wiiuse, WiiuseCpp and Pywii.
  2. Insert the line "memset(&addr, 0, sizeof (addr));" at line 174 of io_nix.c in the wiiuse src folder. This fixes a problem when running the pywii example.
  3. You may need the following packages to compile (these are for Ubuntu 10.10):
    "python2.6-dev libssl-dev swig freeglut3-dev libglut3-dev freeglut3 libsdl1.2-dev libaudio-dev libpulse-dev libxt-dev libesd0-dev libavahi-client-dev libcaca-dev libdbus-1-3 libdbus-1-dev libasound2-dev libaudiofile-dev libavahi-common-dev libaa1-dev libncurses5-dev libslang2-dev libglu1-mesa-dev libgl1-mesa-dev libglw1-mesa-dev libglw1-mesa mesa-common-dev libdrm-dev libkms1 libbluetooth-dev python-bluez bluez-utils bluez-compat bluetooth"
  4. Build and install Wiiuse: "make" then, as root, "make install".
  5. Build and install WiiuseCpp/Pywii: "make" then, as root, "make install".
  6. You should now be able to run all of the wiiuse, wiiusecpp and pywii examples. After starting any, hold down the wiimote's 1 and 2 buttons to enable bluetooth search. If the examples connect successfully, they rumble the wiimote before continuing. You can now let go of the 1 and 2 buttons.

Advantages/Disadvantages

Broad language support.
Nice abstractions: it exposes a simple to use IR cursor coordinate, for example.
Windows and Linux support. You could probably get it working on a Mac.
Not the easiest to install.

Verdict: A solid choice for linux. It's a pain to get working on Windows, though.

WiimoteLib

Well maintained and created with .net, it's the library of choice for Johnny Chung Lee's well known projects. It supports Windows.
http://wiimotelib.codeplex.com/

Installing on Windows
  1. Download a version of Visual Studio to work in. This can be one of the express versions, or the full product, which you can get through Dreamspark.
  2. Download wiimotelib.
  3. To test: just run wiimotetest.exe; to see example code: open one of the example projects in visual studio; to use: add a reference to wiimotelib.dll in a visual studio project.

Advantages
Easy install.
Lots of example code through Johnny Lee.
Beta support for Wii MotionPlus.

Verdict: The best choice if you're on windows.

CWiid


CWidd is another C library that supports only linux. There is also python support.
http://abstrakraft.org/cwiid/

It's in the Ubuntu repositories, but broken. You'll want to install from source.

Installing From Source

  1. Download CWiid.
  2. After unpacking, edit line 125 of bluetooth.c from: "if (hci_remote_name(sock, &dev_list[i].bdaddr, BT_NAME_LEN," to "if (hci_read_remote_name(sock, &dev_list[i].bdaddr, BT_NAME_LEN,"
  3. If you don't have them, install flex and bison.
  4. Build and install: "./configure" then "make" then "sudo make install"
  5. You should now be able to run all of the included files.

Advantages

Nice set of included programs. Notable are wminput, which allows you to use the wiimote as your mouse, and wmgui, which shows a nice gui displaying the wii's current info.
Allows access to accelerometer calibration data, which we didn't find in the other frameworks.

Verdict: Solid, but seems dated compared to Wiiuse. It may be a better choice for heavy accelerometer use, though.



Our Experience


Our initial challenge was getting the frameworks working. We originally planned on investigating more, but we simply couldn't get some to compile. Those that did sometimes required fixing source code on our own. Our experience here will be useful for future wiimote hackers.

Once we had working frameworks, we started off with Pywii. Our original intention was to create a simple music sequencer (like http://www.chemicalgdns.co.uk/fun/lets-make-a-record). However, the IR tracking using Pywii's cursor abstraction seemed very poor. The signal was intermittent and sometimes nonexistant. Trying other wiimotes and a real sensor bar didn't help. Since we only had a week, we decided to move to switch frameworks and try to use the accelerometer instead.

CWiid worked well with the accelerometer. However, it seemed to be giving values with no particular scale. We decided to investigate whether we could normalize the values to something sane, like m/s^2. We could then use this to calculate velocity and displacement, which would be interesting. (we later found out this had already been done: http://convolutedlogic.com/projects/wiimote/index.htm)
After finding some code accessing the calibration data, we found we could get a value that was 1 at rest, 0 in free-fall, and greater than 1 when moving up. The wiimote returns acceleration in g-force.

Having solved that mystery, we were again left without a project idea. Having seen the IR tracking work in the test applications above, we decided to revisit the IR features in Pywii. We eventually got it working well. The sensor bar was shorting out, we needed to move farther away from it, and our testing code was broken.

This led us back to our original idea, but there wasn't time to implement it. We decided instead on a simple drawing application which would utilize all of the main features of the platform: the IR, the accelerometer, and the buttons.