Using the Wii Remote with Isadora (macOS) Print

The Nintendo Wii Remote is a wireless sensory device that can be used in conjunction with Isadora to sense movement or to trigger actions using one of its eleven buttons. Below you will find step-by-step instructions on how to get Isadora and the Wii Remote (or Wiimote as it is often called) to work together.

STEP 1: SETTING UP OSCULATOR

Isadora cannot read the signal from the Wii Remote directly. Instead, you must use an intermediary piece of software that will read the data from the Wiimote, and pass it on to Isadora in a form it can understand. We strongly recommend the software OSCulator to accomplish this task on Mac OS X. OSCulator is robust, reliable, allows you to use multiple WiiMotes at the same time, and is relatively inexpensive.

After downloading and installing OSCulator, you will need to set up an OSCulator document that will allow Isadora to "listen" to the data from the Wii Remote.

Before running OSCulator, make sure that the Bluetooth port on your computer is enabled. (To do this, go to the System Preferences, click on "Bluetooth" and ensure that the top checkbox labeled "On" is checked.)

Before OSCulator can send the WiiMote data to Isadora, it must be "paired" with the WiiMote. To pair OSCulator and the Wiimote, follow these steps

• Start the OSCulator application. A new, empty document window will open.
• At the top right is an icon labeled WiiMote. Click the icon to reveal the Wii Remote Setup Panel.
• To make the Wiimote available for pairing, you must press the little red button inside the battery compartment. On older Wii Remotes, you will need to remove the battery cover to access this button. Newer models have a small hole that allows you to use a paperclip or pin to press the button without removing the cover. Press the red button now.
• Immediately click the "Start Pairing" button in the Wii Remote Setup Panel in OSCulator.
• If the pairing process succeeds, you will see a green checkmark appear next to the the first item in the list labeled  "Address" in the Wii Remote Setup Panel. You should also see an identifier (something like  "00-19-22-11-3f-2b" next to the green checkmark -- this is the unique identifier for your WiiMote) as shown below.

  

• As soon as OSCulator is connected to your Wiimote, several items should appear in the left side of the Window under the headings Message/Event Type/Value. It should look like this:

  

• These values are all related to the accelerometers inside the Wiimote. The diagram below shows which rotation is being measure by the pitch, roll and yaw sensors:  

  

• Whenever OSCulator receives a change in value from one of the Wii's sensors, that value will appear in this list. The accelerometers are always sending data, so you will see these items appear immediately.
• You can add one or more of the buttons on the Wiimote to this window by simply pressing the button. As soon as you do, it will appear in OSCulator's list. Here's how the list looked after we pressed the "trigger" button on the bottom of the Wii.

  

Now you need to set up OSCulator to send the data from the Wiimote to Isadora. To do this, you need to set the Event Type and Value for each parameter you want to send.

If Isadora isn't already running, start it up now. Then:

• In OSCulator, you will need to set up a UDP address and port to which the messages will be sent. Under the Message column in OSCulator, look for the word "pitch." Click on the "-" immediately to the right, under the column Event Type. Choose "OSC Routing" from the popup menu.
• Then, under the heading Valueclick the "-" symbol. In the popup menu that appears, choose "New..." A dialog box will appear.

  

• In line #1, under the area labeled OSC URL or choice from gear menu, click the little "gear" icon. In the popup menu, choose the item labeled "localhost:1234 (VDMX)." This will set the Target address to "osc.udp://localhost:1234"
• You will notice under "Routes" a new entry has appeared that, under the "#" column says "Đ". This special character means "direct" – when you use this routing, the default OSC addresses OSCulator assigns to the various Wiimote sensors will be used when sending OSC to Isadora.
• You're done with this dialog. Click the "Close" box.

The word "localhost" is a shortcut that means "this computer" – since Isadora is running on the same computer, this is the UDP address you want to use. The number 1234 is the UDP port number to which the OSC messages will be sent. Isadora's default UDP port for receiving OSC messages is 1234. (You can change this setting in the Isadora Preferences under the "Midi/Net" tab; but unless you have changed this number previously, it will be the default value which is 1234.)

