wpilibsuite · pjbuterbaugh · Jul 10, 2023 · Jul 10, 2023 · Jul 21, 2023 · May 29, 2023
diff --git a/.gitignore b/.gitignore
@@ -1,6 +1,9 @@
 # Created by https://www.gitignore.io/api/linux,macos,windows,visualstudiocode
 # Edit at https://www.gitignore.io/?templates=linux,macos,windows,visualstudiocode
 
+### Miscellaneous ###
+.wpilib/
+
 ### Sphinx ###
 # Build directories
 build/

diff --git a/miktex-packages.txt b/miktex-packages.txt
@@ -166,7 +166,6 @@ miktex-metapost
 miktex-metapost-bin-x64-2.9
 miktex-mfware-bin-x64-2.9
 miktex-misc
-miktex-mkfntmap-bin-x64-2.9
 miktex-mktex-bin-x64-2.9
 miktex-mo-bin-x64-2.9
 miktex-mpfr-bin-x64-2.9
@@ -256,3 +255,5 @@ zapfchan
 zapfding
 zerohyph
 zhmetrics
+colortbl
+letltxmacro
diff --git a/poetry.lock b/poetry.lock
diff --git a/source/docs/contributing/frc-docs/build-instructions.rst b/source/docs/contributing/frc-docs/build-instructions.rst
@@ -13,15 +13,23 @@ Text Editors / IDE
 
 For development, we recommend that you use VS Code along with the `reStructuredText extension <https://marketplace.visualstudio.com/items?itemName=lextudio.restructuredtext>`_. However, any text editor will work.
 
+By default, the reStructuredText extension enables linting with all doc8 features enabled. As frc-docs does not follow the line length lint, add the following to your VS Code ``settings.json`` to disable line length linting.
+
+.. code-block:: json
+
+   "restructuredtext.linter.doc8.extraArgs": [
+      "--ignore D001"
+   ]
+
 Windows
 ^^^^^^^
 
 .. note:: MikTeX and ``rsvg-convert`` are not required for building HTML, they are only required for Windows PDF builds.
 
 - `Python 3.9 <https://www.python.org/downloads/>`__
-- `MiKTeX <https://miktex.org/download>`__ (Only needed for PDF builds)
 - `Perl <https://strawberryperl.com/>`__
-- `rsvg-convert <https://community.chocolatey.org/packages/rsvg-convert>`__
+- `MiKTeX <https://miktex.org/download>`__ (Only needed for PDF builds)
+- `rsvg-convert <https://community.chocolatey.org/packages/rsvg-convert>`__ (Only needed for PDF builds)
 
 Ensure that Python is in your Path by selecting the **Add Python to PATH** toggle when installing Python.
 
@@ -30,7 +38,7 @@ Ensure that Python is in your Path by selecting the **Add Python to PATH** toggl
 
 Once Python is installed, open up Powershell. Then navigate to the frc-docs directory. Run the following command: ``pip install -r source/requirements.txt``
 
-Install the missing MikTex packages by navigating to the frc-docs directory, then running the following command from Powershell: ``mpm --verbose --require=@miktex-packages.txt``
+Install the missing MikTex packages by navigating to the frc-docs directory, then running the following command from Powershell: ``miktex --verbose packages require --package-id-file miktex-packages.txt``
 
 Linux (Ubuntu)
 ^^^^^^^^^^^^^^

diff --git a/source/docs/controls-overviews/control-system-hardware.rst b/source/docs/controls-overviews/control-system-hardware.rst
@@ -116,11 +116,25 @@ The power supply for an FRC robot is a single 12V 18Ah Sealed Lead Acid (SLA) ba
 Robot Signal Light
 ------------------
 
-.. image:: images/control-system-hardware/robot-signal-light.png
-  :alt: Orange Robot Signal Light
-  :width: 500
+.. tabs::
+
+   .. tab:: Allen-Bradley
+
+      .. figure:: images/control-system-hardware/rsl-allenbradley.png
+         :alt: Orange Robot Signal Light (Allen-Bradley)
+         :width: 500
+
+         Allen-Bradley 855PB-B12ME522
+
+   .. tab:: AndyMark
+
+      .. figure:: images/control-system-hardware/rsl-andymark.png
+         :alt: Orange Robot Signal Light (AndyMark)
+         :width: 500
+
+         AndyMark am-3583
 
