Skip to content

Commit

Permalink
Remove references to control subsystems
Browse files Browse the repository at this point in the history
  • Loading branch information
@Gold856
Gold856 committed Aug 1, 2024
1 parent d337320 commit 23d3351
Show file tree
Hide file tree
Showing 3 changed files with 11 additions and 455 deletions.
166 changes: 4 additions & 162 deletions source/docs/software/commandbased/pid-subsystems-commands.rst
View file
Original file line number Diff line number Diff line change
@@ -1,169 +1,11 @@
.. include:: <isonum.txt>

PID Control through PIDSubsystems and PIDCommands
PID Control through PIDCommands
=================================================

.. note:: For a description of the WPILib PID control features used by these command-based wrappers, see :ref:`docs/software/advanced-controls/controllers/pidcontroller:PID Control in WPILib`.

One of the most common control algorithms used in FRC\ |reg| is the :term:`PID` controller. WPILib offers its own :ref:`PIDController <docs/software/advanced-controls/controllers/pidcontroller:PID Control in WPILib>` class to help teams implement this functionality on their robots. To further help teams integrate PID control into a command-based robot project, the command-based library includes two convenience wrappers for the ``PIDController`` class: ``PIDSubsystem``, which integrates the PID controller into a subsystem, and ``PIDCommand``, which integrates the PID controller into a command.

PIDSubsystems
-------------

The ``PIDSubsystem`` class (`Java <https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/PIDSubsystem.html>`__, `C++ <https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_p_i_d_subsystem.html>`__) allows users to conveniently create a subsystem with a built-in ``PIDController``. In order to use the ``PIDSubsystem`` class, users must create a subclass of it.

Creating a PIDSubsystem
^^^^^^^^^^^^^^^^^^^^^^^

.. note:: If ``periodic`` is overridden when inheriting from ``PIDSubsystem``, make sure to call ``super.periodic()``! Otherwise, PID functionality will not work properly.

When subclassing ``PIDSubsystem``, users must override two abstract methods to provide functionality that the class will use in its ordinary operation:

getMeasurement()
~~~~~~~~~~~~~~~~

.. tab-set::

.. tab-item:: Java
:sync: Java

.. rli:: https://github.com/wpilibsuite/allwpilib/raw/v2024.1.1-beta-4/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/PIDSubsystem.java
:language: java
:lines: 85

.. tab-item:: C++
:sync: C++

.. rli:: https://github.com/wpilibsuite/allwpilib/raw/v2024.1.1-beta-4/wpilibNewCommands/src/main/native/include/frc2/command/PIDSubsystem.h
:language: c++
:lines: 80-80

The ``getMeasurement`` method returns the current measurement of the process variable. The ``PIDSubsystem`` will automatically call this method from its ``periodic()`` block, and pass its value to the control loop.

Users should override this method to return whatever sensor reading they wish to use as their process variable measurement.

useOutput()
~~~~~~~~~~~

.. tab-set::

.. tab-item:: Java
:sync: Java

.. rli:: https://github.com/wpilibsuite/allwpilib/raw/v2024.1.1-beta-4/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/PIDSubsystem.java
:language: java
:lines: 78

.. tab-item:: C++
:sync: C++

.. rli:: https://github.com/wpilibsuite/allwpilib/raw/v2024.1.1-beta-4/wpilibNewCommands/src/main/native/include/frc2/command/PIDSubsystem.h
:language: c++
:lines: 88-88


The ``useOutput()`` method consumes the output of the PID controller, and the current setpoint (which is often useful for computing a feedforward). The ``PIDSubsystem`` will automatically call this method from its ``periodic()`` block, and pass it the computed output of the control loop.

Users should override this method to pass the final computed control output to their subsystem's motors.

Passing In the Controller
~~~~~~~~~~~~~~~~~~~~~~~~~

Users must also pass in a ``PIDController`` to the ``PIDSubsystem`` base class through the superclass constructor call of their subclass. This serves to specify the PID gains, as well as the period (if the user is using a non-standard main robot loop period).

Additional modifications (e.g. enabling continuous input) can be made to the controller in the constructor body by calling ``getController()``.

Using a PIDSubsystem
^^^^^^^^^^^^^^^^^^^^

Once an instance of a ``PIDSubsystem`` subclass has been created, it can be used by commands through the following methods:

setSetpoint()
~~~~~~~~~~~~~

The ``setSetpoint()`` method can be used to set the setpoint of the ``PIDSubsystem``. The subsystem will automatically track to the setpoint using the defined output:

.. tab-set-code::

