WPAD Library Overview

Introduction

The Wii U console communicates with its standard controller, the Wii remote, using wireless technology in the 2.4 GHz band. The Wii remote includes a Rumble motor, Pointer, Motion Sensor, speaker, Player Indicator, and external extension connector. When external extension controllers are connected to the external extension connector, a variety of user interfaces become available. For information on setting up a wired Wii Remote, see Set Up a Wired Wii Remote.

The Wii Balance Board communicates with the Wii U console using the 2.4 GHz wireless band in the same manner as the Wii remote. However, the Wii Balance Board does not have parts such as the Rumble motor, Pointer, Motion Sensor, speaker, or external extension connector. Instead, it has pressure sensors specialized for measuring weight and center of gravity placed on each of its four corners.

Libraries

Library Organization

The WPAD library, which includes a higher-level library (KPAD), is implemented as follows. The WBC library is a high-level WPAD library that calculates weight from the values obtained by the WPAD library for the Wii Balance Board's pressure sensors. The KPAD library is a high-level WPAD library designed to make it easier for games to use input data obtained from the WPAD library. The KPAD library can handle weight data if the WBC library has been linked.

KPAD API
WPAD APIWBC API
WPAD API

Relationship Between the Library and External Extension Controllers

The WPAD library detects the Nunchuk and Classic Controller by default. The WPAD library can detect other external extension controllers and the Wii Balance Board if a special library is linked for each device. If these special libraries are not linked, whenever an external extension controller is connected, it is recognized as WPAD_DEV_FUTURE. A Wii Balance Board cannot be connected if the WBC library is not linked.

Shown below are controllers and the libraries required for the WPAD library to detect them.

WPAD_DEV_BALANCE_CHECKER WBC library.
WPAD_DEV_GUITAR WPADGtr library.
WPAD_DEV_DRUM WPADDrm library.
WPAD_DEV_TAIKO WPADTko library.
WPAD_DEV_TRAIN WPADTrn library.
WPAD_DEV_TAIKO WPADTko library.
NOTE:
Libraries other than WBC are not included with the standard Cafe SDK. Developers who require these libraries should contact your local Nintendo developer support group.

Initialization

Initialization Timing

Wii U Bluetooth devices will stay connected through system restarts and process switches but only if the time that the library is stopped is less than 10 seconds. For this reason, WPAD initialization (see WPADInit) should be performed early in the boot up process.

Initializing Wii Balance Board- and Wii U Pro Controller-Compatible Applications

If an application supports the Wii Balance Board it is necessary that the application registers with the WPAD library using the WPADEnableWBC function after initializing the WPAD library. Similarly, also see WPADEnableURCC and WPDEnableWiiRemote.

Applications That Do Not Support Wii Remotes, Wii U Pro Controller and Wii Balance Board

If an application does not support any Wii U Bluetooth devices (Wii Remotes, Wii U Pro Controller and Wii Balance Board) it is necessary that the application calls WPADDisableBluetooth indicating that the application does not support any of the aforementioned devices. After calling this API, all the connections from all support Bluetooth devices will be denied. The POWER Button on the Wii Remotes (or Wii U Pro Controller) will not work as long as the application which called this API is active.

Allocating Memory

It is no longer necessary for an application to call WPADRegisterAllocator to provide the Bluetooth stack with memory. It is no longer necessary for an application to call WPADGetWorkMemorySize to get the memory size provided by WPADRegisterAllocator. Both of these functions have been deprecated and will be removed in future SDKs.

Registering and Removing Devices

For devices to communicate with the Wii U console, both the Wii U console and the device must first be registered with each other. This registration process is referred to as pairing. The Wii U console and the device can each register only a fixed number of corresponding devices or consoles. If more than this number are paired to either one, information for those already paired are overwritten. For information on setting up a wired Wii Remote, see Set Up a Wired Wii Remote.

Adding and Removing Wii remotes

