Le weblog entièrement nu

Roland, entièrement nu... de temps en temps.



To turn signals coming from a Wiimote into MIDI events.

In more concrete terms: to play real MIDI instruments with the Guitar Hero drumkit. Or to control stage effects (lighting and so on) with your Wiimote buttons. Or to control software sound effects with a hacked Wiimote. Or simply to use your Wiimote as a remote control for your media player.


Get it

The current version of Wiimidi is arbitrarily numbered 0.9, and can be downloaded at wiimidi-0.9.tar.gz.

Wiimidi is developed with Bazaar, and the public branch is at http://alioth.debian.org/~lolando/bzr/wiimidi/trunk/ (may also work in https). So, to grab a copy:

bzr checkout http://alioth.debian.org/~lolando/bzr/wiimidi/trunk/

You'll need a few Python modules, namely configobj, pypm (PortMidi) and of course python-cwiid for accessing the Wiimote data. They're all packaged in major Linux distributions. Wiimidi itself could easily be made available in Debian if there's enough demand (the Bazaar branch actually already contains the packaging).

Run it

wiimidi --verbose --config=./wiimidi.conf --kit=general_midi

The --config option allows specifying a config file (on top of the default locations); --kit allows choosing which of the configurations in the config file to use. After launching the script, press the 1+2 buttons simultaneously on the Wiimote to establish the Bluetooth peering. Oh, yes, you'll need a Bluetooth adapter if it's not built-in, of course.

Configure it

Edit the wiimidi.conf file to fit your needs. (Or copy it to /etc/wiimidi/wiimidi.conf or to your ~/.config/wiimidi/wiimidi.conf.) It's sort of self-documented, and I tried to pick meaningful names for the sections and the variables, as well as providing usable default values, but your use case may be different. The configuration syntax is described below.


Each section describes a “kit”, or set of settings. The DEFAULT section is special, and its values are inherited by other kits. It also has a default_kit setting, which is used if no kit is explicitly specified on the command line.

Kit settings

midi_out describes the MIDI port to which events should be sent. It can be a purely software port (Midi Through Port-0 for instance, or Hydrogen Midi-In) or a hardware adapter (my Roland USB adapter describes itself as UM-1G MIDI 1).

on_startup is a list of actions to be executed on startup. You can send initialization messages to MIDI, or provide some visual feedback using the LEDs on the Wiimote.


map_* values describe the mappings from Wiimote events to actions. The simplest mappings concern the buttons and the cross-pad: map_wiimote_button_1, map_wiimote_button_left and so on. You can also trigger events when the button is released, with mappings such as map_wiimote_button_1_release.

When the Wiimote is plugged into an additional controller that provides buttons, these can be mapped too; for instance, the nunchuck provides map_nunchuck_button_c (and the _release variant).

When the additional controller provides a directional stick, four new virtual buttons appear for up/down/right/left; hence possible mappings such as map_guitar_stick_left (and of course map_nunchuck_stick_right_release for the release action). The exact value of each axis (mapped to the 0-127 range used in MIDI) can also be used for MIDI “control change” events (see cc below) with map_nunchuck_stick_y. The classic controller provides two such sticks, leading to map_classiccontroller_leftstick_up and so on.

The classic controller has a cross-pad and a handful of buttons, used the usual way. The standard classic controller also provides two “analog” triggers, l and r, which can be mapped to a control change using the map_classiccontroller_trigger_l mapping (and ditto for _r of course). This comes in addition to the _button_l/r mappings, so you can use the triggers both as a continuous source of events or as a button. Note that the “classic controller pro“ only provides buttons where these triggers are in the standard one, so the _trigger_l/r mappings will not be particularly useful since they'll only send one of two distinct values.

The drum pads (map_drum_pad_red, map_drum_pad_kick, and so on) are sensitive to velocity (on a range from 1 to 7), and can have a different mapping based on whether the hit is stronger than a threshold. To have the red pad send a “cross-stick” action instead of the standard snare drum action on soft hits, set drum_split_threshold_red to a value such as 2, and set the map_drum_pad_red_soft value to the cross-stick action.

The guitar controller provides five fret buttons (from map_guitar_fret_green to map_guitar_fret_orange). The Guitar Hero World Tour guitar controller also provides five buttons for the sensitive part of the guitar neck, which are accessible with map_guitar_touchfret_1 to map_guitar_touchfret_5; note that these touch-frets they're not quite independent: at most two touch-frets can be active at a time, and that requires them to be contiguous. If you finger several touch-frets in a split way, only the highest one is taken into account (or possibly the highest two, if they're consecutive).

The guitar controller also provides a whammy bar, which can be mapped to a control change action with map_guitar_whammy_bar.

Note that the various controls provided by the guitar generate independent MIDI events; there's no mechanism to only trigger the event when you strum, for instance. This is partly because I have no clue about guitars (I'm a drummer myself), partly because that would probably mean a combinatory explosion in the required mappings, and partly because I feel it goes beyond what Wiimidi should do: Wiimidi is meant as a gateway from the Wii world to the MIDI world. The actual smarts of what to do can (and should) be implemented further down the MIDI pipe, possibly with tools such as Mididings or others.


The syntax for actions is command/parameter or command/parameter/parameter if several parameters are possible. Commands can be grouped in several categories. First, MIDI events:

Then, LED control:

Compound actions:

Cycles (macros)

A cycle_foo directive describes a cycle named foo. It's described as a sequence of actions (possibly compound actions) separated with ;. The number of semicolon-separated components is the length of the cycle. Each time the cycle is called (with an action such as cycle/foo, the actions in the corresponding step are called, and the step is pushed forward by one, unless the end of the cycle has been reached and we loop back to the beginning.

A two-step cycle can be used as a toggle/flip-flop: a possible use would be cycle_playpause = pc/10 + led-on/2 ; pc/11 + led-off/2 (note compound steps). The first time the cycle is called, a program-change/10 event is sent, and the second LED is switched on. The next time, program-change/11 and the LED is switched off.

A one-step cycle can be used as a macro: for readability, you may want to define a cycle_ledsoff = led-off/1 + led-off/2 + led-off/3 + led-off/4.

LED animations

A ledanimation_foo directive describes a LED animation that can be triggered to give visual feedback on some actions. The syntax is a simple semicolon-separated list of the set of LEDs that should be on at a particular step. Flashing all LEDs twice would be ledanimation_flashtwice = 1234;0;1234;0 (the zeroes are optional and only mentioned for readability). A sweep would be defined as ledanimation_sweep = 1;12;123;1234;234;34;4;0, and would be invoked by an action with led-animate/sweep.

Note that LED animations are asynchronous, and further actions do not wait for the animation to complete. As a consequence, if two animations overlap in time because the second one was started before the first one was finished, then you'll see interesting flashing things.

Tell me about it

Patches welcome, of course! Also, I'll be interested to hear about your applications. I use it alternately to add extra pads to my electronic drumkit and to control my music player when practicing. I've already been told about a Wiimote-powered foot controller. If you do a Wiimote-controlled robot dinosaur (with lasers), please tell me!

Improve it

Possible improvements to Wiimidi include:


For the history of Wiimidi, see these blog posts.

Creative Commons License Sauf indication contraire, le contenu de ce site est mis à disposition sous un contrat Creative Commons.