lejos.nxt
Class UltrasonicSensor

java.lang.Object
  lejos.nxt.I2CSensor
      lejos.nxt.UltrasonicSensor

All Implemented Interfaces:

SensorConstants, RangeFinder

public class UltrasonicSensor
extends I2CSensor
implements RangeFinder

Abstraction for a NXT Ultrasonic Sensor. The sensor knows four modes: off, continuous, ping and capture. In continuous mode, the device periodically tests, whether and object in range. In ping mode, the sensor sends a single ping, and records the distance of up to 8 objects. In capture mode, the sensor listens for signals from other UltraSonic devices. At the present time, we (the leJOS team) are not sure, how the capture mode works. Please let us know about your experience with it.

Field Summary

static byte	MODE_CAPTURE
static byte	MODE_CONTINUOUS
static byte	MODE_OFF
static byte	MODE_PING
static byte	MODE_RESET

Fields inherited from class lejos.nxt.I2CSensor

address, DEFAULT_I2C_ADDRESS, port, REG_PRODUCT_ID, REG_VENDOR_ID, REG_VERSION

Fields inherited from interface lejos.nxt.SensorConstants

BLACK, BLANK_INDEX, BLUE, BLUE_INDEX, GREEN, GREEN_INDEX, MAX_AD_RAW, MAX_TYPE, MIN_TYPE, MODE_ANGLESTEP, MODE_BOOLEAN, MODE_CELSIUS, MODE_FARENHEIT, MODE_PCTFULLSCALE, MODE_PERIODCOUNTER, MODE_RAW, MODE_TRANSITIONCNT, RED, RED_INDEX, TYPE_ANGLE, TYPE_COLORBLUE, TYPE_COLORFULL, TYPE_COLORGREEN, TYPE_COLORNONE, TYPE_COLORRED, TYPE_CUSTOM, TYPE_HISPEED, TYPE_LIGHT_ACTIVE, TYPE_LIGHT_INACTIVE, TYPE_LOWSPEED, TYPE_LOWSPEED_9V, TYPE_NO_SENSOR, TYPE_REFLECTION, TYPE_SOUND_DB, TYPE_SOUND_DBA, TYPE_SWITCH, TYPE_TEMPERATURE, WHITE, YELLOW

Constructor Summary

UltrasonicSensor(I2CPort port)

Method Summary

int	capture() Set capture mode Set the sensor into capture mode.
int	continuous() Switch to continuous mode.
int	getActualMode() Returns the current operating mode of the sensor.
int	getCalibrationData(byte[] data) Return 3 bytes of calibration data.
int	getContinuousInterval() Return the interval used in continuous mode.
int	getData(int register, byte[] buf, int off, int len) Executes an I2C read transaction and waits for the result.
int	getDistance() Return distance to an object.
int	getDistances(int[] dist) Return an array of distances.
int	getDistances(int[] dist, int off, int len) Return an array of distances.
int	getFactoryData(byte[] data) Return 10 bytes of factory calibration data.
int	getMode() Returns the current operating mode of the sensor.
float	getRange() Get the range to the nearest object
float[]	getRanges() If the sensor is capable, this method returns multiple range values from a single scan.
String	getUnits() Return a string indicating the type of units in use by the unit.
int	off() Turn off the sensor.
int	ping() Send a single ping.
int	reset() Reset the device.
int	sendData(int register, byte[] buf, int off, int len) Executes an I2C write transaction.
int	setCalibrationData(byte[] data) Set 3 bytes of calibration data.
int	setContinuousInterval(int interval) Set the ping inetrval used when in continuous mode.
int	setMode(int mode) Set the sensor into the specified mode.

Methods inherited from class lejos.nxt.I2CSensor

fetchString, getAddress, getData, getPort, getProductID, getVendorID, getVersion, sendData, sendData, setAddress

Methods inherited from class java.lang.Object

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

Field Detail

MODE_OFF

public static final byte MODE_OFF

See Also:

Constant Field Values

MODE_PING

public static final byte MODE_PING

See Also:

Constant Field Values

MODE_CONTINUOUS

public static final byte MODE_CONTINUOUS

See Also:

Constant Field Values

MODE_CAPTURE

public static final byte MODE_CAPTURE

See Also:

Constant Field Values

MODE_RESET

public static final byte MODE_RESET

See Also:

Constant Field Values

Constructor Detail

UltrasonicSensor

public UltrasonicSensor(I2CPort port)

Method Detail

getData

public int getData(int register,
                   byte[] buf,
                   int off,
                   int len)

Description copied from class: I2CSensor

Executes an I2C read transaction and waits for the result.

Overrides:

getData in class I2CSensor

Parameters:

register - I2C register, e.g 0x41

buf - Buffer to return data

off - Offset of the start of the data

len - Length of the return data

Returns:

negative value on error, 0 otherwise

sendData

public int sendData(int register,
                    byte[] buf,
                    int off,
                    int len)

Description copied from class: I2CSensor

Executes an I2C write transaction.

Overrides:

sendData in class I2CSensor

Parameters:

register - I2C register, e.g 0x42

buf - Buffer containing data to send

off - Offset of the start of the data

len - Length of data to send

Returns:

negative value on error, 0 otherwise

getDistance

public int getDistance()