The pairing information of a normal-paired Wii remote remains registered even after the Wii U console power has been turned OFF, and with a normal-paired Wii remote, Wii U console power can also be turned ON or OFF using the Wii Remote POWER Button.

Paired device count

For Wii remotes, a Wii U console can store 10 normal pairings.

Normal pairing

Normal pairing is performed by pressing the SYNC Button on the front of the Wii U console, or by calling the WPADStartSyncDevice function and pressing the SYNC Button inside the battery cover of the Wii remote. When the pairing completes, the Wii remote information will be stored in the Wii U console. In the same way, the Wii U console information will be stored in the Wii remote.

By calling the WPADSetSyncDeviceCallback function and setting a user callback function in advance, game applications can determine when the SYNC Button on the Wii U console is pressed. If a callback function has been set, pairing will not occur automatically when the SYNC Button is pressed; in such cases you must begin the pairing by calling the WPADStartSyncDevice function. The registered callback function will also be called again after pairing is complete, and it will send notification of how many Wii remotes were successfully paired.

Adding and Removing Wii Balance Boards

The Wii Balance Board can use only normal pairing. While the Wii Balance Board is paired, up to nine Wii remote pairings can be stored. Wii balance Boards are paired, and their pairing information deleted, in the same manner as a Wii remote.

Synchronization Process During Pairing

When you pair a Wii Balance Board to a Wii U console, the Wii Balance Board's pairing information is stored in the system configuration file. If save data for the Japanese version of Wii fit is present on the Wii U console, the pairing information is also stored in that save data.

Controller POWER Button

A Wii U console's power can be turned ON or OFF with the Wii remote POWER Button. If the console is currently turned OFF, it is turned ON by pressing the POWER Button. If the console is currently turned ON, pressing the POWER Button for approximately one second will send a power-OFF signal to the console.

Controller Status Confirmation

Game applications can call the WPADProbe function to get the connection status of each controller by its number. If an external extension controller is plugged into a Wii remote, this function also returns the current type of the external extension controller. Because this function confirms the insertion and removal of an external extension controller, we recommend that the game application call this function at least once within the main loop. To determine if a controller has been connected or disconnected, use the WPADSetConnectCallback function to register a callback function in advance. To detect the insertion and removal of an external extension controller, use the WPADSetExtensionCallback function to register a callback function in advance.

When a Wii remote which already has an external extension controller inserted is connected to a Wii U console, the type of the external extension controller is not immediately known, because recognition of the external extension controller only occurs after the Wii remote has completed its connection. Accordingly, the status obtained by the WPADProbe function changes over time. Immediately after the Wii remote is connected, the function returns WPAD_DEV_CORE. After that, the Wii remote notifies the console that it has an external extension controller attached, and the library checks the external extension controller's type. In the period between notification and verification of the controller's type, the function returns WPAD_DEV_UNKNOWN. Following verification, the function returns a value such as WPAD_DEV_FREESTYLE or WPAD_DEV_CLASSIC, depending on the type.

The WPADGetInfo/WPADGetInfoAsync functions can also be called to get the current information about the controller (remaining battery power, Player LED status, and so on).

Controller Control

Game applications can perform a variety of controls on the Wii remote, including changing the format of the received data, obtaining the status of a Remote, and starting and stopping the Pointer. However, these controls must wait for an ACK to be received from the Wii remote, and must be processed exclusive of one another. When the ACK is returned only the Wii remote's button information (out of all the controller information normally returned) is returned along with it. Be aware that if the Motion Sensor, Pointer, or an external extension controller is being used, it will not be possible to obtain their inputs.

The WPAD library maintains separate command queues internally for each channel, and requests from the game application are managed by these queues. When the WPAD library cannot add a new request, WPAD_ERR_BUSY is returned; when this error is returned to the game application, the request should be issued again after waiting.

Be aware that the WPAD library uses these queues internally immediately after attaching, detaching, or connecting an external extension controller.

Specifying the Received Data Format

