Document IZone (#2266)

Author: Gold856

source/docs/software/advanced-controls/controllers/pidcontroller.rst

@@ -126,6 +126,34 @@ The range limits may be increased or decreased using the ``setIntegratorRange()`
     // the total loop output
     pid.SetIntegratorRange(-0.5, 0.5);
 
+Disabling Integral Gain if the Error is Too High
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Another way integral "wind-up" can be alleviated is by limiting the error range where integral gain is active. This can be achieved by setting ``IZone``. If the error is more than ``IZone``, the total accumulated error is reset, disabling integral gain. When the error is equal to or less than IZone, integral gain is enabled.
+
+By default, ``IZone`` is disabled.
+
+``IZone`` may be set using the ``setIZone()`` method. To disable it, set it to infinity.
+
+.. tabs::
+
+  .. code-tab:: java
+
+    // Disable IZone
+    pid.setIZone(Double.POSITIVE_INFINITY);
+
+    // Integral gain will not be applied if the absolute value of the error is
+    // more than 2
+    pid.setIZone(2);
+
+  .. code-tab:: c++
+    // Disable IZone
+    pid.SetIZone(std::numeric_limits<double>::infinity());
+
+    // Integral gain will not be applied if the absolute value of the error is
+    // more than 2
+    pid.SetIZone(2);
+
 Setting Continuous Input
 ^^^^^^^^^^^^^^^^^^^^^^^^
 

source/docs/software/advanced-controls/introduction/common-control-issues.rst

@@ -11,7 +11,7 @@ Beware that if :math:`K_i` is too large, integral windup can occur. Following a
 There are a few ways to mitigate this:
 
 1. Decrease the value of :math:`K_i`, down to zero if possible.
-2. Add logic to reset the integrator term to zero if the :term:`output` is too far from the :term:`setpoint`. Some smart motor controllers implement this with a ``setIZone()`` method.
+2. Add logic to reset the integrator term to zero if the :term:`output` is too far from the :term:`setpoint`. Some smart motor controllers and WPILib's ``PIDController`` implement this with a ``setIZone()`` method.
 3. Cap the integrator at some maximum value. WPILib's ``PIDController`` implements this with the ``setIntegratorRange()`` method.
 
 .. important:: Most mechanisms in FRC do not require any integral control, and systems that seem to require integral control to respond well probably have an inaccurate feedforward model.