diff --git a/source/docs/software/commandbased/command-based-changes.rst b/source/docs/software/commandbased/command-based-changes.rst deleted file mode 100644 index 297d6a4d77..0000000000 --- a/source/docs/software/commandbased/command-based-changes.rst +++ /dev/null @@ -1,83 +0,0 @@ -2020 Command-Based Rewrite: What Changed? -========================================= - -This article provides a summary of changes from the original command-based framework to the 2020 rewrite. This summary is not necessarily comprehensive - for rigorous documentation, as always, refer to the API docs (`Java `__, `C++ `__). - -Package Location ----------------- - -The new command-based framework is located in the ``wpilibj2`` package for Java, and in the ``frc2`` namespace for C++. The new framework must be installed using the instructions: :ref:`docs/software/vscode-overview/3rd-party-libraries:WPILib Command Libraries`. - -Major Architectural Changes ---------------------------- - -The overall structure of the command-based framework has remained largely the same. However, there are some still a few major architectural changes that users should be aware of: - -Commands and Subsystems as Interfaces -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -``Command`` (`Java `__, `C++ `__) and ``Subsystem`` (`Java `__, `C++ `__) are both now interfaces as opposed to abstract classes, allowing advanced users more potential flexibility. ``CommandBase`` and ``SubsystemBase`` abstract base classes are still provided for convenience, but are not required. For more information, see :doc:`commands` and :doc:`subsystems`. - -Multiple Command Group Classes -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``CommandGroup`` class no longer exists, and has been replaced by a number of narrower classes that can be recursively composed to create more-complicated group structures. For more information see :doc:`command-compositions`. - -Inline Command Definitions -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Previously, users were required to write a subclass of ``Command`` in almost all cases where a command was needed. Many of the new commands are designed to allow inline definition of command functionality, and so can be used without the need for an explicit subclass. For more information, see :ref:`docs/software/commandbased/commands:Included Command Types`. - -Injection of Command Dependencies -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -While not an actual change to the coding of the library, the recommended use pattern for the new command-based framework utilizes injection of subsystem dependencies into commands, so that subsystems are not declared as globals. This is a cleaner, more maintainable, and more reusable pattern than the global subsystem pattern promoted previously. For more information, see :doc:`structuring-command-based-project`. - -Command Ownership (C++ Only) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The previous command framework required users to use raw pointers for all commands, resulting in nearly-unavoidable memory leaks in all C++ command-based projects, as well as leaving room for common errors such as double-allocating commands within command-groups. - -The new command framework offers ownership management for all commands. Default commands and commands bound to buttons are typically owned by the scheduler, and component commands are owned by their encapsulating command groups. As a result, users should generally never heap-allocate a command with ``new`` unless there is a very good reason to do so. - -Transfer of ownership is done using `perfect forwarding `__, meaning rvalues will be *moved* and lvalues will be *copied* (`rvalue/lvalue explanation `__). - -Changes to the Scheduler ------------------------- - -* ``Scheduler`` has been renamed to ``CommandScheduler`` (`Java `__, `C++ `__). -* Interruptibility of commands is now the responsibility of the scheduler, not the commands, and can be specified during the call to ``schedule``. -* Users can now pass actions to the scheduler which are taken whenever a command is scheduled, interrupted, or ends normally. This is highly useful for cases such as event logging. - -Changes to Subsystem --------------------- - -.. note:: For more information on subsystems, see :doc:`subsystems`. - -* As noted earlier, ``Subsystem`` is now an interface (`Java `__, `C++ `__); the closest equivalent of the old ``Subsystem`` is the new ``SubsystemBase`` class. Many of the Sendable-related constructor overloads have been removed to reduce clutter; users can call the setters directly from their own constructor, if needed. -* ``initDefaultCommand`` has been removed; subsystems no longer need to "know about" their default commands, which are instead registered directly with the ``CommandScheduler``. The new ``setDefaultCommand`` method simply wraps the ``CommandScheduler`` call. -* Subsystems no longer "know about" the commands currently requiring them; this is handled exclusively by the ``CommandScheduler``. A convenience wrapper on the ``CommandScheduler`` method is provided, however. - -Changes to Command ------------------- - -.. note:: For more information on commands, see :doc:`commands`. - -* As noted earlier, ``Command`` is now an interface (`Java `__, `C++ `__); the closest equivalent of the old ``Command`` is the new ``CommandBase`` class. Many of the Sendable-related constructor overloads have been removed to reduce clutter; users can call the setters directly from their own constructor, if needed. -* Commands no longer handle their own scheduling state; this is now the responsibility of the scheduler. -* The ``interrupted()`` method has been rolled into the ``end()`` method, which now takes a parameter specifying whether the command was interrupted (``false`` if it ended normally). -* The ``requires()`` method has been renamed to ``addRequirement()``. -* ``void setRunsWhenDisabled(boolean disabled)`` has been replaced by an overridable :ref:`docs/software/commandbased/commands:runsWhenDisabled` method. -* ``void setInterruptible(boolean interruptible)`` has been replaced by an overridable :ref:`docs/software/commandbased/commands:getInterruptionBehavior` method. -* Several :ref:`"decorator" methods ` have been added to allow easy inline modification of commands (e.g. adding a timeout). -* (C++ only) In order to allow the decorators to work with the command ownership model, a :term:`CRTP` is used via the ``CommandHelper`` `class `__. Any user-defined Command subclass ``Foo`` *must* extend ``CommandHelper`` where ``Base`` is the desired base class. - -Changes to PIDSubsystem/PIDCommand ----------------------------------- - -.. note:: For more information, see :doc:`pid-subsystems-commands`, and :ref:`docs/software/advanced-controls/controllers/pidcontroller:PID Control in WPILib` - -* Following the changes to PIDController, these classes now run synchronously from the main robot loop. -* The ``PIDController`` is now injected through the constructor, removing many of the forwarding methods. It can be modified after construction with ``getController()``. -* ``PIDCommand`` is intended largely for inline use, as shown in the GyroDriveCommands example (`Java `__, `C++ `__). -* If users wish to use PIDCommand more "traditionally," overriding the protected ``returnPIDInput()`` and ``usePIDOutput(double output)`` methods has been replaced by modifying the protected ``m_measurement`` and ``m_useOutput`` fields. Similarly, rather than calling ``setSetpoint``, users can modify the protected ``m_setpoint`` field. diff --git a/source/docs/software/commandbased/cpp-command-discussion.rst b/source/docs/software/commandbased/cpp-command-discussion.rst index 0cc5e88798..79a0162dcc 100644 --- a/source/docs/software/commandbased/cpp-command-discussion.rst +++ b/source/docs/software/commandbased/cpp-command-discussion.rst @@ -4,7 +4,7 @@ A Technical Discussion on C++ Commands This article will help you understand the reasoning behind some of the decisions made in the 2020 command-based framework (such as the use of ``std::unique_ptr``, CRTP in the form of ``CommandHelper``, etc.). You do not need to understand the information within this article to use the command-based framework in your robot code. -.. note:: The model was further changed in 2023, as described `below <#2023 Updates>`_. +.. note:: The model was further changed in 2023, as described :ref:`below `. Ownership Model --------------- @@ -187,7 +187,7 @@ After a few years in the new command-based framework, the recommended way to cre A significant root cause of most pain points was commands being passed by value in a non-polymorphic way. This made object slicing mistakes rather easy, and changes in composition structure could propagate type changes throughout the codebase: for example, if a ``ParallelRaceGroup`` were changed to a ``ParallelDeadlineGroup``, those type changes would propagate through the codebase. Passing around the object as a ``Command`` (as done in Java) would result in object slicing. -Additionally, various decorators weren't supported in C++ due to reasons described `above <#Templating Decorators>`_. As long as decorators were rarely used and were mainly to reduce verbosity (where Java was more verbose than C++), this was less of a problem. Once heavy usage of decorators was recommended, this became more of an issue. +Additionally, various decorators weren't supported in C++ due to reasons described :ref:`above `. As long as decorators were rarely used and were mainly to reduce verbosity (where Java was more verbose than C++), this was less of a problem. Once heavy usage of decorators was recommended, this became more of an issue. ``CommandPtr`` ^^^^^^^^^^^^^^ diff --git a/source/docs/software/commandbased/index.rst b/source/docs/software/commandbased/index.rst index 8ae0c93c62..acf476bdbe 100644 --- a/source/docs/software/commandbased/index.rst +++ b/source/docs/software/commandbased/index.rst @@ -1,8 +1,6 @@ Command-Based Programming ========================= -.. note:: Old (pre-2020) command-based is no longer available in 2023. Users should migrate to the new command-based framework below. Documentation for old command-based is available `here `_. - This sequence of articles serves as an introduction to and reference for the WPILib command-based framework. For a collection of example projects using the command-based framework, see :ref:`docs/software/examples-tutorials/wpilib-examples:Command-Based Examples`. @@ -22,7 +20,6 @@ For a collection of example projects using the command-based framework, see :ref pid-subsystems-commands profile-subsystems-commands profilepid-subsystems-commands - command-based-changes Passing Functions As Parameters ------------------------------- diff --git a/source/redirects.txt b/source/redirects.txt index 22e710c31a..cbe9c04629 100644 --- a/source/redirects.txt +++ b/source/redirects.txt @@ -279,4 +279,4 @@ "docs/zero-to-robot/step-4/running-benchtop-test.rst" "docs/zero-to-robot/step-4/running-test-program.rst" "docs/zero-to-robot/step-1/how-to-wire-a-robot.rst" "docs/zero-to-robot/step-1/intro-to-frc-robot-wiring.rst" "docs/hardware/hardware-basics/wiring-pneumatics.rst" "docs/hardware/hardware-basics/wiring-pneumatics-pcm.rst" - +"docs/software/commandbased/command-based-changes.rst" "docs/software/commandbased/index.rst"