lejos.robotics.navigation
Interface Pilot

All Known Implementing Classes:
CompassPilot, TachoPilot

public interface Pilot

The Pilot interface forms a common set of functions an implementation must offer in order to be used by higher level navigation classes. The Pilot hides the details of the robots physical construction and the required control algorithms from the rest of this package.


Method Summary
 void arc(float radius)
          Starts the NXT robot moving along an arc with a specified radius.
 void arc(float radius, float angle)
          Moves the NXT robot along an arc with a specified radius and angle, after which the robot stops moving.
 void arc(float radius, float angle, boolean immediateReturn)
          Moves the NXT robot along an arc with a specified radius and angle, after which the robot stops moving.
 void backward()
          Starts the NXT robot moving backward .
 void forward()
          Starts the NXT robot moving forward.
 float getAngle()
          angle of rotation of the robot since last call to reset.
 float getMoveMaxSpeed()
           
 float getMoveSpeed()
           
 float getTravelDistance()
          distance traveled since the last call to reset.
 float getTurnMaxSpeed()
           
 float getTurnSpeed()
           
 boolean isMoving()
          true if the robot is moving
 void reset()
          Reset traveled distance and rotated angle.
 void rotate(float angle)
          Rotates the NXT robot the specified number of degrees; direction determined by the sign of the parameter.
 void rotate(float angle, boolean immediateReturn)
          Rotates the NXT robot the specifed number of degress; direction determined by the sign of the parameter.
 void setMoveSpeed(float speed)
          Sets the movement speed of the robot.
 void setSpeed(int speed)
          Deprecated. in 0.8, use setTurnSpeed() and setMoveSpeed(). The method was deprecated, as this it requires knowledge of the robots physical construction, which this interface should hide!
 void setTurnSpeed(float speed)
          Sets the turning speed of the robot.
 void steer(float turnRate)
          Starts the robot moving along a curved path.
 void steer(float turnRate, float angle)
          Moves the robot along a curved path through a specified turn angle.
 void steer(float turnRate, float angle, boolean immediateReturn)
          Moves the robot along a curved path for a specified angle of rotation.
 void stop()
          Halts the NXT robot
 void travel(float distance)
          Moves the NXT robot a specific distance.
 void travel(float distance, boolean immediateReturn)
          Moves the NXT robot a specific distance.
 void travelArc(float radius, float distance)
          Moves the NXT robot a specified distance along an arc mof specified radius, after which the robot stops moving.
 void travelArc(float radius, float distance, boolean immediateReturn)
          Moves the NXT robot a specified distance along an arc of specified radius, after which the robot stops moving.
 

Method Detail

forward

void forward()
Starts the NXT robot moving forward.


backward

void backward()
Starts the NXT robot moving backward .


stop

void stop()
Halts the NXT robot


isMoving

boolean isMoving()
true if the robot is moving

Returns:
true if the robot is moving under power.

setMoveSpeed

void setMoveSpeed(float speed)
Sets the movement speed of the robot.

Parameters:
speed - The speed in wheel diameter units per second.

getMoveSpeed

float getMoveSpeed()
Returns:
the movement speed of the robot in wheel diameter units per second.

getMoveMaxSpeed

float getMoveMaxSpeed()
Returns:
the maximal movement speed of the robot in wheel diameter units per second which can be maintained accurately. Will change with time, as it is normally dependent on the battery voltage.

setTurnSpeed

void setTurnSpeed(float speed)
Sets the turning speed of the robot.

Parameters:
speed - The speed in degree per second.

getTurnSpeed

float getTurnSpeed()
Returns:
the turning speed of the robot in degree per second.

getTurnMaxSpeed

float getTurnMaxSpeed()
Returns:
the maximal turning speed of the robot in degree per second which can be maintained accurately. Will change with time, as it is normally dependent on the battery voltage.

setSpeed

@Deprecated
void setSpeed(int speed)
Deprecated. in 0.8, use setTurnSpeed() and setMoveSpeed(). The method was deprecated, as this it requires knowledge of the robots physical construction, which this interface should hide!

Sets drive motor speed.

Parameters:
speed - The speed of the drive motor(s) in degree per second.

travel

void travel(float distance)
Moves the NXT robot a specific distance. A positive value moves it forward and a negative value moves it backward. Method returns when movement is done.

Parameters:
distance - The positive or negative distance to move the robot.

travel

void travel(float distance,
            boolean immediateReturn)
Moves the NXT robot a specific distance. A positive value moves it forward and a negative value moves it backward.

Parameters:
distance - The positive or negative distance to move the robot, in wheel diameter units.
immediateReturn - If immediateReturn is true then the method returns immediately.

rotate

void rotate(float angle)
Rotates the NXT robot the specified number of degrees; direction determined by the sign of the parameter. Method returns when rotation is done.

Parameters:
angle - The angle to rotate in degrees. A positive value rotates left, a negative value right (clockwise).

rotate

void rotate(float angle,
            boolean immediateReturn)
