SteeringPilot (leJOS EV3 API documentation)

java.lang.Object
- lejos.robotics.navigation.SteeringPilot

All Implemented Interfaces:

ArcMoveController, MoveController, MoveProvider, RegulatedMotorListener
```
public class SteeringPilot
extends java.lang.Object
implements ArcMoveController, RegulatedMotorListener
```
Vehicles that are controlled by the SteeringPilot class use a similar steering mechanism to a car, in which the front wheels pivot from side to side to control direction.

If you issue a command for travel(1000) and then issue a command travel(-500) before it completes the travel(1000) movement, it will call stop, properly inform movement listeners that the forward movement was halted, and then start moving backward 500 units. This makes movements from the SteeringPilot leak-proof and incorruptible.

Note: A DifferentialPilot robot can simulate a SteeringPilot robot by calling DifferentialPilot.setMinRadius(double) and setting the value to something greater than zero (example: 15 cm).

Author:

BB

See Also:

DifferentialPilot.setMinRadius(double)

Field Summary
- Fields inherited from interface lejos.robotics.navigation.MoveController
  WHEEL_SIZE_EV3, WHEEL_SIZE_NXT1, WHEEL_SIZE_NXT2, WHEEL_SIZE_RCX

Constructor Summary

Constructors
Constructor and Description
`SteeringPilot(double driveWheelDiameter, RegulatedMotor driveMotor, RegulatedMotor steeringMotor, double minTurnRadius, int leftTurnTacho, int rightTurnTacho)` Creates an instance of the SteeringPilot.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addMoveListener(MoveListener listener)` Adds a MoveListener that will be notified of all movement events.
`void`	`arc(double turnRadius, double arcAngle)` Moves the NXT robot along an arc with a specified radius and angle, after which the robot stops moving.
`void`	`arc(double turnRadius, double arcAngle, boolean immediateReturn)` Moves the NXT robot along an arc with a specified radius and angle, after which the robot stops moving.
`void`	`arcBackward(double turnRadius)` Starts the NXT robot moving backward along an arc with a specified radius.
`void`	`arcForward(double turnRadius)` Starts the NXT robot moving forward along an arc with a specified radius.
`void`	`backward()` Starts the NXT robot moving backwards.
`void`	`calibrateSteering()` This method calibrates the steering mechanism by turning the wheels all the way to the right and left until they encounter resistance and recording the tachometer values.
`void`	`forward()` Starts the NXT robot moving forward.
`double`	`getLinearAcceleration()` Returns the acceleration at which the robot accelerates at the start of a move and decelerates at the end of a move.
`double`	`getLinearSpeed()` Returns the speed at which the robot will travel forward and backward (and to some extent arcs, although actual arc speed is slightly less).
`double`	`getMaxLinearSpeed()` Returns the maximum speed at which this robot is capable of traveling forward and backward.
`double`	`getMinRadius()` In practice, a robot might steer tighter with one turn than the other.
`Move`	`getMovement()` Returns the move made since the move started, but before it has completed.
`float`	`getMovementIncrement()`
`boolean`	`isMoving()` true if the robot is moving
`void`	`rotationStarted(RegulatedMotor motor, int tachoCount, boolean stall, long timeStamp)` Called when the motor starts rotating.
`void`	`rotationStopped(RegulatedMotor motor, int tachoCount, boolean stall, long timeStamp)` Called when the motor stops rotating.
`void`	`setLinearAcceleration(double acceleration)` Sets the acceleration at which the robot will accelerate at the start of a move and decelerate at the end of a move.
`void`	`setLinearSpeed(double speed)` Sets the speed at which the robot will travel forward and backward (and to some extent arcs, although actual arc speed is slightly less).
`void`	`setMinRadius(double minTurnRadius)` Set the radius of the minimum turning circle.
`void`	`stop()` Halts the NXT robot
`void`	`travel(double distance)` Moves the NXT robot a specific distance.
`void`	`travel(double distance, boolean immediateReturn)` Moves the NXT robot a specific distance.
`void`	`travelArc(double turnRadius, double distance)` Moves the NXT robot a specified distance along an arc of specified radius, after which the robot stops moving.
`void`	`travelArc(double turnRadius, double distance, boolean immediateReturn)` Moves the NXT robot a specified distance along an arc of specified radius, after which the robot stops moving.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - SteeringPilot
```
public SteeringPilot(double driveWheelDiameter,
                     RegulatedMotor driveMotor,
                     RegulatedMotor steeringMotor,
                     double minTurnRadius,
                     int leftTurnTacho,
                     int rightTurnTacho)
