ch.aplu.ev3

Class LegoRobot

java.lang.Object

ch.aplu.ev3.LegoRobot

Direct Known Subclasses:

NxtTurtleRobot, TurtleRobot

public class LegoRobot
extends java.lang.Object

Class that represents a EV3 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 names (or addresses).

The communication uses a IP socket connection with port 1299, but the port can be modified in ev3jlib.properties. EV3Jlib 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 'ev3jlib.properties' that may be modified as needed. The property file is searched in the following order:
- Application directory (user.dir)
- Home directory (user.home)
- EV3JLib.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 EV3JLib.jar. Consult the distributed file for more information. Be careful to keep the original formatting.

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.

Constructor Summary

Constructors

Constructor and Description
LegoRobot() Asks for the IP address and creates a EV3Robot instance.
LegoRobot(java.lang.String ipAddress) Creates a EV3Robot instance with given IP address.
LegoRobot(java.lang.String ipAddress, boolean immediateConnect) Creates a EV3Robot instance with given IP address.

Method Summary

Methods

Modifier and Type	Method and Description
void	addButtonListener(ButtonListener listener) Registers a button listener that simulates the events when one of the brick buttons is hit.
void	addConnectionListener(ConnectionListener listener) Registers a connection listener to get notifications when the link is established or broken.
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 an IP socket.
boolean	connect(boolean isConnectPane) Connects the host to the robot via an IP socket.
boolean	connect(boolean isConnectPane, boolean isAnnounce) Connects the host to the robot via an IP socket.
void	disconnect() Disconnects the TCP link.
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 communication link and terminates the program (depending on setting in ev3jlib.properties).
static java.lang.String	getAbout() Returns copywrite information.
int	getBatteryLevel() Returns the battery level.
java.lang.String	getBrickGateVersion() Returns the version of the BrickGate server.
java.io.OutputStream	getDataOutputStream() Returns the OutputStream reference of the connection link.
static int	getDebugLevel() Returns the current debug level.
int	getHitButtonID() Returns the button ID of the button previously hit.
java.io.InputStream	getInputStream() Returns the InputStream reference of the connection link.
java.lang.String	getIPAddress() Returns the IP address (in dotted format).
java.lang.String[]	getIPAddresses() Returns a list with the current brick's IP addresses
static EV3Properties	getProperties() Returns the properties from the EV3JLib property file.
static java.lang.String	getVersion() Returns library version information.
boolean	isAutonomous() Returns true, if the client connects locally (with localhost connection).
boolean	isButtonHit() Returns true, if any of the buttons was hit.
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	playTone(double frequency, double duration) Plays a tone with given frequency and duration.
void	reset() Resets EV3 to start location/direction.
void	setLED(int pattern) Turn on/off the brick's left/right LEDs (only affected in pair).
void	setVolume(int volume) Sets the sound volume.

Methods inherited from class java.lang.Object

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

Constructor Detail

LegoRobot

public LegoRobot(java.lang.String ipAddress,
         boolean immediateConnect)

Creates a EV3Robot instance with given IP address. If immediateConnect is true, a immediateConnection trial is engaged while an information pane is shown. If immediateConnect is false, no connection trial is engaged at this time and connect() should be used. If ipAddress is null, a input dialog is displayed where the IP address can be entered. If more than one LegoRobot instance is needed, use immediateConnect = false.

Parameters:

ipAddress - the IP address of the brick, e.g. "10.0.1.1"

immediateConnect - if true, a connection trial is engaged

LegoRobot

public LegoRobot(java.lang.String ipAddress)

Creates a EV3Robot instance with given IP address. A connection trial is engaged while an information pane is shown. If ipAddress = null, a input dialog is displayed where the IP address can be entered. If more than one LegoRobot instance is needed, use LegoRobot(ipAddress, false).

Parameters:

ipAddress - the IP address of the brick, e.g. "10.0.1.1"

LegoRobot

public LegoRobot()

Asks for the IP address and creates a EV3Robot instance. The initial value for the address is read from the ev3jlib.properties file. A connection trial is engaged while an information pane is shown. If more than one LegoRobot instance is needed, use LegoRobot(ipAddress, false).

Method Detail

addConnectionListener

public void addConnectionListener(ConnectionListener listener)

