The leJOS Tutorial

| Start of Tutorial > Start of Trail

Trail: Getting Started

# 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.

Regarding this we have to assure that program execution doesn't stop or a least at the point of time we choose it to.
As always, there are many ways to accomplish this task. One of the simplest ones, though, is to force the program waiting for the user pressing and releasing the RUN button which is easily got by `Button.RUN.waitForPressAndRelease()`.

The leJOS Tutorial

| Start of Tutorial > Start of Trail