.. code-block:: java
// The subsystem will track to a setpoint of 5.
examplePIDSubsystem.setSetpoint(5);
.. code-block:: c++

// The subsystem will track to a setpoint of 5.
examplePIDSubsystem.SetSetpoint(5);

enable() and disable()
~~~~~~~~~~~~~~~~~~~~~~

The ``enable()`` and ``disable()`` methods enable and disable the PID control of the ``PIDSubsystem``. When the subsystem is enabled, it will automatically run the control loop and track the setpoint. When it is disabled, no control is performed.

Additionally, the ``enable()`` method resets the internal ``PIDController``, and the ``disable()`` method calls the user-defined `useOutput()`_ method with both output and setpoint set to ``0``.

Full PIDSubsystem Example
^^^^^^^^^^^^^^^^^^^^^^^^^

What does a ``PIDSubsystem`` look like when used in practice? The following examples are taken from the FrisbeeBot example project (`Java <https://github.com/wpilibsuite/allwpilib/tree/main/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/frisbeebot>`__, `C++ <https://github.com/wpilibsuite/allwpilib/tree/main/wpilibcExamples/src/main/cpp/examples/Frisbeebot>`__):

.. tab-set::

.. tab-item:: Java
:sync: Java

.. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.1.1/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/frisbeebot/subsystems/ShooterSubsystem.java
:language: java
:lines: 5-
:linenos:
:lineno-start: 5

.. tab-item:: C++
:sync: C++ (Header)

.. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.1.1/wpilibcExamples/src/main/cpp/examples/Frisbeebot/include/subsystems/ShooterSubsystem.h
:language: c++
:lines: 5-
:linenos:
:lineno-start: 5

.. tab-item:: C++ (Source)
:sync: C++ (Source)

.. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.1.1/wpilibcExamples/src/main/cpp/examples/Frisbeebot/cpp/subsystems/ShooterSubsystem.cpp
:language: c++
:lines: 5-
:linenos:
:lineno-start: 5

Using a ``PIDSubsystem`` with commands can be very simple:

.. tab-set::

.. tab-item:: Java
:sync: Java

.. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.1.1/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/frisbeebot/RobotContainer.java
:language: java
:lines: 26-27, 80-87

.. tab-item:: C++
:sync: C++ (Header)

.. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.1.1/wpilibcExamples/src/main/cpp/examples/Frisbeebot/include/RobotContainer.h
:language: c++
:lines: 45-49
:linenos:
:lineno-start: 45

.. tab-item:: C++ (Source)
:sync: C++ (Source)

.. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.1.1/wpilibcExamples/src/main/cpp/examples/Frisbeebot/cpp/RobotContainer.cpp
:language: c++
:lines: 25-31
:linenos:
:lineno-start: 25
One of the most common control algorithms used in FRC\ |reg| is the :term:`PID` controller. WPILib offers its own :ref:`PIDController <docs/software/advanced-controls/controllers/pidcontroller:PID Control in WPILib>` class to help teams implement this functionality on their robots. To further help teams integrate PID control into a command-based robot project, the command-based library includes a convenience wrapper for the ``PIDController`` class: ``PIDCommand``, which integrates the PID controller into a command.