-The Robot Signal Light (RSL) is required to be the Allen-Bradley 855PB-B12ME522.  It is directly controlled by the roboRIO and will flash when enabled and stay solid while disabled.
+The Robot Signal Light (RSL) is required to be either Allen-Bradley 855PB-B12ME522 or AndyMark am-3583.  It is directly controlled by the roboRIO and will flash when enabled and stay solid while disabled.
 
 CTRE Pneumatics Control Module
 ------------------------------

diff --git a/...ol-system-hardware/robot-signal-light.png → ...trol-system-hardware/rsl-allenbradley.png b/...ol-system-hardware/robot-signal-light.png → ...trol-system-hardware/rsl-allenbradley.png
diff --git a/source/docs/controls-overviews/images/control-system-hardware/rsl-andymark.png b/source/docs/controls-overviews/images/control-system-hardware/rsl-andymark.png
diff --git a/source/docs/hardware/hardware-basics/wiring-pneumatics-ph.rst b/source/docs/hardware/hardware-basics/wiring-pneumatics-ph.rst
@@ -5,6 +5,14 @@ This page describes wiring pneumatics with the REV Pneumatic Hub (PH). For instr
 
 .. hint:: For pneumatics safety & mechanical requirements, consult this year's Robot Construction rules. For mechanical design guidelines, the FIRST Pneumatics Manual is located `here <https://www.firstinspires.org/sites/default/files/uploads/resource_library/frc/technical-resources/frc_pneumatics_manual.pdf>`__
 
+.. raw:: html
+
+    <div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%; height: auto;">
+        <iframe src="https://www.youtube-nocookie.com/embed/uQEiNiHT9fs" frameborder="0" allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe>
+    </div>
+
+----
+
 Wiring Overview
 ---------------
 
