ch.aplu.nxt

Class LegoRobot

java.lang.Object

ch.aplu.nxt.LegoRobot

All Implemented Interfaces:

SharedConstants

Direct Known Subclasses:

NxtRobot, TurtleRobot

public class LegoRobot
extends java.lang.Object
implements SharedConstants

Class that represents a NXT robot brick. Parts (e.g. motors, sensors) may be assembled into the robot to make it doing the desired job.

More than one instance may be created. They are identified by different Bluetooth names (or addresses).

The Bluetooth communication uses the Bluecove library and is fully standalone and portable. No serial port emulation (RFCOMM) and no Bluetooth Control Center (BCC) is used. The Bluecove library supports only interfaces with Widcomm compatibility. If more than one brick is used at the same time, the Bluetooth interface must be capable to establish more than one Bluetooth link (e.g. Anycom USB adapter, Part.No: CC-3036).

NxtJlib implements the usual Java event handling model using event listeners and adapters. The sensors are polled at a regular interval from a internal thread and the registered callback method is invoked, when the event condition is fullfilled (e.g. sensor value crosses a given trigger level).

Many library options are defined in a property file 'nxtjlib.properties' that may be modified as needed. The property file is searched in the following order:
- Application directory (user.dir)
- Home directory (user.home)
- NxtJLib.jar (distribution)

As soon as the property file is found, the search is cancelled. This allows to use a personalized property file without deleting or modifing the distributed file in NxtJLib.jar. Consult the distributed file for more information. Be careful to keep the original formatting.

If the property KeepAlive is set to 1, a thread is started that sends keep alive commands every 500 s in order to prevent the automatic shutdown of the NXT.

The library is carefully tested with the leJOS firmware. The Lego firmware is almost 100% compatible, but some special operations may fail (e.g. the motor count)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	LegoRobot.ClosingMode Modes to determine what happens when the title bar close button is hit.

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	isConnecting

Fields inherited from interface ch.aplu.nxt.SharedConstants

ABOUT, ANGLE, ANGLESTEPSMODE, BOOLEANMODE, BOOT, BRAKE, CELSIUSMODE, CLOSE, CUSTOM, DEBUG_LEVEL_HIGH, DEBUG_LEVEL_LOW, DEBUG_LEVEL_MEDIUM, DEBUG_LEVEL_OFF, DELETE, DELETE_USER_FLASH, DIRECT_COMMAND_NOREPLY, DIRECT_COMMAND_REPLY, FAHRENHEITMODE, FIND_FIRST, FIND_NEXT, GET_BATTERY_LEVEL, GET_CURRENT_PROGRAM_NAME, GET_DEVICE_INFO, GET_FIRMWARE_VERSION, GET_INPUT_VALUES, GET_OUTPUT_STATE, HIGH_SPEED_BUFFER, KEEP_ALIVE, LIGHT_ACTIVE, LIGHT_INACTIVE, LOWSPEED, LOWSPEED_9V, LS_GET_STATUS, LS_READ, LS_WRITE, MESSAGE_READ, MESSAGE_WRITE, MODEMASK, MOTOR_RUN_STATE_IDLE, MOTOR_RUN_STATE_RAMPDOWN, MOTOR_RUN_STATE_RAMPUP, MOTOR_RUN_STATE_RUNNING, MOTORON, NO_OF_SENSOR_TYPES, NO_SENSOR, NXJ_FIND_FIRST, NXJ_FIND_NEXT, OPEN_APPEND_DATA, OPEN_READ, OPEN_READ_LINEAR, OPEN_WRITE, OPEN_WRITE_DATA, OPEN_WRITE_LINEAR, PCTFULLSCALEMODE, PERIODCOUNTERMODE, PLAY_SOUND_FILE, PLAY_TONE, POLL, POLL_BUFFER, POLL_LENGTH, RAWMODE, READ, REFLECTION, REGULATED, REGULATION_MODE_IDLE, REGULATION_MODE_MOTOR_SPEED, REGULATION_MODE_MOTOR_SYNC, REPLY_COMMAND, RESET_MOTOR_POSITION, RESET_SCALED_INPUT_VALUE, SET_BRICK_NAME, SET_INPUT_MODE, SET_OUTPUT_STATE, SLOPEMASK, SOUND_DB, SOUND_DBA, START_PROGRAM, STOP_PROGRAM, STOP_SOUND_PLAYBACK, SWITCH, SYSTEM_COMMAND_NOREPLY, SYSTEM_COMMAND_REPLY, TEMPERATURE, TITLE, TITLEMP, TRANSITIONCNTMODE, VERSION, WRITE

