From WiiBrew
Jump to navigation Jump to search

Input interpreters

The Wiimote appears to use the USB HID class to communicate with the Wii. It also supports SDP.

Windows library

Linux XWiimote

XWiimote is a new kernel driver for Wii Remotes. It is available in the Linux kernel since linux-3.1. See [1] for more information.

Linux CWiid

CWiid is a collection of Linux tools written in C for interfacing to the Nintendo Wiimote. It contains a library (libcwiid), an event mouse joystick driver with plugin architecture (wminput), a GUI control panel and test application (wiigui) and a test/demo application (wiidemo).

Download: http://abstrakraft.org/cwiid/

While the original library ceased to be developed around 2010, in 2011 it has been forked by the Linux Laptop Orchestra (L2Ork) project (http://l2ork.music.vt.edu) and has since been upgraded to provide comprehensive support for all Nintendo brand Wii controllers, including Wiimote, Nunchuk, MotionPlus, Classic, Wii Fit board, and the newer version of the Wiimote with MotionPlus Inside. In addition, the library also offers support for interleaved passthrough mode that is necessary when both MotionPlus and an extension are connected (e.g. MotionPlus and Nunchuk). The forked library is a part of L2Ork's pd-l2ork software github repository (https://github.com/pd-l2ork/). It can be also downloaded as a source tarball from L2Ork's website (http://l2ork.music.vt.edu/main/?page_id=56).

Download #1 (github): https://github.com/pd-l2ork/ Download #2 (tarball): http://l2ork.music.vt.edu/main/?page_id=56

Linux test application

Wiimotulator.py doesn't deserve to be called a driver... It's a very poorly written proof of concept, which I rushed to do in a few hours with no prior knowledge of bluetooth. It works under Linux. You need pybluez.

Get wiimotulator.py now!

Linux Wiimote-to-joystick daemon

Using wm2js you can use your Wiimote like a normal Joypad (/dev/input/jsX). The daemon is written in C and needs libbluetooth (bluez) and uinput support

Download: http://spam.workaround.ch/wm2js/

The Managed Library for Nintendo's Wiimote may be adaptable to Mono.

NI LabVIEW Wiimote drivers (VIs)

Several alternatives are available for NI LabVIEW-based interfacing with Wiimote(s).

  1. Example VIs with instructions that invoke the Wiimotelib managed library mentioned above
  2. Driver VIs available through a posting on the NI discussion forum

WiiRemoteJ, a Java library for the Wii Remote

WiiRemoteJ is a pure Java Library developed to allow Java developers easy access to the Wii Remote hardware. WiiRemoteJ sits on top of the Java Bluetooth API, JSR-082, allowing it to be platform-independent.

WiiRemoteJ supports all major features of the Wii Remote, including: IR, accelerometer, extensions (Classic Controller, Nunchuk, and Guitar supported by default; custom extensions possible), button input, LEDs, vibration, speaker, data read/write, and multiple remote support. WiiRemoteJ also supports the Balance Board.

Download: WiiRemoteJ

Mirror: WiiRemoteJ

motej Java library

motej is an Apache licensed JAVA library for the wiimote.

Download: http://motej.sourceforge.net

Wiiuse C Linux/Windows library

Wiiuse is a library written in C that connects with several Nintendo Wii remotes. Supports motion sensing, IR tracking, nunchuk, classic controller, and the Guitar Hero 3 controller. Single threaded and nonblocking makes a light weight and clean API.

Interprets data collected into meaningful information (ie, joystick angles, true x,y position based on IR sensor bar, etc).

The original project at http://wiiuse.net seems to have gone inactive. However, an updated friendly fork exists on Github:

Download: https://github.com/rpavlik/wiiuse

WiiuseJ Linux/Windows Java library

WiiuseJ is a java API to use wiimotes on your computer. This API is built on top of the excellent API wiiuse using JNI.

WiiuseJ intents to be a very simple, easy to use and lightweight java API for wiimotes and delivers most of wiiuse features. Download: http://wiiusej.googlecode.com/

WiiuseCpp / PyWii Linux/Windows C++ and Python library

WiiuseCpp is a C++ API built on top of wiiuse. PyWii is a Python SWIG wrapper of WiiuseCpp which is included with that library distribution.

WiiuseCpp / PyWii makes wiiuse object oriented and provides functions for interfacing with wiiuse's structure functionality. The goal of PyWii is to be the first feature complete, cross platform, and easy to use Python library for the Wii.

Download: http://missioncognition.net

Python HTDP Driver

Developed as part of Google Summer of Code 2008, the Python HTDP Driver is a python tool for tracking IR points in 3D using the wiimote. A single remote can be used for 'head tracking' or two remotes can be used together to track LEDs in full 3D. Currently, only Linux is supported but ports Mac and Windows would only require small changes.

Download: http://code.google.com/p/htdp/

Video: http://www.youtube.com/watch?v=omNQAzBa0-I

Device Drivers

HID Wiimote

HID Wiimote is a Windows Device Driver for the Wii Remote. The driver fixes the communication issue with the default HID driver, so it is recognized as native game controller exposing its inputs. Therefore the Wii Remote can then be used as a normal game controller to play games.

Download and Documentation: http://julianloehr.de/educational-work/hid-wiimote/

Current status

Connection to the Wiimote using hidd, sdptool, and hcitool all work. SDP and HCI seem to work correctly but there seems to be some problems with HID.

A connection can be set up using hidd --connect <bdaddr> afterwards button presses can be seen by running hcidump -X. The kernel registers the connection and creates a event file for the controller in /dev/input/. The connection can later be destroyed using hidd --kill <bdaddr> or hidd --unplug <bdaddr>.

To write HID commands to the wiimote you'll need to patch bluez-utils-2.25/hidd/main.c and recompile. Afterwards do mkfifo /tmp/hid and then write data of the form '%x %x %x ..' to /tmp/hid after connecting with hidd.

Patch: http://spenceal-3.student.rose-hulman.edu/linked/hidd.diff

HID specs

LED's are controlled using a SET_REPORT HID request on Output channel 11. The left 4 bits are the only ones that matter and correspond (in order) to the LED's.

Force feedback can be turned on and off using a SET_REPORT HID request on a either Output channel 10, 11, 13, 14, 15, or 19. Using channel 11 is not advised since it messes with LED's. To turn force feedback on set the least significant bit to 1.

Linear force data can be logged using a SET_REPORT HID request on Output channel 12. The first parameter is a force feedback parameter while the second must be 31. Some other 3X numbers work for the 2nd parameter and do different things, but I'm not sure what exactly. Logging can be turned back off using 30. (example to turn logging on: 52 12 02 31) When logging data data with 31 the last 3 bytes of data represent the forces with ~80 being 0 force. The 1st bit represents the side to side force, the 2nd is the lengthwise force and the 3rd is the up-down force.

The 3x number seems to set the Report type returned, and the valid selections (and report lengths) match the input reports in the Wii Bluetooth Specs#HID Descriptor. Selecting either 0x3e and 0x3f causes the wiimote to return alternating 3e and 3f reports.

See Wii Bluetooth Specs#HID Descriptor for a decoding of the HID descriptor block reported by the Wiimote.


Linear force data can be logged using a SET_REPORT request, however rotational data currently can not be logged. Both are needed in order to obtain decent positions due to the force of gravity. There's a chance that the calculations are done in the wiimote at not sure how to set it to do so. (There's evidence that the controller only has a 3-axis sensor, so any rotation information may need to come from interpretation of the 3-axis sensor readings, possibly combined with the sensor bar position reading...) The speaker does not work but may be controlled with a SET_REPORT HID request.