Rotates the NXT robot the specifed number of degress; direction determined by the sign of the parameter. Motion stops when rotation is done.

Parameters:
angle - The angle to rotate in degrees. A positive value rotates left, a negative value right (clockwise).
immediateReturn - If immediateReturn is true then the method returns immediately

getAngle

float getAngle()
angle of rotation of the robot since last call to reset.

Returns:
the angle of rotation of the robot since last call to reset.

getTravelDistance

float getTravelDistance()
distance traveled since the last call to reset.

Returns:
the distance traveled since last call to reset

steer

void steer(float turnRate)
Starts the robot moving along a curved path. This method is similar to the arc(float radius) method except it uses a ratio of motor speeds to determine the curvature of the path and therefore has the ability to drive straight. This makes it usrful for line following applications.

The turnRate specifies the sharpness of the turn, between -200 and +200.
The turnRate is used to calculate the ratio of inner wheel speed to outer wheel speed as a percent.
Formula: ratio = 100 - abs(turnRate).
When the ratio is negative, the outer and inner wheels rotate in opposite directions.

If turnRate is positive, the center of the turning circle is on the left side of the robot.
If turnRate is negative, the center of the turning circle is on the right side of the robot.
If turnRate is zero, the robot travels in a straight line

Examples of how the formula works:

Note: If you have specified a drift correction in the constructor it will not be applied in this method.

Parameters:
turnRate - If positive, the left side of the robot is on the inside of the turn. If negative, the left side is on the outside.

steer

void steer(float turnRate,
           float angle)
Moves the robot along a curved path through a specified turn angle. This method is similar to the arc(float radius , float angle) method except it uses a ratio of motor speeds to determine the curvature of the path and therefore has the ability to drive straight. This makes it useful for line following applications. This method does not return until the robot has completed moving angle degrees along the arc.
The turnRate specifies the sharpness of the turn, between -200 and +200.
For details about how this paramet works.See steer(float turnRate)

The robot will stop when the degrees it has moved along the arc equals angle.
If angle is positive, the robot will move travel forwards.
If angle is negative, the robot will move travel backwards. If angle is zero, the robot will not move and the method returns immediately.

Note: If you have specified a drift correction in the constructor it will not be applied in this method.

Parameters:
turnRate - If positive, the left side of the robot is on the inside of the turn. If negative, the left side is on the outside.
angle - The angle through which the robot will rotate. If negative, robot traces the turning circle backwards.

steer

void steer(float turnRate,
           float angle,
           boolean immediateReturn)
Moves the robot along a curved path for a specified angle of rotation. This method is similar to the arc(float radius, float angle, boolean immediateReturn) method except it uses a ratio of motor speeds to speeds to determine the curvature of the path and therefore has the ability to drive straight. This makes it useful for line following applications. This method has the ability to return immediately by using the immediateReturn parameter set to true.

The turnRate specifies the sharpness of the turn, between -200 and +200.
For details about how this paramet works, see steer(float turnRate)

The robot will stop when the degrees it has moved along the arc equals angle.
If angle is positive, the robot will move travel forwards.
If angle is negative, the robot will move travel backwards. If angle is zero, the robot will not move and the method returns immediately.

Note: If you have specified a drift correction in the constructor it will not be applied in this method.

Parameters:
turnRate - If positive, the left side of the robot is on the inside of the turn. If negative, the left side is on the outside.
angle - The angle through which the robot will rotate. If negative, robot traces the turning circle backwards.
immediateReturn - If immediateReturn is true then the method returns immediately and your code MUST call updatePostion() when the robot has stopped. Otherwise, the robot position is lost.

arc

void arc(float radius)
Starts the NXT robot moving along an arc with a specified radius.

If radius is positive, the robot arcs left, and the center of the turning circle is on the left side of the robot.
If radius is negative, the robot arcs right, and the center of the turning circle is on the right side of the robot.
If radius is zero, the robot rotates in place.

The arc(float) method can not drive a straight line, which makes it impractical for line following. A better solution for line following is steer(float), which uses proportional steering and can drive straight lines and arcs.

Postcondition: Motor speeds are unpredictable.

Note: If you have specified a drift correction in the constructor it will not be applied in this method.

Parameters:
radius - of the arc path. If positive, the left side of the robot is on the inside of the turn. If negative, the left side of the robot is on the outside of the turn.
See Also:
steer(float)

arc

void arc(float radius,
         float angle)
Moves the NXT robot along an arc with a specified radius and angle, after which the robot stops moving. This method does not return until the robot has completed moving angle degrees along the arc.

If radius is positive, the robot arcs left, and the center of the turning circle is on the left side of the robot.
If radius is negative, the robot arcs right, and the center of the turning circle is on the right side of the robot.
If radius is zero, is zero, the robot rotates in place.

The arc(float) method can not drive a straight line, which makes it impractical for line following. A better solution for line following is steer(float), which uses proportional steering and can drive straight lines and arcs.

