Small documentation updates

tekdemo · tekdemo · commit bafe3d60d67d · 2016-11-15T04:41:03.000-08:00
diff --git a/src/com/stormbots/Main.java b/src/com/stormbots/Main.java
@@ -1,15 +1,14 @@
 package com.stormbots;
 
-public class main {
+public class Main {
 
 	/**
-	 * @param args
+	 * @param args Any arguments passed from stdin
 	 */
 	public static void main(String[] args) {
-		// TODO Auto-generated method stub
 		MiniPID miniPID; 
 		
-		miniPID=new MiniPID( .25,0.01,.4);
+		miniPID = new MiniPID(0.25, 0.01, 0.4);
 		miniPID.setOutputLimits(10);
 		//miniPID.setMaxIOutput(2);
 		//miniPID.setOutputRampRate(3);
@@ -24,29 +23,28 @@ public static void main(String[] args) {
 		miniPID.setSetpoint(0);
 		miniPID.setSetpoint(target);
 		
-		System.err.printf("Target,Actual\tOutput\tError\n");
+		System.err.printf("Target\tActual\tOutput\tError\n");
 		//System.err.printf("Output\tP\tI\tD\n");
 
-		//* Position based test code
-		for (int i=0;i<100 ;i++){
+		// Position based test code
+		for (int i = 0; i < 100; i++){
 			
 			//if(i==50)miniPID.setI(.05);
-			if(i==60)target=(50);
+			
+			if (i == 60)
+				target = 50;
+				
 			//if(i==75)target=(100);
 			//if(i>50 && i%4==0)target=target+(Math.random()-.5)*50;
 			
-			output=miniPID.getOutput(actual,target);
-			actual=actual+output;
+			output = miniPID.getOutput(actual, target);
+			actual = actual + output;
 			
 			//System.out.println("=========================="); 
 			//System.out.printf("Current: %3.2f , Actual: %3.2f, Error: %3.2f\n",actual, output, (target-actual));
-			System.err.printf("%3.2f\t%3.2f\t%3.2f\t%3.2f\n",target,actual, output, (target-actual));
-			
+			System.err.printf("%3.2f\t%3.2f\t%3.2f\t%3.2f\n", target, actual, output, (target-actual));
 			
 			//if(i>80 && i%5==0)actual+=(Math.random()-.5)*20;
-		}
-		//*/
-		
+		}		
 	}
-
 }
diff --git a/src/com/stormbots/MiniPID.java b/src/com/stormbots/MiniPID.java
@@ -2,9 +2,9 @@
 /**
 * Small, easy to use PID implementation with advanced controller capability.<br> 
 * Minimal usage:<br>
-* setPID(p,i,d); <br>
+* MiniPID pid = new MiniPID(p,i,d); <br>
 * ...looping code...{ <br>
-* output=getOutput(sensorvalue,target); <br>
+*   output= pid.getOutput(sensorvalue,target); <br>
 * }
 * 
 * @see http://brettbeauregard.com/blog/2011/04/improving-the-beginners-pid-direction/improving-the-beginners-pid-introduction
@@ -43,10 +43,27 @@ public class MiniPID{
 	//**********************************
 	// Constructor functions
 	//**********************************
+	
+	/**
+	 * Create a MiniPID class object. 
+	 * See setP, setI, setD methods for more detailed parameters.
+	 * @param p Proportional gain. Large if large difference between setpoint and target. 
+	 * @param i Integral gain.  Becomes large if setpoint cannot reach target quickly. 
+	 * @param d Derivative gain. Responds quickly to large changes in error. Small values prevents P and I terms from causing overshoot.
+	 */
 	public MiniPID(double p, double i, double d){
 		P=p; I=i; D=d;
 		checkSigns();
 		}
+
+	/**
+	 * Create a MiniPID class object. 
+	 * See setP, setI, setD, setF methods for more detailed parameters.
+	 * @param p Proportional gain. Large if large difference between setpoint and target. 
+	 * @param i Integral gain.  Becomes large if setpoint cannot reach target quickly. 
+	 * @param d Derivative gain. Responds quickly to large changes in error. Small values prevents P and I terms from causing overshoot.
+	 * @param f Feed-forward gain. Open loop "best guess" for the output should be. Only useful if setpoint represents a rate.
+	 */
 	public MiniPID(double p, double i, double d, double f){
 		P=p; I=i; D=d; F=f;
 		checkSigns();
@@ -57,7 +74,7 @@ public MiniPID(double p, double i, double d, double f){
 	//**********************************
 	/**
 	 * Configure the Proportional gain parameter. <br>
-	 * This responds quicly to changes in setpoint, and provides most of the initial driving force
+	 * This responds quickly to changes in setpoint, and provides most of the initial driving force
 	 * to make corrections. <br>
 	 * Some systems can be used with only a P gain, and many can be operated with only PI.<br>
 	 * For position based controllers, this is the first parameter to tune, with I second. <br>
@@ -95,37 +112,68 @@ public void setI(double i){
 		 // output change due to the I term constant during the transition. 
 	}
 
+	/**
+	 * Changes the D parameter <br>
+	 * This has two primary effects:
+	 * <list>
+	 * <li> Adds a "startup kick" and speeds up system response during setpoint changes
+	 * <li> Adds "drag" and slows the system when moving toward the target
+	 * </list>
+	 * A small D value can be useful for both improving response times, and preventing overshoot.
+	 * However, in many systems a large D value will cause significant instability, particularly 
+	 * for large setpoint changes.
+	 * <br>
+	 * Affects output through <b>output += -D*(current_input_value - last_input_value)</b>
+	 *
+	 * @param d New gain value for the Derivative term
+	 */
 	public void setD(double d){
 		D=d;
 		checkSigns();
 		}
 
 	/**
 	 * Configure the FeedForward parameter. <br>
-	 * This is excellent for Velocity, rate, and other  continuous control modes where you can 
+	 * This is excellent for velocity, rate, and other  continuous control modes where you can 
 	 * expect a rough output value based solely on the setpoint.<br>
-	 * Should not be used in "position" based control modes.
+	 * Should not be used in "position" based control modes.<br>
+	 * Affects output according to <b>output+=F*Setpoint</b>. Note, that a F-only system is actually open loop.
 	 * 
-	 * @param f Feed forward gain. Affects output according to <b>output+=F*Setpoint</b>;
+	 * @param f Feed forward gain. 
 	 */
 	public void setF(double f){
 		F=f;
 		checkSigns();
-		}
+	}
 
 	/** 
-	 * Create a new PID object. 
+	 * Configure the PID object.
+	 * See setP, setI, setD methods for more detailed parameters.
 	 * @param p Proportional gain. Large if large difference between setpoint and target. 
 	 * @param i Integral gain.  Becomes large if setpoint cannot reach target quickly. 
 	 * @param d Derivative gain. Responds quickly to large changes in error. Small values prevents P and I terms from causing overshoot.
 	 */
 	public void setPID(double p, double i, double d){
-		P=p;I=i;D=d;
+		P=p;D=d;
+		//Note: the I term has additional calculations, so we need to use it's 
+		//specific method for setting it.
+		setI(i);
 		checkSigns();
 	}
 
+	/** 
+	 * Configure the PID object.
+	 * See setP, setI, setD, setF methods for more detailed parameters.
+	 * @param p Proportional gain. Large if large difference between setpoint and target. 
+	 * @param i Integral gain.  Becomes large if setpoint cannot reach target quickly. 
+	 * @param d Derivative gain. Responds quickly to large changes in error. Small values prevents P and I terms from causing overshoot.
+	 * @param f Feed-forward gain. Open loop "best guess" for the output should be. Only useful if setpoint represents a rate.
+	 */
 	public void setPID(double p, double i, double d,double f){
-		P=p;I=i;D=d;F=f;
+		P=p;D=d;F=f;
+		//Note: the I term has additional calculations, so we need to use it's 
+		//specific method for setting it.
+		setI(i);
 		checkSigns();
 	}
 
@@ -145,16 +193,19 @@ public void setMaxIOutput(double maximum){
 	}
 
 	/**
-	 * Specify a  maximum output. If a single parameter is specified, the minimum is 
-	 * set to (-maximum).
-	 * @param output 
+	 * Specify a maximum output range. <br>
+	 * When one input is specified, output range is configured to 
+	 * <b>[-output, output]</b>
+	 * @param output
 	 */
 	public void setOutputLimits(double output){
 		setOutputLimits(-output,output);
 	}
 
 	/**
 	 * Specify a  maximum output.
+	 * When two inputs specified, output range is configured to 
+	 * <b>[minimum, maximum]</b>
 	 * @param minimum possible output value
 	 * @param maximum possible output value
 	 */
@@ -182,19 +233,21 @@ public void  setDirection(boolean reversed){
 	//**********************************
 
 	/**
-	 * Set the target for the PID calculations
+	 * Configure setpoint for the PID calculations<br>
+	 * This represents the target for the PID system's, such as a 
+	 * position, velocity, or angle. <br>
+	 * @see MiniPID#getOutput(actual) <br>
 	 * @param setpoint
 	 */
 	public void setSetpoint(double setpoint){
 		this.setpoint=setpoint;
-	} 
+	}
 
 	/**
-	 * Calculate the PID value needed to hit the target setpoint. 
-	 * Automatically re-calculates the output at each call. 
-	 * @param actual The monitored value
-	 * @param target The target value
-	 * @return calculated output value for driving the actual to the target 
+	 * Calculate the output value for the current PID cycle.<br>
+	 * @param actual The monitored value, typically as a sensor input.
+	 * @param setpoint The target value for the system
+	 * @return calculated output value for driving the system
 	 */
 	public double getOutput(double actual, double setpoint){
 		double output;
@@ -287,32 +340,49 @@ else if(maxIOutput!=0){
 	}
 
 	/**
-	 * Calculates the PID value using the last provided setpoint and actual valuess
-	 * @return calculated output value for driving the actual to the target 
+	 * Calculate the output value for the current PID cycle.<br>
+	 * In no-parameter mode, this uses the last sensor value, 
+	 * and last setpoint value. <br>
+	 * Not typically useful, and use of parameter modes is suggested. <br>
+	 * @return calculated output value for driving the system
 	 */
 	public double getOutput(){
 		return getOutput(lastActual,setpoint);
 	}
 
 	/**
-	 * @param actual
-	 * @return calculated output value for driving the actual to the target 
+	 * Calculate the output value for the current PID cycle.<br>
+	 * In one parameter mode, the last configured setpoint will be used.<br>
+	 * @see MiniPID#setSetpoint()
+	 * @param actual The monitored value, typically as a sensor input.
+	 * @param setpoint The target value for the system
+	 * @return calculated output value for driving the system
 	 */
 	public double getOutput(double actual){
 		return getOutput(actual,setpoint);
 	}
 
 	/**
-	 * Resets the controller. This erases the I term buildup, and removes D gain on the next loop.
+	 * Resets the controller. This erases the I term buildup, and removes 
+	 * D gain on the next loop.<br>
+	 * This should be used any time the PID is disabled or inactive for extended
+	 * duration, and the controlled portion of the system may have changed due to
+	 * external forces.
 	 */
 	public void reset(){
 		firstRun=true;
 		errorSum=0;
 	}
 
 	/**
-     * Set the maximum rate the output can increase per cycle. 
-	 * @param rate
+     * Set the maximum rate the output can increase per cycle.<br>
+     * This can prevent sharp jumps in output when changing setpoints or 
+     * enabling a PID system, which might cause stress on physical or electrical
+     * systems.  <br>
+     * Can be very useful for fast-reacting control loops, such as ones 
+     * with large P or D values and feed-forward systems.
+     * 
+	 * @param rate, with units being the same as the output
 	 */
 	public void setOutputRampRate(double rate){
 		outputRampRate=rate;
@@ -323,17 +393,21 @@ public void setOutputRampRate(double rate){
 	 * <br>Can simplify tuning by helping tuning over a small range applies to a much larger range. 
 	 * <br>This limits the reactivity of P term, and restricts impact of large D term
 	 * during large setpoint adjustments. Increases lag and I term if range is too small.
-	 * @param range
+	 * @param range, with units being the same as the expected sensor range. 
 	 */
 	public void setSetpointRange(double range){
 		setpointRange=range;
 	}
 
 	/**
      * Set a filter on the output to reduce sharp oscillations. <br>
-	 * 0.1 is likely a sane starting value. Larger values P and D oscillations, but force larger I values.
-	 * Uses an exponential rolling sum filter, according to a simple <br>
-	 * <pre>output*(1-strength)*sum(0..n){output*strength^n}</pre>
+	 * 0.1 is likely a sane starting value. Larger values use historical data
+	 * more heavily, with low values weigh newer data. 0 will disable, filtering, and use 
+	 * only the most recent value. <br>
+	 * Increasing the filter strength will P and D oscillations, but force larger I 
+	 * values and increase I term overshoot.<br>
+	 * Uses an exponential wieghted rolling sum filter, according to a simple <br>
+	 * <pre>output*(1-strength)*sum(0..n){output*strength^n}</pre> algorithm.
 	 * @param output valid between [0..1), meaning [current output only.. historical output only)
 	 */
 	public void setOutputFilter(double strength){
@@ -364,9 +438,13 @@ private double constrain(double value, double min, double max){
 	 * @param value to test
 	 * @param min Minimum value of range
 	 * @param max Maximum value of range
-	 * @return
+	 * @return true if value is within range, false otherwise
 	 */
 	private boolean bounded(double value, double min, double max){
+		// Note, this is an inclusive range. This is so tests like
+		// `bounded(constrain(0,0,1),0,1)` will return false.
+		// This is more helpful for determining edge-case behaviour
+		// than <= is.
 		return (min<value) && (value<max);
 	}
 