The Wii remote can use its buttons, Pointer, and Motion Sensor. In addition, external extension controller input can be used by attaching an external extension controller like the Nunchuk. However, because of the wireless specifications, not all of this data can be sent. The game application must call the WPADSetDataFormat function to select the format for the controller information according to its application. The following formats for controller information are available.

WPAD_FMT_CORE Wii remote buttons only.
WPAD_FMT_CORE_ACC Wii remote buttons and Motion Sensor.
WPAD_FMT_CORE_ACC_DPD Wii remote buttons, Motion Sensor, and Pointer (coordinate data and size).
WPAD_FMT_FREESTYLE Wii remote buttons and the Nunchuk.
WPAD_FMT_FREESTYLE_ACC Wii remote buttons, Motion Sensor, and the Nunchuk.
WPAD_FMT_FREESTYLE_ACC_DPD Wii remote buttons, Motion Sensor, Pointer (coordinate data), and the Nunchuk.
WPAD_FMT_CLASSIC Wii remote buttons and the Classic Controller.
WPAD_FMT_CLASSIC_ACC Wii remote buttons, Motion Sensor, and the Classic Controller.
WPAD_FMT_CLASSIC_ACC_DPD Wii remote buttons, Motion Sensor, Pointer (coordinate data), and the Classic Controller.
WPAD_FMT_CORE_ACC_DPD_FULL Wii remote buttons, Motion Sensor, and Pointer (coordinate data, size, object radius, pixel value, and range).
NOTE:
The sampling rate is half of the rate for other formats.
WPAD_FMT_TRAIN Wii remote buttons and the Master Controller.
WPAD_FMT_GUITAR Wii remote buttons, Motion Sensor, Pointer (coordinate data), and Guitar Controller.
WPAD_FMT_DRUM Wii remote buttons, Motion Sensor, Pointer (coordinate data), and the Drum Controller.
WPAD_FMT_TAIKO Wii remote buttons, Motion Sensor, Pointer (coordinate data), and the Taiko Controller.
WPAD_FMT_BALANCE_CHECKER Wii Balance Board.
WPAD_FMT_MPLS Wii remote buttons, Motion Sensor, Pointer (coordinate data), and Wii MotionPlus. Use this format when the format is MotionPlus Style, Nunchuk/MotionPlus Style, or Classic/MotionPlus Style. In addition, when using Nunchuk/MotionPlus Style or Classic/MotionPlus Style, the Wii MotionPlus sampling rate and the Nunchuk or Classic Controller sampling rate is half the normal rate. Classic/MotionPlus Style is not supported by Wii MotionPlus PP2.
WPAD_FMT_URCC URCC.
NOTE:
When selecting a format that uses the Pointer, before calling WPADSetDataFormat, call the WPADControlDpd function to start the Pointer.

Getting Controller Information

There are two ways to obtain controller information.

Get only the most recent controller information

Use the WPADRead function to get the most recent controller information for the Wii remote on the specified channel.

Periodically use auto-sampling to store the controller information to the buffer provided by the application

To set the buffer for periodically storing controller information, use the WPADSetAutoSamplingBuf function. Buffers are used internally as ring buffers. The buffer index that stored the most recent controller information can be obtained with the WPADGetLatestIndexInBuf function.

The WPADRead and WPADSetAutoSamplingBuf functions can be used together.

The type of the controller information that can be obtained with the WPADRead and WPADSetAutoSamplingBuf functions is recorded in a structure type that corresponds to the data format specified by the WPADSetDataFormat function. For information on controller types, data formats, and corresponding structure types, see the section about the WPADSetDataFormat function. If the data is recorded in a structure type that does not match the data format, it may not be possible to get valid data.

Use the WPADSetSamplingCallback function to register the callback function called every time the data is received from a Wii remote at a specified channel.

Processing +Control Pad Restrictions

Prohibition processing for the +Control Pad of the Wii remote and the Classic Controller is performed internally by the WPAD library. If the +Control Pad physically breaks and its input is in a state that is ordinarily impossible, such as simultaneous presses of Left and Right, the library processes it as valid input of Left. Similarly, if Up and Down are simultaneously pressed, the library takes the valid input to be Up.