Can someone attempt to capture some of the communication that happens between the Wiimote and the Wii during synchronization? Using hcidump (from the bluez project) could be useful. Data regarding the Wii's bluetooth capabilities. Attempt to initiate a connection to the Wii acting like a Wiimote and see how it responds. Port to unix (for OS X) when linux driver is done Examine the Japanese WiinRemote software

Linux driver architecture and ideas

The Linux Wiimote driver, wiimoted, will be based on hidd. It will run in userland and will require no extra kernel modules. wiimoted will automatically or manually connect to discoverable wiimotes. It will set the LEDs to something sensible.

There is no reason to have a 4 remote limit; let's allow for the 7 devices maximum that Bluetooth supports (using LED combinations, for example: LEDs 1 through 4 will be used as expected, followed by two on the left for the fifth remote, two on the right for the sixth, and finally all four for the seventh).

wiimoted will expose a socket interface for other programs to connect to it. Using ASCII or binary communications is up for debate.

Programs which connect to wiimoted can choose to associate themselves with any combination of remotes available to wiimoted, and will be able to query their capabilities, accessories, etc. Each wiimote will be considered a separate entity, and all further aspects of communication with wiimoted are per-remote.

Programs may request any combination of features from the remote. Multiple clients may use the same remote at once. Since there are fundamental limitations in certain feature combinations, a priority mechanism must be designed.

