[wpimath] Report error on negative PID gains (#6055)

Defaults PID gains to zero if any are invalid.

wpimath/src/main/java/edu/wpi/first/math/controller/PIDController.java

@@ -68,6 +68,9 @@ public class PIDController implements Sendable, AutoCloseable {
    * @param kp The proportional coefficient.
    * @param ki The integral coefficient.
    * @param kd The derivative coefficient.
+   * @throws IllegalArgumentException if kp < 0
+   * @throws IllegalArgumentException if ki < 0
+   * @throws IllegalArgumentException if kd < 0
    */
   public PIDController(double kp, double ki, double kd) {
     this(kp, ki, kd, 0.02);
@@ -79,7 +82,11 @@ public class PIDController implements Sendable, AutoCloseable {
    * @param kp The proportional coefficient.
    * @param ki The integral coefficient.
    * @param kd The derivative coefficient.
-   * @param period The period between controller updates in seconds. Must be non-zero and positive.
+   * @param period The period between controller updates in seconds.
+   * @throws IllegalArgumentException if kp < 0
+   * @throws IllegalArgumentException if ki < 0
+   * @throws IllegalArgumentException if kd < 0
+   * @throws IllegalArgumentException if period <= 0
    */
   @SuppressWarnings("this-escape")
   public PIDController(double kp, double ki, double kd, double period) {
@@ -87,8 +94,17 @@ public class PIDController implements Sendable, AutoCloseable {
     m_ki = ki;
     m_kd = kd;
 
-    if (period <= 0) {
-      throw new IllegalArgumentException("Controller period must be a non-zero positive number!");
+    if (kp < 0.0) {
+      throw new IllegalArgumentException("Kp must be a non-negative number!");
+    }
+    if (ki < 0.0) {
+      throw new IllegalArgumentException("Ki must be a non-negative number!");
+    }
+    if (kd < 0.0) {
+      throw new IllegalArgumentException("Kd must be a non-negative number!");
+    }
+    if (period <= 0.0) {
+      throw new IllegalArgumentException("Controller period must be a positive number!");
     }
     m_period = period;
 
@@ -121,7 +137,7 @@ public class PIDController implements Sendable, AutoCloseable {
   /**
    * Sets the Proportional coefficient of the PID controller gain.
    *
-   * @param kp proportional coefficient
+   * @param kp The proportional coefficient. Must be &gt;= 0.
    */
   public void setP(double kp) {
     m_kp = kp;
@@ -130,7 +146,7 @@ public class PIDController implements Sendable, AutoCloseable {
   /**
    * Sets the Integral coefficient of the PID controller gain.
    *
-   * @param ki integral coefficient
+   * @param ki The integral coefficient. Must be &gt;= 0.
    */
   public void setI(double ki) {
     m_ki = ki;
@@ -139,7 +155,7 @@ public class PIDController implements Sendable, AutoCloseable {
   /**
    * Sets the Differential coefficient of the PID controller gain.
    *
-   * @param kd differential coefficient
+   * @param kd The differential coefficient. Must be &gt;= 0.
    */
   public void setD(double kd) {
     m_kd = kd;
@@ -153,6 +169,7 @@ public class PIDController implements Sendable, AutoCloseable {
    * of {@link Double#POSITIVE_INFINITY} disables IZone functionality.
    *
    * @param iZone Maximum magnitude of error to allow integral control.
+   * @throws IllegalArgumentException if iZone &lt; 0
    */
   public void setIZone(double iZone) {
     if (iZone < 0) {

wpimath/src/main/java/edu/wpi/first/math/controller/ProfiledPIDController.java

@@ -35,6 +35,9 @@ public class ProfiledPIDController implements Sendable {
    * @param Ki The integral coefficient.
    * @param Kd The derivative coefficient.
    * @param constraints Velocity and acceleration constraints for goal.
+   * @throws IllegalArgumentException if kp < 0
+   * @throws IllegalArgumentException if ki < 0
+   * @throws IllegalArgumentException if kd < 0
    */
   public ProfiledPIDController(
       double Kp, double Ki, double Kd, TrapezoidProfile.Constraints constraints) {
@@ -49,6 +52,10 @@ public class ProfiledPIDController implements Sendable {
    * @param Kd The derivative coefficient.
    * @param constraints Velocity and acceleration constraints for goal.
    * @param period The period between controller updates in seconds. The default is 0.02 seconds.
+   * @throws IllegalArgumentException if kp < 0
+   * @throws IllegalArgumentException if ki < 0
+   * @throws IllegalArgumentException if kd < 0
+   * @throws IllegalArgumentException if period <= 0
    */
   @SuppressWarnings("this-escape")
   public ProfiledPIDController(
@@ -67,9 +74,9 @@ public class ProfiledPIDController implements Sendable {
    *
    * <p>Sets the proportional, integral, and differential coefficients.
    *
-   * @param Kp Proportional coefficient
-   * @param Ki Integral coefficient
-   * @param Kd Differential coefficient
+   * @param Kp The proportional coefficient. Must be &gt;= 0.
+   * @param Ki The integral coefficient. Must be &gt;= 0.
+   * @param Kd The differential coefficient. Must be &gt;= 0.
    */
   public void setPID(double Kp, double Ki, double Kd) {
     m_controller.setPID(Kp, Ki, Kd);
@@ -78,7 +85,7 @@ public class ProfiledPIDController implements Sendable {
   /**
    * Sets the proportional coefficient of the PID controller gain.
    *
-   * @param Kp proportional coefficient
+   * @param Kp The proportional coefficient. Must be &gt;= 0.
    */
   public void setP(double Kp) {
     m_controller.setP(Kp);
@@ -87,7 +94,7 @@ public class ProfiledPIDController implements Sendable {
   /**
    * Sets the integral coefficient of the PID controller gain.
    *
-   * @param Ki integral coefficient
+   * @param Ki The integral coefficient. Must be &gt;= 0.
    */
   public void setI(double Ki) {
     m_controller.setI(Ki);
@@ -96,7 +103,7 @@ public class ProfiledPIDController implements Sendable {
   /**
    * Sets the differential coefficient of the PID controller gain.
    *
-   * @param Kd differential coefficient
+   * @param Kd The differential coefficient. Must be &gt;= 0.
    */
   public void setD(double Kd) {
     m_controller.setD(Kd);
@@ -110,6 +117,7 @@ public class ProfiledPIDController implements Sendable {
    * of {@link Double#POSITIVE_INFINITY} disables IZone functionality.
    *
    * @param iZone Maximum magnitude of error to allow integral control.
+   * @throws IllegalArgumentException if iZone &lt;= 0
    */
   public void setIZone(double iZone) {
     m_controller.setIZone(iZone);