Attaching and Detaching External Extension Controllers

A variety of external extension controllers can be attached to the Wii remote through the external extension connector, even while the Wii remote is communicating. The game application can detect the insertion or removal of an external extension controller. It does this by polling with the WPADProbe function or by registering a callback function in advance using the WPADSetExtensionCallback function. Immediately after an External Extension Controller has been inserted in the Wii U console, however, it is impossible to know what has been inserted. Therefore WPAD_DEV_UNKNOWN is used as the device type at the time of detection. Later, as soon as the type of External Extension Controller is known, the device type is updated (for example, WPAD_DEV_FREESTYLE or WPAD_DEV_CLASSIC). Also, if an external extension controller is inserted or removed during communications, the Wii remote stops sending controller information. Therefore, when a plug insertion or removal is detected, use the WPADSetDataFormat function to reset the controller information's data format according to the situation. After the settings are complete, controller information will be sent from the Wii remote.

Rumble Feature Controls

The Rumble feature of the Wii remote can be turned ON or OFF. The ON/OFF setting is stored internally within the library. When the library is initialized, the ON/OFF setting for the Rumble feature is set by default to the value in the console settings. When the Rumble feature is turned ON, the WPADControlMotor function can be used to control the rumble feedback of the Wii remote on a specified channel. In addition, the WPADStartMotor and WPADStopMotor functions are available as macro functions.

The status of the Rumble feature's ON/OFF setting maintained within the library can be obtained with the WPADIsMotorEnabled function. Although the WPADEnableMotor function can turn the Rumble feature ON or OFF, do not enable the Rumble Feature when it has been turned OFF in the console settings.

Speaker Controls

Outputting Audio Through the Speaker

Use the WPADControlSpeaker function to control the speaker of the Wii remote on the specified channel. Activate the speaker using the function WPADControlSpeaker. After activation, audio can be output from the speaker by sending audio data using the WPADSendStreamData function. Due to the audio specifications of the audio processor of the Wii remote, 20 bytes of audio data must be sent three times every 20 ms to achieve correct audio playback.

Adjusting the Speaker Volume

To set the speaker volume of the Wii remote on a specified channel, use the WPADSetSpeakerVolume function. However, because this volume change is not enabled until the speaker is restarted with the WPADControlSpeaker function, the volume of the Wii remote speaker's currently playing audio will not change. To alter the volume of the currently playing audio, change the volume of the audio data source. The volume configured using this function can be saved in the Wii U console using the WPADSaveConfig function.

Starting and Stopping the Speaker

To avoid wearing down the batteries in scenes where no audio is output through the Wii remote speaker for a period of time, use the WPADControlSpeaker function to send the WPAD_SPEAKER_OFF command whenever possible to stop the speaker. However, starting or stopping the speaker will prevent you from being able to obtain several samples' worth of input from the Motion Sensor, Pointer, and external extension controller of the Wii remote. Accordingly, in scenes in which audio is output frequently, there is no need to start and stop the speaker often. In such scenes, keep the speaker ON the whole time, and instead of starting and stopping the speaker, use the WPADControlSpeaker function to send a WPAD_SPEAKER_MUTE or WPAD_SPEAKER_MUTE_OFF command to turn muting ON/OFF.

Broken or Skipping Audio

Due to the audio processor and wireless communication specifications of the Wii U console and the Wii remote, there are times when the audio will break or skip. Broken audio (crackling and popping) occurs when the state of the encoder on the Wii U console side and the decoder on the Wii remote side are out of sync with each other. The audio will break up as long as the encoder and decoder are out of sync. To synchronize the state of the encoder and decoder, you must restart the speaker. Audio skipping occurs when a sample on the Wii remote side could not be processed. Consequently, even if you do not take any specific action, there are no problems with subsequent playback.

