xorg-xwiimote.4

.\"
.\" Written 2012 by David Herrmann
.\" Dedicated to the Public Domain
.\"
.ds q \N'34'
.TH XORG-XWIIMOTE 4 "xf86-input-xwiimote" "David Herrmann" "X Version 11"
.SH NAME
xf86-input-xwiimote \- X.Org Nintendo Wii Remote Input Driver
.SH SYNOPSIS
.nf
.B "Section \*qInputDevice\*q"
.BI "  Identifier \*q" devname \*q
.B  "  Driver \*qxwiimote\*q"
\ \ ...
.BI "  Option \*qDevice\*q        \*q" devpath \*q
.BI "  Option \*qMotionSource\*q  \*q" source \*q
\ \ ...
.BI "  Option \*qMPNormalization\*q \*q" Int:Int:Int \*q
.BI "  Option \*qMPCalibrationFactor\*q \*q" Int \*q
.BI "  Option \*qMPXAxis\*q       " "\*qx\*q or \*qy\*q or \*qz\*q"
.BI "  Option \*qMPXScale\*q      \*q" Int \*q
\ \ ...
.BI "  Option \*qIRAvgRadius\*q   \*q" Int \*q
.BI "  Option \*qIRAvgMaxSamples\*q \*q" Int \*q
.BI "  Option \*qIRAvgMinSamples\*q \*q" Int \*q
.BI "  Option \*qIRAvgWeight\*q   \*q" Int \*q
.BI "  Option \*qIRKeymapExpirySecs\*q \*q" Int \*q
\ \ ...
.BI "  Option \*qMapLeft\*q       \*q" val \*q
.BI "  Option \*qMapRight\*q      \*q" val \*q
.BI "  Option \*qMapUp\*q         \*q" val \*q
.BI "  Option \*qMapDown\*q       \*q" val \*q
.BI "  Option \*qMapA\*q          \*q" val \*q
.BI "  Option \*qMapB\*q          \*q" val \*q
.BI "  Option \*qMapPlus\*q       \*q" val \*q
.BI "  Option \*qMapMinus\*q      \*q" val \*q
.BI "  Option \*qMapHome\*q       \*q" val \*q
.BI "  Option \*qMapOne\*q        \*q" val \*q
.BI "  Option \*qMapTwo\*q        \*q" val \*q
.BI "  Option \*qMapIRLeft\*q     \*q" val \*q
.BI "  Option \*qMapIRRight\*q    \*q" val \*q
.BI "  Option \*qMapIRUp\*q       \*q" val \*q
.BI "  Option \*qMapIRDown\*q     \*q" val \*q
.BI "  Option \*qMapIRA\*q        \*q" val \*q
.BI "  Option \*qMapIRB\*q        \*q" val \*q
.BI "  Option \*qMapIRPlus\*q     \*q" val \*q
.BI "  Option \*qMapIRMinus\*q    \*q" val \*q
.BI "  Option \*qMapIRHome\*q     \*q" val \*q
.BI "  Option \*qMapIROne\*q      \*q" val \*q
.BI "  Option \*qMapIRTwo\*q      \*q" val \*q
\ \ ...
.BI "  Option \*qXkbRules\*q      \*q" rules \*q
.BI "  Option \*qXkbModel\*q      \*q" model \*q
.BI "  Option \*qXkbLayout\*q     \*q" layout \*q
.BI "  Option \*qXkbVariant\*q    \*q" variant \*q
.BI "  Option \*qXkbOptions\*q    \*q" options \*q
.B EndSection
.fi
.SH DESCRIPTION
.B xwiimote
is an Xorg input driver for Nintendo Wii Remotes on Linux. It is based on the
.B xwiimote
tools and kernel driver. With this driver you can use the Wii Remote as input
for any X application including games. It is highly customizable but comes with
sane default values.
.br
The Wii Remote can serve as pointer and keyboard device. The Pointer
capabilities are disabled by default. The buttons are mapped to sane default
keys so you can directly use the Wii Remote as input device without configuring
it.
.br
It is recommended that
.B xwiimote
devices are configured through the
.B InputClass
directive (refer to xorg.conf(5)) instead of manual
per-device configuration. Devices configured in the
xorg.conf(5) are not hot-plug capable so use an
.B InputClass
instead. This package comes with the default configuration installed as
.B /etc/X11/xorg.conf.d/60-xwiimotes.conf
but your distribution may have installed it into other locations. Use this
default to configure your Wii Remotes.

.SH CONFIGURATION DETAILS
Please refer to xorg.conf(5) for general configuration
details and for options that can be used with all input drivers.  This
section only covers configuration details specific to this driver.
.PP
The following driver 
.B Options
are supported:

.IP "\fBOption \*qDevice\*q \fP\*qdevpath\*q"
This specifies the device path to the input event-device of the Wii Remote. This
is most often a device in /dev/input/eventX. Do not use this option unless you
want to disable device hot-plug.