Robot will stop when the degrees it has moved along the arc equals angle.
If angle is positive, the robot will move travel forwards.
If angle is negative, the robot will move travel backwards. If angle is zero, the robot will not move and the method returns immediately.

Postcondition: Motor speeds are unpredictable.

Note: If you have specified a drift correction in the constructor it will not be applied in this method.

Parameters:
radius - of the arc path. If positive, the left side of the robot is on the inside of the turn. If negative, the left side of the robot is on the outside of the turn.
angle - The sign of the angle determines the direction of robot motion. Positive drives the robot forward, negative drives it backward.
See Also:
steer(float, float), travelArc(float, float)

arc

void arc(float radius,
         float angle,
         boolean immediateReturn)
Moves the NXT robot along an arc with a specified radius and angle, after which the robot stops moving. This method has the ability to return immediately by using the immediateReturn parameter.

If radius is positive, the robot arcs left, and the center of the turning circle is on the left side of the robot.
If radius is negative, the robot arcs right, and the center of the turning circle is on the right side of the robot.
If radius is zero, is zero, the robot rotates in place.

The arc(float, float, boolean) method can not drive a straight line, which makes it impractical for line following. A better solution for line following is steer(float, float, boolean), which uses proportional steering and can drive straight lines and arcs.

The robot will stop when the degrees it has moved along the arc equals angle.
If angle is positive, the robot will move travel forwards.
If angle is negative, the robot will move travel backwards. If angle is zero, the robot will not move and the method returns immediately.

Postcondition: Motor speeds are unpredictable.

Note: If you have specified a drift correction in the constructor it will not be applied in this method.

Parameters:
radius - of the arc path. If positive, the left side of the robot is on the inside of the turn. If negative, the left side of the robot is on the outside of the turn.
angle - The sign of the angle determines the direction of robot motion. Positive drives the robot forward, negative drives it backward.
immediateReturn - If immediateReturn is true then the method returns immediately and your code MUST call updatePostion() when the robot has stopped. Otherwise, the robot position is lost.
See Also:
steer(float, float, boolean), travelArc(float, float, boolean)

travelArc

void travelArc(float radius,
               float distance)
Moves the NXT robot a specified distance along an arc mof specified radius, after which the robot stops moving. This method does not return until the robot has completed moving distance along the arc. The units (inches, cm) for distance must be the same as the units used for radius.

If radius is positive, the robot arcs left, and the center of the turning circle is on the left side of the robot.
If radius is negative, the robot arcs right, and the center of the turning circle is on the right side of the robot.
If radius is zero, the robot rotates in place

The travelArc(float, float) method can not drive a straight line, which makes it impractical for line following. A better solution for line following is steer(float), which uses proportional steering and can drive straight lines and arcs.

The robot will stop when it has moved along the arc distance units.
If distance is positive, the robot will move travel forwards.
If distance is negative, the robot will move travel backwards. If distance is zero, the robot will not move and the method returns immediately.

Postcondition: Motor speeds are unpredictable.

Note: If you have specified a drift correction in the constructor it will not be applied in this method.

Parameters:
radius - of the arc path. If positive, the left side of the robot is on the inside of the turn. If negative, the left side of the robot is on the outside of the turn.
distance - to travel, in same units as radius. The sign of the distance determines the direction of robot motion. Positive drives the robot forward, negative drives it backward.
See Also:
steer(float, float), arc(float, float)

travelArc

void travelArc(float radius,
               float distance,
               boolean immediateReturn)
Moves the NXT robot a specified distance along an arc of specified radius, after which the robot stops moving. This method has the ability to return immediately by using the immediateReturn parameter. The units (inches, cm) for distance should be the same as the units used for radius. Warning: Your code must call updatePostion() when the robot has stopped, otherwise, the robot position is lost.

If radius is positive, the robot arcs left, and the center of the turning circle is on the left side of the robot.
If radius is negative, the robot arcs right, and the center of the turning circle is on the right side of the robot.
If radius is zero, ...

The travelArc(float, float, boolean) method can not drive a straight line, which makes it impractical for line following. A better solution for line following is steer(float, float, boolean), which uses proportional steering and can drive straight lines and arcs.

The robot will stop when it has moved along the arc distance units.
If distance is positive, the robot will move travel forwards.
If distance is negative, the robot will move travel backwards. If distance is zero, the robot will not move and the method returns immediately.

Postcondition: Motor speeds are unpredictable.

Note: If you have specified a drift correction in the constructor it will not be applied in this method.

Parameters:
radius - of the arc path. If positive, the left side of the robot is on the inside of the turn. If negative, the left side of the robot is on the outside of the turn.
distance - to travel, in same units as radius. The sign of the distance determines the direction of robot motion. Positive drives the robot forward, negative drives it backward.
immediateReturn - If immediateReturn is true then the method returns immediately and your code MUST call updatePostion() when the robot has stopped. Otherwise, the robot position is lost.
See Also:
steer(float, float, boolean), arc(float, float, boolean)

reset

void reset()
Reset traveled distance and rotated angle.