The leJOS Tutorial

| Start of Tutorial > Start of Trail

Trail: Essential leJOS classes
Lesson: Controlling the Hardware

# Controlling the Hardware: Sensors

Sensors are the senses of your robot, which enables it to generate an inner model of its environment and to react to events accordingly.

There's a bunch of hardware sensors available which may be connected to one of the three gray ports mounted above the RCX's display:

Similarly to the motor ports, the three ports are implemented as static fields of the `Sensor` class:

- Sensor.S1
- Sensor.S2
- Sensor.S3

Hence a typical call would be

                Sensor.S1.readValue();

Another possibility to access the sensor ports is via the static `Sensor[]` array, which contains the three sensors.

## Configuring a sensor

Before data can be read from a sensor, it has to be configured, which means that you have to tell the actual instance of the `Sensor`

- which kind of sensor is connected and
- in which kind of mode the sensor data should be read.

This is done by the `public static void setTypeAndMode(int aType, int aMode)` method, where `type` is one of the five types

- SensorConstants.SENSOR_TYPE_LIGHT: light sensor
- SensorConstants.SENSOR_TYPE_ROT: rotation sensor
- SensorConstants.SENSOR_TYPE_TEMP: temperature sensor
- SensorConstants.SENSOR_TYPE_TOUCH: touch sensor
- SensorConstants.SENSOR_TYPE_RAW: unspecific sensor for raw data reading

`mode` can be set to

- SensorConstants.SENSOR_MODE_ANGLE: angle measurement (for rotation sensors)
- SensorConstants.SENSOR_MODE_BOOL: pressed/not pressed measurement (for touch sensors)
- SensorConstants.SENSOR_MODE_DEGC: Celsius measurement (for temperature sensors)
- SensorConstants.SENSOR_MODE_DEGF: Fahrenheit measurement (for temperature sensors)
- SensorConstants.SENSOR_MODE_EDGE: edge counting, which counts the number of times the state of a touch sensor changes
- SensorConstants.SENSOR_MODE_PCT: percent measurement (for light sensors)
- SensorConstants.SENSOR_MODE_PULSE: click count (for touch sensors)
- SensorConstants.SENSOR_MODE_RAW: raw value measurement (0 - 1023).

The edge mode has some peculiarity: when the RCX is turned off, the counter remains its values. So be sure to call `Sensor.setPreviousValue(0)` before starting new measurements.

When configuring the sensor make sure that you use a meaningful combination of mode and type else the measured value won't make much sense.

## Activating a sensor

Some of the sensors, such as light sensors, require electricity to work. By calling `Sensor.activate()` the sensor port in question is "switched on" in a sense that it constantly toggles between supplying power to the connected sensor and reading data (the light sensor's electronics smoothens out this toggling so you won't notice it).
The opposite `Sensor.passivate()` method turns off this power supply.

## Reading a sensor's value

The easiest way to read a sensor's value is the use of one of the `read...()` methods:

- public static boolean readBooleanValue()
- public static int readValue()
- public static int readRawValue()

which delivers the actual state or the measured data of the sensor at the moment the method is called (keep in mind to use the correct method depending on the type and mode the sensor was configured before!).

There's is an additional low-level API method `public static int readSensorValue(int aSensorId,int aRequestType)` where `aSensorId` is the sensor's id (0,1,2) and `aRequestType` is the type of data to read (0 = raw value, 1 = configured value,2 = boolean value).

In most cases, though, you might want to be notified when some sensor is "triggered" or measures a certain value. For such cases you will use Java's event listener technology:
Your class to listen for such a sensor event will implement the `public void stateChanged(Sensor aSource, int aOldValue, int aNewValue)` method of the `josx.platform.rcx.SensorListener` interface, where the two value parameters reflect the value before and after the change in value measurement:

                public class MySensorListener implements SensorListener {
                    public void stateChanged(Sensor aSource, int aOldValue, int aNewValue) {
                        // respond to sensor value change here
                    } // stateChanged()
                } // class MySensorListener

Now you are able to add this class as a listener to the sensor port in question:

                Sensor.S1.addSensorListener(mySensorListener);

Every time the sensor notifies a change in the value it measures, the `stateChanged()` method of the `MySensorListener` will be called.
This technology is extremely useful for touch sensors, for example.

If you are unfamiliar with event listeners, feel free to consult the section of The Java Tutorial™ in question.

## A convenience sensor: ProximitySensor

When the first versions of the leJOS platform were released it was quickly detected that a special class for the detection of proximity would be quite useful: your robot wouldn't have to bump into objects any longer to detect their existence by the means of a touch sensor but were able to avoid it by using the light sensor for perception.
Yet the implementation wasn't as easy as the idea sounded: the values measured by the light sensors vary immensely among two measurements even if there is no object nearby.
So the `ProximitySensor` which tackled that issue was added to the `josx.platform.rcx` package.
It's not a subclass of the `Sensor` class, but is constructed with one. In the constructor you also might set the threshold, a integer value which defines the distance to an object by which the sensor is triggered: the bigger the value, the closer the robot gets.
The sensor is used by calling the `waitTillNear(long aMilliseconds)` method which blocks the current thread until an object is detected; the parameter defines how long may be waited, where 0 means forever (until an object is in fact detected).

## An example which uses the Sensor class

is Rotator.java which may be found in the `examples/rotator` section of the leJOS tree.

## The Sensor API

may be found here.

The leJOS Tutorial

| Start of Tutorial > Start of Trail