.IP "\fBOption \*qMotionSource\*q \fP\*qsource\*q"
The Wii Remote can be used as motion input device (like a mouse). This selects
what kind of motion-emulation should be performed. \fBsource\fP can be one of
\fBaccelerometer\fP, \fBir\fP, \fBMotionPlus\fP or \fBoff\fP. Default is
\fBoff\fP which means no motion-emulation is done. \fBaccelerometer\fP means
that the accelerometer is used to calculate current tilt and use this as
absolute pointer input.

\fBir\fP means that the IR sensor is used to detect the mouse-location. You need
to place an IR emitter in front of you. The Wii Remote has a built-in camera to
scan it and calculate the pointer-position from it.

\fBMotionPlus\fP means that the gyroscope of MotionPlus extensions (or Gen2.0
Devices with built-in MotionPlus) is used. You need to set \fBMPNormalization\fP
and \fBMPCalibrationFactor\fP or use run-time calibration to make use of this.
This does nothing if no MotionPlus is detected. With newer kernels, you can
plug/replug the MotionPlus adapter during runtime and it gets detected
automatically.

.PP
.IR "\fBOption \*qMPNormalization\*q \fP" "\*qOn\*q or \*qInt:Int:Int\*q"
.br
.IR "\fBOption \*qMPCalibrationFactor\*q \fP" "\*qOn\*q or \*qInt\*q"
.br
.IR "\fBOption \*qMPXAxis\*q \fP" "\*qx\*q or \*qy\*q or \*qz\*q"
.br
.IR "\fBOption \*qMPXScale\*q \fP" "\*qInt\*q"
.br
.IR "\fBOption \*qMPYAxis\*q \fP" "\*qx\*q or \*qy\*q or \*qz\*q"
.br
.IR "\fBOption \*qMPYScale\*q \fP" "\*qInt\*q"
.br
.IR "\fBOption \*qMPZAxis\*q \fP" "\*qx\*q or \*qy\*q or \*qz\*q"
.br
.IR "\fBOption \*qMPZScale\*q \fP" "\*qInt\*q"
.RS
If running in MotionSource MotionPlus configuration, MPNormalization can be
used to apply a constant offset to normalize MotionPlus data. Please use
\fBxwiishow\fP or some similar tool from the \fBxwiimote\fP distribution to
get these offsets.
Set this to \fBon\fP to let the driver perform automatic normalization during
startup.

The calibration factor is used to apply calibration values during runtime to
keep the data smooth. A factor between 10 and 100 is normally used. If set to
\fBon\fP, 50 will be used.

The \fBAxis\fP and \fBScale\fP options for each axis define remappings and
scaling in case the default mappings are not what you want. The Axis selector
specifies which axis to use as source. So if you set MPXAxis to \fBz\fP, then
whenever the driver wants to read the X-axis values, it gets the Z-axis instead.
The Scale options specify a multiplier. The default is 1 (no scaling). The
default for the axis-mappings are the trivial mappings. Note that the
MP-motion-source only uses X and Z axis for movement calculations.
.RE

.PP
.IR "\fBOption \*qIRAvgRadius\*q \fP" "\*qInt\*q"
.br
.IR "\fBOption \*qIRAvgMaxSamples\*q \fP" "\*qInt\*q"
.br
.IR "\fBOption \*qIRAvgMinSamples\*q \fP" "\*qInt\*q"
.br
.IR "\fBOption \*qIRAvgWeight\*q \fP" "\*qInt\*q"
.br
.IR "\fBOption \*qIRKeymapExpirySecs\*q \fP" "\*qInt\*q"
.RS
If running in MotionSource IR configuration, IRAvgRadius (default: 10)
configures the distance of a new data point at which the current averaging is
discarded. IRAvgMaxSamples (default: 8) and IRAvgMinSamples (default: 4)
configure respectively how points to average, and how many averaged points are
needed before applying the averaged value to the cursor location. IRAvgWeight
(default: 3) sets the weight of the averaged point in comparison to the current
data point when generating the final cursor position.

When the Wii Remote is turned away from the IR source, IRKeymapExpirySecs
(default: 1) dictates how many seconds before the control mapping reverts to the
non-IR keys.
.RE

.PP
The following options specify keymaps for the buttons of a Wii Remote. The
\fIval\fP field of the options must be one of the linux input-key/btn constants.
You can find them in
.B /usr/include/linux/input.h.
They start with
.B KEY_*
or
.B BTN_*.
The option is case-insensitive so KEY_ENTER and Key_Enter are the same.
Additional values are \fBnone\fP, \fBoff\fP, \fB0\fP or \fBfalse\fP to disable
the given button or \fBleft-button\fP, \fBright-button\fP or \fBmiddle-button\fP
to emulate mouse-buttons instead of keyboard keys.