```
    Creates an instance of the SteeringPilot. The drive wheel measurements are written on the side of the LEGO tire, such as 56 x 26 (= 56 mm or 5.6 centimeters).
    The accuracy of this class is dependent on physical factors:
  - the surface the vehicle is driving on (hard smooth surfaces are much better than carpet)
  - the accuracy of the steering vehicle (backlash in the steering mechanism will cause turn-angle accuracy problems)
  - the ability of the steering robot to drive straight (if you see your robot trying to drive straight and it is driving a curve instead, accuracy will be thrown off significantly)
  - When using SteeringPilot with ArcPoseController, the starting position of the robot is also important. Is it truly lined up with the x axis? Are your destination targets on the floor accurately measured?
    Note: If your drive motor is geared for faster movement, you must multiply the wheel size by the gear ratio. e.g. If gear ratio is 3:1, multiply wheel diameter by 3. If your drive motor is geared for slower movement, divide wheel size by gear ratio.
    *

Parameters:: driveWheelDiameter - The diameter of the wheel(s) used to propel the vehicle.; driveMotor - The motor used to propel the vehicle, such as Motor.B; steeringMotor - The motor used to steer the steering wheels, such as Motor.C; minTurnRadius - The smallest turning radius the vehicle can turn. e.g. 41 centimeters; leftTurnTacho - The tachometer the steering motor must turn to in order to turn left with the minimum turn radius.; rightTurnTacho - The tachometer the steering motor must turn to in order to turn right with the minimum turn radius.

Method Detail
- calibrateSteering
```
public void calibrateSteering()
```
  This method calibrates the steering mechanism by turning the wheels all the way to the right and left until they encounter resistance and recording the tachometer values. These values determine the outer bounds of steering. The center steering value is the average of the two. NOTE: This method only works with steering robots that are symmetrical (same maximum steering threshold left and right).
  TODO: Should be able to get steering parity right from this class! No need to fish for boolean.
  When you run the method, if you notice the wheels turn left first, then right, it means you need to set the reverse parameter to true for proper calibration. NOTE: The next time you run the calibrate method it will still turn left first, but...
- getMinRadius
```
public double getMinRadius()
```
  In practice, a robot might steer tighter with one turn than the other. Currently returns minimum steering radius for the least tight turn direction.
  
  Specified by:
  
  getMinRadius in interface ArcMoveController
  
  Returns:
  
  minimum turning radius, in centimeters
- arcForward
```
public void arcForward(double turnRadius)
```
  Description copied from interface: ArcMoveController
  
  Starts the NXT robot moving forward 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.
  Postcondition: Motor speeds are unpredictable.
  Note: If you have specified a drift correction in the constructor it will not be applied in this method.
  
  Specified by:
  
  arcForward in interface ArcMoveController
  
  Parameters:
  
  turnRadius - 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.
- arcBackward
```
public void arcBackward(double turnRadius)
```
  Description copied from interface: ArcMoveController
  
  Starts the NXT robot moving backward 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.
  Postcondition: Motor speeds are unpredictable.
  Note: If you have specified a drift correction in the constructor it will not be applied in this method.
  
  Specified by:
  
  arcBackward in interface ArcMoveController
  
  Parameters:
  
  turnRadius - 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.
- arc
```
public void arc(double turnRadius,
                double arcAngle)
         throws java.lang.IllegalArgumentException