Constructor Summary

Constructors

Constructor and Description
LegoRobot() Asks for the Bluetooth name and creates a LegoRobot instance.
LegoRobot(long btAddress) Creates a LegoRobot instance with given Bluetooth address.
LegoRobot(long btAddress, boolean connect) Creates a LegoRobot instance with given Bluetooth address.
LegoRobot(java.lang.String btName) Creates a LegoRobot instance with given Bluetooth name.
LegoRobot(java.lang.String btName, boolean connect) Creates a LegoRobot instance with given Bluetooth name.

Method Summary

Methods

Modifier and Type	Method and Description
void	addPart(Part part) Assembles the given part into the robot.
void	clearDisplay() Clears the display.
boolean	connect() Connects the host to the robot via Bluetooth.
boolean	connect(boolean isConnectPane) Connects the host to the robot via Bluetooth.
boolean	connect(boolean isConnectPane, boolean isAnnounce) Connects the host to the robot via Bluetooth.
boolean	disconnect() Closes the Bluetooth communication.
void	drawString(java.lang.String text, int x, int y) Draws the given text line starting at given position.
void	drawStringAt(java.lang.String text, int count) Draws the given text line starting at given screen cell count.
void	exit() Closes the connection dialog and any open QuitPane, disconnects the Bluetooth communication and terminates the program.
boolean	fileExists(java.lang.String filename) Searches for given file in the brick's file system.
FileInfo	findFirst() Start file enumeration in the brick's file system.
FileInfo	findNext(byte handle) Searches the next file in a file enumeration.
static java.lang.String	getAbout() Returns copywrite information.
double	getBatteryLevel() Returns the battery level.
java.lang.String	getBtAddress() Returns the Bluetooth address (hex).
long	getBtAddressLong() Returns the Bluetooth address (long).
java.lang.String	getBtName() Returns the Bluetooth name
static int	getDebugLevel() Returns the current debug level.
java.lang.String	getFriendlyName() Sends a request to the brick to get the Bluetooth friendly name.
int	getHitButtonID() Returns the button ID of the button previously hit.
java.io.InputStream	getInputStream() Returns the InputStream reference of the Bluetooth connection.
java.io.OutputStream	getOutputStream() Returns the OutputStream reference of the Bluetooth connection.
static ch.aplu.nxt.platform.NxtProperties	getProperties() Returns the properties from the NxtJLib property file.
javax.microedition.io.StreamConnection	getStreamConnection() Returns the StreamConnection reference of the Bluetooth connection.
static java.lang.String	getVersion() Returns library version information.
boolean	isButtonHit() Returns true, if any of the buttons was hit.
boolean	isButtonListenerRunning() Returns the current state of the button listener thread.
boolean	isConnected() Returns the connection state.
boolean	isDownHit() Returns true, if the DOWN button was the last button hit since the last call of this method.
boolean	isEnterHit() Returns true, if the ENTER button was the last button hit since the last call of this method.
boolean	isEscapeHit() Returns true, if the ESCAPE button was the last button hit since the last call of this method.
boolean	isLeftHit() Returns true, if the LEFT button was the last button hit since the last call of this method.
boolean	isRightHit() Returns true, if the RIGHT button was the last button hit since the last call of this method.
boolean	isRunning() Returns true as long as exit() is not called and the close button of the Connection Pane is not hit.
boolean	isUpHit() Returns true, if the UP button was the last button hit since the last call of this method.
void	keepAlive() Sends a keep alive command to prevent the automatic shutdown of the brick.
void	playConnectMelody() Plays a standard connect melody.
void	playDisconnectMelody() Plays a standard disconnect melody.
void	playTone(int frequency, int duration) Plays a tone with given frequency (in Hertz) and duration (in seconds).
byte[]	readData() Reads the data returned as a reply from the brick.
byte[]	requestData(byte[] request) Combines sendData() and readData() in synchronized block.
void	reset() Resets Nxt to start location/direction.
void	sendData(byte[] command) Sends a direct command to the brick.
void	setChannel(int channel) Sets the Bluetooth channel (default: 1).
void	startButtonListener() Starts a button listener to get button hit events.
boolean	startProgram(java.lang.String filename)
void	stopButtonListener() Stops the button listener and disables button hit events.