Due to the audio processor specifications, audio played with the Wii remote's speaker may break or skip if audio is played back continuously for eight minutes or longer.To avoid this, do one of the following:

In addition, due to the specifications for wireless communication, it has been confirmed that the Wii remote speaker will break up audio in the following situations. To avoid broken audio in the following cases, call the WPADCanSendStreamData function when sending audio to make sure the audio can be sent and played without breaking up.

Configuring Controller Features

The Rumble feature ON/OFF setting and speaker volume setting for Wii remotes can be saved on the Wii U console. Values set with the WPADEnableMotor and WPADSetSpeakerVolume functions can be saved on the Wii U console using the WPADSaveConfig function.

NOTE:
Do not allow these settings to be changed outside the HOME Menu in the release version.

Handling Wii remote Acceleration Noise

If your application makes use of small acceleration values, be sure to realize the existence of Wii remote acceleration noise.

For more information, see the Wii U Overview.

Classic Controller and Classic Controller Pro

The Classic Controller and the Classic Controller Pro differ in terms of the shapes of the L and R analog buttons and the quantity of analog input. However, the Classic Controller Pro is recognized as a regular Classic Controller when it is attached to the Wii remote, so applications cannot distinguish between the two.

For this reason, L and R analog button input is not allowed and always returns zero. Also, it is harder to send input from the L Button and R Button of the Classic Controller than from the Classic Controller Pro because the buttons must be pressed down. Now, even partially pressing the L Button or the R Button is recognized as button input.

URCC

URCC is a controller with buttons and two analog sticks which connects the same way with Bluetooth. It looks like an attachment device for Wii Remote for WPAD library. There are no buttons or sensor for the Wii Remote. URCC is only able to connect to an application which supports it. To support URCC, the application needs to call WPADEnableURCC.

Error Codes

The error codes returned from the WPAD library can be grouped into the following three categories.

Because only the first and second categories of error codes will be described here, for the third category of errors, refer to the individual function descriptions.

Among the error codes defined in the WPAD library, those returned by the WPADProbe function are described below.

WPAD_ERR_NONE The Wii remote is connected, and control commands are not being sent from the Wii U console to the Wii remote.
WPAD_ERR_NO_CONTROLLER The Wii remote is disconnected.
WPAD_ERR_BUSY A control command has been sent to a connected Wii remote, and the system is waiting for an ACK from the Wii remote.

Shown below are the error codes that are passed to the err member variable of the WPADStatus structure, and the descriptions of those error codes.

WPAD_ERR_NONE Data with the specified data format was received.
WPAD_ERR_NO_CONTROLLER Data has never been received.
WPAD_ERR_INVALID The format of incoming data is different from the format specified for the WPAD library. Values other than err and dev are undefined.
(In this case, the Wii remote and external extension controller data is invalid.)
WPAD_ERR_CORRUPTED An external extension controller, such as the Nunchuk or Classic Controller, is partially inserted into the Wii remote. Data for the external extension controller is corrupted. (However, Wii remote data is not corrupted.)

Automatic Disconnect

If there has been no change in controller input for a fixed period of time, the WPAD library will disconnect. This prevents the Wii remote's battery power from running out due to user neglect. The WPAD Library checks for input from the buttons, Motion Sensor, Pointer, and external extension controller. Consequently, even if the Wii remote is left alone, its input may change if someone walks heavily around it, if the Pointer is facing the window, or in some other situations. Be aware that the Wii remote may therefore not be disconnected after the set period of time.

Although the initial setting is 5 minutes, it can be changed with the WPADSetAutoSleepTime function. It is also possible to use the WPADResetAutoSleepTimeCount function to reset the elapsed time since input stopped changing.

Resetting the Analog Stick Origin

The analog stick origin of a Nunchuk or Classic Controller can be reset by holding down the A Button, B Button, + Button and the - Button on the Wii remote or Classic Controller for three seconds. However, the origin cannot be reset with button combinations such as the A Button and B Button on the Wii remote combined with the + Button and the - Button on the Classic Controller.

