wiiremotej
Class BalanceBoard

java.lang.Object
  extended by wiiremotej.BalanceBoard
All Implemented Interfaces:
WiiDevice

public class BalanceBoard
extends java.lang.Object
implements WiiDevice

A class representing a Nintendo (R) Wii Balance Board (TM). It has commands to control all of the Balance Board features. You can register a BalanceBoardListener with addBalanceBoardListener.
WiiRemoteJ uses the Java logging API. The log for the package is named "wiiremotej" and can be obtained through the java.util.logging.Logger class.

Note that this document uses the following notation to represent hexadecimal numbers: 0x--. A hexadecimal number is simply a number in base-16. This convention is used because it is easier to represent a single unsigned byte (256 in decimal) in hexadecimal: 0xFF.

When the balance board is disconnected (either via the disconnect() method or by an action from the board), the board clears pointers to all variables to free up memory. Do not try to get status of the lights or any other information from the balance board after it has disconnected, as you will probably end up throwing. NullPointerExceptions. The only methods guaranteed to work after the board has been disconnected are the isConnected() method (will always return false) and the getBluetoothAddress() method.


Field Summary
static byte I_EXTENSION
          Input channel for button information (2 byte payload) and extension information (8 byte payload).
static byte I_EXTENSION2
          Input channel for button information (2 byte payload) and extension information (19 byte payload).
 
Constructor Summary
BalanceBoard(MassConstants massConstants)
          Constructs a blank Balance BOard that is not connected to an actual Board using the passed in parameters.
 
Method Summary
 void addBalanceBoardListener(BalanceBoardListener listener)
          Adds the specified BalanceBoardListener to this BalanceBoard.
 void disconnect()
          Disconnects from the Balance Board.
 boolean equals(java.lang.Object other)
          Compares BalanceBoards based on their bluetooth addresses.
 java.lang.String getBluetoothAddress()
          Returns the bluetooth address of the Balance Board.
 byte getInputReport()
          Returns the input report the balance board is currently using to receive data.
 MassConstants getMassConstants()
          Returns the mass constants located on the Balance Board.
 boolean isConnected()
          Returns true if connected to the Balance Board; otherwise false.
 boolean isLEDIlluminated()
          Returns true if the LED is illuminated; otherwise false.
 boolean isReadingData()
          Returns true if reading data; otherwise false.
 int readData(byte[] address, byte[] buffer, int firstIndex, int numBytes)
          Reads data from the Balance Board at the specified address.
 byte[] readData(byte[] address, int numBytes)
          Reads data from the Balance Board at the specified address.
 void removeBalanceBoardListener(BalanceBoardListener listener)
          Removes the specified BalanceBoardListener from this BalanceBoard.
 void requestStatus()
          Requests status of the Balance Board, including battery level, LED status, etc.
 void setLEDIlluminated(boolean illuminated)
          Sets the LED light to illuminated, where true is on and false is off.
 void waitForDataReadCompletion()
          Waits for the current readData operation to complete before returning.
 void writeData(byte[] address, byte[] data)
          Writes data to the Balance Board at the specified address.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

I_EXTENSION

public static final byte I_EXTENSION
Input channel for button information (2 byte payload) and extension information (8 byte payload).

See Also:
Constant Field Values

I_EXTENSION2

public static final byte I_EXTENSION2
Input channel for button information (2 byte payload) and extension information (19 byte payload).

See Also:
Constant Field Values
Constructor Detail

BalanceBoard

public BalanceBoard(MassConstants massConstants)
Constructs a blank Balance BOard that is not connected to an actual Board using the passed in parameters.

Parameters:
massConstants - information used in interpreting the Balance Board's mass sensor data.
Method Detail

requestStatus

public void requestStatus()
                   throws java.io.IOException
Requests status of the Balance Board, including battery level, LED status, etc. Note that status is not returned, but sent to a BBStatusEvent.

Throws:
java.io.IOException - if there is an error sending data to the Balance Board.

setLEDIlluminated

public void setLEDIlluminated(boolean illuminated)
                       throws java.lang.IllegalArgumentException,
                              java.io.IOException
Sets the LED light to illuminated, where true is on and false is off.

Parameters:
illuminated - if true, turns the light on; otherwise, turns the light off.
Throws:
java.io.IOException - if there is an error sending data to the Balance Board.
java.lang.IllegalArgumentException

writeData

public void writeData(byte[] address,
                      byte[] data)
               throws java.io.IOException,
                      java.lang.IllegalArgumentException
Writes data to the Balance Board at the specified address.

Parameters:
address - the address to write to. Must be 4 bytes. The first byte of the address indicates whether to write to memory (0x00) or registers (0x04).
data - the data to write. Must be between 1 and 16 bytes in length.
Throws:
java.io.IOException - if there is an error sending data to the Balance Board.
java.lang.IllegalArgumentException - if address is not 4 bytes long.
java.lang.IllegalArgumentException - if data.length is not between 1 and 16.

readData

public byte[] readData(byte[] address,
                       int numBytes)
                throws java.io.IOException,
                       java.lang.IllegalArgumentException,
                       java.lang.IllegalStateException,
                       java.lang.InterruptedException
