diff options
Diffstat (limited to 'src')
9 files changed, 168 insertions, 16 deletions
diff --git a/src/org/usfirst/frc/team4272/robotlib/DoubleSolenoid.java b/src/org/usfirst/frc/team4272/robotlib/DoubleSolenoid.java index 7ae7441..00f520c 100644 --- a/src/org/usfirst/frc/team4272/robotlib/DoubleSolenoid.java +++ b/src/org/usfirst/frc/team4272/robotlib/DoubleSolenoid.java @@ -1,5 +1,5 @@ /** - * Copyright (c) 2015 Luke Shumaker. + * Copyright (c) 2015, 2017 Luke Shumaker. * All rights reserved. * * Redistribution and use in source and binary forms, with or without @@ -29,7 +29,15 @@ package org.usfirst.frc.team4272.robotlib; /** - * TODO: Write JavaDocs + * DoubleSoleniod extends + * {@link edu.wpi.first.wpilibj.DoubleSolenoid wpilibj.DoubleSoleniod}, + * adding the ability to disable it. + * + * Now, where things get useful is with enabling or disabling. If + * {@link #setEnabled(boolean) .setEnabled(false)}, then any calls to + * {@link #set(Value) .set()} will be remembered, but ignored until + * {@code .setEnabled(true)}. As long as {@code .setEnabled(false)}, + * the actuated value will {@link Value.kOff}. */ public class DoubleSolenoid extends edu.wpi.first.wpilibj.DoubleSolenoid { private boolean enabled = true; @@ -44,6 +52,15 @@ public class DoubleSolenoid extends edu.wpi.first.wpilibj.DoubleSolenoid { value = get(); } + /** + * Set whether the soleniod is enabled. If the solenoid is + * not enabled, then the actuated state is {@link Value.kOff}. + * If {@link #set(Value)} or similar is call while disabled, + * the set will be remembered, but not take effect until it is + * re-enabled. + * + * @param enabled Whether the soleniod is enabled. + */ public void setEnabled(boolean enabled) { this.enabled = enabled; if (enabled) { @@ -53,10 +70,24 @@ public class DoubleSolenoid extends edu.wpi.first.wpilibj.DoubleSolenoid { } } + /** + * A convenience wrapper around {@link #set(Value) .set()} + * because {@link Value.kForward} and {@link Value.kReverse} + * are awkward to deal with. + * + * @param forward Whether to {@code .set(Value.kForward)} or {@code kBackward}. + */ public void setForward(boolean forward) { set(forward ? Value.kForward : Value.kReverse); } + /** + * Returns whether or not it is set to forward. If the + * solenoid is disabled, the return value is based on the + * remembered value that it will use upon being enabled. + * + * @return The current value of the solenoid. + */ public boolean getForward() { return value == Value.kForward; } diff --git a/src/org/usfirst/frc/team4272/robotlib/LimitSwitchedPIDOutput.java b/src/org/usfirst/frc/team4272/robotlib/LimitSwitchedPIDOutput.java index 8d314b0..91d059c 100644 --- a/src/org/usfirst/frc/team4272/robotlib/LimitSwitchedPIDOutput.java +++ b/src/org/usfirst/frc/team4272/robotlib/LimitSwitchedPIDOutput.java @@ -1,5 +1,5 @@ /** - * Copyright (c) 2015 Luke Shumaker. + * Copyright (c) 2015, 2017 Luke Shumaker. * All rights reserved. * * Redistribution and use in source and binary forms, with or without @@ -32,7 +32,8 @@ import edu.wpi.first.wpilibj.DigitalInput; import edu.wpi.first.wpilibj.PIDOutput; /** - * TODO: Write JavaDocs + * LimitSwitchedPIDOutput wraps a {@link PIDOutput}, ensuring that it + * does not go in a direction if a limit switch is tripped. */ public class LimitSwitchedPIDOutput implements PIDOutput { private final PIDOutput out; @@ -41,6 +42,13 @@ public class LimitSwitchedPIDOutput implements PIDOutput { private final boolean for_pressed; private final boolean bak_pressed; + /** + * @param out The actual PIDOutput to write to. + * @param forward The forward (positive-direction) limit switch. + * @param for_pressed Which value from the forward switch is to be considered "pressed". + * @param backward The backward (negative-direction) limit switch. + * @param back_pressed Which value from the backward switch is to be considered "pressed". + */ public LimitSwitchedPIDOutput(PIDOutput out, DigitalInput forward, boolean for_pressed, DigitalInput backward, boolean back_pressed) { @@ -51,6 +59,14 @@ public class LimitSwitchedPIDOutput implements PIDOutput { this.bak_pressed = back_pressed; } + /** + * Like the full constructor, but assume that {@code true} + * indicates "pressed" for both switches. + * + * @param out The actual PIDOutput to write to. + * @param forward The forward (positive-direction) limit switch. + * @param backward The backward (negative-direction) limit switch. + */ public LimitSwitchedPIDOutput(PIDOutput out, DigitalInput forward, DigitalInput backward) { this(out, forward, true, backward, true); } diff --git a/src/org/usfirst/frc/team4272/robotlib/PIDOutputSplitter.java b/src/org/usfirst/frc/team4272/robotlib/PIDOutputSplitter.java index b9d19da..1c63b22 100644 --- a/src/org/usfirst/frc/team4272/robotlib/PIDOutputSplitter.java +++ b/src/org/usfirst/frc/team4272/robotlib/PIDOutputSplitter.java @@ -1,5 +1,5 @@ /** - * Copyright (c) 2011-2012, 2015 Luke Shumaker + * Copyright (c) 2011-2012, 2015, 2017 Luke Shumaker * All rights reserved. * * Redistribution and use in source and binary forms, with or without @@ -31,12 +31,28 @@ package org.usfirst.frc.team4272.robotlib; import edu.wpi.first.wpilibj.PIDOutput; /** - * TODO: Write JavaDocs + * PIDOutputSplitter sets a single setpoint on many underlying {@link PIDOutput}s. + * + * Because it is undesirable that an exception from one underlying + * PIDOutput prevent the others from receiving the value; rather than + * letting an exception be thrown normally, it is handle by the + * {@link error(Exception)} method--see the documentation there for + * advanced error handling. */ public class PIDOutputSplitter implements PIDOutput { private final PIDOutput[] outputs; private final double[] scalars; + /** + * Construct with a scalar for each underlying output. If the + * length of the arrays do not match, a + * {@link RuntimeException} is thrown. + * + * @param outputs The underlying PIDOutputs that are written + * to. + * @param scalars How much to scale the setpoint written to + * each output by. + */ public PIDOutputSplitter(PIDOutput[] outputs, double[] scalars) { this.outputs = outputs; this.scalars = scalars; @@ -45,6 +61,12 @@ public class PIDOutputSplitter implements PIDOutput { } } + /** + * Construct a PIDOutputSplitter that applies no scaling. + * + * @param outputs The underlying PIDOutputs that are written + * to. + */ public PIDOutputSplitter(PIDOutput... outputs) { double[] s = new double[outputs.length]; for (int i=0; i<s.length; i++) { diff --git a/src/org/usfirst/frc/team4272/robotlib/PIDServo.java b/src/org/usfirst/frc/team4272/robotlib/PIDServo.java index 783bbf9..ae00928 100644 --- a/src/org/usfirst/frc/team4272/robotlib/PIDServo.java +++ b/src/org/usfirst/frc/team4272/robotlib/PIDServo.java @@ -1,5 +1,6 @@ /** * Copyright (c) 2012 Precise Path Robotics, Inc + * Copyright (c) 2017 Luke Shumaker * * This program is free software: you can redistribute it and/or modify it under * the terms of the GNU General Public License as published by the Free Software @@ -22,7 +23,8 @@ import edu.wpi.first.wpilibj.Servo; import edu.wpi.first.wpilibj.PIDOutput; /** - * TODO: Write JavaDocs + * PIDServo simply extends {@link Servo wpilibj.Servo} to implement + * the {@link PIDOutput} interface; for uniformity. */ public class PIDServo extends Servo implements PIDOutput { public PIDServo(int channel) { diff --git a/src/org/usfirst/frc/team4272/robotlib/PushButton.java b/src/org/usfirst/frc/team4272/robotlib/PushButton.java index f6615ff..acfe89f 100644 --- a/src/org/usfirst/frc/team4272/robotlib/PushButton.java +++ b/src/org/usfirst/frc/team4272/robotlib/PushButton.java @@ -1,5 +1,5 @@ /** - * Copyright (c) 2015-2016 Luke Shumaker. + * Copyright (c) 2015-2017 Luke Shumaker. * All rights reserved. * * Redistribution and use in source and binary forms, with or without @@ -29,7 +29,11 @@ package org.usfirst.frc.team4272.robotlib; /** - * TODO: Write JavaDocs + * PushButton fires an event on-button-down. + * + * In each iteration of the main loop, call the + * {@link #update(boolean)} method with the current button state. It + * will return whether or not an event should be fired this iteration. */ public class PushButton { private boolean prev = false; diff --git a/src/org/usfirst/frc/team4272/robotlib/RateLimitedPIDOutput.java b/src/org/usfirst/frc/team4272/robotlib/RateLimitedPIDOutput.java index 70010c6..42121a5 100644 --- a/src/org/usfirst/frc/team4272/robotlib/RateLimitedPIDOutput.java +++ b/src/org/usfirst/frc/team4272/robotlib/RateLimitedPIDOutput.java @@ -1,5 +1,6 @@ /** * Copyright (c) 2012 Precise Path Robotics, Inc + * Copyright (c) 2017 Luke Shumaker * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -22,7 +23,12 @@ import edu.wpi.first.wpilibj.PIDOutput; import edu.wpi.first.wpilibj.Timer; /** - * TODO: Write JavaDocs + * RateLimitedPIDOutput wraps a {@link PIDOutput}, unsuring that the + * set value does not change too quickly. + * + * If the writer attempts to call {@link pidWrite(double)} with a + * value that is too different than the previous value; it will + * instead write a value that is closer to the previous value. */ public class RateLimitedPIDOutput implements PIDOutput { PIDOutput o; @@ -30,6 +36,11 @@ public class RateLimitedPIDOutput implements PIDOutput { double prev_rate = 0; double prev_time = 0; + /** + * @param out The actual PIDOutput to write to. + * @param maxChange the maximum amount that the setpoint can + * change by per second. + */ public RateLimitedPIDOutput(PIDOutput out, double maxChange) { o = out; m = maxChange; diff --git a/src/org/usfirst/frc/team4272/robotlib/RollingAvg.java b/src/org/usfirst/frc/team4272/robotlib/RollingAvg.java index 7f0af11..c052099 100644 --- a/src/org/usfirst/frc/team4272/robotlib/RollingAvg.java +++ b/src/org/usfirst/frc/team4272/robotlib/RollingAvg.java @@ -1,5 +1,5 @@ /** - * Copyright (c) 2011, 2016 Luke Shumaker + * Copyright (c) 2011, 2016-2017 Luke Shumaker * All rights reserved. * * Redistribution and use in source and binary forms, with or without @@ -33,7 +33,7 @@ import edu.wpi.first.wpilibj.PIDSourceType; import edu.wpi.first.wpilibj.PIDOutput; /** - * TODO: Write JavaDocs + * RollingAvg implements a rolling average. */ public class RollingAvg implements PIDSource, PIDOutput { private PIDSource source = null; @@ -41,16 +41,44 @@ public class RollingAvg implements PIDSource, PIDOutput { private double avg; private int i; + /** + * Construct a RollingAvg that must be updated with the + * {@link #push(double)} or {@link #pidWrite(double)} methods. + * + * @param len The number of samples to keep in the average. + */ public RollingAvg(int len) { points = new double[len]; i = 0; avg = 0; } + /** + * Construct a RollingAvg that will automatically update + * itself from a {@link PIDSource} each time {@link #pidGet()} + * is called. + * + * That is, it wraps the {@link PIDSource} to stabalize any + * noise. + * + * If {@link #pidGet()} is not called an iteration, then it is + * not updated that iteration; so be sure to call it each + * iteration whether or not you actually care about the value. + * + * @param len The number of samples to keep in the average. + * @param src The underlying PIDSource to read from. + */ public RollingAvg(int len, PIDSource src) { this(len); source = src; } + /** + * Push a new value on to the rolling average (pushing out a + * previous value). + * + * @param v The new value to push. + * @return The new average after pushing v. + */ public double push(double v) { avg -= points[i]; points[i] = v/points.length; @@ -59,10 +87,26 @@ public class RollingAvg implements PIDSource, PIDOutput { return avg; } + /** + * Return the current value of the rolling average, without + * mutating anything. + * + * @return The current value of the rolling average. + */ public double get() { return avg; } + /** + * If constructed with an underlying {@link PIDSource}, read from it + * and push the value; returning the new average after pushing + * that value. + * + * If not constructed with an underlying {@link PIDSource}, + * then this is simply an alias for {@link #get()}. + * + * @return The value of the rolling average. + */ public double pidGet() { if (source!=null) return push(source.pidGet()); @@ -70,15 +114,28 @@ public class RollingAvg implements PIDSource, PIDOutput { return get(); } + /** + * An alias for {@link #push(double)} (but doesn't return the + * new average), in order to implement the {@link PIDOutput} + * interface. + * + * @param output The value to push. + */ public void pidWrite(double output) { push(output); } + /** + * See the documentation for {@link PIDSource#setPIDSourceType(PIDSourceType)}. + */ public void setPIDSourceType(PIDSourceType srcType) { if (source!=null) source.setPIDSourceType(srcType); } + /** + * See the documentation for {@link PIDSource#getPIDSourceType}. + */ public PIDSourceType getPIDSourceType() { if (source!=null) return source.getPIDSourceType(); diff --git a/src/org/usfirst/frc/team4272/robotlib/SendablePIDOutput.java b/src/org/usfirst/frc/team4272/robotlib/SendablePIDOutput.java index 38e64e0..38f994b 100644 --- a/src/org/usfirst/frc/team4272/robotlib/SendablePIDOutput.java +++ b/src/org/usfirst/frc/team4272/robotlib/SendablePIDOutput.java @@ -1,6 +1,6 @@ /** * Copyright (c) 2012 Precise Path Robotics, Inc - * Copyright (c) 2015 Luke Shumaker + * Copyright (c) 2015, 2017 Luke Shumaker * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -23,12 +23,17 @@ import edu.wpi.first.wpilibj.PIDOutput; import edu.wpi.first.wpilibj.smartdashboard.SmartDashboard; /** - * TODO: Write JavaDocs + * SendablePIDOutput wraps a {@link PIDOutput}, sending the setpoint + * to the {@link SmartDashboard}; which is useful for debugging. */ public class SendablePIDOutput implements PIDOutput { PIDOutput o; String n; + /** + * @param name The name of the value in the SmartDashboard. + * @param out The actual PIDOutput to write to. + */ public SendablePIDOutput(String name, PIDOutput out) { n = name; o = out; diff --git a/src/org/usfirst/frc/team4272/robotlib/ToggleButton.java b/src/org/usfirst/frc/team4272/robotlib/ToggleButton.java index 40367e7..8c15514 100644 --- a/src/org/usfirst/frc/team4272/robotlib/ToggleButton.java +++ b/src/org/usfirst/frc/team4272/robotlib/ToggleButton.java @@ -1,5 +1,5 @@ /** - * Copyright (c) 2015 Luke Shumaker. + * Copyright (c) 2015, 2017 Luke Shumaker. * All rights reserved. * * Redistribution and use in source and binary forms, with or without @@ -29,7 +29,11 @@ package org.usfirst.frc.team4272.robotlib; /** - * TODO: Write JavaDocs + * ToggleButton toggles a value on-button-down. + * + * In each iteration of the main loop, call the + * {@link #update(boolean)} method with the current button state. It + * will return the current value of what the button toggles. */ public class ToggleButton { private boolean prev = false; |