Kernel ABI constants. More...

Macros
#define	XWII__NAME "Nintendo Wii Remote"

#define	XWII_NAME_CORE XWII__NAME
	Name of the core input device.

#define	XWII_NAME_ACCEL XWII__NAME " Accelerometer"
	Name of the accelerometer input device.

#define	XWII_NAME_IR XWII__NAME " IR"
	Name of the IR input device.

#define	XWII_NAME_MOTION_PLUS XWII__NAME " Motion Plus"
	Name of the motion-plus input device.

#define	XWII_NAME_NUNCHUK XWII__NAME " Nunchuk"
	Name of the nunchuk input device.

#define	XWII_NAME_CLASSIC_CONTROLLER XWII__NAME " Classic Controller"
	Name of the classic-controller input device.

#define	XWII_NAME_BALANCE_BOARD XWII__NAME " Balance Board"
	Name of the balance-board input device.

#define	XWII_NAME_PRO_CONTROLLER XWII__NAME " Pro Controller"
	Name of the pro-controller input device.

Detailed Description

Kernel ABI constants.

Several constants and objects that are used by the kernel to communicate with user-space. These indirectly define the kernel ABI, which is guaranteed to be stable at all times. Note that the direct kernel ABI is defined through kernel headers. The ABI defined here extends it with information that we also guarantee to be stable but isn't part of the direct ABI.

The kernel ABI is almost complete abstracted by this library so these constants are only needed for integration into existing applications. You should try to avoid them and use them only if you need direct kernel access.

The kernel driver hid-wiimote provides connected Wii-Remotes, and all Nintendo or 3rd party devices that are compatible (including balance-boards, pro-controllers, gamepads, ...), as HID devices. All HID devices can be found in /sys/bus/hid/devices/. The kernel creates one directory for each device. A wiimote compatible device (wiimote) can be detected via normal udev-filters. The subsystem field is hid and the driver field is wiimote. If both match, the device is guaranteed to be handled by the hid-wiimote driver and compatible with this library.

Each wiimote provides several sub-devices as child-devices of the HID node. During device-setup and device-detection, the kernel sets up most of these nodes and sends a change event on the HID device after it is done. Userspace must react to this event by re-reading the device state. Otherwise, userspace might miss some nodes. For each hotpluggable sub-device (like extensions or motion-plus), the kernel attaches/detaches such nodes during runtime. Userspace must use udev-monitors to react to those events, if interested. All available interfaces on the HID device are explained below. From now on we assume that /sys/bus/hid/devices/[dev]/ is a valid wiimote device.

Global Interfaces

The following interfaces are always present, regardless of the device-type and extension-type.

devtype

The HID device has a devtype attribute which can be found in /sys/bus/hid/devices/[dev]/devtype. This attribute provides a newline-terminated string which describes the device-type. If support for new devices is added to the kernel, new identifiers may be added. Valid values are:

pending: Device detection is not done, yet. The kernel will send a change uevent after it is done. A device must not be in this state for longer than a few hundred milliseconds.
unknown: The device-type is unknown and couldn't be initialized. Such devices are normally useles and should be ignored by most applications.
generic: The device-type could not be detected, but the device was successfully initialized. That means, most standard interfaces are available on this device, but may not function properly. Nearly all interfaces are enabled for such devices so no special policies apply.
gen1[num]: First generation of Wii-Remotes. This is mostly gen10, but there are also 1st-gen devices with built-in motion-plus which might be reported as gen15 or similar. Newer WiiRemotePlus devices with built-in motion-plus extensions belong to the 2nd-gen devices, though. Nearly all interfaces are enabled for such devices.
gen2[num]: Second generation of Wii-Remotes. These are guaranteed to have motion-plus built-in and use a different bluetooth-chipset. Hence, there VID/PID changed and a few details differ to gen1 devices. Nearly all interfaces are enabled for such devices.
balanceboard: Balance-boards and compatible devices. Nearly no interfaces are available on balance-boards. They are limited to an extension port (which is normally occupied by the balance-board extension), one LED and the battery interface. No MotionPlus is available.
procontroller: Wii-U Pro Controller and compatible devices. Nearly no interfaces are available. One extension port is supported (which is normally occupied by the pro-controller extension), 4 LEDs and a battery. MotionPlus may be available but is currently not supported.

Note that this attribute does not describe the extensions. Instead, it describes the type of device. So users might build custom extensions which allow a balance-board extension to be plugged on a regular WiiRemote. This would cause devtype to be gen10 but extension to be balanceboard.

extension

An extension attribute is provided as /sys/bus/hid/devices/[dev]/extension and provides a newline-terminated string that describes the currently attached extension. New identifiers might be added if we add support for new extensions to the kernel driver. Note that normal Wii-Remotes provide a physical I2C extension port, but other devices might not. So if devtype reports a different device-type than a normal Wii-Remote, the extension might be built-in and not physically unpluggable. Valid values are:

none: No extension is plugged.
unknown: An unknown extension is plugged or the driver failed to initialize it.
nunchuk: A Nintendo Nunchuk extension is plugged.
classic: A Classic Controller or Classic Controller Pro extension is plugged.
balanceboard: A balance-board extension is plugged. This is normally a built-in extension.
procontroller: A pro-controller extension is plugged. This is normally a built-in extension.

Device-dependant interfaces

The following interfaces depend on the device-type. They may be present, depending on the device. However, not that even if they are present, they are not guaranteed to be physically available. For instance, many 3rd party-device pretend to have a built-in battery, but do not report real battery-capacity values. Instead they return a constant or fake value. All the following interfaces are created during device-detection. After device-detection is done, a change uevent is sent. Device-detection is normally performed only once, but may be triggered via debug-hooks from user-space at any time. Applications should be aware of that.

Battery

A power_supply device is available as /sys/bus/hid/devices/[dev]/power_supply/wiimote_battery_[bdaddr]/ and the interface is defined by the kernel power_supply interface. *[bdaddr]* is the bluetooth-address of the remote device.

LEDs

Player-LEDs on a device are available as /sys/bus/hid/devices/[dev]/leds/[dev]:blue:p[num]/ and the interface is defined by the kernel led interface. *[dev]* is the same as the device-name. *[num]* can be any non-negative integer and defines which LED this is. Normally these are 0-3 for the 4 player-LEDs which can be found on any Nintendo Remote. However, newer hardware may use more or less LEDs or skip some (unlikely).

Input: Core

Input-Core: Core input device. It is available as /sys/bus/hid/device/[dev]/input/input[num]/ and can be detected via the device name XWII_NAME_CORE.