Methods inherited from class java.lang.Object

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

Field Detail

isConnecting

public static boolean isConnecting

Constructor Detail

LegoRobot

public LegoRobot(java.lang.String btName,
         boolean connect)

Creates a LegoRobot instance with given Bluetooth name. If connect is true, a connection trial is engaged while an information pane is shown. If the connection fails, the calling thread will be put in a wait state and the program hangs. The user can then terminate the application by closing the information pane. established at this time.

If connect = false, no connection trial is engaged at this time and connect() should be used. If any method that needs the connection is invoked before connect() is called, the connection is automatically established.

If btName = null, a input dialog is displayed where the Bluetooth name can be entered.

No connection pane is shown, if connect = false and connect(false) is called.

Parameters:

btName - the Bluetooth friendly name of the brick, e.g. "NXT"

connect - if true, a connection trial is engaged

LegoRobot

public LegoRobot(java.lang.String btName)

Creates a LegoRobot instance with given Bluetooth name. A connection trial is engaged while an information pane is shown. If the connection fails, the calling thread will be put in a wait state and the program hangs. The user can then terminate the application by closing the information pane.

If btName = null, a input dialog is displayed where the Bluetooth name can be entered.

Parameters:

btName - the Bluetooth friendly name of the brick, e.g. "NXT"

LegoRobot

public LegoRobot(long btAddress,
         boolean connect)

Creates a LegoRobot instance with given Bluetooth address. If connect is true, a connection trial is engaged while an information pane is shown. If the connection fails, the calling thread will be put in a wait state and the program hangs. The user can then terminate the application by closing the information pane. If connect = false, no connection trial is engaged at this time and connect() should be used. If any method that needs the connection is invoked before connect() is called, the connection is automatically established.

No connection pane is shown, if connect = false and connect(false) is called.

Parameters:

btAddress - the Bluetooth address of the brick, e.g. 0x0000A762B001

connect - if true, a connection trial is engaged

LegoRobot

public LegoRobot(long btAddress)

Creates a LegoRobot instance with given Bluetooth address. A connection trial is engaged while an information pane is shown. If the connection fails, the calling thread will be put in a wait state and the program hangs. The user can then terminate the application by closing the information pane.

Parameters:

btAddress - the Bluetooth address of the brick, e.g. 0x0000A762B001

LegoRobot

public LegoRobot()

Asks for the Bluetooth name and creates a LegoRobot instance. The initial value for the name is read from the nxtjlib.properties file. In J2ME the modified name is stored in the RMS and reread at the next program execution. A connection trial is engaged while an information pane is shown. If the connection fails, the calling thread will be put in a wait state and the program hangs. The user can then terminate the application by closing the information pane.

Method Detail

setChannel

public void setChannel(int channel)

Sets the Bluetooth channel (default: 1). Used only when calling connect().

Parameters:

channel - the channel number

getProperties

public static ch.aplu.nxt.platform.NxtProperties getProperties()

Returns the properties from the NxtJLib property file.

Returns:

the reference to the NxtPropeties

getDebugLevel