Clients that connect to wiimoted will specify a priority level. Lower numerical values for priority are considered to take precedence over higher values (same as the UNIX process priorities). Negative values are allowed.

Note: the previous system discussed here was deemed too complicated and possibly inconsistent, and has been replaced with a simpler one.

Here is a proposed scheme to manage access to the different features. Each feature will be individually associated an open mode flag set. Three flags may be specified in any combination:

F_REQUIRED If this flag is set and the feature is not available at this time (with the constraints set by the other features), an error is returned. If the feature is revoked later due to a higher-prio client override and this flag is set, the whole connection to this Wiimote is closed with an error. Otherwise, while a feature is not available, a notification is sent to the client, but it is still kept open and pending, and the feature and data may be made available at a later time.
F_FORCE If this feature cannot be granted due to other clients, we are willing to force lower-prio clients into closing or disabling features (depending on the status of their F_REQUIRED flag). This won't work with higher-prio clients of course.
F_EXCLUSIVE We require to be the only users of the feature. The effects of this depend on the prior two flags. If F_FORCE is set, we might force lower-prio clients to pause or stop connections on this feature. If F_REQUIRED is not set, we don't get data even if it would be available, as long as other (lower-prio) clients are using the feature.

Features would be things such as F_BUTTONS, F_MOTION, F_IR_STD, F_IR_EXT, F_IR_FULL, F_FULLSPEED (pseudo-feature that excludes F_IR_FULL since it halves speed - note that F_EXCLUSIVE is meaningless here), F_EXT_BUTTONS, F_EXT_MOTION, F_EXT_ANALOG, etc.

The algorithm for this simplified system should be pretty simple. Just walk along the priority chain of clients, high to low priority, and grant the features as you see them, while pausing or rejecting features that are in conflict.

Ideas for clients:

  • Mouse emulation daemon. Plugs into the kernel via uevent, and sends mouse events to an event device. Buttons mapped onto mouse buttons or keys. This could also be done with an X client using the XTrap extension, instead of going through the event subsystem.
  • Linux generic joystick. Plugs into uevent. Could be merged with the mouse emulation.
  • Gesture recognition, in similarity to mouse gestures and what Nintendo and AiLive are using, LiveMove [1]. Many games use such "gestures" for control. A classifier can be trained to recognize such gestures (based on raw acceleration data). A classifier can be based on hidden Markov models. Alternatively, a clustering technique based on wavelet transforms could also render suitable. Implementing the math is fairly straightforward. There's many examples in academic literature (search for accelerometer, gesture, recognition, classifier, ...).
  • Game engine mod. Say, hack Quake 3 (which is GPL) to use the Wiimote natively.
  • Virtual keyboard tailored to the Wiimote. I'm not talking the stuff we see on the Wii, since that could be done with mouse emulation and xvkbd easily. Instead, experiment with faster typing schemes using the wiimote. I especially like the typing system that Pogoshell / libpogo for the GBA uses. An adaptation of that to the Wiimote would be awesome.
  • beryl / compiz interface. 'nuff said.
  • Media player control
  • Audio player for the Wiimote speaker (don't expect much quality, but could be useful for effects)
  • Calibration application
  • Mii creator with support for saving to the Wiimote to transfer back to the Wii :)
  • Using three wiimotes (possibly 2) to track an IR laser pointer in 3D space. for scanning an object and creating a 3d mesh.

See also

External links