From 4072bf33cd2e9611bf527b99b7b987bc6bad0661 Mon Sep 17 00:00:00 2001 From: Gold856 <117957790+Gold856@users.noreply.github.com> Date: Wed, 2 Aug 2023 23:04:28 -0400 Subject: [PATCH] Update TrapezoidProfile docs (#2301) * Update TrapezoidProfile docs * Update source/docs/software/advanced-controls/controllers/trapezoidal-profiles.rst Co-authored-by: Tyler Veness --------- Co-authored-by: Tyler Veness --- .../controllers/trapezoidal-profiles.rst | 34 ++++++++--------- .../profile-subsystems-commands.rst | 38 ++++++++++++------- 2 files changed, 40 insertions(+), 32 deletions(-) diff --git a/source/docs/software/advanced-controls/controllers/trapezoidal-profiles.rst b/source/docs/software/advanced-controls/controllers/trapezoidal-profiles.rst index b77057b419..14e9e2af59 100644 --- 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,23 +74,15 @@ 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 profile{ - frc::TrapezoidProfile::Constraints{5_mps, 10_mps_sq}, - frc::TrapezoidProfile::State{5_m, 0_mps}, - frc::TrapezoidProfile::State{0_m, 0_mps}}; + frc::TrapezoidProfile::Constraints{5_mps, 10_mps_sq}}; Using a ``TrapezoidProfile`` ---------------------------- @@ -98,41 +90,47 @@ 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::State{5_m, 0_mps}, + frc::TrapezoidProfile::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 `__, `C++ `__): diff --git a/source/docs/software/commandbased/profile-subsystems-commands.rst b/source/docs/software/commandbased/profile-subsystems-commands.rst index 890b91b34a..c13add5cf5 100644 --- a/source/docs/software/commandbased/profile-subsystems-commands.rst +++ b/source/docs/software/commandbased/profile-subsystems-commands.rst @@ -144,7 +144,7 @@ The ``TrapezoidProfileCommand`` class (`Java `. Both methods ultimately extremely similar, and ultimately the choice of which to use comes down to where the user desires that the relevant code be located. +A ``TrapezoidProfileCommand`` can be created two ways - by subclassing the ``TrapezoidProfileCommand`` class, or by defining the command :ref:`inline `. Both methods are ultimately extremely similar, and ultimately the choice of which to use comes down to where the user desires that the relevant code be located. .. note:: If subclassing ``TrapezoidProfileCommand`` and overriding any methods, make sure to call the ``super`` version of those methods! Otherwise, motion profiling functionality will not work properly. @@ -154,30 +154,40 @@ In either case, a ``TrapezoidProfileCommand`` is created by passing the necessar .. group-tab:: Java - .. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2023.4.3/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/TrapezoidProfileCommand.java + .. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/main/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/TrapezoidProfileCommand.java :language: java - :lines: 25-34 + :lines: 28-43 :linenos: - :lineno-start: 25 + :lineno-start: 28 .. group-tab:: C++ - .. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2023.4.3/wpilibNewCommands/src/main/native/include/frc2/command/TrapezoidProfileCommand.h + .. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/main/wpilibNewCommands/src/main/native/include/frc2/command/TrapezoidProfileCommand.h :language: c++ - :lines: 35-45 + :lines: 35-49 :linenos: :lineno-start: 35 profile ~~~~~~~ -The ``profile`` parameter is the ``TrapezoidProfile`` object that will be executed by the command. By passing this in, users specify the start state, end state, and motion constraints of the profile that the command will use. +The ``profile`` parameter is the ``TrapezoidProfile`` object that will be executed by the command. By passing this in, users specify the motion constraints of the profile that the command will use. output ~~~~~~ The ``output`` parameter is a function (usually passed as a :ref:`lambda `) 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``. +goal +~~~~ + +The ``goal`` parameter is a function that supplies the desired state of the motion profile. This can be used to change the goal at runtime if desired. + +currentState +~~~~~~~~~~~~ + +The ``currentState`` parameter is a function that supplies the starting state of the motion profile. Combined with ``goal``, this can be used to dynamically generate and follow any motion profile at runtime. + requirements ~~~~~~~~~~~~ @@ -192,7 +202,7 @@ What does a ``TrapezoidProfileSubsystem`` look like when used in practice? The .. group-tab:: Java - .. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2023.4.3/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/drivedistanceoffboard/commands/DriveDistanceProfiled.java + .. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/main/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/drivedistanceoffboard/commands/DriveDistanceProfiled.java :language: java :lines: 5- :linenos: @@ -200,7 +210,7 @@ What does a ``TrapezoidProfileSubsystem`` look like when used in practice? The .. group-tab:: C++ (Header) - .. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2023.4.3/wpilibcExamples/src/main/cpp/examples/DriveDistanceOffboard/include/commands/DriveDistanceProfiled.h + .. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/main/wpilibcExamples/src/main/cpp/examples/DriveDistanceOffboard/include/commands/DriveDistanceProfiled.h :language: c++ :lines: 5- :linenos: @@ -208,7 +218,7 @@ What does a ``TrapezoidProfileSubsystem`` look like when used in practice? The .. group-tab:: C++ (Source) - .. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2023.4.3/wpilibcExamples/src/main/cpp/examples/DriveDistanceOffboard/cpp/commands/DriveDistanceProfiled.cpp + .. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/main/wpilibcExamples/src/main/cpp/examples/DriveDistanceOffboard/cpp/commands/DriveDistanceProfiled.cpp :language: c++ :lines: 5- :linenos: @@ -220,16 +230,16 @@ And, for an :ref:`inlined