Reads data from the Balance Board at the specified address. Only one data read operation can happen at a time. If you try to read data twice at the same time, the second read will throw an IllegalStateException. There is no guarantee of the data being read when calling this method. The only way you can guarantee the success of a call to this method is to check isReadingData() immediately before calling it; even then, there is a slight chance one of your methods could call readData between the time you call isReadingData() and readData. Make sure that you are careful wait for a read to complete before starting a second one! This method blocks until the specified amount of data has been read or an exception is thrown.

Parameters:
address - the address to read from. Must be 4 bytes. The first byte of the address indicates whether to read from memory (0x00) or registers (0x04).
numBytes - the length of the data to read (in bytes).
Returns:
a byte array of length numBytes containing all of the data read.
Throws:
java.io.IOException - if there is an error sending data to the Balance Board.
java.lang.IllegalArgumentException - if address is not 4 bytes in length or if numBytes is less than 1.
java.lang.IllegalStateException - if data is already being read.
java.io.IOException - if there is an error reading the data. See BBDataEvent constant field values for details.
java.lang.InterruptedException - if interrupted waiting for the data read to complete.
See Also:
waitForDataReadCompletion()

readData

public int readData(byte[] address,
                    byte[] buffer,
                    int firstIndex,
                    int numBytes)
             throws java.io.IOException,
                    java.lang.IllegalArgumentException,
                    java.lang.IllegalStateException,
                    java.lang.InterruptedException
Reads data from the Balance Board at the specified address. Only one data read operation can happen at a time. If you try to read data twice at the same time, the second read will throw an IllegalStateException. There is no guarantee of the data being read when calling this method. The only way you can guarantee the success of a call to this method is to check isReadingData() immediately before calling it; even then, there is a slight chance one of your methods could call readData between the time you call isReadingData() and readData. Make sure that you are careful wait for a read to complete before starting a second one! This method blocks until the specified amount of data has been read or an exception is thrown.

Parameters:
address - the address to read from. Must be 4 bytes. The first byte of the address indicates whether to read from memory (0x00) or registers (0x04).
buffer - the array to read data into.
firstIndex - the first index of buffer to add data to.
numBytes - the length of the data to read (in bytes). Must be between 1 and 65535 (0xFFFF).
Returns:
the number of bytes read.
Throws:
java.io.IOException - if there is an error sending data to the Balance Board.
java.lang.IllegalArgumentException - if address is not 4 bytes in length or if numBytes is less than 1 or greater than 65535 (0xFFFF).
java.lang.IllegalStateException - if data is already being read.
java.io.IOException - if there is an error reading the data. See BBDataEvent constant field values for details.
java.lang.InterruptedException - if interrupted waiting for the data read to complete.
See Also:
waitForDataReadCompletion()

waitForDataReadCompletion

public void waitForDataReadCompletion()
                               throws java.lang.InterruptedException
Waits for the current readData operation to complete before returning.

Throws:
java.lang.InterruptedException - if interrupted waiting for the data read to complete.

disconnect

public void disconnect()
Disconnects from the Balance Board. If the Balance Board is already disconnected, no action is taken and no exceptions are thrown. Note that the BalanceBoardListeners' disconnected() method will NOT be called.

Specified by:
disconnect in interface WiiDevice

isConnected

public boolean isConnected()
Returns true if connected to the Balance Board; otherwise false.

Specified by:
isConnected in interface WiiDevice
Returns:
true if connected to the Balance Board; otherwise false.

isReadingData

public boolean isReadingData()
Returns true if reading data; otherwise false.

Returns:
true if reading data; otherwise false.

isLEDIlluminated

public boolean isLEDIlluminated()
Returns true if the LED is illuminated; otherwise false.

Returns:
true if the LED is illuminated; otherwise false.

getMassConstants

public MassConstants getMassConstants()
Returns the mass constants located on the Balance Board. These values can be used to convert raw balance board data into kilograms.

Returns:
the mass constants located on the Balance Board.

getInputReport

public byte getInputReport()
Returns the input report the balance board is currently using to receive data.

Returns:
the input report the balance board is currently using to receive data.

addBalanceBoardListener

public void addBalanceBoardListener(BalanceBoardListener listener)
Adds the specified BalanceBoardListener to this BalanceBoard. If the specified listener is null, no action is taken.

Parameters:
listener - the listener to add.

removeBalanceBoardListener

public void removeBalanceBoardListener(BalanceBoardListener listener)
Removes the specified BalanceBoardListener from this BalanceBoard. If the specified listener was not previously added or is null, no action is taken.

Parameters:
listener - the listener to remove.

getBluetoothAddress

public java.lang.String getBluetoothAddress()
Returns the bluetooth address of the Balance Board. This information persists even after the balance board has been disconnected.

Specified by:
getBluetoothAddress in interface WiiDevice
Returns:
the bluetooth address of this Balance Board.

equals

public boolean equals(java.lang.Object other)
Compares BalanceBoards based on their bluetooth addresses.

Overrides:
equals in class java.lang.Object
Returns:
true if the BalanceBoards are the same (have the same Bluetooth address); otherwise false.