Copyright (C) 2007 L. Donnie Smith <wiimote@abstrakraft.org>

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA


------------------------------------------------------------------------------------------------
CWiid Wiimote Interface
------------------------------------------------------------------------------------------------

DESCRIPTION
The CWiid package contains the following parts:
1.wiimote library - abstracts the interface to the wiimote by hiding the details of the underlying Bluetooth connection.
2.wmgui - provides a simple GTK gui to the wiimote.
3.wminput - an event driver for the wiimote, supporting all buttons (except Power) and pointer tracking, and featuring a tracking algorithm plugin architecture.

REQUIREMENTS
autoconf, awk, bluez-libs, gtk+-2 dev libs, uinput kernel support, kernel sources

CONFIGURATION
wminput:
Your kernel must be configured with uinput support (INPUT_UINPUT, or Device Drivers/Input Device Support/Miscellaneous Drivers/User Level Driver Support under menuconfig).  Compile into the kernel or as a module.  See http://gentoo-wiki.com/HOWTO_Compile_a_Kernel_Manually for information on kernel compilation.
By default, some (most? all?) udev configurations set up a uinput device file readable only by root.  Using wminput as a user other than root requires configuration udev to change the permissions on uinput.  Place the following line in a file in /etc/udev/rules.d (see the documentation for your distro for the recommended file for local rules) to allow anyone on the system to use uinput:
KERNEL=="uinput", MODE="0666"
A more secure method uses the following line to allow anyone in <group> to use wminput, and adds only the desired users to <group>:
KERNEL=="uinput", GROUP="<group>"
A uinput group can be created specifically for this purpose, or another existing group such as wheel can be used.

See CWiid/doc/wminput.conf.sample for an example wminput configuration file.  Copy this file to ~/.CWiid/wminput.conf and change as desired.

Getting X to recognize non-standard key symbols, and mapping actions to those symbols, is not automatic.  An excellent tutorial at http://gentoo-wiki.com/HOWTO_Use_Multimedia_Keys can help you set this up.  An overview of the process (see the HOWTO for more information):
1.Edit ~/.CWiid/wminput.conf
2.Use xev, wminput, and your wiimote to find out if the key symbols are already mapped, and find the key codes if they are not.
3.If the codes are not mapped to the appropriate symbols, edit ~/.Xmodmap, and use xmodmap to map them.  (A copy of my ~/.Xmodmap is included in CWiid/doc)
4.Use xbindkeys or a window manager-specific utility to map the key symbols to specific actions.

wminput tracking plugins are, by default, installed to /usr/local/lib/CWiid/plugins.  Plugins may also be placed in ~/.CWiid/plugins, and plugins placed here will take precedence.

COMPILATION
./configure
make
make install

NOTE: many distributions do not have /usr/local/lib in the library search path, and on many of these same distributions, the library installation directory (as determined by autoconf) is /usr/local/lib, creating a problem when you try to run programs depending on libraries installed there. There are two clean ways to fix this:
1.Add a --prefix=/usr argument to ./configure
2.Add /usr/local/lib to /etc/ld.so.conf, then run ldconfig. 

I prefer the second method since it keeps local software in the local directory where it should be, and it fixes the problem for every package using /usr/local/lib, not just CWiid. Until someone convinces me that /usr/local/lib shouldn't be in the library search path, I consider this to be a distribution bug, and method #2 above is the fix.

Please report any compilation errors to <wiimote@abstrakraft.org>.

EXECUTION
wmgui [-h] [bdaddr]
wminput [-h] [-t tracking_plugin] [bdaddr]

The bluetooth device address (bdaddr) of the wiimote can be specified on the command-line, or through the WIIMOTE_BDADDR environment variable, in the that order of precedence.  If neither is given, the first wiimote found by hci_inquiry will be used.
Plugins are given on the command line without the .so extension, e.g., to invoke the acc plugin, the appropriate command is 'wminput -tacc'.

PLUGINS
default - identical to the default tracking algorithm compiled into wminput.  It exists for testing purposes.  It uses IR data control the cursor.
acc - uses only accelerometer data.  Pitch angle controls vertical movement, roll angle controls horizontal movement.

TODO/ROADMAP
The following list is neither complete nor ordered:
Move wiimote communications into a separate daemon (wiimoted) with which applications communicate via sockets (or some other means)
wmgui logging
Implement speaker
Clean up all code, split up long functions and files, add error checks, improve command-line, etc.
Implement other drivers such as gesture recognition.
