lejos.nxt
Class NXTRegulatedMotor

java.lang.Object
  extended by lejos.nxt.NXTRegulatedMotor
All Implemented Interfaces:
BaseMotor, Encoder, RegulatedMotor, Tachometer

public class NXTRegulatedMotor
extends Object
implements RegulatedMotor

Abstraction for a NXT motor. The basic control methods are: forward, backward, reverseDirection, stop and flt. To set each motor's velocity, use setSpeed . The maximum velocity of the motor is limited by the battery voltage and load. With no load, the maximum degrees per second is about 100 times the voltage.
The velocity is regulated by comparing the tacho count with velocity times elapsed time, and adjusting motor power to keep these closely matched. Changes in velocity will be made at the rate specified via the setAcceleration(int acceleration) method. The methods rotate(int angle) and rotateTo(int ange) use the tachometer to control the position at which the motor stops, usually within 1 degree or 2.

Listeners. An object implementing the RegulatedMotorListener interface may register with this class. It will be informed each time the motor starts or stops.
Stall detection If a stall is detected or if for some other reason the speed regulation fails, the motor will stop, and isStalled() returns true.
Motors will hold thier position when stopped. If this is not what you require use the flt() method instead of stop().

Example:

   Motor.A.setSpeed(720);// 2 RPM
   Motor.C.setSpeed(720);
   Motor.A.forward();
   Motor.C.forward();
   Delay.msDelay(1000);
   Motor.A.stop();
   Motor.C.stop();
   Motor.A.rotateTo( 360);
   Motor.A.rotate(-720,true);
   while(Motor.A.isMoving()Thread.yield();
   int angle = Motor.A.getTachoCount(); // should be -360
   LCD.drawInt(angle,0,0);
 

Author:
Roger Glassey/Andy Shaw

Nested Class Summary
protected static class NXTRegulatedMotor.Controller
          This class provides a single thread that drives all of the motor regulation process.
protected  class NXTRegulatedMotor.Regulator
          Inner class to regulate velocity; also stop motor at desired rotation angle.
 
Field Summary
protected  int acceleration
           
protected static NXTRegulatedMotor.Controller cont
           
protected  int limitAngle
           
protected  RegulatedMotorListener listener
           
protected static int NO_LIMIT
           
protected  NXTRegulatedMotor.Regulator reg
           
protected  float speed
           
protected  boolean stalled
           
protected  int stallLimit
           
protected  int stallTime
           
protected  TachoMotorPort tachoPort
           
 
Constructor Summary
NXTRegulatedMotor(TachoMotorPort port)
          Use this constructor to assign a variable of type motor connected to a particular port.
 
Method Summary
 void addListener(RegulatedMotorListener listener)
          Add a motor listener.
 void backward()
          Causes motor to rotate backwards until stop() or flt() is called.
 void flt()
          Set the motor into float mode.
 void flt(boolean immediateReturn)
          Set the motor into float mode.
 void forward()
          Causes motor to rotate forward until stop() or flt() is called.
 int getAcceleration()
          returns acceleration in degrees/second/second
 int getLimitAngle()
          Return the angle that this Motor is rotating to.
 float getMaxSpeed()
          Returns the maximim speed of the motor.
 int getPosition()
          Returns the current position that the motor regulator is trying to maintain.
 int getRotationSpeed()
          Return the current velocity.
 int getSpeed()
          Return the current target speed.
 int getTachoCount()
          Returns the tachometer count.
 boolean isMoving()
          This method returns true if the motor is attempting to rotate.
 boolean isStalled()
          Return true if the motor is currently stalled.
 void lock(int power)
          Deprecated. The regulator will always try to hold position unless the motor is set into float mode using flt().
 RegulatedMotorListener removeListener()
          Removes the RegulatedMotorListener from this class.
 void resetTachoCount()
          Reset the tachometer associated with this motor.
 void rotate(int angle)
          Rotate by the requested number of degrees.
 void rotate(int angle, boolean immediateReturn)
          Rotate by the request number of degrees.
 void rotateTo(int limitAngle)
          Rotate to the target angle.
 void rotateTo(int limitAngle, boolean immediateReturn)
          causes motor to rotate to limitAngle;
if immediateReturn is true, method returns immediately and the motor stops by itself
and getTachoCount should be within +- 2 degrees if the limit angle If any motor method is called before the limit is reached, the rotation is canceled.
 void setAcceleration(int acceleration)
          sets the acceleration rate of this motor in degrees/sec/sec
The default value is 6000; Smaller values will make speeding up.
 void setSpeed(float speed)
          Sets desired motor speed , in degrees per second; The maximum reliably sustainable velocity is 100 x battery voltage under moderate load, such as a direct drive robot on the level.
 void setSpeed(int speed)
          Sets desired motor speed , in degrees per second; The maximum reliably sustainable velocity is 100 x battery voltage under moderate load, such as a direct drive robot on the level.
 void setStallThreshold(int error, int time)
          Set the parameters for detecting a stalled motor.
 void stop()
          Causes motor to stop, pretty much instantaneously.
 void stop(boolean immediateReturn)
          Causes motor to stop, pretty much instantaneously.
 boolean suspendRegulation()
          Removes this motor from the motor regulation system.
 void waitComplete()
          Wait until the current movement operation is complete (this can include the motor stalling).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NO_LIMIT

protected static final int NO_LIMIT
See Also:
Constant Field Values

reg

protected final NXTRegulatedMotor.Regulator reg

tachoPort

protected TachoMotorPort tachoPort

stalled

protected boolean stalled

listener

protected RegulatedMotorListener listener

speed

protected float speed

acceleration

protected int acceleration

limitAngle

protected int limitAngle

stallLimit

protected int stallLimit

stallTime

protected int stallTime

cont

protected static final NXTRegulatedMotor.Controller cont
Constructor Detail

NXTRegulatedMotor

public NXTRegulatedMotor(TachoMotorPort port)
Use this constructor to assign a variable of type motor connected to a particular port.

Parameters:
port - to which this motor is connected
Method Detail

suspendRegulation

public boolean suspendRegulation()
Removes this motor from the motor regulation system. After this call the motor will be in float mode and will have stopped. Note calling any of the high level move operations (forward, rotate etc.), will automatically enable regulation.

Returns:
true iff regulation has been suspended.

getTachoCount

public int getTachoCount()
Description copied from interface: Encoder
Returns the tachometer count.

Specified by:
getTachoCount in interface Encoder
Returns:
the current tachometer count.
See Also:
Encoder.getTachoCount()

getPosition

public int getPosition()
Returns the current position that the motor regulator is trying to maintain. Normally this will be the actual position of the motor and will be the same as the value returned by getTachoCount(). However in some circumstances (activeMotors that are in the process of stalling, or activeMotors that have been forced out of position), the two values may differ. Note this value is not valid if regulation has been terminated.

Returns:
the current position calculated by the regulator.

forward

public void forward()
Description copied from interface: BaseMotor
Causes motor to rotate forward until stop() or flt() is called.

Specified by:
forward in interface BaseMotor
See Also:
BasicMotor.forward()

backward

public void backward()
Description copied from interface: BaseMotor
Causes motor to rotate backwards until stop() or flt() is called.

Specified by:
backward in interface BaseMotor
See Also:
BasicMotor.backward()

flt

public void flt()
Set the motor into float mode. This will stop the motor without braking and the position of the motor will not be maintained.

Specified by:
flt in interface BaseMotor

flt

public void flt(boolean immediateReturn)
Set the motor into float mode. This will stop the motor without braking and the position of the motor will not be maintained.

Specified by:
flt in interface RegulatedMotor
Parameters:
immediateReturn - If true do not wait for the motor to actually stop

stop

public void stop()
Causes motor to stop, pretty much instantaneously. In other words, the motor doesn't just stop; it will resist any further motion. Cancels any rotate() orders in progress

Specified by:
stop in interface BaseMotor

stop

public void stop(boolean immediateReturn)
Causes motor to stop, pretty much instantaneously. In other words, the motor doesn't just stop; it will resist any further motion. Cancels any rotate() orders in progress

Specified by:
stop in interface RegulatedMotor
Parameters:
immediateReturn - if true do not wait for the motor to actually stop

isMoving

public boolean isMoving()
This method returns true if the motor is attempting to rotate. The return value may not correspond to the actual motor movement.
For example, If the motor is stalled, isMoving() will return true.
After flt() is called, this method will return false even though the motor axle may continue to rotate by inertia. If the motor is stalled, isMoving() will return true. . A stall can be detected by calling isStalled();

Specified by:
isMoving in interface BaseMotor
Returns:
true iff the motor is attempting to rotate.

waitComplete

public void waitComplete()
Wait until the current movement operation is complete (this can include the motor stalling).

Specified by:
waitComplete in interface RegulatedMotor

rotateTo

public void rotateTo(int limitAngle,
                     boolean immediateReturn)
Description copied from interface: RegulatedMotor
causes motor to rotate to limitAngle;
if immediateReturn is true, method returns immediately and the motor stops by itself
and getTachoCount should be within +- 2 degrees if the limit angle If any motor method is called before the limit is reached, the rotation is canceled. When the angle is reached, the method isMoving() returns false;

Specified by:
rotateTo in interface RegulatedMotor
Parameters:
limitAngle - to which the motor will rotate, and then stop (in degrees). Includes any positive or negative int, even values > 360.
immediateReturn - iff true, method returns immediately, thus allowing monitoring of sensors in the calling thread.

setSpeed

public void setSpeed(int speed)
Sets desired motor speed , in degrees per second; The maximum reliably sustainable velocity is 100 x battery voltage under moderate load, such as a direct drive robot on the level.

Specified by:
setSpeed in interface RegulatedMotor
Parameters:
speed - value in degrees/sec

setSpeed

public void setSpeed(float speed)
Sets desired motor speed , in degrees per second; The maximum reliably sustainable velocity is 100 x battery voltage under moderate load, such as a direct drive robot on the level.

Parameters:
speed - value in degrees/sec

setAcceleration

public void setAcceleration(int acceleration)
sets the acceleration rate of this motor in degrees/sec/sec
The default value is 6000; Smaller values will make speeding up. or stopping at the end of a rotate() task, smoother;

Specified by:
setAcceleration in interface RegulatedMotor
Parameters:
acceleration -

getAcceleration

public int getAcceleration()
returns acceleration in degrees/second/second

Returns:
the value of acceleration

getLimitAngle

public int getLimitAngle()
Return the angle that this Motor is rotating to.

Specified by:
getLimitAngle in interface RegulatedMotor
Returns:
angle in degrees

resetTachoCount

public void resetTachoCount()
Reset the tachometer associated with this motor. Note calling this method will cause any current move operation to be halted.

Specified by:
resetTachoCount in interface Encoder

addListener

public void addListener(RegulatedMotorListener listener)
Add a motor listener. Move operations will be reported to this object.

Specified by:
addListener in interface RegulatedMotor
Parameters:
listener -

removeListener

public RegulatedMotorListener removeListener()
Description copied from interface: RegulatedMotor
Removes the RegulatedMotorListener from this class.

Specified by:
removeListener in interface RegulatedMotor
Returns:
The RegulatedMotorListener that was removed, if any. Null if none existed.

rotate

public void rotate(int angle,
                   boolean immediateReturn)
Rotate by the request number of degrees.

Specified by:
rotate in interface RegulatedMotor
Parameters:
angle - number of degrees to rotate relative to the current position
immediateReturn - if true do not wait for the move to complete
See Also:
RegulatedMotor.rotate(int, boolean)

rotate

public void rotate(int angle)
Rotate by the requested number of degrees. Wait for the move to complete.

Specified by:
rotate in interface RegulatedMotor
Parameters:
angle -

rotateTo

public void rotateTo(int limitAngle)
Rotate to the target angle. Do not return until the move is complete.

Specified by:
rotateTo in interface RegulatedMotor
Parameters:
limitAngle - Angle to rotate to.

getSpeed

public int getSpeed()
Return the current target speed.

Specified by:
getSpeed in interface RegulatedMotor
Returns:
the current target speed.

lock

@Deprecated
public void lock(int power)
Deprecated. The regulator will always try to hold position unless the motor is set into float mode using flt().

Parameters:
power - - a value between 1 and 100;

isStalled

public boolean isStalled()
Return true if the motor is currently stalled.

Specified by:
isStalled in interface RegulatedMotor
Returns:
true if the motor is stalled, else false

setStallThreshold

public void setStallThreshold(int error,
                              int time)
Set the parameters for detecting a stalled motor. A motor will be recognised as stalled if the movement error (the amount the motor lags the regulated position) is greater than error for a period longer than time.

Specified by:
setStallThreshold in interface RegulatedMotor
Parameters:
error - The error threshold
time - The time that the error threshold needs to be exceeded for.

getRotationSpeed

public int getRotationSpeed()
Return the current velocity.

Specified by:
getRotationSpeed in interface Tachometer
Returns:
current velocity in degrees/s

getMaxSpeed

public float getMaxSpeed()
Description copied from interface: RegulatedMotor
Returns the maximim speed of the motor.

Specified by:
getMaxSpeed in interface RegulatedMotor
Returns:
the maximum speed of the Motor in degrees per second.