1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<html> 3 4<head> 5<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> 6<meta http-equiv="Content-Style-Type" content="text/css"> 7<title>WBC Library Introduction</title> 8<link rel="stylesheet" type="text/css" href="../CSS/revolution.css"> 9</head> 10 11<body> 12 13<h1> 14WBC API Introduction 15</h1> 16 17<h2>Introduction</h2> 18 19<p> 20The WBC Library converts the raw values obtained using <CODE>WPADRead</CODE> from Wii Balance Board (<SPAN class="argument">press</SPAN> values) into weight values. 21</p> 22 23<h2><strong>To Use This Library</strong></h2> 24 25<p>The following include file is required. </p> 26 27<ul> 28 <li><code>$REVOLUTION_SDK_ROOT/include/revolution/wbc.h</code></li> 29</ul> 30 31<p> 32The library archive file is <code>$REVOLUTION_SDK_ROOT/RVL/lib/wbc[D].a</code>. 33</p> 34 35 36 37<h2>About the Wii Balance Board</h2> 38<p> 39The Wii Balance Board has four legs, with a balance sensor attached to each leg. When subjected to a load, they return a value in proportion to the weight of the load. Specifically, the heavier the load, the larger the value returned.<br><br>The Wii console communicates wirelessly with the Wii Balance Board at 200 samples per second, the same as the Wii Remote. However, the Wii Balance Board's balance sensor values can change at a rate of only 60 samples per second. 40 41The order of the <SPAN class="argument">press</SPAN> values in the array obtained by <CODE>WPADRead</CODE> corresponds to the Balance Board's legs as shown below. 42</p> 43<P> 44<IMG src="image/wbc.gif" width="427" height="275"> 45</P> 46 47<p> 48To use the Wii Balance Board, it must first be normal-paired with a Wii console. Pair the Balance Board by pressing SYNC on the Wii console and on the Wii Balance Board at the same time.<br><br> 49 50Only a single Wii console can be normal-paired with a Wii Balance Board. Use <CODE>WPADIsRegisteredBLC</CODE> to check whether a Wii Balance Board has already been paired. If a paired Wii Balance Board is then paired with a different Wii console, the Wii Balance Board's settings are overwritten and it will need to be normal-paired again. <br><br>Wii Balance Board is always connected to P4. <font color="#FF0000"><u><strong>The application must perform disconnection processing if a Wii Remote has already been connected to P4. Be aware that the library does not perform this disconnection processing.</strong></u></font> 51</p> 52 53<h2>Using the Library</h2> 54 55 56<h3>1. Loading Calibration Data and Creating a Conversion Formula</h3> 57 58<p> 59First, create a conversion formula within the library, which will convert the readings to weights. Each Wii Balance Board stores unique calibration data, and the conversion formula uses that calibration data. By calling <a href="WBCSetupCalibration.html"><code>WBCSetupCalibration</code></a>, the calibration data will be loaded and the conversion formula will be created within the library. 60 61Bear in mind that <font color="#FF0000"><u><code>WBCSetupCalibration</code> may be executed only after the Wii Balance Board is paired.</u></font>For details, see the sample demo (<CODE>handling_weight.c</CODE>).<br> 62 63After this function is executed, the <a href="WBCRead.html"><code>WBCRead</code></a>, <a href="WBCSetZEROPoint.html"><code>WBCSetZEROPoint</code></a>, and <a href="WBCGetTGCWeight.html"><code>WBCGetTGCWeight</code></a> functions 64 65may be used. 66 67(The function <a href="WBCGetBatteryLevel.html"><code>WBCGetBatteryLevel</code></a> can be used without executing <a href="WBCSetupCalibration.html"><code>WBCSetupCalibration</code></a> beforehand, but it is the only exception.) <br><br>Control will return immediately after executing this function, but its actual processing continues for a short time (about 650ms) before completing. Use <a href="WBCGetCalibrationStatus.html"><code>WBCGetCalibrationStatus</code></a> to determine whether this function has completed normally. 68 69</p> 70 71 72<h3>2. Setting the Zero Point</h3> 73 74<p>Setting the zero point is the act of setting the Wii Balance Board's unloaded state in the WBC Library. The zero point <font color="#FF0000"><u><strong>must be set every time before measuring a weight</strong></u></font>. (Refer to <a href="#mark2">6. Balance Sensors</a> for more on the importance of always setting the zero point.)) 75 76</p> 77 78<p><em><CODE>s32 WBCSetZEROPoint(double press_ave[], u32 size);</CODE></em></p> 79 80<p> 81For the <SPAN class="argument">press_ave</SPAN> argument, set the average value of all the <SPAN class="argument">press</SPAN> values obtained by <CODE>WPADRead</CODE> over a period of two seconds. Set <SPAN class="argument">press_ave</SPAN> in the same order as the <SPAN class="argument">press</SPAN> values. (For example, the average of <SPAN class="argument">status.press[1]</SPAN> should be inserted into <SPAN class="argument">press_ave[1]</SPAN>.) In <SPAN class="argument">size</SPAN>, specify the the number of elements in the <SPAN class="argument">press_ave</SPAN> array. (Normally, allocate space for four elements.))<br> <br> 82 83Before sampling for each <SPAN class="argument">press</SPAN> value, use the temperature update command (<a href="../wpad/WPADControlBLC.html"><code>WPADControlBLC</code></a>) to update the Wii Balance Board's temperature information. 84 85 86After updating the temperature with the temperature update command (<a href="../wpad/WPADControlBLC.html"><code>WPADControlBLC</code></a>), use <CODE>WPADRead</CODE> to confirm that temperature was correctly updated.<font color="#FF0000"><u><strong>On very rare occasions a value of -128 or 127 is returned for temperature. If that happens, execute the temperature update command again.</strong></u></font><br> 87 88On very rare occasions, the Wii Balance Board <SPAN class="argument">press</SPAN> values can fluctuate wildly for a short period after a command is sent.<font color="#FF0000"><u><strong>Therefore, after issuing the temperature update command, wait a short time (roughly 200 ms) before getting the <SPAN class="argument">press</SPAN> values.</strong></u></font><br> 89</p> 90 91 92<h3>3. Converting to Weight Values</h3> 93 94<p>The readings are converted into weight values with the following function.</p> 95 96<p><em><CODE>s32 WBCRead(WPADBLStatus *status, double weight[], u32 size);</CODE></em></p> 97 98<p> 99Specify the <CODE>WPADBLStatus</CODE> structure, obtained with <CODE>WPADRead</CODE>, as an argument. The converted weight values will be stored in <SPAN class="argument">weight</SPAN> array in the same order as the array of <SPAN class="argument">press</SPAN> values. In <SPAN class="argument">size</SPAN>, specify the the number of elements in the <SPAN class="argument">weight</SPAN> array. (Normally, allocate space for four elements.)) 100</p> 101 102<h3>4. Correcting the Values</h3> 103 104<p> 105The following function carries out both temperature correction and correction for gravitational acceleration. 106</p> 107<p><em><CODE>double WBCGetTGCWeight(double total_weight_ave, WPADBLStatus *status);</CODE></em></p> 108 109 110<p> 111In the <SPAN class="argument">total_weight_ave</SPAN> argument, specify the average value obtained over a period of two seconds (120 samples) for the total of the weight values obtained by <CODE>WBCRead</CODE> at four different points.<font color="#FF0000"><u><strong>You must always execute correction before actually using the weight values. </strong></u></font> See <a href="#mark2"><B>6. Balance Sensors</B></a> for more information on the importance of correcting for temperature and gravitational acceleration. 112</p> 113 114<h3>5. Sensors and Battery Lifetime</h3> 115<p> 116The balance sensors on each of the Wii Balance Board's four corners will cease to operate when their remaining battery life drops below a certain threshold. However, the wireless module will continue to operate even below the threshold, causing data to continue to be sent from the Wii Balance Board. All values of <SPAN class="argument">press</SPAN> become zero at this time.<br><br> When the remaining battery life is below the threshold, the <code>WBCGetBatteryLevel</code> function returns zero. The application uses this function to check the remaining battery life; if zero is returned, prompt the user to replace the battery. 117</p> 118 119 120<a name="mark2"> 121<h3>6. Balance Sensors</h3> 122</a> 123 124<p> 125Balance sensors have the characteristic of not completely returning to their original state after a weight is applied and then subsequently reduced; that is, they exhibit hysteresis. For example, assume that the zero point has been set. A person (or object) gets onto and then off of the Wii Balance Board. Now, the state of the Wii Balance Board is not exactly the same as its state when the zero point was set.<br>In this way, the unloaded state of the balance sensors changes every time a person (or object) gets onto and off of the Board. For this reason, <font color="#FF0000"><u><strong>you must always set the zero point before making an accurate measurement.</strong></u></font><br><br> 126 127The balance sensors are metallic (aluminum). The malleability of a metal changes with the temperature. Specifically, they are more malleable (easier to bend) at high temperatures and more stiff (difficult to bend) at low temperatures. More malleable balance sensors yield heavier weight values, and stiffer ones yield lighter weight values.<br><br> "Weight" changes in proportion to gravity. As a result, weight values must take gravitational acceleration into account. Gravitational acceleration differs slightly with latitude. Specifically, the earth's rotation applies the greatest centrifugal force to a latitude of zero (right on the equator), causing a smaller gravitational acceleration there. The end result is that weight values at the equator will be lighter, and weight values at the north and south poles will be heavier. <br><br> 128 129The <CODE>WBCGetTGCWeight</CODE> function corrects for both temperature and gravitational acceleration. Always use the <CODE>WBCGetTGCWeight</CODE> function to correct weight values when making accurate measurements. 130</p> 131<p> 132The following steps summarize the ideal process for making accurate measurements: 133<blockquote> 1341. Have the player step off the Wii Balance Board. <br>2. Set the zero point when there is no load. <br>3. Immediately have the player step onto the Wii Balance Board and measure the player's weight. <br>4. Correct the measured weight value using the correction function.<br> 135</blockquote> 136</p> 137<p> 138 139</p> 140 141 142<h2>Caution</h2> 143<p> 144<font color="#FF0000"><u><strong>If you are using the 2008/02/27 WBC package or previous versions, use the Wii Balance Board-dedicated version of the HOME Menu library. </strong></u></font> This is because the portion that processes remaining battery power is different from that used with the Wii Remote. 145</p> 146 147<h2>Revision History</h2> 148<p> 1492008/08/28 Revised terminology.<br>2008/03/19 Updated the caution regarding the HOME Menu library.<br>2008/02/22 Supplemented the description of the two-second average with information about 120 samples.<br>2007/12/06 Added a warning related to disconnecting a P4 link. Added a cautionary note on setting the zero point.<br>2007/11/15 Changed internal processing of the Wii Balance Board's pairing information. Revised the text to reflect this. Added text regarding Sensors and Battery Lifetime.<br>2007/10/02 Changed the name of <CODE>WBCInit</CODE> to <CODE>WBCSetupCalibration</CODE>. Revised the text to reflect this.<br>2007/09/28 Corrected typos.<br>2007/09/26 Added more to the Wii Balance Board description. Added the caution about obtaining the temperature.<br>2007/09/10 Added to the Wii Balance Board description. Revised text in line with changes to the function format.<br>2007/08/31 Initial version. 150</p> 151 152<hr><p>CONFIDENTIAL</p></body> 153</html> 154