When \fBMotionSource\fP is set to \fBir\fP and the Wii Remote is pointed
towards the IR source, the IR mappings are used.  Otherwise, the non-IR
mappings are used.

.PP
.IR "\fBOption \*qMapLeft\*q \fP\*qval\*q"
.br
.IR "\fBOption \*qMapIRLeft\*q \fP\*qval\*q"
.RS
Specify the mapping of the
.B LEFT
button of the Wii Remote. Default is
.B KEY_LEFT
.RE

.PP
.IR "\fBOption \*qMapRight\*q \fP\*qval\*q"
.br
.IR "\fBOption \*qMapIRRight\*q \fP\*qval\*q"
.RS
Specify the mapping of the
.B RIGHT
button of the Wii Remote. Default is
.B KEY_RIGHT
.RE

.PP
.IR "\fBOption \*qMapUp\*q \fP\*qval\*q"
.br
.IR "\fBOption \*qMapIRUp\*q \fP\*qval\*q"
.RS
Specify the mapping of the
.B UP
button of the Wii Remote. Default is
.B KEY_UP
.RE

.PP
.IR "\fBOption \*qMapDown\*q \fP\*qval\*q"
.br
.IR "\fBOption \*qMapIRDown\*q \fP\*qval\*q"
.RS
Specify the mapping of the
.B DOWN
button of the Wii Remote. Default is
.B KEY_DOWN
.RE

.PP
.IR "\fBOption \*qMapA\*q \fP\*qval\*q"
.br
.IR "\fBOption \*qMapIRA\*q \fP\*qval\*q"
.RS
Specify the mapping of the
.B A
button of the Wii Remote. Default is
.B KEY_ENTER
.RE

.PP
.IR "\fBOption \*qMapB\*q \fP\*qval\*q"
.br
.IR "\fBOption \*qMapIRB\*q \fP\*qval\*q"
.RS
Specify the mapping of the
.B B
button of the Wii Remote. Default is
.B KEY_SPACE
.RE

.PP
.IR "\fBOption \*qMapPlus\*q \fP\*qval\*q"
.br
.IR "\fBOption \*qMapIRPlus\*q \fP\*qval\*q"
.RS
Specify the mapping of the
.B PLUS
button of the Wii Remote. Default is
.B KEY_VOLUMEUP
.RE

.PP
.IR "\fBOption \*qMapMinus\*q \fP\*qval\*q"
.br
.IR "\fBOption \*qMapIRMinus\*q \fP\*qval\*q"
.RS
Specify the mapping of the
.B MINUS
button of the Wii Remote. Default is
.B KEY_VOLUMEDOWN
.RE

.PP
.IR "\fBOption \*qMapHome\*q \fP\*qval\*q"
.br
.IR "\fBOption \*qMapIRHome\*q \fP\*qval\*q"
.RS
Specify the mapping of the
.B HOME
button of the Wii Remote. Default is
.B KEY_ESC
.RE

.PP
.IR "\fBOption \*qMapOne\*q \fP\*qval\*q"
.br
.IR "\fBOption \*qMapIROne\*q \fP\*qval\*q"
.RS
Specify the mapping of the
.B ONE
button of the Wii Remote. Default is
.B KEY_1
.RE

.PP
.IR "\fBOption \*qMapTwo\*q \fP\*qval\*q"
.br
.IR "\fBOption \*qMapIRTwo\*q \fP\*qval\*q"
.RS
Specify the mapping of the
.B TWO
button of the Wii Remote. Default is
.B KEY_2
.RE

.PP
The following options are standard X.org input device options which also apply
to Wii Remote devices:

.I "\fBOption \*qXkbRules\*q \fP\*qrules\*q"
.br
.I "\fBOption \*qXkbModel\*q \fP\*qmodel\*q"
.br
.I "\fBOption \*qXkbLayout\*q \fP\*qlayout\*q"
.br
.I "\fBOption \*qXkbVariant\*q \fP\*qvariant\*q"
.br
.I "\fBOption \*qXkbOptions\*q \fP\*qoptions\*q"
.RS
These are the standard Xkb options that select the RMLVO parameters of the
keyboard. See the Xkb man-pages for more information. Please be aware that
keymaps are applied to all keys before they are sent to the X clients. So take
that into account when configuring the other mappings of Wii Remotes.
.RE

.SH AUTHORS
David Herrmann <dh.herrmann@gmail.com>
.br
The XWiimote Project: http://dvdhrm.github.io/xwiimote
.br
The xf86-input-xwiimote Project: http://github.com/dvdhrm/xf86-input-xwiimote

.SH "SEE ALSO"
.BR xwiimote (7),
.BR xorg.conf (5),
.BR Xorg (1),
.BR X (7)