WPAD API Introduction

Introduction

The Wii console communicates with its standard controller, the Wii Remote, using wireless technology in the 2.4GHz bandwidth. The Wii Remote includes a rumble motor, a pointer, a motion sensor, a speaker, a player indicator and an external expansion connector. By connecting a variety of external expansion controllers to the external expansion connector, a greater variety of user interfaces is available.

Library Structure

The WPAD library includes a higher-level library (KPAD), and is implemented as follows. The KPAD library is a high-level portion of the WPAD library which was designed so that WPAD library is easier to use within games.

Initialization

Begin initialization of the WPAD library by calling the WPADRegisterAllocator function. This registers the allocator function used to obtain work memory during the initialization process. The size of the work memory allocated by the library can be retrieved using the function WPADGetWorkMemorySize.

Then call the WPADInit function to initialize the WPAD library. Because it will take time to initialize the WPAD library, call the WPADGetStatus function periodically and check when initialization is complete.

Controller Registration

To enable communication between the Wii console and the Wii Remote, you must first register the Wii Remote to the Wii console. Registration occurs automatically when the SYNCHRO button on the front of the Wii console and the SYNCHRO button within the battery cover on the Wii Remote are pressed. Game applications, by calling the WPADSetSyncDeviceCallback function and setting a user callback function in advance, can determine whether the SYNCHRO button on the Wii console was pressed. When a callback function is set, registration will not occur automatically, even when the SYNCHRO button is pressed; begin registration by calling the WPADStartSyncDevice function. In addition, the registered callback function is called again after registration is complete, and you can determine how many Wii Remotes are registered.

Controller Removal

If the SYNCHRO button on the Wii console is pressed for 10 seconds or more, all information on the Wii Remote Controls registered to the Wii console will be automatically deleted. The game application can get this event by calling the WPADSetClearDeviceCallback function and setting a user callback function in advance. When a callback function is set, information on the remote controls is not automatically deleted; this can be started by calling the WPADStartClearDevice function. In addition, the registered callback function is called again when the deletion is complete.

Controller Status Confirmation

The game application can call the WPADProbe function to get the connection status of each number's controller. If an external expansion controller was inserted into a Wii Remote, this function also returns the current type of the external expansion controller. Since this function confirms the insertion and removal of an external expansion controller, we recommend that the game application call this function at least once within the main loop. In addition, you can determine if a controller has been connected or disconnected by using the WPADSetConnectCallback function to register a callback function in advance. Also, the insertion and removal of an external expansion controller can be detected by registering a callback function in advance using the WPADSetExtensionCallback function.

In addition, the WPADGetInfo(Async) function can be called to get the current controller information (remaining battery power, player indicator status, etc.).

Controller Controls

The game application can perform a variety of controls with the Wii Remote, including changing the format of received data, getting the remote control's status, and starting and stopping the pointer. However, all of these controls must be handled exclusively. 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 for some time.

In addition, be aware that the WPAD library uses these queues internally immediately after inserting/removing or connecting an external expansion controller.

Specifying the Received Data Format

The Wii Remote can use its buttons, pointer, and motion sensor. In addition, external expansion controller input can be used by inserting an external expansion controller like a Nunchuk device. However, not all data can be sent because of the wireless specifications. Therefore, 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.

Obtaining Controller Information

There are two ways to obtain the controller information.

• Obtain 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 store (auto-sampling) controller information to the buffer provided by the application.

The buffer for periodically storing controller information is set with 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.

WPADRead and WPADSetAutoSamplingBuf can be used together.

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

The callback function to call every time data is received from a Wii Remote at a specified channel can be registered with the WPADSetSamplingCallback function.

Inserting/Removing External Expansion Controllers

A variety of external expansion controllers can be inserted into the external expansion connector on the Wii Remote even while the Wii Remote is communicating. The game application can detect an insertion/removal of an external expansion controller by using polling with the WPADProbe function or by registering a callback function in advance with the WPADSetExtensionCallback function. If an external expansion controller is inserted/removed during communications, the Wii Remote stops sending controller information. Therefore, when an insertion or a removal is detected, reset the data format for controller information based on that status using the WPADSetDataFormat function. Once settings are complete, controller information will be sent from the Wii Remote.

Rumble Motor Controls

You can use WPADControlMotor function to control the vibration of the Wii Remote for the specified channel. In addition, the WPADStartMotor and WPADStopMotor functions are available as macro functions. You can use WPADEnableMotor function to turn ON or OFF the Rumble Feature of the Wii Remote for the specified channel. The current state of the Rumble Feature can be retrieved using the function WPADIsMotorEnabled. In addition, the configured state can be saved for the Wii Remote using the function WPADSaveConfig.

Speaker Controls

You can use WPADControlSpeaker function to control the speaker of the Wii Remote on the specified channel. Activate the speaker using the function WPADControlSpeaker. Once activated, audio can be output from the speaker by sending audio data using the WPADSendStreamData function. Due to audio specifications of the audio processor of the Wii Remote, 20 bytes of audio data must be sent three times every 20 ms in order to achieve correct audio playback.

You can use WPADSetSpeakerVolume function to set the speaker of the Wii Remote on the specified channel. Note, however, that audio may be interrupted if the volume is changed during playback. Furthermore, the configured volume can be saved for the Wii Remote using the function WPADSaveConfig.

Configuring Controller Features

ON/OFF setting of the Rumble Feature and the speaker volume setting can be saved for each Wii Remote. Values set using the WPADEnableMotor and WPADSetSpeakerVolume functions can be saved for the Wii Remote using the WPADSaveConfig function.

Cautions for Using Wireless LAN

As the Wii console and the Wii Remote Control communicate using a 2.4GHz bandwidth, the use of a wireless LAN running on the same 2.4GHz bandwidth may cause interference with the Wii device, which can prevent proper communications. As a result, when launching a wireless LAN, call the WPADSetDisableChannel function so as not to use the same frequency bandwidths used for the wireless LAN.

Revision History

08/01/2005 Initial version.
08/30/2005 Modified description of buttons in Introduction; added a bug report
09/27/2005 Changed abbreviation to DPD. Deleted description of hardware in the Introduction section
11/01/2005 Added caution about SI to reflect the change of the interface from EXI to SI. Added links to functions. Added KPAD library introduction text. Added bug report.
11/09/2005 Corrected warnings about use of GameCube standard controller. Changed description of PAD library treatment in GameCube SDK. Added bug report.
11/10/2005 Added description of DPD module's hardware bug.
06/19/2006 Deleted the object size restriction from the cautions specific to UI tools.
07/04/2006 Added speaker-related information.