Controller Port Mapping

The WPAD library keeps track of the last Wii remote that connected to each controller port only while the Wii U console is running. That is, this information is cleared if the Wii U console is shut down, but remains unchanged if the Wii U console is reset. (Information recorded to each controller port is cleared immediately after the Wii U console is started.)

When a Wii remote initiates a connection, its information is compared with the information for the last Wii remote to be connected to each controller port. If the same information is found, the Wii remote is assigned to that controller port. If the same information could not be found after checking all of the controller ports, it is assigned to the open controller port with the lowest number.

Recorded Wii remote information is cleared in the following situations. If the WPADDisconnect function is used to disconnect a Wii remote, information is cleared for the Wii remote on the disconnected controller port. If the POWER Button is pressed and held to shut down the Wii U console, the Wii remote information for all controller ports is cleared.

For example, the following shows the Wii U console immediately after starting up.

Port 1----
Port 2----
Port 3----
Port 4----

If Wii remotes A, B, and C are connected in order, the lowest-numbered open port is assigned to each Wii remote in order because no Wii remote information has been stored.

Port 1Wii remote A
Port 2Wii remote B
Port 3Wii remote C
Port 4----

Assume that Wii remote A is disconnected due to a depleted battery and that Wii remote B is disconnected after a fixed period of time without input. At this point, the information in Port 1 and Port 2 is kept unchanged.

Port 1Wii remote A
Port 2Wii remote B
Port 3Wii remote C
Port 4----

When Wii remote B is reconnected after its battery has been replaced, it is assigned to Port 2 because its information is still recorded there.

Port 1Wii remote A
Port 2Wii remote B
Port 3Wii remote C
Port 4----

When Wii remote D is connected, its information has not been recorded anywhere, so it is assigned to the open port with the lowest number: Port 1. The information in Port 1 is replaced with Wii remote D's information.

Port 1Wii remote D
Port 2Wii remote B
Port 3Wii remote C
Port 4----

When Port 1 is disconnected using the WPADDisconnect function, its information is cleared.

Port 1----
Port 2Wii remote B
Port 3Wii remote C
Port 4----

When the Wii U console is shut down, all information is cleared.

Port 1----
Port 2----
Port 3----
Port 4----

Termination Processing

WPAD cannot be terminated by the game application; termination is managed by the Cafe Operating System.

Cautions When Using the Wireless LAN

The Wii U console and the Wii remote communicate using the 2.4 GHz band. Using a wireless LAN on the same 2.4 GHz band may cause interference, resulting in communication problems. To avoid such interference, the SDK automatically switches the frequency band that it uses. The application no longer needs to track this issue.

Interference from Other Wireless Devices

When the application is reset while the Wii remote is attached, in some rare instances the Auto-Reconnect process does not work properly and the Wii remote is not automatically connected.

This is because the process may occasionally fail if a rash of communication errors occur during the reconnection process (for example, due to jamming).

Because it is impossible for the application to do anything to avoid these symptoms when they occur, there is no specific workaround.

Caution Messages Under a Bad Wireless Environment

WPAD measures wireless environment automatically. When Bluetooth packet rate is less than half of the maximum packet rate, WPAD dumps messages similar to the following.

WPAD: !!! Radio quality is critically bad. chan=CHAN,radioSense=PACKET_RATE

When this message appears to the console, the following issues will occur.

Revision History

2014/09/29 Caution message under bad wireless environment.
2013/06/21 Clarify termination processing.
2013/05/08 Automated cleanup pass.
2013/04/17 Moved MotionPlus information to it's own page in KPAD.
2012/06/28 Added information about recalibration.
2012/06/27 Removed deprecated WPADRegisterAllocator API.
2012/06/25 Removed deprecated WBC API.
2012/04/02 Removed deprecated mpls API.
2012/02/27 Add description for URCC. Add WPAD_FMT_URCC
2011/02/21 DRAFT


CONFIDENTIAL