The list of Messages in the main OSCulator window now looks like this:

Notice that next to "pitch" that under the heading Event Type its says "OSC Routing" and under the heading Value it has the special symbol "Đ." The "pitch" accelerometer data is now configured to be sent to Isadora via OSC.

• The final step is to set the Event Type to OSC Routing, and the "Value" to "Đ" for each parameter below, including "roll", "yaw", "accel" and "/wii/1/button/B."

You are done with the OSCulator setup. The OSCulator window should now look something like this:

Make sure to save the OSCulator document. Next time, instead of going through this setup procedure, you need only double-click the saved document, and all the settings you just make will be restored. (You do need to pair the Wiimote with OSCulator each time you start up the program however.)

STEP 2: SET UP ISADORA

In Isadora, choose Stream Setup from the Communications menu. A dialog will appear that looks like this.

• The Stream Select menu will already be set to Open Sound Control.
• Click the Auto-Detect Input checkbox to enable the auto-detect feature.
• As soon as you enable the Auto-Detect Inputfeature and shake the Wiimote, you should see some lines of information appear in the Isadora's Stream Setup Window, as shown in the picture below. At this time, you should also press all the buttons you added to OSCulator's Wiimote Setup Panel above. (If you don't see any lines appear, go back to the OSCulator setup procedure described above and make sure you didn't miss a step.)

  

The first four addresses refer to the accelerometer data: pitch, roll, yaw and acceleration, respectively. Note that these numbers will change if you pick up the Wiimote and move it around. The last address refers to the trigger button; this value will change only when you press the button. In all cases, the values vary from a minimum of 0.0 to a maximum of 1.0. (The button sends 1.0 when pressed, 0.0 when released.)

To finish the Isadora setup, you need to assign a "channel" number to each control. (Note: this parameter used to be called "port" in older versions of Isadora before 1.3.1f03) This channel number is used by Isadora to "listen" to the control.

Why do we use these channel numbers and not the OSC address itself? Because, later you may want to switch to another controller with different OSC addresses. If that were the case, all you would need to do is to edit the OSC addresses in the Stream Setup window and your Isadora patch will work exactly as it did before – no need to edit every scene in your show.

An easy way to set up the port numbers is to click the Renumber Channels button. It will automatically fill in the channel numbers for you. After pressing this button, our setup looks like this:

Now you're ready to receive the values in Isadora. Based on these channel settings, you'll receive the pitch accelerometer values on channel 1, roll on channel 2, yaw on channel 3, acceleration on channel 4, and the trigger button on channel 5.

Click OK to close the Stream Setup Dialog

STEP 3: RECEIVE THE VALUES IN ISADORA

Now, in your Isadora patch, add an OSC Listener actor. The 'channel' input is set to 1 by default.

Now, tilt the nose of the Wiimote straight down, and then point it straight up.  You should see the 'value' output of the OSC Listener change, nearly reaching 1.0 when pointing straight up, and reaching nearly 0.0 when pointed straight down. Add another OSC Listener, and change the 'channel' input to 2, and now roll the Wiimote, rotating it on the axis that runs along it's longest edge. Again, you should see the 'value' output change from nearly 0.0 to nearly 1.0. You can add an OSC Listener for as many channels as you added in the Stream Setup window.

Let's make an example. Choose an OSC Listener that uses the pitch of the Wiimote to control the brightness of a movie.

First, add a movie to the Media Window. Then, add a Movie Player and Projector actors to your Scene. Connect the 'video' output of the Movie Player to the 'video' input of the Projector. Finally, connect the 'value' output of the OSC Listener to the 'intensity' input of the Projector. Your patch should look something like this.

If you haven't done so already, choose Show Stages from the Output menu to show the Isadora stage.

