1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<html> 3<head> 4<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> 5<meta name="ProgId" content="FrontPage.Editor.Document"> 6<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> 7<LINK rel="stylesheet" type="text/css" href="../CSS/revolution.css"> 8<base target="main"> 9<title>WPAD API Introduction</title> 10</head> 11 12<body> 13 14<h1>WPAD API</h1> 15 16<h2>Introduction</h2> 17<p> 18The Wii 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. 19</p> 20<p> 21The Wii Balance Board communicates with the Wii 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. 22</p> 23 24<h2>Libraries</h2> 25<ul><li>Library Organization</li></ul> 26<blockquote> 27The 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. 28 29<table border="0" width="200"> 30 <tbody> 31 <tr height="25"> 32 <td colspan="2" align="center" bgcolor="khaki">KPAD API</td> 33 </tr> 34 <tr height="25"> 35 <td align="center" bgcolor="palegreen">WPAD API</td><td align="center" bgcolor="lightblue" width="50%">WBC API</td> 36 </tr> 37 <tr height="25"> 38 <td colspan="2" align="center" bgcolor="palegreen">WPAD API</td> 39 </tr> 40 </tbody> 41</table> 42</blockquote> 43 44<ul><li>Relationship Between the Library and External Extension Controllers</li></ul> 45<blockquote> 46The WPAD library recognizes the Nunchuk and Classic Controller by default. The WPAD library can recognize other external extension controllers and the Wii Balance Board if a special library is linked for each device.<br><br> 47 48Shown below are controllers and the libraries required for the WPAD library to recognize them. 49<table class="arguments" border="1"> 50 <tbody> 51 <tr> 52 <th>WPAD_DEV_BALANCE_CHECKER</th> 53 <td>WBC library</td> 54 </tr> 55 <tr> 56 <th>WPAD_DEV_GUITAR</th> 57 <td>WPADGtr library</td> 58 </tr> 59 <tr> 60 <th>WPAD_DEV_TRAIN</th> 61 <td>WPADTrn library</td> 62 </tr> 63 </tbody> 64</table> 65 66<font color="red"><b> The <code>WPADGtr</code> and <code>WPADTrn</code> libraries are not included with the standard Revolution SDK. Developers who require these libraries should contact Nintendo.</b></font> 67</blockquote> 68 69<h2>Initialization</h2> 70<h3>Work Memory Registration</h3> 71<p> 72Begin initialization of the WPAD library by calling the <a href="./WPADRegisterAllocator.html"><code>WPADRegisterAllocator</code></a> function; this registers the allocator function used to obtain work memory during initialization. Be sure to implement the allocator in such a way that work memory can be acquired from MEM2. To retrieve the total size of work memory allocated by the library, use the <a href="WPADGetWorkMemorySize.html"><code>WPADGetWorkMemorySize</code></a> function. 73</p> 74<h3>Notes on Initializing Wii Balance Board-Compatible Applications</h3> 75<p> 76Wii Balance Board registration data could not be saved to the console while the Japanese version of Wii Fit was under development, so it is saved with Wii Fit's save data. Consequently, <font color="red">Japanese applications that use the Wii Balance Board</font> should use the <a href="./WPADRegisterBLCWorkarea.html"><code>WPADRegisterBLCWorkarea</code></a> function to register a buffer for the library to obtain Wii Balance Board registration data from the Wii Fit save data. There is no need for applications to register the buffer in regions outside Japan because Wii Balance Board registration data can now be saved to the console. 77</p> 78<h3>Library Initialization</h3> 79<p> 80After registering the work memory, call the <a href="WPADInit.html"><code>WPADInit</code></a> function to initialize the WPAD library. Because it will take time to initialize the WPAD library, periodically call the <a href="./WPADGetStatus.html"><code>WPADGetStatus</code></a> function to check when initialization is complete. After initialization is complete, the buffer registered by the <a href="./WPADRegisterBLCWorkarea.html"><code>WPADRegisterBLCWorkarea</code></a> function is not used and may be deleted. 81</p> 82 83<h2>Adding and Removing Devices</h2> 84<p> 85In order for devices to communicate with the Wii console, the Wii console and device must first be registered with each other. This registration process is called <EM>pairing</EM>. The Wii console and the device can each only register a fixed number of corresponding devices or consoles. If more than this number are paired to either one, information for those already paired will be overwritten. In addition, all pairing information maintained by the Wii console will be automatically deleted if the SYNC button on the Wii console is held down for 10 or more seconds. (However, this information is not automatically deleted if a callback has been registered using the <a href="./WPADSetClearDeviceCallback.html"><code>WPADSetClearDeviceCallback</code></a> function.) Note that doing this will not delete the pairing information maintained by the Wii Remote. 86</p> 87<h3>Adding and Removing Wii Remotes</h3> 88<p> 89There are two methods of registering Wii Remotes with a Wii console; these are referred to as normal pairing and simple pairing. The pairing information of a normal-paired Wii Remote remains registered even after the Wii console power has been turned OFF, and with a normal-paired Wii Remote, Wii console power can also be turned ON or OFF using the Wii Remote Power Button. However, if the Wii Remote has been simple-paired and the Wii console is reset or turned OFF, the pairing information maintained by the Wii console is deleted. Also, power to the Wii console cannot be turned ON/OFF using the power button on a simple-paired Wii Remote. The reason for this is that normal pairing is intended to be used when a user pairs their own Wii Remote to their own Wii console, but simple pairing is intended to be used when a user pairs their Wii Remote to a Wii console owned by a friend. 90</p> 91<p> 92<font color="red"><STRONG>Note:</STRONG> The specification for simple pairing has been changed: the pairing information for a simple-paired Wii Remote is now maintained until the Wii console power is turned OFF.</font>As a result, simple-paired Wii Remotes can remain connected to Wii even when applications are reset and when the user moves between Wii Menu and various Wii Channels.<font color="red"><b>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 simple-paired Wii Remote's connection will be dropped. </b></font>Furthermore, if simple pairing is conducted while this kind of application is running, the connection will be dropped even if the process later moves to an application that uses the new specification for simple pairing. 93</p> 94 95<ul> 96<li><b>Paired device count</b></li> 97</ul> 98<blockquote> 99For Wii Remotes, a Wii console can store ten normal pairings and six simple pairings. A single Wii Remote will be treated as paired through one of these two methods. For Wii consoles, a Wii Remote can store both one standard pairing and one simple pairing. A single Wii console will be treated as paired through one of these two methods. 100</blockquote> 101<blockquote> 102When a normal pairing is performed on a simple-paired device, that device is then treated as normal-paired. However, when a simple pairing is performed on a normal-paired device, that device continues to be treated as normal-paired. 103</blockquote> 104 105<ul> 106<li><b>Normal pairing</b></li> 107</ul> 108<blockquote> 109Normal pairing is performed by pressing SYNCHRO on the front of the Wii console, or by calling the <a href="./WPADStartSyncDevice.html"><code>WPADStartSyncDevice</code></a> or <a href="./WPADStartFastSyncDevice.html"><code>WPADStartFastSyncDevice</code></a> function and pressing SYNCHRO inside the battery cover of the Wii Remote. When the pairing completes, the Wii Remote information will be stored in the Wii console. In the same way, the Wii console information will be stored in the Wii Remote. 110</blockquote> 111<blockquote> 112By calling the <a href="WPADSetSyncDeviceCallback.html"><code>WPADSetSyncDeviceCallback</code></a> function and setting a user callback function in advance, game applications can determine when SYNCHRO on the Wii console is pressed. If a callback function has been set, pairing will not occur automatically when SYNCHRO is pressed; in such cases you must begin the pairing by calling the <a href="WPADStartSyncDevice.html"><code>WPADStartSyncDevice</code></a> 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. 113</blockquote> 114 115<ul> 116<li><b>Simple pairing</b></li> 117</ul> 118<blockquote> 119The simple pairing remains effective only until the Wii console is shut down. Game applications can start a simple pairing by calling the <a href="./WPADStartSimpleSync.html"><code>WPADStartSimpleSync</code></a> or <a href="./WPADStartFastSimpleSync.html"><code>WPADStartFastSimpleSync</code></a> function. Simple pairing occurs when the Wii Remote 1 and 2 Buttons are pressed at the same time. However, if a Wii console is already registered, the Wii Remote will attempt to connect with that Wii console when the buttons are pressed. If that connection fails, simple pairing will start.</font><br><br>Simple pairing will be executed repeatedly until either four Wii Remotes have been connected, or the application stops the simple pairing by calling the <a href="./WPADStopSimpleSync.html"><code>WPADStopSimpleSync</code></a> function. If a callback is registered, the callback function is called as soon as the pairing process completes, and it sends notification of the number of paired Wii Remotes. 120</blockquote> 121 122<ul> 123<li><b>Attempting to pair different pairing types for the Wii console and Wii Remote</b></li> 124</ul> 125<blockquote> 126Pairing fails when the two devices attempt to perform fundamentally different pairing. However, it can be successful in the following cases: 127</blockquote> 128<blockquote> 129<ul> 130<li>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 they are.</li> 131<li>When the Wii console is normal-pairing and the Wii Remote is simple-pairing, in some cases the Wii Remote becomes connected before it even begins to perform simple pairing.</li> 132</ul> 133</blockquote> 134 135<ul> 136<li><b>Repeatedly pairing an already-paired Wii Remote</b></li> 137</ul> 138<blockquote> 139<ul> 140<li>When a Wii console is already normal-paired to a Wii Remote and then attempts to perform simple pairing with that Remote, the pairing will succeed as normal pairing.</li> 141<li>When a Wii console is already simple-paired to a Wii Remote and then attempts to perform normal pairing with that Remote, the simple pairing is eliminated and replaced by a normal pairing.</li> 142</ul> 143</blockquote> 144 145<ul> 146<li><b>Deleting</b></li> 147</ul> 148<blockquote> 149If the Wii console's SYNC button is pressed for 10 or more seconds, all information on Wii Remotes paired to that Wii console will be deleted. The game application can get this event by calling the <a href="WPADSetClearDeviceCallback.html"><code>WPADSetClearDeviceCallback</code></a> function and setting a user callback function in advance. When a callback function has been set, deletion of the pairing information will not occur automatically; in such cases you must start the deletion by calling the <a href="WPADStartClearDevice.html"><code>WPADStartClearDevice</code></a> function. The registered callback function will be called again when the deletion is complete. <br><br>Neither normal pairing nor simple pairing can be carried out while the Wii Remote's pairing information is being deleted. 150</blockquote> 151 152<h3>Adding and Removing Wii Balance Boards</h3> 153<p> 154The Wii Balance Board can only use 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. 155</p> 156<ul> 157<li><b>Synchronizing with the Japanese Version of WiiFit</b></li> 158</ul> 159<blockquote> 160Although also mentioned in "Notes on Initializing Wii Balance Board-Compatible Applications," the Japanese version of WiiFit is the only application with a different way of handling pairing information for the Wii Balance Board. Although pairing information is usually stored in the Wii console's system configuration file, in the case of the Japanese version of WiiFit it is stored inside the WiiFit save data because of circumstances surrounding development. Because the Wii Balance Board pairing information is also subsequently recorded in the Wii console's system configuration file, Wii Balance Board-compatible applications intended for Japan must synchronize the pairing information in WiiFit save data with that in the system configuration file. This synchronization process is carried out internally by the library. Because a large work memory is required for the synchronization process during initialization, be sure to register a work memory using the <a href="./WPADRegisterBLCWorkarea.html"><code>WPADRegisterBLCWorkarea</code></a> function. The work memory is not required after initialization. 161</blockquote> 162<ul> 163<li><b>Synchronization Process During Pairing</b></li> 164</ul> 165<blockquote> 166When you pair a Wii Balance Board to a Wii console, the Balance Board's pairing information is stored in the system configuration file. If save data for the Japanese version of WiiFit is present on the Wii console, the pairing information is also stored in that save data. 167</blockquote> 168<ul> 169<li><b>Synchronization Process During Deletion</b></li> 170</ul> 171<blockquote> 172Pairing information in the system configuration file is deleted by holding down the Wii console SYNC button for 10 or more seconds. If save data for the Japanese version of WiiFit is present on the Wii console, its pairing information is deleted. However, because of WiiFit specifications, pairing information is not completely deleted. 173</blockquote> 174 175 176<h2>Controller Power Button</h2> 177<p> 178A Wii 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, and the callback registered by the <a href="../os/Resetbutton/OSSetPowerCallback.html"><code>OSSetPowerCallback</code></a> function will be called. 179</p> 180<p> 181The power ON/OFF operation cannot be performed with a simple-paired Wii Remote, only with a normal-paired Remote. 182</p> 183 184<h2>Controller Status Confirmation</h2> 185<p> 186Game applications can call the <a href="./WPADProbe.html"><code>WPADProbe</code></a> 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 <a href="./WPADSetConnectCallback.html"><code>WPADSetConnectCallback</code></a> function to register a callback function in advance. To detect the insertion and removal of an external extension controller, use the <a href="./WPADSetExtensionCallback.html"><code>WPADSetExtensionCallback</code></a> function to register a callback function in advance. 187</p> 188<p> 189When a Wii Remote which already has an external extension controller inserted is connected to a Wii 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. Because of this the status obtained by the <a href="./WPADProbe.html"><code>WPADProbe</code></a> function will change over time. Immediately after the Wii Remote is connected, the function returns <code>WPAD_DEV_CORE</code>. 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 <code>WPAD_DEV_UNKNOWN</code>. Following verification, the function returns a value such as <code>WPAD_DEV_FREESTYLE</code> or <code>WPAD_DEV_CLASSIC</code>, depending on the type. 190</p> 191<p> 192The <a href="./WPADGetInfo.html"><code>WPADGetInfo(Async)</code></a> function can also be called to get the current information about the controller (remaining battery power, Player LED status, and so on). 193</p> 194 195<h2>Controller Control</h2> 196<p> 197Game 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. Furthermore, 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. 198</p> 199<p> 200The 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, <code>WPAD_ERR_BUSY</code> is returned; when this error is returned to the game application, the request should be issued again after waiting. 201</p> 202<p> 203Be aware that the WPAD library uses these queues internally immediately after attaching, detaching, or connecting an external extension controller. 204</p> 205 206<h2>Specifying the Received Data Format</h2> 207<p> 208The 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. Thus, the game application must call the <a href="./WPADSetDataFormat.html"><code>WPADSetDataFormat</code></a> function to select the format for the controller information according to its application. The following formats for controller information are available. 209</p> 210 211<TABLE class="arguments" border="1" > 212 <tbody> 213 <tr> 214 <th>WPAD_FMT_CORE</th> 215 <td>Wii Remote buttons only.</td> 216 </tr> 217 <tr> 218 <th>WPAD_FMT_CORE_ACC</th> 219 <td>Wii Remote buttons and Motion Sensor.</td> 220 </tr> 221 <tr> 222 <th>WPAD_FMT_CORE_ACC_DPD</th> 223 <td>Wii Remote buttons, Motion Sensor, and Pointer (coordinate data and size).</td> 224 </tr> 225 <tr> 226 <th>WPAD_FMT_FREESTYLE</th> 227 <td>Wii Remote buttons and the Nunchuk.</td> 228 </tr> 229 <tr> 230 <th>WPAD_FMT_FREESTYLE_ACC</th> 231 <td>Wii Remote buttons, Motion Sensor, and the Nunchuk.</td> 232 </tr> 233 <tr> 234 <th>WPAD_FMT_FREESTYLE_ACC_DPD</th> 235 <td>Wii Remote buttons, Motion Sensor, Pointer (coordinate data), and the Nunchuk.</td> 236 </tr> 237 <tr> 238 <th>WPAD_FMT_CLASSIC</th> 239 <td>Wii Remote buttons and the Classic Controller.</td> 240 </tr> 241 <tr> 242 <th>WPAD_FMT_CLASSIC_ACC</th> 243 <td>Wii Remote buttons, Motion Sensor, and the Classic Controller.</td> 244 </tr> 245 <tr> 246 <th>WPAD_FMT_CLASSIC_ACC_DPD</th> 247 <td>Wii Remote buttons, Motion Sensor, Pointer (coordinate data), and the Classic Controller.</td> 248 </tr> 249 <tr> 250 <th>WPAD_FMT_CORE_ACC_DPD_FULL</th> 251 <td>Wii Remote buttons, Motion Sensor, and Pointer (coordinate data, size, object radius, pixel value, and range). 252 <font color="red"><B>Note:</B> The sampling rate is half of the rate for other formats.</font></td> 253 </tr> 254 <tr> 255 <th>WPAD_FMT_TRAIN</th> 256 <td>Wii Remote buttons and the master controller.</td> 257 </tr> 258 <tr> 259 <th>WPAD_FMT_GUITAR</th> 260 <td>Wii Remote buttons, Motion Sensor, Pointer (coordinate data), and the Guitar controller.</td> 261 </tr> 262 <tr> 263 <th>WPAD_FMT_BALANCE_CHECKER</th> 264 <td>Wii Balance Board.</td> 265 </tr> 266 </tbody> 267</table> 268 269<p> 270<font color="red"><B>Note:</B> When selecting a format that uses the Pointer, before calling <a href="./WPADSetDataFormat.html"><code>WPADSetDataFormat</code></a>, call the <a href="./WPADControlDpd.html"><code>WPADControlDpd</code></a> function to start the Pointer.</font> 271</p> 272 273<h2>Getting Controller Information</h2> 274<p> 275There are two ways to obtain controller information. 276<ul> 277<li>Obtain only the most recent controller information.</li> 278</ul> 279<blockquote> 280Use the <a href="./WPADRead.html"><code>WPADRead</code></a> function to get the most recent controller information for the Wii Remote on the specified channel. 281</blockquote> 282 283<ul> 284<li>Periodically use auto-sampling to store the controller information to the buffer provided by the application.</li> 285</ul> 286<blockquote> 287To set the buffer for periodically storing controller information, use the <a href="./WPADSetAutoSamplingBuf.html"><code>WPADSetAutoSamplingBuf</code></a> function. Buffers are used internally as ring buffers. The buffer index that stored the most recent controller information can be obtained with the <a href="./WPADGetLatestIndexInBuf.html"><code>WPADGetLatestIndexInBuf</code></a> function. 288</blockquote> 289<p> 290The <a href="./WPADRead.html"><code>WPADRead</code></a> and <a href="./WPADSetAutoSamplingBuf.html"><code>WPADSetAutoSamplingBuf</code></a> functions can be used together. 291</p> 292<p> 293The type of the controller information that can be obtained with the <a href="./WPADRead.html"><code>WPADRead</code></a> and <a href="./WPADSetAutoSamplingBuf.html"><code>WPADSetAutoSamplingBuf</code></a> functions is recorded in a structure type that corresponds to the data format specified by the <a href="./WPADSetDataFormat.html"><code>WPADSetDataFormat</code></a> function. For information on controller types, data formats, and corresponding structure types, see the section about the <a href="./WPADSetDataFormat.html"><code>WPADSetDataFormat</code></a> 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. 294</p> 295<p> 296Use the <a href="./WPADSetSamplingCallback.html"><code>WPADSetSamplingCallback</code></a> function to register the callback function called every time the data is received from a Wii Remote at a specified channel. 297</p> 298 299<h2>Processing +Control Pad Restrictions</h2> 300<p> 301Prohibited processes concerning the +Control Pad of the Wii Remote and the Classic Controller are performed internally by the WPAD library. If the +Control Pad breaks and its input is in a state that is ordinarily impossible, such as simultaneous left and right (or up and down) presses, it will be processed as valid input of left and up. 302</p> 303 304<h2>Attaching/Detaching External Extension Controllers</h2> 305<p> 306A 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 <a href="./WPADProbe.html"><code>WPADProbe</code></a> function or by registering a callback function in advance using the <a href="./WPADSetExtensionCallback.html"><code>WPADSetExtensionCallback</code></a> function. 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 <a href="./WPADSetDataFormat.html"><code>WPADSetDataFormat</code></a> function to reset the controller information's data format according to the situation. Once the settings are complete, controller information will be sent from the Wii Remote. 307</p> 308 309<h2>Rumble Feature Controls</h2> 310<p> 311The 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 <a href="./WPADControlMotor.html"><code>WPADControlMotor</code></a> function can be used to control the vibration of the Wii Remote on a specified channel. In addition, the <a href="./WPADStartMotor.html"><code>WPADStartMotor</code></a> and <a href="./WPADStopMotor.html"><code>WPADStopMotor</code></a> functions are available as macro functions. 312</p> 313<p> 314The status of the Rumble feature's ON/OFF setting maintained within the library can be obtained with the <a href="./WPADIsMotorEnabled.html"><code>WPADIsMotorEnabled</code></a> function. Although the <a href="./WPADEnableMotor.html"><code>WPADEnableMotor</code></a> 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. 315 316The value maintained by the library can be saved to the console settings using the <a href="./WPADSaveConfig.html"><code>WPADSaveConfig</code></a> function, but do not call this function from an application. 317</p> 318 319<h2>Speaker Controls</h2> 320<ul> 321<li><b>Outputting Audio Through the Speaker</b></li> 322</ul> 323<blockquote> 324You can use the <a href="./WPADControlSpeaker.html"><code>WPADControlSpeaker</code></a> function to control the speaker of the Wii Remote on the specified channel. Activate the speaker using the function <a href="./WPADControlSpeaker.html"><code>WPADControlSpeaker</code></a>. Once activated, audio can be output from the speaker by sending audio data using the <a href="./WPADSendStreamData.html"><code>WPADSendStreamData</code></a> 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 in order to achieve correct audio playback. 325</blockquote> 326<ul> 327<li><b>Adjusting the Speaker Volume</b></li> 328</ul> 329<blockquote> 330To set the speaker volume of the Wii Remote on a specified channel, use the <a href="./WPADSetSpeakerVolume.html"><code>WPADSetSpeakerVolume</code></a> function. However, because this volume change is not enabled until the speaker is restarted with the <a href="./WPADControlSpeaker.html"><code>WPADControlSpeaker</code></a> function, the volume of the Wii Remote speaker's currently playing audio will not change. In order 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 console using the <a href="./WPADSaveConfig.html"><code>WPADSaveConfig</code></a> function. 331</blockquote> 332<ul> 333<li><b>Starting and Stopping the Speaker</b></li> 334</ul> 335<blockquote> 336In order 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 <a href="./WPADControlSpeaker.html"><code>WPADControlSpeaker</code></a> function to send the <code>WPAD_SPEAKER_OFF</code> 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 <a href="WPADControlSpeaker.html"><code>WPADControlSpeaker</code></a> function to send a <code>WPAD_SPEAKER_MUTE</code> or <code>WPAD_SPEAKER_MUTE_OFF</code> command to turn muting ON/OFF. 337</blockquote> 338<ul> 339<li><b>Broken or Skipping Audio</b></li> 340</ul> 341<blockquote> 342Due to the audio processor and wireless communication specifications of the Wii 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 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. In order to synchronize the state of the encoder and decoder, you must restart the speaker. Audio skipping will occur when a sample on the Wii Remote side cannot be processed. Consequently, even if you do not take any specific action, there will be no problems with subsequent playback.<br /> <br /> Due to the audio processor specifications, audio played with the Wii Remote's speaker <font color="red"><b>may break or skip if audio is played back continuously for eight minutes or longer.</b></font>To avoid this, do one of the following: 343<ul> 344<li>Restart the speaker using the <a href="WPADControlSpeaker.html"><code>WPADControlSpeaker</code></a> within 8 minutes of playing a sound.</li> 345<li>Refrain from playing audio for one second or more within eight minutes after beginning audio playback.</li> 346</ul> 347 348In addition, due to the specifications for wireless communication, it has been confirmed that the Wii Remote speaker <font color="red"><b>will break up audio in the following situations.</b></font>In order to avoid broken audio in the following cases, call the <a href="./WPADCanSendStreamData.html"><code>WPADCanSendStreamData</code></a> function when sending audio in order to make sure the audio can be sent and played without breaking up. 349<ul> 350<li>When packet loss due to external noise goes above a certain amount</li> 351<li>When an External Extension Controller is inserted</li> 352<li>When attempting to pair another Wii Remote to the Wii console (regardless of whether the pairing succeeds or fails)</li> 353<li>When a command is sent (especially when accessing internal memory)</li> 354</ul> 355</blockquote> 356 357<h2>Configuring Controller Features</h2> 358<p> 359The Rumble feature ON/OFF setting and speaker volume setting for Wii Remotes can be saved on the Wii console. Values set with the <a href="./WPADEnableMotor.html"><code>WPADEnableMotor</code></a> and <a href="./WPADSetSpeakerVolume.html"><code>WPADSetSpeakerVolume</code></a> functions can be saved on the Wii console using the <a href="./WPADSaveConfig.html"><code>WPADSaveConfig</code></a> function. 360</p> 361<p><font color="red"><b>However, do not allow these settings to be changed outside the HOME Menu in the release version.</b></font></p> 362 363<h2>Wii Remote Memory</h2> 364<p> 365The memory built into the Wii Remote is called Wii Remote memory. The Wii Remote memory secures only one slot for the saving of game data. Although 4,000 bytes are allocated for this slot, the first 112 bytes are used by the library to manage file information. Thus, the application actually has access to only 3,888 bytes for the saving of game data. Using the <a href="./WPADReadGameData.html"><code>WPADReadGameData</code></a> and <a href="./WPADWriteGameData.html"><code>WPADWriteGameData</code></a> functions, the application can freely read and write data in the region of the slot starting from the 112th byte through the 4,000th byte. Be aware that the file information is updated whenever game data are written to this region. 366</p> 367<p> 368The file information contains the following. 369</p> 370<table border="1"> 371<tbody> 372<tr> 373<th>Title Name</th> 374<td>A string of up to 16 characters, UTF-16 encoded. This character string can be configured using the <a href="./WPADSetGameTitleUtf16.html"><code>WPADSetGameTitleUtf16</code></a> function.</td> 375</tr> 376<tr> 377<th>Time of Last Update</th> 378<td>The time when the game data were last updated can be stored in <code>OSTime</code> format. This can be obtained using the <a href="./WPADGetGameDataTimeStamp.html"><code>WPADGetGameDataTimeStamp</code></a> function. The obtained value can be converted to calendar time using the <a href="../os/Time/OSTicksToCalendarTime.html"><code>OSTicksToCalendarTime</code></a> function.</td> 379</tr> 380<tr> 381<th>Game Code</th> 382<td>Stores the game code of the application to which the game data are written. This value is used internally by the library.</td> 383</tr> 384</tbody> 385</table> 386<p> 387To read details about the error codes that are returned when reading and writing game data, see the explanations for the <a href="./WPADReadGameData.html"><code>WPADReadGameData</code></a> and <a href="./WPADWriteGameData.html"><code>WPADWriteGameData</code></a> functions. Please also see the Guidelines to read about other notes and precautions. 388</p> 389 390<h2>Error Codes</h2> 391<p> 392The error codes returned from the WPAD library can be grouped into the following three categories. 393</p> 394<ul> 395<li>Returned by the <a href="./WPADProbe.html"><code>WPADProbe</code></a> function. Shows the Wii Remote status.</li> 396<li>Passed into the <SPAN class="argument">err</SPAN> member variable of the <a href="./WPADStatus.html"><code>WPADStatus</code></a> structure. Shows the status of the acquired input data.</li> 397<li>Returned from functions that control the Pointer, speaker, and so on. Shows whether the library was able to accept that processing.</li> 398</ul> 399<p> 400Because 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. 401</p> 402<p> 403Among the error codes defined in the WPAD library, those returned by the <a href="./WPADProbe.html"><code>WPADProbe</code></a> function are described below. 404</p> 405 406<TABLE class="arguments" border="1" > 407 <tbody> 408 <tr> 409 <th>WPAD_ERR_NONE</th> 410 <td>The Wii Remote is connected but control commands are not being sent from the Wii console to the Wii Remote.</td> 411 </tr> 412 <tr> 413 <th>WPAD_ERR_NO_CONTROLLER</th> 414 <td>Wii Remote is disconnected.</td> 415 </tr> 416 <tr> 417 <th>WPAD_ERR_BUSY</th> 418 <td>A control command has been sent to a connected Wii Remote, and the system is waiting for an ACK from the Wii Remote.</td> 419 </tr> 420 </tbody> 421</table> 422 423<p> 424Shown below are the error codes that are passed to the <SPAN class="argument">err</SPAN> member variable of the <a href="./WPADStatus.html"><code>WPADStatus</code></a> structure, and the descriptions of those error codes. 425</p> 426 427<TABLE class="arguments" border="1" > 428 <tbody> 429 <tr> 430 <th>WPAD_ERR_NONE</th> 431 <td>Data with the specified data format was received.</td> 432 </tr> 433 <tr> 434 <th>WPAD_ERR_NO_CONTROLLER</th> 435 <td>Data has never been received.</td> 436 </tr> 437 <tr> 438 <th>WPAD_ERR_INVALID</th> 439 <td>The format of incoming data is different from the format specified for the WPAD library.<br> 440 (In this case the Wii Remote and external extension controller data is invalid.)</td> 441 </tr> 442 <tr> 443 <th>WPAD_ERR_CORRUPTED</th> 444 <td>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.<br>(However, Wii Remote data is not corrupted.)</td> 445 </tr> 446 </tbody> 447</table> 448 449<h2>Automatic Disconnect</h2> 450<p> 451If 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. 452</p> 453<p> 454Although the initial setting is 5 minutes, it can be changed with the <a href="./WPADSetAutoSleepTime.html"><code>WPADSetAutoSleepTime</code></a> function. It is also possible to use the <a href="./WPADResetAutoSleepTimeCount.html"><code>WPADResetAutoSleepTimeCount</code></a> function to reset the elapsed time since input stopped changing. 455</p> 456 457<h2>Resetting the Analog Stick Origin</h2> 458<p> 459The 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 button combinations such as the A and B Buttons on the Wii Remote combined with the + and - Buttons on the Classic Controller. 460</p> 461 462<h2>Controller Port Mapping</h2> 463<p> 464The WPAD library keeps track of information for the last Wii Remote to connect to each controller port only while the Wii console is running. In other words, this will be cleared if the Wii console is shut down, but will remain unchanged if the Wii console is reset. (Information recorded to each controller port is cleared immediately after the Wii console is started.)) 465</p> 466<p> 467When a Wii Remote initiates a connection, its information will be 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 will be assigned to that controller port. If the same information could not be found after checking all of the controller ports, it will be assigned to the open controller port with the lowest number. 468</p> 469<p> 470Recorded Wii Remote information will be cleared in the following situations. If the <a href="./WPADDisconnect.html"><code>WPADDisconnect</code></a> function is used to disconnect a Wii Remote, information will be cleared for the Wii Remote on the disconnected controller port. If the <a href="./../os/Reset/OSShutdownSystem.html"><code>OSShutdownSystem</code></a> function is called or the Power Button is pressed and held to shut down the Wii console, the Wii Remote information for all controller ports will be cleared. 471</P> 472<p> 473For example, the following shows the Wii console immediately after starting up. 474</p> 475<table border="1"> 476<tr><th width="100px">Port 1</th><td width="100px" align="center">----</td></tr> 477<tr><th width="100px">Port 2</th><td width="100px" align="center">----</td></tr> 478<tr><th width="100px">Port 3</th><td width="100px" align="center">----</td></tr> 479<tr><th width="100px">Port 4</th><td width="100px" align="center">----</td></tr> 480</table> 481<p> 482If Wii Remotes A, B, and C are connected in order, the lowest-numbered open port will be assigned to each Wii Remote in order because no Wii Remote information has been stored. 483</p> 484<table border="1"> 485<tr><th width="100px" bgcolor="lightblue">Port 1</th><td width="100px" align="center">Wii Remote A</td></tr> 486<tr><th width="100px" bgcolor="lightblue">Port 2</th><td width="100px" align="center">Wii Remote B</td></tr> 487<tr><th width="100px" bgcolor="lightblue">Port 3</th><td width="100px" align="center">Wii Remote C</td></tr> 488<tr><th width="100px">Port 4</th><td width="100px" align="center">----</td></tr> 489</table> 490<p> 491Assume that Wii Remote A is disconnected due to a depleted battery, and 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. 492</p> 493<table border="1"> 494<tr><th width="100px">Port 1</th><td width="100px" align="center">Wii Remote A</td></tr> 495<tr><th width="100px">Port 2</th><td width="100px" align="center">Wii Remote B</td></tr> 496<tr><th width="100px" bgcolor="lightblue">Port 3</th><td width="100px" align="center">Wii Remote C</td></tr> 497<tr><th width="100px">Port 4</th><td width="100px" align="center">----</td></tr> 498</table> 499<p> 500When Wii Remote B is reconnected after its battery has been replaced, it will be assigned to Port 2 because its information is still recorded there. 501</p> 502<table border="1"> 503<tr><th width="100px">Port 1</th><td width="100px" align="center">Wii Remote A</td></tr> 504<tr><th width="100px" bgcolor="lightblue">Port 2</th><td width="100px" align="center">Wii Remote B</td></tr> 505<tr><th width="100px" bgcolor="lightblue">Port 3</th><td width="100px" align="center">Wii Remote C</td></tr> 506<tr><th width="100px">Port 4</th><td width="100px" align="center">----</td></tr> 507</table> 508<p> 509When 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. 510</p> 511<table border="1"> 512<tr><th width="100px" bgcolor="lightblue">Port 1</th><td width="100px" align="center">Wii Remote D</td></tr> 513<tr><th width="100px" bgcolor="lightblue">Port 2</th><td width="100px" align="center">Wii Remote B</td></tr> 514<tr><th width="100px" bgcolor="lightblue">Port 3</th><td width="100px" align="center">Wii Remote C</td></tr> 515<tr><th width="100px">Port 4</th><td width="100px" align="center">----</td></tr> 516</table> 517<p> 518When Port 1 is disconnected using the <a href="./WPADDisconnect.html"><code>WPADDisconnect</code></a> function, its information will be cleared. 519</p> 520<table border="1"> 521<tr><th width="100px">Port 1</th><td width="100px" align="center">----</td></tr> 522<tr><th width="100px" bgcolor="lightblue">Port 2</th><td width="100px" align="center">Wii Remote B</td></tr> 523<tr><th width="100px" bgcolor="lightblue">Port 3</th><td width="100px" align="center">Wii Remote C</td></tr> 524<tr><th width="100px">Port 4</th><td width="100px" align="center">----</td></tr> 525</table> 526<p> 527When the Wii console is shut down, all information will be cleared. 528</p> 529<table border="1"> 530<tr><th width="100px">Port 1</th><td width="100px" align="center">----</td></tr> 531<tr><th width="100px">Port 2</th><td width="100px" align="center">----</td></tr> 532<tr><th width="100px">Port 3</th><td width="100px" align="center">----</td></tr> 533<tr><th width="100px">Port 4</th><td width="100px" align="center">----</td></tr> 534</table> 535 536<h2>Termination Processing</h2> 537<p> 538The WPAD library's close process is now performed inside the OS library's reset function. When closing the library, call the OS library reset/shutdown function from the application. 539</p> 540<p> 541The <a href="./../os/Reset/OSShutdownSystem.html"><code>OSShutdownSystem</code></a> function disconnects all communicating Wii Remotes. Although the <a href="./../os/Reset/OSRestart.html"><code>OSRestart</code></a>, <a href="./../os/WiiMenu/OSReturnToMenu.html"><code>OSReturnToMenu</code></a>, and <a href="./../os/Reset/OSRebootSystem.html"><code>OSRebootSystem</code></a> 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 Wii Menu, it is possible to restore the pre-reset state without any button input from the user. 542</p> 543 544<h2>Cautions When Using the Wireless LAN</h2> 545<p> 546The Wii 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 will automatically switch the frequency band that it uses. The application no longer needs to be aware of this issue. 547</p> 548 549<h2>Revision History</h2> 550<p> 5512008/08/27 Revised the descriptions of the Wii Balance Board.<br>2008/06/04 Revised the explanation about Wii Remote memory.<br>2008/05/29 Added a description of prohibition processing for the +Control Pad.<br>2008/05/19 Revised the description of controller port mapping and added specific examples.<br>2008/04/16 Added a note stating that external causes may stop automatic disconnection from occurring as configured. Added an explanation for resetting the time elapsed since input stopped changing. Added explanations for the Wii Balance Board. Added information on the relationship between the library and external extension controllers. Added the WBC library to the library structure. Revised error code descriptions.<br>2007/10/11 Updated the description for speaker controls.<br> 2007/06/07 Added explanation about the simple pairing specification change.<br>2007/04/03 Added error code descriptions.<br>2007/03/22 Added a supplemental explanation about turning the Rumble Feature ON and OFF.<br>2007/02/08 Noted that the Classic Controller can also reset its origin. Noted that Wii Remote pairing is not possible while pairing information is being deleted. Added text about stopping the Wii Remote speaker when it is not in use.<br>2006/11/09 Added explanation for the process of reconnecting while an external extension controller is attached.<br>2006/10/23 Changed explanations for pairing and termination processing.<br>2006/09/18 Added a description for avoiding wireless LAN interference internally. Deleted warnings for the bugs found in SDK 2.2. Added text about change in mapping table handling. Added explanation for controller registration.<br>2006/09/06 Reflected changes to specifications about turning the Rumble Feature ON/OFF and speaker volume settings. Described problems with controller controls and the speaker. Added information about simple registration, internal memory, automatic disconnect, controller port mapping, close operation, and Control Stick origin reset.<br>2006/07/04 Added speaker-related information.<br>2006/06/19 Deleted the object size restriction from the cautions specific to UI tools.<br>2005/11/10 Added description of DPD module's hardware bug.<BR>2005/11/09 Corrected warnings about the use of the GameCube standard controller. Changed the description of the PAD library treatment in DolphinSDK. Added bug report.<br>2005/11/01 To reflect the change of interface from EXI to SI, added a caution related to SI. Added links to functions. Added introduction text for the KPAD library. Added bug report.<br>2005/09/27 Changed the name to DPD. Deleted some hardware descriptions in <B>Introduction</B>.<br>2005/08/30 Modified description of buttons in <B>Introduction</B>; added a bug report.<br>2005/08/01 Initial version.<br> 552</p> 553 554<hr><p>CONFIDENTIAL</p></body></html>