Skip to content

Commit

Permalink
Update TrapezoidProfile docs (#2301)
Browse files Browse the repository at this point in the history 
* Update TrapezoidProfile docs

* Update source/docs/software/advanced-controls/controllers/trapezoidal-profiles.rst

Co-authored-by: Tyler Veness <[email protected]>

---------

Co-authored-by: Tyler Veness <[email protected]>
  • Loading branch information
@Gold856 @calcmogul
Gold856 and calcmogul authored Aug 3, 2023
1 parent 7ac0fed commit 4072bf3
Show file tree
Hide file tree
Showing 2 changed files with 40 additions and 32 deletions.
34 changes: 16 additions & 18 deletions source/docs/software/advanced-controls/controllers/trapezoidal-profiles.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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::

Expand All @@ -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>`__):

Expand Down
38 changes: 24 additions & 14 deletions source/docs/software/commandbased/profile-subsystems-commands.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -144,7 +144,7 @@ The ``TrapezoidProfileCommand`` class (`Java <https://github.wpilib.org/allwpili
Creating a TrapezoidProfileCommand
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A ``TrapezoidProfileCommand`` can be created two ways - by subclassing the ``TrapezoidProfileCommand`` class, or by defining the command :ref:`inline <docs/software/commandbased/organizing-command-based:Inline Commands>`. 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 <docs/software/commandbased/organizing-command-based:Inline Commands>`. 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.

Expand All @@ -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 <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``.

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
~~~~~~~~~~~~

Expand All @@ -192,23 +202,23 @@ 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:
:lineno-start: 5

.. 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:
:lineno-start: 5

.. 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:
Expand All @@ -220,16 +230,16 @@ And, for an :ref:`inlined <docs/software/commandbased/organizing-command-based:I

.. group-tab:: Java

.. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2023.4.3/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/drivedistanceoffboard/RobotContainer.java
.. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/main/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/drivedistanceoffboard/RobotContainer.java
:language: java
:lines: 66-83
:lines: 66-85
:linenos:
:lineno-start: 66

.. group-tab:: C++

.. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2023.4.3/wpilibcExamples/src/main/cpp/examples/DriveDistanceOffboard/cpp/RobotContainer.cpp
.. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/main/wpilibcExamples/src/main/cpp/examples/DriveDistanceOffboard/cpp/RobotContainer.cpp
:language: c++
:lines: 37-56
:lines: 37-60
:linenos:
:lineno-start: 37

0 comments on commit 4072bf3

Please sign in to comment.