Now tilt the Wiimote forward and backward to change the pitch accelerometer value. The stage is dark. Why? Well, the 'intensity' value of the Projector is going between 1.0 and 0.0, but the 'intensity' value expects a value of 100.0 to show the image at its full brightness.

The problem here one of scaling. (This topic is covered in depth in the Isadora manual and in the two part video tutorial "Value Scaling" on You Tube, click here for part 1 or part 2.) But here's how to fix it for the Wiimote and the OSC Listener.

Mini Tutorial On Scaling

• Click on the word 'intensity' in the Projector actor. This will open an "inspector." Inside you'll see the words Scale Min and Scale Max, and these values will be set to 0 and 100 respectively. That defines the range of values that the 'intensity' input will accept. So far so good.

• Now, click on the word 'value' in the OSC Listener
• In the inspector box that appears, look at the Limit Min and Limit Max parameters. They say MIN and MAX respectively. These special values mean "no limit." Isadora cannot know what range of values an OSC device will send,  each product might send a different range. When any of the scaling parameters are set to MIN or MAX, no scaling can occur because Isadora needs a valid range for both the input and the output.
• To solve this problem, the Limit Min value to 0 and the Limit Max to 1.
• Try tilting the Wiimote again, and you'll see that it works: tilting the Wiimote down makes the image darker, tilting it up makes it brighter.

Why? Because Isadora now knows the output range of the OSC Listener is 0 to 1, and the input range of the intensity is 0 to 100. It can then automatically scale the values, so that 0.25 from the OSC Listener becomes 25 in the intensity input, 0.64 becomes 64, and so on.

Isadora's automatic scaling is one of the most important features to understand if you want to get the most out of the program. We encourage to you read the manual and consult the tutorials if you are unfamiliar with this part of Isadora.

STEP 4: ROTATE AN OBJECT

Given that the Wiimote accelerometers measure rotation, it might be a nicer example to use those rotations to rotate an image. Create a new scene in Isadora that looks like this:

This time, instead of using a Projector actor, we're using a 3D Quad Distort actor, which is like the projector but has the ability to rotate in three dimensions. We've added a OSC Listener actor for channels 1 and 2, which are the Wiimote's pitch and roll accelerometers. Also, because the Wiimote accelerometer data is so jittery (noisy would be a more technical description) we've added a Smoother actor after each OSC Listener. The Smoother actor will smooth out the values, producing a less jittery (and hopefully more pleasing) result.

But, like the example above, this patch needs a few tweaks to get the scaling right and give the results we desire.

Then do the following:

• Click on the 'value out' of both Smoother actors. Note that Limit Min and the Limit Max are set to MIN and MAX. This means no scaling can occur. So we set these to 0.0 and 1.0 respectively, which matches the range of values that we receive from the OSC Listener actor.
• Make sure you've set the 'smoothing' input of both Smoother actors to 0.7.
• Click on the 'x-rotation' input of the 3D Quad Distort actor. Currently, the Scale Min is -360 and the Scale Max is +360. That means the a 180° rotation of the Wiimote (nose pointed straight up, nose pointed straight down) will give two full revolutions of rotation in the 3D Quad Distort. To get the rotation of the 3D Quad Distort match the rotation of the Wiimote, we need to set Scale Min to -90 and the Scale Max to 90. (A total rotation of 180°.)
• Do the same for the 'y-rotation' input of the 3D Quad Distort actor.
• Finally, after making sure you have a imported a into slot 1 under Video in the Media Window, choose Output > Show Stages if you haven't already.

You should now be able to rotate the Wiimote and have the image in the Stage mimic your movements. Note that the Smoother actors have made the movements much less jittery. (You can try values of 0.8 or 0.9 in the 'smoothing' input if you want to smooth out the movement even more.)

STEP 5: CONCLUSION

Hopefully this tutorial allowed you to get up and running with the Wii Remote. If you have any comments are corrections for this page, please post them in this forum so we can continue to improve this tutorial.