PIDCommand
----------
Expand Down Expand Up @@ -209,7 +51,7 @@ When subclassing ``PIDCommand``, additional modifications (e.g. enabling continu
measurementSource
~~~~~~~~~~~~~~~~~

The ``measurementSource`` parameter is a function (usually passed as a :ref:`lambda <docs/software/commandbased/index:Lambda Expressions (Java)>`) that returns the measurement of the process variable. Passing in the ``measurementSource`` function in ``PIDCommand`` is functionally analogous to overriding the `getMeasurement()`_ function in ``PIDSubsystem``.
The ``measurementSource`` parameter is a function (usually passed as a :ref:`lambda <docs/software/commandbased/index:Lambda Expressions (Java)>`) that returns the measurement of the process variable.

When subclassing ``PIDCommand``, advanced users may further modify the measurement supplier by modifying the class's ``m_measurement`` field.

Expand All @@ -223,7 +65,7 @@ When subclassing ``PIDCommand``, advanced users may further modify the setpoint
useOutput
~~~~~~~~~

The ``useOutput`` parameter is a function (usually passed as a :ref:`lambda <docs/software/commandbased/index:Lambda Expressions (Java)>`) that consumes the output and setpoint of the control loop. Passing in the ``useOutput`` function in ``PIDCommand`` is functionally analogous to overriding the `useOutput()`_ function in ``PIDSubsystem``.
The ``useOutput`` parameter is a function (usually passed as a :ref:`lambda <docs/software/commandbased/index:Lambda Expressions (Java)>`) that consumes the output and setpoint of the control loop.

When subclassing ``PIDCommand``, advanced users may further modify the output consumer by modifying the class's ``m_useOutput`` field.

Expand Down
139 changes: 4 additions & 135 deletions source/docs/software/commandbased/profile-subsystems-commands.rst
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
Motion Profiling through TrapezoidProfileSubsystems and TrapezoidProfileCommands
Motion Profiling through TrapezoidProfileCommands
================================================================================

.. note:: For a description of the WPILib motion profiling features used by these command-based wrappers, see :ref:`docs/software/advanced-controls/controllers/trapezoidal-profiles:Trapezoidal Motion Profiles in WPILib`.
Expand All @@ -7,138 +7,7 @@ Motion Profiling through TrapezoidProfileSubsystems and TrapezoidProfileCommands

When controlling a mechanism, is often desirable to move it smoothly between two positions, rather than to abruptly change its setpoint. This is called "motion-profiling," and is supported in WPILib through the ``TrapezoidProfile`` class (`Java <https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/trajectory/TrapezoidProfile.html>`__, `C++ <https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_trapezoid_profile.html>`__).

To further help teams integrate motion profiling into their command-based robot projects, WPILib includes two convenience wrappers for the ``TrapezoidProfile`` class: ``TrapezoidProfileSubsystem``, which automatically generates and executes motion profiles in its ``periodic()`` method, and the ``TrapezoidProfileCommand``, which executes a single user-provided ``TrapezoidProfile``.

TrapezoidProfileSubsystem
-------------------------

.. note:: In C++, the ``TrapezoidProfileSubsystem`` class is templated on the unit type used for distance measurements, which may be angular or linear. The passed-in values *must* have units consistent with the distance units, or a compile-time error will be thrown. For more information on C++ units, see :ref:`docs/software/basic-programming/cpp-units:The C++ Units Library`.

The ``TrapezoidProfileSubsystem`` class (`Java <https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/TrapezoidProfileSubsystem.html>`__, `C++ <https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_trapezoid_profile_subsystem.html>`__) will automatically create and execute trapezoidal motion profiles to reach the user-provided goal state. To use the ``TrapezoidProfileSubsystem`` class, users must create a subclass of it.

Creating a TrapezoidProfileSubsystem
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. note:: If ``periodic`` is overridden when inheriting from ``TrapezoidProfileSubsystem``, make sure to call ``super.periodic()``! Otherwise, motion profiling functionality will not work properly.

When subclassing ``TrapezoidProfileSubsystem``, users must override a single abstract method to provide functionality that the class will use in its ordinary operation:

useState()
~~~~~~~~~~

.. tab-set::

.. tab-item:: Java
:sync: Java

.. rli:: https://github.com/wpilibsuite/allwpilib/raw/v2024.3.2/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/TrapezoidProfileSubsystem.java
:language: java
:lines: 105-105

.. tab-item:: C++
:sync: C++

.. rli:: https://github.com/wpilibsuite/allwpilib/raw/v2024.3.2/wpilibNewCommands/src/main/native/include/frc2/command/TrapezoidProfileSubsystem.h
:language: c++
:lines: 75-75

The ``useState()`` method consumes the current state of the motion profile. The ``TrapezoidProfileSubsystem`` will automatically call this method from its ``periodic()`` block, and pass it the motion profile state corresponding to the subsystem's current progress through the motion profile.

Users may do whatever they want with this state; a typical use case (as shown in the `Full TrapezoidProfileSubsystem Example`_) is to use the state to obtain a setpoint and a feedforward for an external "smart" motor controller.

Constructor Parameters
~~~~~~~~~~~~~~~~~~~~~~

Users must pass in a set of ``TrapezoidProfile.Constraints`` to the ``TrapezoidProfileSubsystem`` base class through the superclass constructor call of their subclass. This serves to constrain the automatically-generated profiles to a given maximum velocity and acceleration.

Users must also pass in an initial position for the mechanism.

Advanced users may pass in an alternate value for the loop period, if a non-standard main loop period is being used.

Using a TrapezoidProfileSubsystem
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Once an instance of a ``TrapezoidProfileSubsystem`` subclass has been created, it can be used by commands through the following methods:

setGoal()
~~~~~~~~~

.. note:: If you wish to set the goal to a simple distance with an implicit target velocity of zero, an overload of ``setGoal()`` exists that takes a single distance value, rather than a full motion profile state.

The ``setGoal()`` method can be used to set the goal state of the ``TrapezoidProfileSubsystem``. The subsystem will automatically execute a profile to the goal, passing the current state at each iteration to the provided `useState()`_ method.

.. tab-set-code::

.. code-block:: java
// The subsystem will execute a profile to a position of 5 and a velocity of 3.
examplePIDSubsystem.setGoal(new TrapezoidProfile.State(5, 3);
.. code-block:: c++
// The subsystem will execute a profile to a position of 5 meters and a velocity of 3 mps.
examplePIDSubsyste.SetGoal({5_m, 3_mps});
enable() and disable()
~~~~~~~~~~~~~~~~~~~~~~
The ``enable()`` and ``disable()`` methods enable and disable the motion profiling control of the ``TrapezoidProfileSubsystem``. When the subsystem is enabled, it will automatically run the control loop and call ``useState()`` periodically. When it is disabled, no control is performed.
Full TrapezoidProfileSubsystem Example
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
What does a ``TrapezoidProfileSubsystem`` look like when used in practice? The following examples are taking from the ArmbotOffobard example project (`Java <https://github.com/wpilibsuite/allwpilib/tree/main/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/armbotoffboard>`__, `C++ <https://github.com/wpilibsuite/allwpilib/tree/main/wpilibcExamples/src/main/cpp/examples/ArmBotOffboard>`__):
.. tab-set::
.. tab-item:: Java
:sync: Java
.. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.3.2/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/armbotoffboard/subsystems/ArmSubsystem.java
:language: java
:lines: 5-
:linenos:
:lineno-start: 5
.. tab-item:: C++ (Header)
:sync: C++ (Header)
.. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.3.2/wpilibcExamples/src/main/cpp/examples/ArmBotOffboard/include/subsystems/ArmSubsystem.h
:language: c++
:lines: 5-
:linenos:
:lineno-start: 5
.. tab-item:: C++ (Source)
:sync: C++ (Source)
.. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.3.2/wpilibcExamples/src/main/cpp/examples/ArmBotOffboard/cpp/subsystems/ArmSubsystem.cpp
:language: c++
:lines: 5-
:linenos:
:lineno-start: 5
Using a ``TrapezoidProfileSubsystem`` with commands can be quite simple:
.. tab-set::
.. tab-item:: Java
:sync: Java
.. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.3.2/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/armbotoffboard/RobotContainer.java
:language: java
:lines: 52-58
:linenos:
:lineno-start: 52
.. tab-item:: C++
:sync: C++
.. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.3.2/wpilibcExamples/src/main/cpp/examples/ArmBotOffboard/cpp/RobotContainer.cpp
:language: c++
:lines: 25-30
:linenos:
:lineno-start: 25
To further help teams integrate motion profiling into their command-based robot projects, WPILib includes a convenience wrapper for the ``TrapezoidProfile`` class: ``TrapezoidProfileCommand``, which executes a single user-provided ``TrapezoidProfile``.

TrapezoidProfileCommand
-----------------------
Expand Down Expand Up @@ -184,7 +53,7 @@ The ``profile`` parameter is the ``TrapezoidProfile`` object that will be execut
output
~~~~~~

The ``output`` parameter is a function (usually passed as a :ref:`lambda <docs/software/commandbased/index:Lambda Expressions (Java)>`) that consumes the output and setpoint of the control loop. Passing in the ``useOutput`` function in ``PIDCommand`` is functionally analogous to overriding the `useState()`_ function in ``PIDSubsystem``.
The ``output`` parameter is a function (usually passed as a :ref:`lambda <docs/software/commandbased/index:Lambda Expressions (Java)>`) that consumes the output and setpoint of the control loop.

goal
~~~~
Expand All @@ -204,7 +73,7 @@ Like all inlineable commands, ``TrapezoidProfileCommand`` allows the user to spe
Full TrapezoidProfileCommand Example
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

What does a ``TrapezoidProfileSubsystem`` look like when used in practice? The following examples are taking from the DriveDistanceOffboard example project (`Java <https://github.com/wpilibsuite/allwpilib/tree/main/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/drivedistanceoffboard>`__, `C++ <https://github.com/wpilibsuite/allwpilib/tree/main/wpilibcExamples/src/main/cpp/examples/DriveDistanceOffboard>`__):
What does a ``TrapezoidProfileCommand`` look like when used in practice? The following examples are taking from the DriveDistanceOffboard example project (`Java <https://github.com/wpilibsuite/allwpilib/tree/main/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/drivedistanceoffboard>`__, `C++ <https://github.com/wpilibsuite/allwpilib/tree/main/wpilibcExamples/src/main/cpp/examples/DriveDistanceOffboard>`__):

.. tab-set::

Expand Down
Loading

0 comments on commit 23d3351

Please sign in to comment.