|FreeVR: Virtual Reality Integration Library|
WIIMOTESection: FreeVR Usage (7FV)
Updated: 5 December 2013
Index Return to Main Contents
The Nintendo Wiitm remote, frequently referred to as a "Wiimote" has been a popular input device for virtual reality enthusiasts due to it's low-cost, rich input features, and wireless connectivity.
The wireless connectivity is handled through the blue-tooth technology standard. Part of FreeVR's design constraints is to minimize the number of external requirements, and at least for now, blue-tooth is not included as part of FreeVR's features. Therefore, other, indirect mechanisms must be used to integrate Wiimote controllers into FreeVR, each of which is essentially an input data server, though one ("CWiid") interfaces as a standard X11 input.
The three interfaces are:
NOTE: Presently all the methods presented are for use with the Linux operating system. As methods are ascertained for interfacing on other operating systems, this manpage will be augmented. Also of note is that there is a project ("XWiimote") to integrate Nintendo Wiitm remotes directly into the Linux kernel. This is part of the Linux 3.x distribution effort.
Each of the following subsections provide instructions on how each of the interfaces listed above can be used to accomplish Wiimote interaction with FreeVR.
Before delving into specific methods of the three interfaces, verify that the low-level blue-tooth communication with the device is operational.
On Linux this can be accomplished with the "hcitool" --- specifically the "scan" command:
(press the 1 and 2 buttons on your Wiimote) % hcitool scan Scanning ... 00:24:1E:7A:CC:2D Nintendo RVL-CNT-01
CWiid / wminput
The CWiid package is a Wiitm remote "daemon" library written in C. The library provides a convenient API for interfacing with Wiimote devices, and the CWiid package includes the wminput daemon which converts Wiimote events into Linux event device system (aka "evdev", or in FreeVR parlance "EVIO") using the Linux "uinput" kernel module.
So wminput is the actual program that one executes to link the Wiimote to the uinput system. Usually, this will have to be run with superuser authority. And furthermore, doing so will also set the permissions of the "/dev/input/event<N>" device to be readable by root only, so proper accommodations must be made --- generally changing the permissions on the input device.
# /usr/local/lib/cwiid/wminput -c /usr/local/lib/cwiid/config/buttons Put Wiimote in discoverable mode now (press 1+2)... Ready. # chmod 666 /dev/input/event<N>
NOTE: by default, the wminput program does not look in the local directory to find a file, so when giving a relative path, the "./" must be explicitly specified.
Once "wminput" is configured and running, you can test the inputs using the "eviotest" program that comes with the FreeVR distribution.
% ./eviotest /dev/input/event<N> [...] epttn12kdtt buttons: 00000000000
NOTE: the characters above the input values are the last character of each name.
The accompanying lswm tool can be executed first in order to list all the Wiimotes currently in discoverable mode. (Which really can also be done with the "hcitool scan" operation.)
% lswm Put Wiimotes in discoverable mode now (press 1+2)... 00:24:1E:7A:CC:2D
VRPNThe VRPN (Virtual Reality Peripheral Network) is an input device, really and I/O device, server system that can interface with a wide variety of devices, old and new. The Nintendo Wiimote is one of the many devices handled. And as FreeVR can interface directly with VRPN, all that is needed is to install VRPN and configure the "WiiMote" interface.
VRPN is not generally included with Linux distributions, but it is easy to download and compile.
Enabling the basic "WiiMote" input is straightforward:
% cat wiimote_vrpn.cfg vrpn_WiiMote WiiMote0 1 0 0 1 % vrpn_server -f wiimote_vrpn.cfg
There is also a tracking form of VRPN interface with the WiiMote which involves the use of the IR sensor information along with some post-processing (all handled within VRPN):
% cat wiimote_vrpn.cfg vrpn_WiiMote WiiMote0 1 1 1 1 vrpn_Tracker_WiimoteHead Tracker0 WiiMote0@localhost % vrpn_server -f wiimote_vrpn.cfgNOTE: that the middle two flags ("useMotionSensing" and "useIR") must be enabled to create tracking output.
Here are the VRPN configuration arguments for the two input types:
for vrpn_WiiMote: 1) name_of_this_device (string) 2) Player number (int) 3) Use motion Sensing (bool/int) --- from the base Wiimote, not motion sensor 4) Use IR tracking (bool/int) 5) Reorder the buttons (bool/int) 6) [optional] Bluetooth address --- provided in all uppercase with colons for vrpn_Tracker_WiimoteHead 1) name_of_this_device (string) 2) name_of_vrpn_WiiMote_device (string) 3) [optional] min_update_rate (default=60) (float) 4) [optional] led_distance (default=0.205) (float) On the FreeVR side, these can be mapped into inputs with configuration settings similar to: input "2switch[A]" = "2switch(WiiMote0:button)"; input "2switch[B]" = "2switch(WiiMote0:button)"; input "2switch" = "2switch(WiiMote0:button)"; input "val[x]" = "Valuator(WiiMote0:analog[ 1])"; # roll/twist input "val[y]" = "Valuator(WiiMote0:analog[-2])"; # pitch/elevation input "val[u]" = "Valuator(WiiMote0:analog[ 3])"; # right-side-upidness input "val[b]" = "Valuator(WiiMote0:analog[ 0])"; # battery level input "wand2" = "6sensor(Tracker0:tracker)";
The Vrui "VRDeviceDaemon" server can handle a variety of input devices, much like VRPN. And the Nintendo Wiitm remote is one input device it can handle.
In fact it is fairly straightforward. The only real requirement is that the Vrui system be compiled with the Bluetooth feature enabled.
Once Vrui is compiled, a "VRDevices.cfg" configuration file for the VRDeviceDaemon program must be created. To collection button and valuator inputs only (valuators with an attached Nunchuk of course), use this configuration (replacing the hostname with the correct value):
section "<hostname>" section DeviceManager deviceNames (Wiimote1) section Wiimote1 deviceType WiimoteTracker # Set this to the bluetooth ID of the Wiimote devicename "00:24:1E:7A:CC:2D" # Set the LED pattern for this Wiimote (any 4-bit value) ledMask 1 # Disable motion tracking using the Wiimote's camera enableTracker false endsection endsection endsection
and then run the Vrui VRDeviceDaemon:
% bin/VRDeviceDaemon VRDeviceDaemon: Reading configuration file VRDeviceDaemon: Initializing device manager VRDeviceManager: Loading device Wiimote1 of type WiimoteTracker WiimoteTracker: Connecting to first compatible bluetooth device. WiimoteTracker: Please press buttons 1 and 2 to initiate connection... done WiimoteTracker: Connected wiimote's battery level is 145% VRDeviceManager: Managing 0 trackers, 13 buttons, 2 valuators VRDeviceManager: Managing 0 virtual devices VRDeviceDaemon: Initializing device server VRDeviceServer: Waiting for client connection
In another shell, the inputs can be tested with the FreeVR "vruiddtest" program:
For position tracking, there are a handful of additional options that must be specified. However, position tracking with the Vrui system only works with physical LED configurations that have four LED markers rather than the customary two. So this system does not work with the standard Wii sensor bar.
The additional configuration options are:
cameraCenter (512, 384) cameraFocalLength 1280 targetPoints ((-2.0, 0.0, 0.0), (0.0, -1.0, 2.0), (2.0, 0.0, 0.0), (0.0, -1.0, -2.0)) targetTransformation identity homeTransform identity
The sample FreeVR configuration file for VRPN:
Copyright 2013, Bill Sherman, All rights reserved.
This document was created by man2html, using the manual pages.
Time: 05:02:19 GMT, December 13, 2013