public static int getDebugLevel()

Returns the current debug level.

Returns:

the debug level set in the properties file.

addPart

public void addPart(Part part)

Assembles the given part into the robot. If already connected, initialize the part.

Parameters:

part - the part to assemble

connect

public boolean connect()

Connects the host to the robot via Bluetooth. Initializes all parts already assembled. Shows a information pane while connecting. A connect/disconnect melody is played.

Returns:

true, if successful or already connected; false, if connection fails or already connected

connect

public boolean connect(boolean isConnectPane)

Connects the host to the robot via Bluetooth. Initializes all parts already assembled. If isConnectPane = true, an information pane is shown while connecting.

Parameters:

isConnectPane - if true an information pane is shown

Returns:

true, if successful or already connected; false, if connection fails or already connected

connect

public boolean connect(boolean isConnectPane,
              boolean isAnnounce)

Connects the host to the robot via Bluetooth. Initializes all parts already assembled. If isConnectPane = true, an information pane is shown while connecting. If isAnnounce = true, a melody is by the brick when the connection is established and when the connection is closed.

Parameters:

isConnectPane - if true, an information pane is shown

isAnnounce - if true, a connect/disconnect melody is played

Returns:

true, if successful or already connected; false, if connection fails or already connected

disconnect

public boolean disconnect()

Closes the Bluetooth communication. Delegates cleaning to a cleanup thread. Waits for thread termination for 5 seconds and returns true, if cleanup successful. If cleanup fails, returns false. If not connected immediately returns true.

Returns:

true if cleanup successful or not connected; otherwise false

exit

public void exit()

Closes the connection dialog and any open QuitPane, disconnects the Bluetooth communication and terminates the program.

isRunning

public boolean isRunning()

Returns true as long as exit() is not called and the close button of the Connection Pane is not hit.

Returns:

the running state of the robot

playConnectMelody

public void playConnectMelody()

Plays a standard connect melody.

playDisconnectMelody

public void playDisconnectMelody()

Plays a standard disconnect melody.

getStreamConnection

public javax.microedition.io.StreamConnection getStreamConnection()

Returns the StreamConnection reference of the Bluetooth connection.

Returns:

StreamConnection or null, if not connected

getInputStream

public java.io.InputStream getInputStream()

Returns the InputStream reference of the Bluetooth connection.

Returns:

InputStream or null, if not connected

getOutputStream

public java.io.OutputStream getOutputStream()

Returns the OutputStream reference of the Bluetooth connection.

Returns:

OutputStream or null, if not connected

getFriendlyName

public java.lang.String getFriendlyName()

Sends a request to the brick to get the Bluetooth friendly name.

Returns:

the Bluetooth friendly name

requestData

public byte[] requestData(byte[] request)

Combines sendData() and readData() in synchronized block.

Parameters:

request - the data to send

Returns:

the brick's reply

sendData

public void sendData(byte[] command)

Sends a direct command to the brick.

Parameters:

command - the data to send

readData

public byte[] readData()

Reads the data returned as a reply from the brick.

Returns:

the brick's reply

isConnected

public boolean isConnected()

Returns the connection state.

Returns:

true, if connected, otherwise false

playTone

public void playTone(int frequency,
            int duration)

Plays a tone with given frequency (in Hertz) and duration (in seconds).

getBatteryLevel

public double getBatteryLevel()

Returns the battery level.

Returns:

voltage (in Volt)

getBtAddress

public java.lang.String getBtAddress()

Returns the Bluetooth address (hex).

Returns:

Bluetooth address as string in hex format

getBtName

public java.lang.String getBtName()

Returns the Bluetooth name

Returns:

Bluetooth friendly name

getBtAddressLong

public long getBtAddressLong()

Returns the Bluetooth address (long).

Returns:

Bluetooth address as long.

getVersion

public static java.lang.String getVersion()

Returns library version information.

Returns:

library version

getAbout

public static java.lang.String getAbout()

Returns copywrite information.

Returns:

copywrite information

