WBC Library Overview

Introduction

The WBC Library converts the raw values obtained using WPADRead from the Wii Balance Board (press values) into weight values.

To Use this Library

The following include file is required.

cafe/pads/wbc/wbc.h

About the Wii Balance Board

The Wii Balance Board has four legs, with a balance sensor attached to each leg. When subjected to a load, they return a value proportional to the weight of the load. Specifically, the heavier the load, the larger the value returned.

Consider that this value itself has no meaning. It is the amount of change in this value that has meaning. In this context, the amount of change refers to the amount of change compared to the state when nothing is on the Wii Balance Board accessory (the no-load state). A method called zero point setting is required to recognize this no-load state. The balance of a person (or object) on the Wii Balance Board accessory is to be determined by observing the amount of change across the four balance sensors. The load, then, is the total value of the amount of change at the four balance sensors.

The 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. The order of the press values in the array obtained by WPADRead corresponds to the Wii Balance Board's legs as shown below.

To use the Wii Balance Board, it must first be normal-paired with a console. Pair the Wii Balance Board by pressing the SYNC Button on the console and on the Wii Balance Board at the same time.

Only one console can be normal-paired with a Wii Balance Board. Use WPADIsRegisteredBLC to check whether a Wii Balance Board has already been paired. If a paired Wii Balance Board is then paired with a different console, the Wii Balance Board's settings are overwritten and it will need to be normal-paired again.

NOTE:
The Wii Balance Board is always connected to P4. The application must perform the disconnect process if a Wii Remote is already connected to P4. The library does not perform the disconnect process.

Using the Library

This chapter describes basic programming used to control the Wii Balance Board accessory. The Wii Balance Board accessory uses two libraries: the WPAD and the WBC. The WPAD library allows direct access to hardware, and its WPADRead function is called to get raw output values from the balance sensors. The WBC library is used to convert values obtained by WPADRead into load values, in kilogram units. Therefore, it is positioned as a higher order library than the WPAD library. Because some functions must be directly controlled from the WPAD library, the library organization associated with the Wii Balance Board accessory is as shown below.

Basic library functions are provided below.

  1. Load Calibration Data and Create a Conversion Formula

    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 WBCSetupCalibration, the calibration data will be loaded and the conversion formula will be created within the library.

    NOTE:
    WBCSetupCalibration may be executed only after the Wii Balance Board is paired. For more information, see the sample demo (handling_weight.c).

    After this function is executed, the WBCRead, WBCSetZEROPoint, and WBCGetTGCWeight functions may be used.

    (The function WBCGetBatteryLevel can be used without executing WBCSetupCalibration beforehand, but it is the only exception.)

    Control returns immediately after executing this function, but its actual processing continues for a short time (about 650ms) before completing. Use WBCGetCalibrationStatus to determine whether this function has completed normally.

  2. Set the Zero Point

    Setting the zero point is the act of setting the Wii Balance Board's unloaded state in the WBC Library.

    NOTE:
    The zero point must be set each time before measuring a weight. For more on the importance of setting the zero point, see Balance Sensors.
    s32 WBCSetZEROPoint(double press_ave[ ], u32 size);

    For the press_ave argument, set the average value of all the press values obtained by WPADRead over a period of two seconds. Set press_ave in the same order as the press values. (For example, the average of status.press[1] should be inserted into press_ave[1].) In size, specify the number of elements in the press_ave array. (Normally, allocate space for four elements.)

    Before sampling for each press value, use the temperature update command (WPADControlBLC) to update the Wii Balance Board's temperature information.

    After updating the temperature with the temperature update command (WPADControlBLC), use WPADRead to confirm that the temperature was updated correctly. On rare occasions a value of -128 or 127 is returned for the temperature. If that happens, execute the temperature update command again.

    On rare occasions, the Wii Balance Board press values can fluctuate wildly for a short period after a command is sent. Therefore, after issuing the temperature update command, wait a short time (roughly 200 ms) before getting the press values.

  3. Convert to Weight Values

    The readings are converted into weight values with the following function.

    s32 WBCRead(WPADBLStatus *status, double weight[ ], u32 size);

    Specify the WPADBLStatus structure, obtained with WPADRead, as an argument. The converted weight values will be stored in weight array in the same order as the array of press values. In size, specify the number of elements in the weight array. (Normally, allocate space for four elements.)

  4. Correct the Values

    The following function carries out both temperature correction and correction for gravitational acceleration.

    s32 WBCGetTGCWeight(double total_weight_ave, double *tgc_weight, WPADBLStatus *status);

    In the total_weight_ave argument, specify the average value obtained over a period of two seconds (120 samples) for the total of the weight values obtained by WBCRead at four different points.

    NOTE:
    Always execute correction before actually using the weight values. For more information on the importance of correcting for temperature and gravitational acceleration, see Balance Sensors.
  5. Sensors and Battery Lifetime

    The balance sensors on each of the Wii Balance Board's four corners will cease to operate when the 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 press become zero at this time.

    When the remaining battery life is below the threshold, the WBCGetBatteryLevel function returns zero. Have your applications use this function to check the remaining battery life and prompt the user to replace the battery if zero is returned.

  6. Balance Sensors

    Balance 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.
    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, always set the zero point before making an accurate measurement.

    The 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 relay heavier weight values, and stiffer ones relay lighter values.

    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.

    The WBCGetTGCWeight function corrects for both temperature and gravitational acceleration. Always use the WBCGetTGCWeight function to correct weight values when making accurate measurements.