Registers a connection listener to get notifications when the link is established or broken. Keep in mind that you may get no "connection established" notification before the listener is registered (e.g if the constructor calls connect() immediately).

Parameters:

listener - the ConnectionListener to register

getProperties

public static EV3Properties getProperties()

Returns the properties from the EV3JLib property file.

Returns:

the reference to the EV3Properties

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.

Parameters:

part - the part to assemble

connect

public boolean connect()

Connects the host to the robot via an IP socket. Shows a information pane while connecting. A connect/disconnect melody is played. If more than one LegoRobot instance is needed, use connect(false) or connect(false, false).

Returns:

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

connect

public boolean connect(boolean isConnectPane)

Connects the host to the robot via an IP socket. Initializes all parts already assembled. If isConnectPane = true, an information pane is shown while connecting. If more than one LegoRobot instance is used, do no show the connect pane.

Parameters:

isConnectPane - if true an information pane is shown

Returns:

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

connect

public boolean connect(boolean isConnectPane,
              boolean isAnnounce)

Connects the host to the robot via an IP socket. 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. If more than one LegoRobot instance is used, do no show the connect pane.

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

exit

public void exit()

Closes the connection dialog and any open QuitPane, disconnects the communication link and terminates the program (depending on setting in ev3jlib.properties).

disconnect

public void disconnect()

Disconnects the TCP link.

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

getInputStream

public java.io.InputStream getInputStream()

Returns the InputStream reference of the connection link.

Returns:

InputStream or null, if not connected

getDataOutputStream

public java.io.OutputStream getDataOutputStream()

Returns the OutputStream reference of the connection link.

Returns:

OutputStream or null, if not connected

isConnected

public boolean isConnected()

Returns the connection state.

Returns:

true, if connected, otherwise false

playTone

public void playTone(double frequency,
            double duration)

Plays a tone with given frequency and duration.

Parameters:

frequency - the frequency of the tone (in Hertz) (double rounded to int)

duration - the duration of the tone (in Millisec) (double rounded to int)

setVolume

public void setVolume(int volume)

Sets the sound volume. Master volume, used also for connect/disconnect melody.

Parameters:

volume - the sound volume (0..100)

setLED

public void setLED(int pattern)

Turn on/off the brick's left/right LEDs (only affected in pair). Pattern mask:
0: off
1: green
2: red
3: red bright
4: green blinking
5: red blinking
6: red blinking bright
7: green double blinking
8: red double blinking
9: red double blinking bright

Parameters:

pattern - the pattern 0..9

getBatteryLevel

public int getBatteryLevel()

Returns the battery level.

Returns:

voltage (in Millivolt)

getIPAddress

public java.lang.String getIPAddress()

Returns the IP address (in dotted format).

Returns:

IP address

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

getBrickGateVersion

public java.lang.String getBrickGateVersion()

Returns the version of the BrickGate server.

Returns:

version of BrickGate

getIPAddresses

public java.lang.String[] getIPAddresses()

Returns a list with the current brick's IP addresses

Returns:

the IP addresses used by the brick

isAutonomous

public boolean isAutonomous()

Returns true, if the client connects locally (with localhost connection).

Returns:

true, if the client is running on the brick; otherwise false

reset

public void reset()

Resets EV3 to start location/direction. Empty method for compatibility with EV3Sim.

addButtonListener

public void addButtonListener(ButtonListener listener)

Registers a button listener that simulates the events when one of the brick buttons is hit. The keyboard simulates the EV3 buttons as follows:
ESCAPE button->escape key
ENTER button->enter key
UP button->cursor up key
DOWN button->cursor down key
LEFT button->cursor left key
RIGHT button->cursor right key

Parameters:

listener - the ButtonListener to register

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

drawString

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

Draws the given text line starting at given position. The display is 18 characters wide and 8 lines high. Characters outside the visual range are hidden.

Parameters:

text - the text to show

x - the column number (0..17)

y - the line number (0..7)

drawStringAt

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

Draws the given text line starting at given screen cell count. The display is 18 characters wide and 8 lines high. Characters outside the visual range are hidden.

Parameters:

text - the text to show

count - the cell count (cells are counted from zero line-per-line

clearDisplay

public void clearDisplay()

Clears the display.