```
  Description copied from interface: ArcMoveController
  
  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.
  Robot will stop when the degrees it has moved along the arc equals angle.
  If angle is positive, the robot will turn to the left (anti-clockwise).
  If angle is negative, the robot will turn to the right (clockwise). 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.
  
  Specified by:
  
  arc in interface ArcMoveController
  
  Parameters:
  
  turnRadius - 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.
  
  arcAngle - The sign of the angle determines the direction of the robot turns: Positive is anti-clockwise, negative is clockwise.
  
  Throws:
  
  java.lang.IllegalArgumentException
  
  See Also:
  
  ArcMoveController.travelArc(double, double)
- arc
```
public void arc(double turnRadius,
                double arcAngle,
                boolean immediateReturn)
```
  Description copied from interface: ArcMoveController
  
  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 robot will stop when the degrees it has moved along the arc equals angle.
  If angle is positive, the robot will turn to the left (anti-clockwise).
  If angle is negative, the robot will turn to the right (clockwise). 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.
  
  Specified by:
  
  arc in interface ArcMoveController
  
  Parameters:
  
  turnRadius - 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.
  
  arcAngle - The sign of the angle determines the direction of the robot turns: Positive is anti-clockwise, negative is clockwise.
  
  immediateReturn - If immediateReturn is true then the method returns immediately.
  
  See Also:
  
  ArcMoveController.travelArc(double, double, boolean)
- setMinRadius
```
public void setMinRadius(double minTurnRadius)
```
  Description copied from interface: ArcMoveController
  
  Set the radius of the minimum turning circle.
  
  Specified by:
  
  setMinRadius in interface ArcMoveController
  
  Parameters:
  
  minTurnRadius - the radius in degrees
- travelArc
```
public void travelArc(double turnRadius,
                      double distance)
```
  Description copied from interface: ArcMoveController
  
  Moves the NXT robot a specified distance along an arc of 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 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.
  
  Specified by:
  
  travelArc in interface ArcMoveController
  
  Parameters:
  
  turnRadius - 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:
  
  ArcMoveController.arc(double, double)
- travelArc
```
public void travelArc(double turnRadius,
                      double distance,
                      boolean immediateReturn)
               throws java.lang.IllegalArgumentException
```
  Description copied from interface: ArcMoveController
  
  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.
  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 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.
  
  Specified by:
  
  travelArc in interface ArcMoveController
  
  Parameters:
  
  turnRadius - 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.
  
  Throws:
  
  java.lang.IllegalArgumentException
  
  See Also:
  
  ArcMoveController.arc(double, double, boolean)
- backward
```
public void backward()
```
  Description copied from interface: MoveController
  
  Starts the NXT robot moving backwards.
  
  Specified by:
  
  backward in interface MoveController
- forward
```
public void forward()
```
  Description copied from interface: MoveController
  
  Starts the NXT robot moving forward.
  
  Specified by:
  
  forward in interface MoveController
- getMaxLinearSpeed
```
public double getMaxLinearSpeed()
```
  Description copied from interface: MoveController
  
  Returns the maximum speed at which this robot is capable of traveling forward and backward. Speed is measured in units/second. e.g. If wheel diameter is cm, then speed is cm/sec.
  
  Specified by:
  
  getMaxLinearSpeed in interface MoveController
  
  Returns:
  
  Speed in chosen units per second (e.g. cm/sec)
- getLinearSpeed
```
public double getLinearSpeed()
```
  Description copied from interface: MoveController
  
  Returns the speed at which the robot will travel forward and backward (and to some extent arcs, although actual arc speed is slightly less). Speed is measured in units/second. e.g. If wheel diameter is cm, then speed is cm/sec.
  
  Specified by:
  
  getLinearSpeed in interface MoveController
  
  Returns:
  
  Speed in chosen units per second (e.g. cm/sec)
- getMovementIncrement
```
public float getMovementIncrement()
```
- isMoving
```
public boolean isMoving()
```
  Description copied from interface: MoveController
  
  true if the robot is moving
  
  Specified by:
  
  isMoving in interface MoveController
  
  Returns:
  
  true if the robot is moving under power.
- setLinearSpeed
```
public void setLinearSpeed(double speed)
```
  Description copied from interface: MoveController
  
  Sets the speed at which the robot will travel forward and backward (and to some extent arcs, although actual arc speed is slightly less). Speed is measured in units/second. e.g. If wheel diameter is cm, then speed is cm/sec.
  
  Specified by:
  
  setLinearSpeed in interface MoveController
  
  Parameters:
  
  speed - In chosen units per second (e.g. cm/sec)
- stop
```
public void stop()
```
  Description copied from interface: MoveController
  
  Halts the NXT robot
  
  Specified by:
  
  stop in interface MoveController
- travel
```
public void travel(double distance)
```
  Description copied from interface: MoveController
  
  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.
  
  Specified by:
  
  travel in interface MoveController
  
  Parameters:
  
  distance - The positive or negative distance to move the robot.
- travel
```
public void travel(double distance,
                   boolean immediateReturn)