The following steps summarize the ideal process for making accurate measurements:

  1. Have the player step off the Wii Balance Board.
  2. Set the zero point when there is no load.
  3. Immediately have the player step onto the Wii Balance Board and measure the player's weight.
  4. Correct the measured weight value using the correction function.

Wii Balance Board Operations Check

Games that support the Wii Balance Board accessory must implement a check of Wii Balance Board operations, which allows the user to verify that the Wii Balance Board is working normally. Because the purpose of this mode is to allow the user to troubleshoot voluntarily, implement a check of Wii Balance Board operations as a separate mode from the game.
Within the check of Wii Balance Board operations, check whether it is possible to get measurement values from each of the four sensors of the Wii Balance Board accessory. The board fails the check if a measurement value cannot be obtained from even one sensor.

Wii Balance Board Operations Check Procedure

  1. Use the WBCGetBatteryLevel function to check the battery level; if 0 is returned, prompt the user to replace the batteries.
  2. Display "Please step off the Wii Balance Board." Have the user step off the Wii Balance Board. To determine whether the user has stepped off the Wii Balance Board, you can read the return value of the WBCRead function. However, depending on how the Wii Balance Board was broken, the return value of the WBCRead function may not be correct. For this reason, we recommend requiring the user to press a button after they have stepped off the Wii Balance Board, then checking the WBCRead function’s return value. If WBCRead returns a value of 1 at this time, there is a possibility that the Wii Balance Board is malfunctioning. In this case, treat it as a malfunctioning Wii Balance Board.
  3. After confirming the user has stepped off, set the zero point.
  4. Display "Step onto the Wii Balance Board with your legs spread evenly." and then prompt the user to step on the Wii Balance Board within 10 seconds with his weight evenly distributed. Verify the user has stepped on the Wii Balance Board by confirming that the load has changed by at least 2 kilograms compared to the zero point. If the user has not stepped on the Wii Balance Board within 10 seconds, display "Could not detect. Step off the Wii Balance Board and press the A Button." After the A Button is pressed, the process starts again from when the zero point is set. If the user cannot be detected on the third try, display a message stating the Wii Balance Board accessory is not operating correctly.
  5. If the user has been detected, calculate the average load over 2 seconds, and ensure that the maximum load has not been exceeded. If the maximum load has not been exceeded, and the average load for each sensor is greater than or equal to 2 kilograms, the Wii Balance Board accessory is working correctly; otherwise, it is not. Display the result of the troubleshooting (for example, “OK” or “NG”) to inform the user whether the Wii Balance Board is broken.

Revision History

2013/05/08 Automated cleanup pass.
2012/07/25 Cleanup pass
2011/07/20 Initial Version


CONFIDENTIAL