The Wii console communicates with its standard controller, the Wii Remote, using wireless technology in the 2.4 GHz bandwidth. The Wii Remote features a rumble motor, a pointer, a motion sensor, a speaker, a set of player indicators, and an External Extension Connector. By connecting an assortment of External Extension Controllers to the External Extension Connector, a variety of user interfaces are available.
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 would be easier to use within games.
| KPAD API |
| WPAD API |
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. Be sure to implement the allocator so that that work memory can be acquired from MEM2. The total 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, periodically call the WPADGetStatus function to check when initialization is complete.
To enable communication between the Wii console and the Wii Remote, you must first pair the Wii Remote with the Wii console. Controller pairing comes in two formats: normal pairing and simple pairing. The pairing information of a Wii Remote that has been normal paired remains registered even after the power to the Wii console is turned off. Also, the on/off operation of the Wii console can be performed with the Wii Remote Power Button.
Changed the specification for simple pairing: the pairing information for a simple-paired Wii Remote is now maintained until the Wii console is shut down.As a result, simple-paired Wii Remotes can remain connected to the Wii even when applications are reset, and when moving between the Wii Menu and various Channels.However, applications built with SDK versions SDK2.4 patch6 or earlier use the old specification for simple pairing. Thus, when you move to one of these applications, the connection of the simple-paired Wii Remote will be dropped. Furthermore, if simple pairing is conducted while this kind of application (an application built with the SDK versions SDK2.4 patch6 or earlier) is running, the connection will be dropped even if the process later moves to an application that uses the new specification for simple pairing.
The Wii console can store 10 normal pairings for Wii Remotes and six simple pairings for Wii Remotes. A single Wii Remote will be treated as being paired using one of these two methods. The Wii Remote can store both one standard pairing for a Wii console and one simple pairing for a Wii console. A single Wii console will be treated as paired using one of these two methods.
When a normal pairing is performed on a device paired with simple pairing, that device is then treated as having normal pairing. However, when a simple pairing is performed on a device paired with normal pairing, that device continues to be treated as having normal pairing.
Normal pairing is performed by pressing the SYNCHRO button on the front of the Wii console or by calling theWPADStartSyncDeviceorWPADStartFastSyncDevicefunction and pressing the SYNCHRO button inside the battery cover of the Wii Remote. Once pairing completes, the information in the Wii Remote is stored in the Wii console. Similarly, the information for the paired Wii console is stored in the Wii Remote.
Game applications, by calling theWPADSetSyncDeviceCallbackfunction 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, pairing will not occur automatically, even when the SYNCHRO button is pressed; begin pairing by calling theWPADStartSyncDevicefunction. In addition, the registered callback function is called again after pairing is complete, and you can determine how many Wii Remotes are paired.
The simple pairing remains effective only until the Wii console is shut down. The game application may start a simple pairing by calling theWPADStartSimpleSyncorWPADStartFastSimpleSyncfunctions. Simple pairing occurs when the 1 and 2 Buttons on the Wii Remote are pressed at the same time. However, if there is a currently registered Wii console, the Wii Remote will attempt connection with that Wii console when the 1 and 2 Buttons are pressed. When the connection fails, the simple pairing starts.
Simple pairing is executed repeatedly until there are up to four Wii Remotes or is stopped when an application calls theWPADStopSimpleSyncfunction. If a callback is registered, the callback function is called once the pairing process is complete to indicate the number of paired Wii Remotes.
Pairing fails when carrying out fundamentally different pairing. However, pairing will be successful in the following cases:
- When the Wii console is simple pairing and the Wii Remote is normal pairing, the existing pairing information will not be updated and the two will be connected as-is.
- When the Wii console is normal pairing and the Wii Remote is simple pairing, the Wii Remote may be connected before starting simple pairing.
- When the Wii console is simple paired with an already normal paired Wii Remote, the pairing will succeed as normal pairing.
- When normal pairing is invoked for a Wii remote that has already undergone simple pairing by the Wii console, the simple pairing is eliminated and replaced by normal pairing.
If the Wii console SYNCHRO is pressed for 10 seconds or more, all information on the Wii Remotes paired to that Wii console will be deleted. However, the pairing information in the Wii Remote remains intact.
The game application can get this information 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 deleted; this can be started by calling the WPADStartClearDevice function. The registered callback function is called again when the all Wii Remotes are released.
Furthermore, neither normal pairing nor simple pairing can be carried out while deleting the Wii Remote's pairing information.
The Wii console can be turned on and off using the Wii Remote Power Button. If turned off, the Wii console is turned on by pressing the Power Button. If the Wii console is turned on, pressing the Power Button for approximately one second will send a power off signal to the console. Also, the callback registered by the OSSetPowerCallback function is called.
However, the power on/off operation can be performed only with a Wii Remote paired with normal pairing. This will not work with a Wii Remote paired with simple pairing.
The game application can perform a variety of controls with the Wii Remote by sending control commands, including changing the format of received data, getting the Wii Remote's status, and starting and stopping the pointer. If a control command is sent to the Wii Remote, an ACK will be returned from the Wii Remote. If an ACK is received, the next control command can be sent to the Wii Remote.
If the game application calls a function that sends a control command, the control command will be stored in the queue maintained within the WPAD library. The WPAD library will start to process the control commands stored in the queue while checking the ACKs from the Wii Remote. When it is not possible to 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.
In addition, be aware that the WPAD library uses these queues internally immediately after attaching/detaching an external extension controller in order to initialize the Wii Remote or external extension controller.
A game application can call the WPADProbe function to get the connection status and the controller type of each controller number. The connection statuses that can be obtained and their respective meanings are shown below:
WPAD_ERR_NONE |
The Wii Remote is connected and control commands are not being sent from the Wii 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. However, in this state, the Wii Remote sends the controller information just as it does normally. This means that the WPADRead function can be used to obtain controller information. |
WPAD_ERR_TRANSFER |
The control command that was sent to the Wii Remote has failed. |
In order to check the controller status, you can send notification by means of a callback in addition to periodically calling the WPADProbe function. The WPADSetConnectCallback function calls the registered callback when a controller is connected or disconnected. The WPADSetExtensionCallback function calls the registered callback when an external extension controller is inserted or removed and the controller type changes.
When connecting a Wii Remote with an external extension controller inserted in the Wii console, the type of the external extension controller is not immediately known, because awareness of the external extension controller only occurs after the Wii Remote has completed its connection. The status obtained by the WPADProbe function changes with time.
| Immediately after connection | WPAD_DEV_CORE |
| ↓ | |
| The period of time between when a external extension controller notification is made from the Wii Remote until the type is obtained | WPAD_DEV_UNKNOWN |
| ↓ | |
| After the type of the external extension controller is obtained | WPAD_DEV_FREESTYLEWPAD_DEV_CLASSIC |
In addition, the WPADGetInfo(Async) function can be called to get the current information about the controller (remaining battery power, player indicator light status, and so on).
There are two methods of obtaining controller information: (1) obtaining only the latest controller information using the WPADRead function and (2) using the WPADSetAutoSamplingBuf function to automatically store the controller information in a buffer prepared by the application. WPADRead and WPADSetAutoSamplingBuf can be used together.
The WPADRead function can be called at any time as long as the Wii Remote is connected. In other words, it can be called when the WPADProbe function returns anything other than WPAD_ERR_NO_CONTROLLER.(It can also be called when WPAD_ERR_BUSY is returned.)
The WPADSetAutoSamplingBuf function sets the buffer that stores controller information automatically when controller information is received from the Wii Remote, and the buffer is used internally as a ring buffer. The buffer index that stored the most recent controller information can be obtained with the WPADGetLatestIndexInBuf function. Using the WPADSetSamplingCallback function, it gets the number of times that controller information has been received, and by comparing this number with the previous index, it can process the stored controller information in the order in which it was received.
The types of the controller information that can be obtained with the WPADRead and WPADSetAutoSamplingBuf functions are stored in the types of the structure that corresponds to the data format specified by the WPADSetDataFormat function. The data format of the received data and the corresponding types of structures are shown below.
WPAD_FMT_CORE |
Wii Remote data format (WPADStatus structure). Only button information is valid. Note: This is the default type. |
WPAD_FMT_CORE_ACC |
Wii Remote data format (WPADStatus structure). The button and motion sensor information is valid. |
WPAD_FMT_CORE_ACC_DPD |
Wii Remote data format (WPADStatus structure). The button, motion sensor, and pointer information is valid. The pointer has valid size and coordinate data. |
WPAD_FMT_FREESTYLE |
Nunchuk Style data format type (WPADFSStatus structure). For the Wii Remote, only the button information is valid. |
WPAD_FMT_FREESTYLE_ACC |
Nunchuk Style data format type (WPADFSStatus structure). For the Wii Remote, the button and motion sensor information is valid. |
WPAD_FMT_FREESTYLE_ACC_DPD |
Nunchuk Style data format type (WPADFSStatus structure). The Wii Remote button, motion sensor, and pointer information is valid. However, only the coordinate data is valid for the pointer. |
WPAD_FMT_CLASSIC |
Classic Style data format type (WPADCLStatus structure). Only the button information is valid for the Wii Remote. |
WPAD_FMT_CLASSIC_ACC |
Classic Style data format type (WPADCLStatus structure). The button and motion sensor information is valid for the Wii Remote. |
WPAD_FMT_CLASSIC_ACC_DPD |
Classic Style data format type (WPADCLStatus structure). The Wii Remote button, motion sensor, and pointer information is valid. However, only the coordinate data is valid for the pointer. |
WPAD_FMT_CORE_ACC_DPD_FULL |
Wii Remote extended data format (WPADStatusEx structure). The Wii Remote button, motion sensor, and pointer information is valid. For the pointer, the coordinate data, size, object radius, pixel value, and range are valid. However, the data rate is half that of normal (roughly 100 samples per second). |
The err member of the WPADStatus structure indicates the status of the controller information, and the value of the dev member indicates the controller type at the point in time when the controller information was received. For controller information that was obtained with the WPADRead or WPADSetAutoSamplingBuf functions, check the value of the err member and only use valid input information. The error codes that are passed to err and their descriptions are shown below.
WPAD_ERR_NONE |
The case when the controller information was received correctly. In this case, the data for the Wii Remote and the external extension controllers were all valid. |
WPAD_ERR_INVALID |
The case when the data that was received has a different data format than what was specified for the WPAD library. In this case, the data for the Wii Remote and external extension controllers is all invalid. |
WPAD_ERR_CORRUPTED |
The case when an external extension controller such as the Nunchuk or Classic Controller is partially inserted into the Wii Remote, and the data for the external extension controller is corrupted. In this case, the data from the Wii Remote's buttons, motion sensors, and pointer are not corrupted. |
WPAD_ERR_BUSY |
The case when an ACK has been received in response to a control command. In this case, the Wii Remote's button data can be used, but the motion sensor and pointer data are invalid. |
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 a Nunchuk. 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.
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 values, and range) Note that the sampling rate is half that of other formats. |
Note: When specifying a format from among the above that uses the pointer, call the WPADControlDpd function to start the pointer before calling the WPADSetDataFormat function.
A variety of External Extension Controllers can be attached to the Wii Remote via the External Extension Connector even while the Wii Remote is communicating. The game application can detect the attachment/detachment of an External Extension Controller by using polling with the WPADProbe function or by registering a callback function in advance with the WPADSetExtensionCallback function. If an External Extension Controller plug is inserted/removed during communications, the Wii Remote stops sending controller information. Therefore, when a plug insertion or removal is detected, reset the data format for controller information to match the situation using the WPADSetDataFormat function. Once the settings are complete, controller information will be sent from the Wii Remote.
The Rumble Feature of the Wii Remote can be turned ON/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 Wii Settings. When the Rumble feature is set to ON, you can use the 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.
The status of the ON/OFF setting for the Rumble feature that is stored within the library can be obtained using the WPADIsMotorEnabled function.
You can use theWPADControlSpeakerfunction to control the speaker of the Wii Remote on the specified channel. Activate the speaker using the functionWPADControlSpeaker. Once activated, audio can be output from the speaker by sending audio data using theWPADSendStreamDatafunction. 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 in order to achieve correct audio playback.
In order to avoid wearing down the batteries in scenes where no sound is output through the Wii Remote speaker for a period of time, use theWPADControlSpeakerfunction to send theWPAD_SPEAKER_OFFcommand whenever possible to stop the speaker. However, starting or stopping the speaker will prevent you from being able to obtain several input samples from the motion sensor, pointer, and external extension controller of the Wii Remote. Accordingly, in scenes in which sound 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 theWPADControlSpeakerfunction to send aWPAD_SPEAKER_MUTEorWPAD_SPEAKER_MUTE_OFFcommands to turn muting ON/OFF.
Due to the audio processor and wireless communication specifications of the Wii console and the Wii Remote, there are times when the sound will break or jump. Broken sound occurs when the start of the encoder on the Wii console side and the decoder on the Wii Remote side are out of sync with each other. Consequently, the sound will break up as long as the starts are out of sync. In order to synchronize the starts, you must restart the speaker. Jumps in sounds occur when the sample on the Wii Remote side could not be processed. Consequently, even if you don't take any particular action, there won't be any problems with subsequent playback.
Due to the specifications of the audio processor, the Wii Remote's speaker may cause the sound to break or jump if sound 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 sound in the following situations.In order to avoid the broken sound in the following cases, call the
- Restart the speaker using the
WPADControlSpeakerwithin eight minutes of playing a sound.- Refrain from playing a sound for one second or more before eight minutes pass after playing back a sound.
WPADCanSendStreamDatafunction when sending sounds, and make sure the sound can be sent without breaking up.
- When packet loss due to external noise goes above a certain amount
- When an External Extension Controller is plugged in
- When attempting to pair another Wii Remote to the Wii console (regardless of whether the pairing succeeds or fails)
- When a command is sent (especially when accessing internal memory)
Wii Remotes are equipped with internal memory that can be used by game applications. Game applications can use 3888 bytes of this memory and save one file only. Furthermore, such files can be read only by the application that saved them. All game applications can overwrite files.
The WPAD library disconnects if there has been no change in controller input for a fixed period of time. This is done to avoid using up battery power of the Wii Remote due to user inattention. The WPAD Library checks all input from the buttons, motion sensor, pointer, and input from the External Extension Controller.
The wait time is set to five minutes by default. However, the setting can be changed using the WPADSetAutoSleepTime function.
The analog stick origin of a Nunchuk or Classic Controller can be reset by holding down the A, B, +, and - buttons on the Wii Remote or Classic Controller for three seconds. However, the origin cannot be reset with combinations like the A and B Buttons on the Wii Remote and the + and - Buttons on the Classic Controller.
The WPAD library remembers the Wii Remote last used with each controller port. When a Wii Remote is connected, the same port as the previous time as based on the mapping table is assigned if possible. If the connected Wii Remote cannot be found in the mapping table, the port with the smallest number of those available is assigned.
This mapping table can be cleared with the WPADDisconnect or WPADShutdownSystem functions. It is also cleared when the Wii Remote Power Button is held down, causing disconnection.
The WPAD library close process is now performed inside the OS library reset function. When closing, call the OS library reset/shutdown function from the application.
The OSShutdownSystem function disconnects all communicating Wii Remotes. Although the OSRestart, OSReturnToMenu, and OSRebootSystem functions will disconnect all communicating Wii Remotes, the remotes will be in an auto-reconnect state (reconnect without any button input) for about 15 to 20 seconds after disconnection. When a game application is restarted or moves to the console menu, it is possible to restore the state before reset without any button input on the part of the user.
The Wii console and the Wii Remote communicate using the 2.4 GHz band. Using a wireless LAN on the same 2.4Ghz band may cause interference that results in communication problems. To prevent this, the SDK automatically switches the frequency band it uses in order to avoid such interference. The application no longer needs to be aware of this issue.
2007/12/10 Deleted descriptions of WPADSaveConfig, WPADEnableMotor, and WPADSetSpeakerVolume, and updated the description about checking the controller status and obtaining controller information.
2007/10/11 updated the description about controlling the speaker.
2007/06/07 Added an explanation about the simple pairing specification change.
2007/04/03 Added a description about the error codes.
2007/03/22 Added a supplemental description about turning the Rumble Feature on and off.
2007/02/08 Noted that the Classic Controller can also reset the origin. Noted that Wii Remote pairing is not possible while deleting pairing information. Added text about stopping the Wii Remote speaker when it is not in use.
2006/11/09 Added an explanation about the process of reconnecting while an external extension controller is attached.
2006/10/23 Changed explanations about pairing and end process.
2006/09/18 Added an explanation about the internal process to avoid interference with wireless LANs.
CONFIDENTIAL