```
  Description copied from interface: MoveController
  
  Moves the NXT robot a specific distance. A positive value moves it forward and a negative value moves it backward.
  
  Specified by:
  
  travel in interface MoveController
  
  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.
- addMoveListener
```
public void addMoveListener(MoveListener listener)
```
  Description copied from interface: MoveProvider
  
  Adds a MoveListener that will be notified of all movement events.
  
  Specified by:
  
  addMoveListener in interface MoveProvider
  
  Parameters:
  
  listener - the move listener
- getMovement
```
public Move getMovement()
```
  Description copied from interface: MoveProvider
  
  Returns the move made since the move started, but before it has completed. This method is used by GUI maps to display the movement of a robot in real time. The robot must be capable of determining the move while it is in motion.
  
  Specified by:
  
  getMovement in interface MoveProvider
  
  Returns:
  
  The move made since the move started.
- rotationStarted
```
public void rotationStarted(RegulatedMotor motor,
                            int tachoCount,
                            boolean stall,
                            long timeStamp)
```
  Description copied from interface: RegulatedMotorListener
  
  Called when the motor starts rotating.
  
  Specified by:
  
  rotationStarted in interface RegulatedMotorListener
- rotationStopped
```
public void rotationStopped(RegulatedMotor motor,
                            int tachoCount,
                            boolean stall,
                            long timeStamp)
```
  Description copied from interface: RegulatedMotorListener
  
  Called when the motor stops rotating. This includes both Motor.stop() which locks the shaft, and Motor.flt() in which the shaft floats freely after power is cut to the motor. Beware: In the second case, it's possible the tachomoter reading will continue changing after notification.
  
  Specified by:
  
  rotationStopped in interface RegulatedMotorListener
- setLinearAcceleration
```
public void setLinearAcceleration(double acceleration)
```
  Description copied from interface: MoveController
  
  Sets the acceleration at which the robot will accelerate at the start of a move and decelerate at the end of a move. Acceleration is measured in units/second^2. e.g. If wheel diameter is cm, then acceleration is cm/sec^2.
  If acceleration is set during a move it will not be in used for the current move, it will be in effect with the next move.
  
  Specified by:
  
  setLinearAcceleration in interface MoveController
  
  Parameters:
  
  acceleration - in chosen units/second^2
- getLinearAcceleration
```
public double getLinearAcceleration()
```
  Description copied from interface: MoveController
  
  Returns the acceleration at which the robot accelerates at the start of a move and decelerates at the end of a move.
  
  Specified by:
  
  getLinearAcceleration in interface MoveController
  
  Returns:
  
  acceleration in chosen units/second^2

Class SteeringPilot

Field Summary

Fields inherited from interface lejos.robotics.navigation.MoveController

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

SteeringPilot

Method Detail

calibrateSteering

getMinRadius

arcForward

arcBackward

arc

arc

setMinRadius

travelArc

travelArc

backward

forward

getMaxLinearSpeed

getLinearSpeed

getMovementIncrement

isMoving

setLinearSpeed

stop

travel

travel

addMoveListener

getMovement

rotationStarted

rotationStopped

setLinearAcceleration

getLinearAcceleration