Start of Tutorial > Start of Trail

Lesson: A Sample Application

In this section we will take a closer look on a simple sample application using the leJOS API and discuss some of its fundamental concepts.
We assume your RCX is connected to a motor via a cable mounted on port A.

The complete program

            import josx.platform.rcx.*;

            //////////////////////////////////////
            /**
            * Represents a simple sample application.
            *
            * @author The leJOS Tutorial
            * @version 1.0 
            */
            public class SimpleSample {        

                ////////////////////////////////////////////
                // public methods
                ////////////////////////////////////////////

                ////////////////////////////////////////////
                /**
                 * main method 
                 * @throws InterruptedException
                 */
                public static void main(String[] args) 
                    throws InterruptedException {

                    // message
                    TextLCD.print("DRIVE");

                    // drive forward
                    Motor.A.forward();

                    // just run until RUN button is pressed again
                    Button.RUN.waitForPressAndRelease();

                } // main()

            } // class SimpleSample
        

The import statement

            import josx.platform.rcx.*;
        

The basic package, which contains most of the essential leJOS classes, is josx.platform.rcx. The name is somewhat due to historical reasons, for Jose Solarzano was the inventor and first developer of leJOS.
For an overview of this package consult the API.

The entry point: main()

        public static void main(String[] args) 
                    throws InterruptedException {
        

As with most Java applications, the entry point of a lejos program is the main() method.
In our case, it throws a InterruptedException arising eventually from the Button.RUN.waitForPressAndRelease() call below.
What will happen when such an exception occurs?
The RCX will stop the execution of the main() method and display some (rather cryptic) error information on its LCD. For details see the section on exceptions later in this tutorial.

Output

        TextLCD.print("DRIVE");
        

You might have noticed that the graphical user interface of the RCX is rather limited - in fact, there's only the little LCD in its middle for such a purpose.
Thus the abilities of a leJOS program for visual output are quite weak (compared to Java applications running on a PC) - a fact that makes debugging in leJOS a somewhat challenging task.
After all, there's the possibility to write up to five numbers or letters to the LCD using the static methods of the TextLCD or the LCD class.

There ARE mechanisms, though, to display graphical information to the user: you might transfer information to the IR tower using the IR sensor in front of the RCX and display it on your PC's screen. However, this is a more advanced feature - see the specialized trail on communication contained in this tutorial.

You already might have noticed two things of importance here:

1. You can use the well-known java.lang.String class in leJOS.
2. You use static methods of TextLCD. This is a major concept of leJOS: The classes which are directly connected to the actual RCX hardware parts - e.g. motors, sensors, buttons or the LCD - are designed to be static ones. As a result you never will construct any of these but just use the methods of the existing single instance.

Running a motor

        // drive forward
        Motor.A.forward();
        

This piece of code runs the motor connected to the RCX's port A in "forward" mode (the direction the motor actually spins depends on the orientation in which you mounted the connector).
Again note that you use a static instance of the Motor class - to be more precise, a static member (named A) of this class, which refers to "motor connected to port A". As you might have already guessed, the two other motors are referred to as Motor.B and Motor.C, respectively.
You see that you don't have to bother with any hardware aspect or electro engineering here - just one single line of code and your motor will run! It's pretty easy, isn't it?

If the motor in question is connected to some wheel assembly accurately, your robot will now drive forward.

Keep on running

        // just run until RUN button is pressed again
        Button.RUN.waitForPressAndRelease();
        

So, what's the use of this? you might be tempted to ask at this point of time, Isn't my robot running yet?.
The answer is: yes AND no.
Let's take a look at the program and assume the last statement would be missing:

1. The motor is running now and the Motor.forward() method returns immediately, so the program moves to the next statement.
2. But there is none, so main() comes to an end and returns control to the operating system, which terminates program execution (for there is no thread left to be executed).
3. This results, among others, in the motor stopping.
4. Thus, the effect of the missing Button.RUN.waitForPressAndRelease() statement is the motor running for a very short period of time (maybe not noticeable at all, leaving behind a staggered user) and stopping right away.

Start of Tutorial > Start of Trail