keepAlive

public void keepAlive()

Sends a keep alive command to prevent the automatic shutdown of the brick. This may be automated by setting KeepAlive = 1 in the NxtJLib properties file.

See Also:

LegoRobot

startProgram

public boolean startProgram(java.lang.String filename)

findFirst

public FileInfo findFirst()

Start file enumeration in the brick's file system. For a file enumeration do the following
Call findFirst(). It returns the FileInfo reference of the first file. If it returns null, there is no file and you can't proceed.
Keep calling findNext() until it returns null, meaning there are no more files

Returns:

FileInfo reference giving details of the first file found or null if the search fails

findNext

public FileInfo findNext(byte handle)

Searches the next file in a file enumeration.

Parameters:

handle - the handle of the previous found file

Returns:

FileInfo reference giving details of the file or null if the search fails

fileExists

public boolean fileExists(java.lang.String filename)

Searches for given file in the brick's file system.

Returns:

true, if file exists, otherwise false

reset

public void reset()

Resets Nxt to start location/direction. Empty method for compatibility with NxtSim.

startButtonListener

public void startButtonListener()

Starts a button listener to get button hit events. The listener is started automatically by the LegoRobot constructor.

stopButtonListener

public void stopButtonListener()

Stops the button listener and disables button hit events.

isButtonHit

public boolean isButtonHit()

Returns true, if any of the buttons was hit. Calls Thread.sleep(10) to be used in narrow loops. A button listener must be started before by calling startButtonListener.

Returns:

true, if a button was hit or the connection in not established

getHitButtonID

public int getHitButtonID()

Returns the button ID of the button previously hit. The button hit buffer is cleared then.

Returns:

the ID of the button; if the hit buffer is empty or the button listener is is not running or the connection in not established, return 0

isUpHit

public boolean isUpHit()

Returns true, if the UP button was the last button hit since the last call of this method. On return, the button hit is cleared. Calls Thread.sleep(10) to be used in narrow loops.

Returns:

true, if the up button was clicked or the connection in not established

isDownHit

public boolean isDownHit()

Returns true, if the DOWN button was the last button hit since the last call of this method. On return, the button hit is cleared. Calls Thread.sleep(10) to be used in narrow loops.

Returns:

true, if the up button was clicked or the connection in not established

isLeftHit

public boolean isLeftHit()

Returns true, if the LEFT button was the last button hit since the last call of this method. On return, the button hit is cleared. Calls Thread.sleep(10) to be used in narrow loops.

Returns:

true, if the up button was clicked or the connection in not established

isRightHit

public boolean isRightHit()

Returns true, if the RIGHT button was the last button hit since the last call of this method. On return, the button hit is cleared. Calls Thread.sleep(10) to be used in narrow loops.

Returns:

true, if the up button was clicked or the connection in not established

isEnterHit

public boolean isEnterHit()

Returns true, if the ENTER button was the last button hit since the last call of this method. On return, the button hit is cleared. Calls Thread.sleep(10) to be used in narrow loops.

Returns:

true, if the up button was clicked or the connection in not established

isEscapeHit

public boolean isEscapeHit()

Returns true, if the ESCAPE button was the last button hit since the last call of this method. On return, the button hit is cleared. Calls Thread.sleep(10) to be used in narrow loops.

Returns:

true, if the up button was clicked or the connection in not established

isButtonListenerRunning

public boolean isButtonListenerRunning()

Returns the current state of the button listener thread.

drawString

public void drawString(java.lang.String text,
              int x,
              int y)

Draws the given text line starting at given position. Writes to System.out only (compatibility with EV3JLib).

Parameters:

text - the text to display

x - unused

y - unused

drawStringAt

public void drawStringAt(java.lang.String text,
                int count)

Draws the given text line starting at given screen cell count. Writes to System.out only (compatibility with EV3JLib).

Parameters:

text - the text to display

count - unused

clearDisplay

public void clearDisplay()

Clears the display. Empty method for compatibility with EV3JLib.