xwiimote 2

- Main Page
- Modules
- Data Structures
- Files

Macros
Kernel ABI

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.

TODO: Describe the provided interface

## Input: Accelerometer

Input-Accel: Accelerometer input device. Available as `/sys/bus/hid/device/[dev]/input/input[num]/` and can be detected via the device name XWII_NAME_ACCEL. If this input-interface is not opened by user-space, the accelerometer on the remote is disabled to save energy.

TODO: Describe the provided interface

## Input: IR

IR input device. It is available as `/sys/bus/hid/device/[dev]/input/input[num]/` and can be detected via the device name XWII_NAME_IR. If this input-interface is not opened by user-space, the IR-cam on the remote is disabled to save energy.

TODO: Describe the provided interface

# Motion-Plus Interfaces

The following interfaces belong to motion-plus capabilities. Motion-Plus extension may be hotplugged or built-in. Even if built-in, they are handled as special hotplugged extensions. So if you want to use Motion-Plus, you must handle uevents properly. As MotionPlus hotplug events are not generated by the device, the kernel driver needs to periodically poll for them (only if not built-in). Hence, hotplug-events may be delayed by up to 5s. MotionPlus and related hardware is often abbreviated with MP or **M+**.

## Input: MP

Motion-Plus input device. Is is available as `/sys/bus/hid/device/[dev]/input/input[num]/` and can be detected via the device name XWII_NAME_MOTION_PLUS. If this input-interface is not opened by user-space, the MP device is disabled to save energy. While the interface is opened, MP hardware hotplug events are generated by the remote device so we don't need to poll for MP availability.

TODO: Describe the provided interface

# Extension Interfaces

The following interfaces are extension interfaces. They are created whenever an extension is hotplugged to a device. Only one extension-port is currently available on each hardware (exposed via extension attribute), but newer hardware may introduce more ports. Therefore, these extension might be available simultaneously. However, in this case additional extension2 or similar attributes will also be introduced. Note that some devices have built-in extensions which cannot be hotplugged. But these extensions are handled as if they were normal hotpluggable extensions.

Extension-changes are advertized via udev uevents. The remote device sends hotplug-events for regular extensions so they are deteced immediately (in a few hundred milliseconds). Note that devices are not initialized unless userspace opens them. This saves energy as we don't need to power them up or stream any data.

## Input: Nunchuk

Nunchuk extension input device. Available as `/sys/bus/hid/device/[dev]/input/input[num]/` and can be detected via the device name XWII_NAME_NUNCHUK.

TODO: Describe the provided interface

## Input: Classic Controller

Classic Controller extension input device. Available as `/sys/bus/hid/device/[dev]/input/input[num]/` and can be detected via the device name XWII_NAME_CLASSIC_CONTROLLER. The Classic Controller Pro is also reported via this interface, but cannot be distinguished from a normal classic controller extension.

TODO: Describe the provided interface

## Input: Balance Board

BalanceBoard extension input device. Available as `/sys/bus/hid/device/[dev]/input/input[num]/` and can be detected via the device name XWII_NAME_BALANCE_BOARD.

TODO: Describe the provided interface

## Input: Pro Controller

Wii-U Pro Controller extension input device. Available as `/sys/bus/hid/device/[dev]/input/input[num]/` and can be detected via the device name XWII_NAME_PRO_CONTROLLER.

TODO: Describe the provided interface