Return distance to an object. To ensure that the data returned is valid this method may have to wait a short while for the distance data to become available.

Returns:

distance or 255 if no object in range or an error occurred

getRange

public float getRange()

Get the range to the nearest object

Specified by:

getRange in interface RangeFinder

Returns:

the distance to the nearest object

getDistances

public int getDistances(int[] dist)

Return an array of distances. If in continuous mode, at most one distance is returned. If in ping mode, up to 8 distances are returned. If the distance data is not yet available the method will wait until it is. Same as getDistances(dist, 0, dist.length).

Parameters:

dist - the destination array

Returns:

negative value on error, the number of values returned otherwise

getDistances

public int getDistances(int[] dist,
                        int off,
                        int len)

Return an array of distances. If in continuous mode, at most one distance is returned. If in ping mode, up to 8 distances are returned, but not more than len. If the distance data is not yet available the method will wait until it is. The LEGO ultrasonic sensor can return multiple readings in approx. 75 ms.

Parameters:

dist - the destination array

off - the index of the first distance

len - the number of distances to read

Returns:

negative value on error, the number of distances returned otherwise

setMode

public int setMode(int mode)

Set the sensor into the specified mode. A value of MODE_RESET will reset the sensor. After a reset, the sensor will be off. A value of MODE_PING sends a single ping.

Parameters:

mode - the mode, either MODE_OFF, MODE_RESET, MODE_CONTINUOUS, MODE_PING, or MODE_CAPTURE

Returns:

a negative value on error, 0 otherwise

See Also:

ping(), continuous(), capture(), reset(), off()

ping

public int ping()

Send a single ping. Up to 8 echoes are captured. These may be read by making a call to getDistances(int[]) or getDistances(int[], int, int) and passing a suitable array. A delay is required between the call to ping() and obtaining the results. The getDistances methods automatically takes care of this. getDistance() may also be used with ping, returning information for the first echo.

Returns:

negative value on error, 0 otherwise

continuous

public int continuous()

Switch to continuous mode. The device will periodically test, whether an object is in range. The current distance of the object can be obtained using getDistance(). Calling getDistances(int[]) and getDistances(int[], int, int) is also supported, but at most 1 distance is returned.

Returns:

negative value on error, 0 otherwise

See Also:

ping()

off

public int off()

Turn off the sensor. This call disables the sensor. No pings will be issued after this call, until either ping, continuous or reset is called.

Returns:

negative value on error, 0 otherwise

capture

public int capture()

Set capture mode Set the sensor into capture mode. The Lego documentation states: "Within this mode the sensor will measure whether any other ultrasonic sensors are within the vicinity. With this information a program can evaluate when it is best to make a new measurement which will not conflict with other ultrasonic sensors." I have no way of testing this. Perhaps someone with a second NXT could check it out!

Returns:

negative value on error, 0 otherwise

reset

public int reset()

Reset the device. Performs a "soft reset" of the device. Restores things to the default state. Following this call the sensor will be off.

Returns:

negative value on error, 0 otherwise

getFactoryData

public int getFactoryData(byte[] data)

Return 10 bytes of factory calibration data. The bytes are as follows data[0] : Factory zero (cal1) data[1] : Factory scale factor (cal2) data[2] : Factory scale divisor.

Returns:

negative value on error, 0 otherwise

getUnits

public String getUnits()

Return a string indicating the type of units in use by the unit. The default response is 10E-2m indicating centimeters in use.

Returns:

"" on error, the units string otherwise

getCalibrationData

public int getCalibrationData(byte[] data)

Return 3 bytes of calibration data. The bytes are as follows data[0] : zero (cal1) data[1] : scale factor (cal2) data[2] : scale divisor.

Returns:

negative value on error, 0 otherwise

setCalibrationData

public int setCalibrationData(byte[] data)

Set 3 bytes of calibration data. The bytes are as follows data[0] : zero (cal1) data[1] : scale factor (cal2) data[2] : scale divisor. This does not currently seem to work.

Returns:

0 if ok <> 0 otherwise

getContinuousInterval

public int getContinuousInterval()

Return the interval used in continuous mode. This seems to be in the range 1-15. It can be read and set. However tests seem to show it has no effect. Others have reported that this does vary the ping interval (when used in other implementations). Please report any new results.

Returns:

negative value on error, the interval otherwise

setContinuousInterval

public int setContinuousInterval(int interval)

Set the ping inetrval used when in continuous mode. See getContinuousInterval for more details.

Returns:

negative value on error, 0 otherwise.

getMode

public int getMode()

Returns the current operating mode of the sensor.

Returns:

the operating mode

See Also:

MODE_OFF, MODE_CONTINUOUS, MODE_PING, MODE_CAPTURE

getActualMode

public int getActualMode()

Returns the current operating mode of the sensor. In contrast to getMode(), this method determines the operation mode by actually querying the hardware.

Returns:

negative value on error, the operating mode otherwise

See Also:

MODE_OFF, MODE_CONTINUOUS, MODE_PING, MODE_CAPTURE

getRanges

public float[] getRanges()

Description copied from interface: RangeFinder

If the sensor is capable, this method returns multiple range values from a single scan. Sensors that can only return a single value should return an array containing a single value.

Specified by:

getRanges in interface RangeFinder

Returns:

an array of ranges, ordered from closest to farthest.