ve.ucv.ciens.icaro.libnxtarcontrol

Class NxtARControlProtocol

java.lang.Object

ve.ucv.ciens.icaro.libnxtarcontrol.NxtARControlProtocol

public class NxtARControlProtocol
extends java.lang.Object

A wrapper around the NxtAR robot control protocol for the LejOS operating system.

Since:

December 15, 2014

See Also:

The LejOS operating system., NxtAR-core Github repository.

Constructor Summary

Constructors

Constructor and Description
NxtARControlProtocol(java.io.DataInputStream inputStream, java.io.DataOutputStream outputStream) Create a new ARControl object.

Method Summary

Methods

Modifier and Type	Method and Description
DecodedControlAction	decodeMessage(byte[] message) Decodes a protocol message encoded as a byte array of two elements as specified in the package definition.
byte[]	encodeControlAction(DecodedControlAction action) Encodes a given DecodedControlAction into a two byte array.
boolean	executeControlAction(DecodedControlAction controlAction) Executes an already decoded DecodedControlAction, calling the user operation listeners if needed.
boolean	readAndExecuteMessage() Attempts to read, decode and execute a message, calling the user operation listeners if needed.
byte[]	readRawControlMessage() Attempts to read a 2-byte message and returns it as is.
void	registerUserActionListener(UserActionListener listener) Adds an UserActionListener to this object's listeners list calling it's UserActionListener.onListenerRegistered() method.
void	removeUserActionListener(UserActionListener listener) Removes an UserActionListener from this object's listeners list calling it's UserActionListener.onListenerRemoved() method.
void	setInputStream(java.io.DataInputStream inputStream) Changes the input stream associated with this ARControl to the input stream passed as parameter.
void	setOutputStream(java.io.DataOutputStream outputStream) Changes the DataOutputStream associated with this ARControl to the output stream passed as parameter.
boolean	writeMessage(DecodedControlAction action) Encodes and writes a DecodedControlAction into the associated DataOutputStream if any.
void	writeRawControlMessage(byte[] message) Attempts to write a 2-byte message to the associated DataOutputStream if any.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NxtARControlProtocol

public NxtARControlProtocol(java.io.DataInputStream inputStream,
                    java.io.DataOutputStream outputStream)

Create a new ARControl object.

Parameters:

inputStream - A DataInputStream used to read protocol messages from. Can be null.

outputStream - An DataOutputStream used to write protocol messages to. Can be null.

Method Detail

setOutputStream

public void setOutputStream(java.io.DataOutputStream outputStream)
                     throws java.io.IOException

Changes the DataOutputStream associated with this ARControl to the output stream passed as parameter. The currently set output stream is flushed and closed before replacing it.

Parameters:

outpuStream - An opened output stream. Can be null.

Throws:

java.io.IOException - If an error happened while closing the previous output stream.

writeRawControlMessage

public void writeRawControlMessage(byte[] message)
                            throws java.io.IOException,
                                   java.lang.IllegalArgumentException

Attempts to write a 2-byte message to the associated DataOutputStream if any.

Returns immediately if no DataOutputStream has been set with setOutputStream(DataOutputStream) or if the message is null. If the message is longer than two bytes only the first two bytes are written to the output stream.

Throws:

java.io.IOException - If writing the message fails. It is the same IOException as thrown by DataOutput.write(byte[], int, int).

java.lang.IllegalArgumentException - If the message lenght is less than two.

encodeControlAction

public byte[] encodeControlAction(DecodedControlAction action)

Encodes a given DecodedControlAction into a two byte array.

Parameters:

action - the action to encode.

Returns:

The encoded action. Null if said action is null.

writeMessage

public boolean writeMessage(DecodedControlAction action)
                     throws java.io.IOException

Encodes and writes a DecodedControlAction into the associated DataOutputStream if any.

Parameters:

action - The action to write.

Returns:

True if writing the action succeded. False if either the action or the DataOutputStream are null.

Throws:

java.io.IOException - If writing the message fails.

setInputStream

public void setInputStream(java.io.DataInputStream inputStream)
                    throws java.io.IOException

Changes the input stream associated with this ARControl to the input stream passed as parameter. The currently set input stream is closed before replacing it.

Parameters:

inputStream - An opened input stream. Can be null.

Throws:

java.io.IOException - If an error happened while closing the previous input stream.

readRawControlMessage

public byte[] readRawControlMessage()
                             throws java.io.IOException

Attempts to read a 2-byte message and returns it as is.

Returns null if no DataInputStream has been set with setInputStream(DataInputStream).

Returns:

The two bytes read from the associated connection as an array.

Throws:

java.io.IOException - If reading the message fails. It is the same IOException as thrown by DataInput.readByte().

readAndExecuteMessage

public boolean readAndExecuteMessage()
                              throws java.io.IOException

Attempts to read, decode and execute a message, calling the user operation listeners if needed.

Returns:

True if a message could be read, decoded and executed successfully. False otherwise.

Throws:

java.io.IOException - If reading the message fails. It is the same IOException as thrown by DataInput.readByte() if any.

decodeMessage

public DecodedControlAction decodeMessage(byte[] message)
                                   throws java.lang.IllegalArgumentException

Decodes a protocol message encoded as a byte array of two elements as specified in the package definition.

User actions have precedence over motor recentering and this in turn has precedence over other movement actions. User actions have precedence in decreasing order; that is, user action 1 has precedence over user actions 2 and 3, etc.

If the message indicates a movement (forward or backward) with all motors off, then it is interpreted as a request to stop all motors. A recenter or user action with all motors off will be decoded as is and must be interpreted by the user.

Parameters:

message - A byte array of size two encoding a message recognized by the protocol. If the array has 3 or more elements then only the first 2 are used during the decoding process.

Returns:

A DecodedControlAction instance containing the decoded message.

Throws:

java.lang.IllegalArgumentException - If the array is null or has less than 2 elements.

executeControlAction

public boolean executeControlAction(DecodedControlAction controlAction)
                             throws java.lang.IllegalArgumentException

Executes an already decoded DecodedControlAction, calling the user operation listeners if needed.

Parameters:

controlAction - The action to execute.

Returns:

True if the action could be executed successfully. False otherwise.

Throws:

java.lang.IllegalArgumentException - If controlAction is null.

registerUserActionListener

public void registerUserActionListener(UserActionListener listener)
                                throws java.lang.IllegalArgumentException

Adds an UserActionListener to this object's listeners list calling it's UserActionListener.onListenerRegistered() method. Adding a listener that is already registered does nothing.

Parameters:

listener - The listener to add.

Throws:

java.lang.IllegalArgumentException - If listener is null.

removeUserActionListener

public void removeUserActionListener(UserActionListener listener)
                              throws java.lang.IllegalArgumentException

Removes an UserActionListener from this object's listeners list calling it's UserActionListener.onListenerRemoved() method. Removing a listener that is NOT on the list does nothing.

Parameters:

listener - The listener to remove.

Throws:

java.lang.IllegalArgumentException - If listener is null.