@@ -42,7 +50,7 @@ Analog
 
 An analog pressure switch (`REV-11-1107 <https://www.revrobotics.com/rev-11-1107/>`__ can be connected directly to the analog pressure sensor port 0 input terminals. Using an analog pressure sensor allows reading the pressure in the pneumatic system through code and setting custom trigger thresholds for turning on and off the compressor.
 
-..warning:: The Analog Pressure Sensor port is a very tight fit and requires special attention. See `REV Wiring an Analog Pressure Sensor <https://docs.revrobotics.com/rev-11-1852/pneumatic-hub-getting-started/wiring-the-pneumatic-hub#wiring-an-analog-pressure-sensor>`__ for more tips
+.. warning:: The Analog Pressure Sensor port is a very tight fit and requires special attention. See `REV Wiring an Analog Pressure Sensor <https://docs.revrobotics.com/rev-11-1852/pneumatic-hub-getting-started/wiring-the-pneumatic-hub#wiring-an-analog-pressure-sensor>`__ for more tips
 
 Solenoids
 ---------

diff --git a/source/docs/hardware/sensors/encoders-hardware.rst b/source/docs/hardware/sensors/encoders-hardware.rst
@@ -52,6 +52,7 @@ On-shaft encoders couple to a shaft by fitting *around* it, forming a friction c
 Examples of On-shaft encoders:
 
 - `AMT103-V <https://www.cuidevices.com/product/motion/rotary-encoders/incremental/modular/amt10-v-kit/amt103-v>`__ available through FIRST Choice
+- `CIMcoder <https://www.andymark.com/products/cimcoder-encoder-cim-motor-high-resolution>`__
 - `REV Through Bore Encoder <https://www.revrobotics.com/rev-11-1271/>`__
 - `US Digital E4T <https://www.andymark.com/products/e4t-oem-miniature-optical-encoder-kit>`__
 
@@ -86,6 +87,7 @@ As each square wave pulse is a digital signal, quadrature encoders connect to th
 Examples of quadrature encoders:
 
 - `AMT103-V <https://www.cuidevices.com/product/motion/rotary-encoders/incremental/modular/amt10-v-kit/amt103-v>`__ available through FIRST Choice
+- `CIMcoder <https://www.andymark.com/products/cimcoder-encoder-cim-motor-high-resolution>`__
 - `CTRE Mag Encoder <https://store.ctr-electronics.com/srx-mag-encoder/>`_
 - `Grayhill 63r <https://www.grayhill.com/documents/63R-Datasheet>`__
 - `REV Through Bore Encoder <https://www.revrobotics.com/rev-11-1271/>`__

diff --git a/.../docs/software/advanced-controls/controllers/combining-feedforward-feedback.rst b/.../docs/software/advanced-controls/controllers/combining-feedforward-feedback.rst
@@ -12,7 +12,7 @@ Feedforward and feedback controllers can each be used in isolation, but are most
 Using Feedforward with a PIDController
 --------------------------------------
 
-Users familiar with the old ``PIDController`` class may notice the lack of any feedforward gain in the new controller.  As users are expected to use the controller output themselves, there is no longer any need for the ``PIDController`` to implement feedforward - users may simply add any feedforward they like to the output of the controller before sending it to their motors:
+Users may add any feedforward they like to the output of the controller before sending it to their motors:
 
 .. tabs::
 

diff --git a/source/docs/software/advanced-controls/controllers/pidcontroller.rst b/source/docs/software/advanced-controls/controllers/pidcontroller.rst
@@ -10,8 +10,6 @@ WPILib supports PID control of mechanisms through the ``PIDController`` class (`
 Using the PIDController Class
 -----------------------------
 
-.. note:: The ``PIDController`` class in the ``frc`` namespace is deprecated - C++ teams should use the one in the ``frc2`` namespace, instead.  Likewise, Java teams should use the class in the ``edu.wpi.first.math.controller`` package.
-
 Constructing a PIDController
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -38,8 +36,6 @@ Using the Feedback Loop Output
 
 .. note:: The ``PIDController`` assumes that the ``calculate()`` method is being called regularly at an interval consistent with the configured period.  Failure to do this will result in unintended loop behavior.
 
-.. warning:: Unlike the old ``PIDController``, the new PIDController does not automatically control an output from its own thread - users are required to call ``calculate()`` and use the resulting output in their own code.
-
 Using the constructed ``PIDController`` is simple: simply call the ``calculate()`` method from the robot's main loop (e.g. the robot's ``autonomousPeriodic()`` method):
 
 .. tabs::
@@ -126,6 +122,35 @@ 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
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -152,8 +177,6 @@ To configure a ``PIDController`` to automatically do this, use the ``enableConti
 Clamping Controller Output
 --------------------------
 
-Unlike the old ``PIDController``, the new controller does not offer any output clamping features, as the user is expected to use the loop output themselves.  Output clamping can be easily achieved by composing the controller with WPI's ``clamp()`` function (or ``std::clamp`` in c++):
-
 .. tabs::
 
   .. code-tab:: java

diff --git a/source/docs/software/advanced-controls/controllers/trapezoidal-profiles.rst b/source/docs/software/advanced-controls/controllers/trapezoidal-profiles.rst
@@ -65,7 +65,7 @@ Putting It All Together
 
 .. note:: C++ is often able to infer the type of the inner classes, and thus a simple initializer list (without the class name) can be sent as a parameter.  The full class names are included in the example below for clarity.
 
-Now that we know how to create a set of constraints and the desired start/end states, we are ready to create our motion profile.  The ``TrapezoidProfile`` constructor takes 3 parameters, in order: the constraints, the goal state, and the initial state.
+Now that we know how to create a set of constraints and the desired start/end states, we are ready to create our motion profile.  The ``TrapezoidProfile`` constructor takes 1 parameter: the constraints.
 
 .. tabs::
 
@@ -74,65 +74,63 @@ Now that we know how to create a set of constraints and the desired start/end st
     // Creates a new TrapezoidProfile
     // Profile will have a max vel of 5 meters per second
     // Profile will have a max acceleration of 10 meters per second squared
-    // Profile will end stationary at 5 meters
-    // Profile will start stationary at zero position
-    TrapezoidProfile profile = new TrapezoidProfile(new TrapezoidProfile.Constraints(5, 10),
-                                                    new TrapezoidProfile.State(5, 0),
-                                                    new TrapezoidProfile.State(0, 0));
+    TrapezoidProfile profile = new TrapezoidProfile(new TrapezoidProfile.Constraints(5, 10));
 
   .. code-tab:: c++
 
     // Creates a new TrapezoidProfile
     // Profile will have a max vel of 5 meters per second
     // Profile will have a max acceleration of 10 meters per second squared
-    // Profile will end stationary at 5 meters
-    // Profile will start stationary at zero position
     frc::TrapezoidProfile<units::meters> profile{
-      frc::TrapezoidProfile<units::meters>::Constraints{5_mps, 10_mps_sq},
-      frc::TrapezoidProfile<units::meters>::State{5_m, 0_mps},
-      frc::TrapezoidProfile<units::meters>::State{0_m, 0_mps}};
+      frc::TrapezoidProfile<units::meters>::Constraints{5_mps, 10_mps_sq}};
 
 Using a ``TrapezoidProfile``
 ----------------------------
 
 Sampling the Profile
 ^^^^^^^^^^^^^^^^^^^^
 
-Once we've created a ``TrapezoidProfile``, using it is very simple: to get the profile state at the given time after the profile has started, call the ``calculate()`` method:
+Once we've created a ``TrapezoidProfile``, using it is very simple: to get the profile state at the given time after the profile has started, call the ``calculate()`` method with the goal state and initial state:
 
 .. tabs::
 
   .. code-tab:: java
 
+    // Profile will end stationary at 5 meters
+    // Profile will start stationary at zero position
     // Returns the motion profile state after 5 seconds of motion
-    profile.calculate(5);
+    profile.calculate(5, new TrapezoidProfile.State(5, 0), new TrapezoidProfile.State(0, 0));
 
   .. code-tab:: c++
 
+    // Profile will end stationary at 5 meters
+    // Profile will start stationary at zero position
     // Returns the motion profile state after 5 seconds of motion
-    profile.Calculate(5_s);
+    profile.Calculate(5_s,
+    frc::TrapezoidProfile<units::meters>::State{5_m, 0_mps},
+    frc::TrapezoidProfile<units::meters>::State{0_m, 0_mps});
 
 Using the State
 ^^^^^^^^^^^^^^^
 
-The ``calculate`` method returns a ``TrapezoidProfile.State`` class (the same one that was used to specify the initial/end states when constructing the profile).  To use this for actual control, simply pass the contained position and velocity values to whatever controller you wish (for example, a PIDController):
+The ``calculate`` method returns a ``TrapezoidProfile.State`` class (the same one that was used to specify the initial/end states when calculating the profile state).  To use this for actual control, simply pass the contained position and velocity values to whatever controller you wish (for example, a PIDController):
 
 .. tabs::
 
   .. code-tab:: java
 
-    var setpoint = profile.calculate(elapsedTime);
+    var setpoint = profile.calculate(elapsedTime, goalState, initialState);
     controller.calculate(encoder.getDistance(), setpoint.position);
 
   .. code-tab:: c++
 
-    auto setpoint = profile.Calculate(elapsedTime);
+    auto setpoint = profile.Calculate(elapsedTime, goalState, initialState);
     controller.Calculate(encoder.GetDistance(), setpoint.position.value());
 
 Complete Usage Example
 ----------------------
 
-.. note:: In this example, the profile is re-computed every timestep.  This is a somewhat different usage technique than is detailed above, but works according to the same principles - the profile is sampled at a time corresponding to the loop period to get the setpoint for the next loop iteration.
+.. note:: In this example, the initial state is re-computed every timestep. This is a somewhat different usage technique than is detailed above, but works according to the same principles - the profile is sampled at a time corresponding to the loop period to get the setpoint for the next loop iteration.
 
 A more complete example of ``TrapezoidProfile`` usage is provided in the ElevatorTrapezoidProfile example project (`Java <https://github.com/wpilibsuite/allwpilib/tree/main/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/elevatortrapezoidprofile>`__, `C++ <https://github.com/wpilibsuite/allwpilib/tree/main/wpilibcExamples/src/main/cpp/examples/ElevatorTrapezoidProfile/cpp>`__):