ch.aplu.nxt
Class NxtRobot

java.lang.Object
  ch.aplu.nxt.NxtRobot

All Implemented Interfaces:

SharedConstants

Direct Known Subclasses:

TurtleRobot

public class NxtRobot
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 indentified 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.

Field Summary

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

NxtRobot()
Asks for the Bluetooth name and creates a NxtRobot instance.

NxtRobot(long btAddress)
Creates a NxtRobot instance with given Bluetooth address.

NxtRobot(long btAddress, boolean connect)
Creates a NxtRobot instance with given Bluetooth address.

NxtRobot(java.lang.String btName)
Creates a NxtRobot instance with given Bluetooth name.

NxtRobot(java.lang.String btName, boolean connect)
Creates a NxtRobot instance with given Bluetooth name.

Method Summary

void	addPart(Part part) Assembles the given part into the robot.
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() Cuts the Bluetooth communication.
void	exit() Cuts 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.
java.io.InputStream	getInputStream() Returns the InputStream reference of the Bluetooth connection.
protected ch.aplu.nxt.InputValues	getInputValues(int portId) Reads the values from given a sensor port.
protected ch.aplu.nxt.OutputState	getOutputState(int port) Retrieves the current output state of a specific port.
java.io.OutputStream	getOutputStream() Returns the OutputStream reference of the Bluetooth connection.
static 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	isConnected() Returns the connection state.
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	sendData(byte[] command) Sends a direct command to the brick.
void	setChannel(int channel) Sets the Bluetooth channel (default: 1).
protected void	setInputMode(int portId, int sensorType, int sensorMode)
protected void	setOutputState(int portId, byte power, int mode, int regulationMode, int turnRatio, int runState, int tachoLimit) Sets the output state of a specific sensor port.
boolean	startProgram(java.lang.String filename)

Methods inherited from class java.lang.Object

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

Constructor Detail

NxtRobot

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

Creates a NxtRobot 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 friedly name of the brick, e.g. "NXT"

connect - if true, a connection trial is engaged

NxtRobot

public NxtRobot(java.lang.String btName)

Creates a NxtRobot 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 friedly name of the brick, e.g. "NXT"

NxtRobot

public NxtRobot(long btAddress,
                boolean connect)

Creates a NxtRobot 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

NxtRobot

public NxtRobot(long btAddress)

Creates a NxtRobot 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

NxtRobot

public NxtRobot()

Asks for the Bluetooth name and creates a NxtRobot 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 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()

Cuts the Bluetooth communication.

exit

public void exit()

Cuts the Bluetooth communication and terminates the program.

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

setOutputState

protected void setOutputState(int portId,
                              byte power,
                              int mode,
                              int regulationMode,
                              int turnRatio,
                              int runState,
                              int tachoLimit)

Sets the output state of a specific sensor port.

getOutputState

protected ch.aplu.nxt.OutputState getOutputState(int port)

Retrieves the current output state of a specific port.

Parameters:

port - (0,..,3)

Returns:

OutputState an OutputState reference

setInputMode

protected void setInputMode(int portId,
                            int sensorType,
                            int sensorMode)

getInputValues

protected ch.aplu.nxt.InputValues getInputValues(int portId)

Reads the values from given a sensor port.

Parameters:

portId - the Id of the sensor port (0,..3)

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:

NxtRobot

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