wpilibsuite · jasondaming · Nov 13, 2025 · Nov 13, 2025 · Nov 13, 2025 · Nov 13, 2025
diff --git a/source/docs/software/advanced-controls/controllers/pidcontroller.rst b/source/docs/software/advanced-controls/controllers/pidcontroller.rst
@@ -2,7 +2,7 @@
 
 .. note:: This article focuses on in-code implementation of PID control in WPILib. For a conceptual explanation of the working of a PIDController, see :ref:`docs/software/advanced-controls/introduction/introduction-to-pid:Introduction to PID`
 
-.. note:: For a guide on implementing PID control through the :ref:`command-based framework <docs/software/commandbased/what-is-command-based:What Is "Command-Based" Programming?>`, see :ref:`docs/software/commandbased/pid-subsystems-commands:PID Control in Command-based`.
+.. note:: For a guide on implementing PID control through the :ref:`command-based framework <docs/software/commandbased/commands-v2/what-is-command-based:What Is "Command-Based" Programming?>`, see :ref:`docs/software/commandbased/commands-v2/pid-subsystems-commands:PID Control in Command-based`.
 
 WPILib supports PID control of mechanisms through the ``PIDController`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/controller/PIDController.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_p_i_d_controller.html), :external:py:class:`Python <wpimath.controller.PIDController>`).  This class handles the feedback loop calculation for the user, as well as offering methods for returning the error, setting tolerances, and checking if the control loop has reached its setpoint within the specified tolerances.
 

diff --git a/source/docs/software/advanced-controls/controllers/profiled-pidcontroller.rst b/source/docs/software/advanced-controls/controllers/profiled-pidcontroller.rst
@@ -1,6 +1,6 @@
 # Combining Motion Profiling and PID Control with ProfiledPIDController
 
-.. note:: For a guide on implementing the ``ProfiledPIDController`` class in the :ref:`command-based framework <docs/software/commandbased/what-is-command-based:What Is "Command-Based" Programming?>` framework, see :ref:`docs/software/commandbased/profilepid-subsystems-commands:Combining Motion Profiling and PID in Command-Based`.
+.. note:: For a guide on implementing the ``ProfiledPIDController`` class in the :ref:`command-based framework <docs/software/commandbased/commands-v2/what-is-command-based:What Is "Command-Based" Programming?>` framework, see :ref:`docs/software/commandbased/commands-v2/profilepid-subsystems-commands:Combining Motion Profiling and PID in Command-Based`.
 
 In the previous article, we saw how to use the ``TrapezoidProfile`` class to create and use a trapezoidal motion profile.  The example code from that article demonstrates manually composing the ``TrapezoidProfile`` class with the external PID control feature of a "smart" motor controller.
 

diff --git a/source/docs/software/advanced-controls/controllers/trapezoidal-profiles.rst b/source/docs/software/advanced-controls/controllers/trapezoidal-profiles.rst
@@ -4,7 +4,7 @@
 
 .. note:: This article covers the in-code generation of trapezoidal motion profiles.  Documentation describing the involved concepts in more detail is forthcoming.
 
-.. note:: For a guide on implementing the ``TrapezoidProfile`` class in the :ref:`command-based framework <docs/software/commandbased/what-is-command-based:What Is "Command-Based" Programming?>` framework, see :doc:`/docs/software/commandbased/profile-subsystems-commands`.
+.. note:: For a guide on implementing the ``TrapezoidProfile`` class in the :ref:`command-based framework <docs/software/commandbased/commands-v2/what-is-command-based:What Is "Command-Based" Programming?>` framework, see :doc:`/docs/software/commandbased/commands-v2/profile-subsystems-commands`.
 
 .. note:: The ``TrapezoidProfile`` class, used on its own, is most useful when composed with a custom controller (such as a "smart" motor controller with a built-in PID functionality).  To integrate it with a WPILib ``PIDController``, see :doc:`profiled-pidcontroller`.
 

diff --git a/source/docs/software/basic-programming/functions-as-data.rst b/source/docs/software/basic-programming/functions-as-data.rst
@@ -10,7 +10,7 @@ Typically, code that calls a function is coupled to (depends on) the definition
 
 For example, WPILib offers several ways for users to execute certain code whenever a joystick button is pressed - one of the easiest and cleanest ways to do this is to allow the user to *pass a function* to one of the WPILib joystick methods.  This way, the user only has to write the code that deals with the interesting and team-specific things (e.g., "move my robot arm") and not the boring, error-prone, and universal thing ("properly read button inputs from a standard joystick").
 
-For another example, the :ref:`Command-based framework <docs/software/commandbased/what-is-command-based:What Is "Command-Based" Programming?>` is built on ``Command`` objects that refer to methods defined on various ``Subsystem`` classes.  Many of the included ``Command`` types (such as ``InstantCommand`` and ``RunCommand``) work with *any* function - not just functions associated with a single ``Subsystem``.  To support building commands generically, we need to support passing functions from a ``Subsystem`` (which interacts with the hardware) to a ``Command`` (which interacts with the scheduler).
+For another example, the :ref:`Command-based framework <docs/software/commandbased/commands-v2/what-is-command-based:What Is "Command-Based" Programming?>` is built on ``Command`` objects that refer to methods defined on various ``Subsystem`` classes.  Many of the included ``Command`` types (such as ``InstantCommand`` and ``RunCommand``) work with *any* function - not just functions associated with a single ``Subsystem``.  To support building commands generically, we need to support passing functions from a ``Subsystem`` (which interacts with the hardware) to a ``Command`` (which interacts with the scheduler).
 
 In these cases, we want to be able to pass a single function as a piece of data, as if it were a variable - it doesn't make sense to ask the user to provide an entire class, when we really just want them to give us a single appropriately-shaped function.
 
@@ -24,7 +24,7 @@ Java represents functions-as-data as instances of [functional interfaces](https:
 
 This might sound complicated, but in the context of WPILib we don't really need to worry much about using the functional interfaces themselves - the code that does that is internal to WPILib.  Instead, all we need to know is how to pass a function that we've written to a method that takes a functional interface as a parameter.  For a simple example, consider the signature of ``Commands.runOnce`` (which creates an ``InstantCommand`` that, when scheduled, runs the given function once and then terminates):
 
-.. note:: The ``requirements`` parameter is explained in the :ref:`Command-based documentation <docs/software/commandbased/commands:getRequirements>`, and will not be discussed here.
+.. note:: The ``requirements`` parameter is explained in the :ref:`Command-based documentation <docs/software/commandbased/commands-v2/commands:getRequirements>`, and will not be discussed here.
 ```java
 public static Command runOnce(Runnable action, Subsystem... requirements)
 ```
@@ -104,7 +104,7 @@ In WPILibC, function types are represented with the ``std::function`` class (htt
 
 This sounds a lot more complicated than it is to use in practice.  Let's look at the call signature of ``cmd::RunOnce`` (which creates an ``InstantCommand`` that, when scheduled, runs the given function once and then terminates):
 
-.. note:: The ``requirements`` parameter is explained in the :ref:`Command-based documentation <docs/software/commandbased/commands:getRequirements>`, and will not be discussed here.
+.. note:: The ``requirements`` parameter is explained in the :ref:`Command-based documentation <docs/software/commandbased/commands-v2/commands:getRequirements>`, and will not be discussed here.
 
 ```c++
 CommandPtr RunOnce(

diff --git a/source/docs/software/basic-programming/joystick.rst b/source/docs/software/basic-programming/joystick.rst
@@ -4,7 +4,7 @@
 
 A joystick can be used with the Driver Station program to control the robot.  Almost any "controller" that can be recognized by Windows can be used as a joystick.  Joysticks are accessed using the ``GenericHID`` class.  This class has three relevant subclasses for preconfigured joysticks.  You may also implement your own for other controllers by extending ``GenericHID``.  The first is ``Joystick`` which is useful for standard flight joysticks.  The second is ``XboxController`` which works for the Xbox 360, Xbox One, or Logitech F310 (in XInput mode).  Finally, the ``PS4Controller`` class is ideal for using that controller.  Each axis of the controller ranges from -1 to 1.
 
-The command based way to use the these classes is detailed in the section: :ref:`docs/software/commandbased/binding-commands-to-triggers:Binding Commands to Triggers`.
+The command based way to use the these classes is detailed in the section: :ref:`docs/software/commandbased/commands-v2/binding-commands-to-triggers:Binding Commands to Triggers`.
 
 ## Driver Station Joysticks
 
@@ -136,7 +136,7 @@ An axis can be used with ``.getRawAxis(int index)`` (if not using any of the cla
 
 ## Button Usage
 
-.. note:: Usage such as the following is for code not using the command-based framework. For button usage in the command-based framework, see :ref:`docs/software/commandbased/binding-commands-to-triggers:Binding Commands to Triggers`.
+.. note:: Usage such as the following is for code not using the command-based framework. For button usage in the command-based framework, see :ref:`docs/software/commandbased/commands-v2/binding-commands-to-triggers:Binding Commands to Triggers`.
 
 Unlike an axis, you will usually want to use the ``pressed`` and ``released`` methods to respond to button input.  These will return true if the button has been activated since the last check.  This is helpful for taking an action once when the event occurs but not having to continuously do it while the button is held down.
 

diff --git a/...andbased/binding-commands-to-triggers.rst → ...mands-v2/binding-commands-to-triggers.rst b/...andbased/binding-commands-to-triggers.rst → ...mands-v2/binding-commands-to-triggers.rst
diff --git a/...are/commandbased/command-compositions.rst → ...ased/commands-v2/command-compositions.rst b/...are/commandbased/command-compositions.rst → ...ased/commands-v2/command-compositions.rst
@@ -327,4 +327,4 @@ Command compositions can also be written as a constructor-only subclass of the m
          :lines: 7-
          :lineno-match:
 
-The advantages and disadvantages of this subclassing approach in comparison to others are discussed in :ref:`docs/software/commandbased/organizing-command-based:Subclassing Command Groups`.
+The advantages and disadvantages of this subclassing approach in comparison to others are discussed in :ref:`docs/software/commandbased/commands-v2/organizing-command-based:Subclassing Command Groups`.
diff --git a/...ftware/commandbased/command-scheduler.rst → ...ndbased/commands-v2/command-scheduler.rst b/...ftware/commandbased/command-scheduler.rst → ...ndbased/commands-v2/command-scheduler.rst
@@ -19,7 +19,7 @@ To schedule a command, users call the ``schedule()`` method ([Java](https://gith
 This method walks through the following steps:
 
 #. Verifies that the command isn't in a composition.
-#. :term:`No-op` if scheduler is disabled, command is already scheduled, or robot is disabled and command doesn't :ref:`docs/software/commandbased/commands:runsWhenDisabled`.
+#. :term:`No-op` if scheduler is disabled, command is already scheduled, or robot is disabled and command doesn't :ref:`docs/software/commandbased/commands-v2/commands:runsWhenDisabled`.
 #. If requirements are in use:
 
    * If all conflicting commands are interruptible, cancel them.

diff --git a/...e/docs/software/commandbased/commands.rst → ...are/commandbased/commands-v2/commands.rst b/...e/docs/software/commandbased/commands.rst → ...are/commandbased/commands-v2/commands.rst
@@ -98,7 +98,7 @@ As a rule, command compositions are ``kCancelIncoming`` if all their components
 
 ## Included Command Types
 
-The command-based library includes many pre-written command types. Through the use of :ref:`lambdas <docs/software/commandbased/index:Lambda Expressions (Java)>`, these commands can cover almost all use cases and teams should rarely need to write custom command classes. Many of these commands are provided via static factory functions in the ``Commands`` utility class (Java), in the ``frc2::cmd`` namespace defined in the ``Commands.h`` header (C++), or in the ``commands2.cmd`` namespace (Python). In Java and C++, classes inheriting from ``Subsystem`` also have instance methods that implicitly require ``this``.
+The command-based library includes many pre-written command types. Through the use of :ref:`lambdas <docs/software/commandbased/commands-v2/index:Lambda Expressions (Java)>`, these commands can cover almost all use cases and teams should rarely need to write custom command classes. Many of these commands are provided via static factory functions in the ``Commands`` utility class (Java), in the ``frc2::cmd`` namespace defined in the ``Commands.h`` header (C++), or in the ``commands2.cmd`` namespace (Python). In Java and C++, classes inheriting from ``Subsystem`` also have instance methods that implicitly require ``this``.
 
 ### Running Actions
 
@@ -306,7 +306,7 @@ To wait until a certain condition becomes ``true``, the library offers the ``Com
 
 There are commands for various control setups:
 
-- ``TrapezoidProfile`` tracks a trapezoid motion profile. For more info, see :doc:`/docs/software/commandbased/profile-subsystems-commands`.
+- ``TrapezoidProfile`` tracks a trapezoid motion profile. For more info, see :doc:`/docs/software/commandbased/commands-v2/profile-subsystems-commands`.
 
 - ``MecanumControllerCommand`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/MecanumControllerCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_mecanum_controller_command.html)) is useful for controlling mecanum drivetrains. See API docs and the **MecanumControllerCommand** ([Java](https://github.com/wpilibsuite/allwpilib/tree/2027/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/mecanumcontrollercommand), [C++](https://github.com/wpilibsuite/allwpilib/tree/2027/wpilibcExamples/src/main/cpp/examples/MecanumControllerCommand)) example project for more info.
 

diff --git a/...e/commandbased/cpp-command-discussion.rst → ...ed/commands-v2/cpp-command-discussion.rst b/...e/commandbased/cpp-command-discussion.rst → ...ed/commands-v2/cpp-command-discussion.rst
@@ -3,7 +3,7 @@
 
 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<Base, Derived>``, 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 :ref:`below <docs/software/commandbased/cpp-command-discussion:2023 Updates>`.
+.. note:: The model was further changed in 2023, as described :ref:`below <docs/software/commandbased/commands-v2/cpp-command-discussion:2023 Updates>`.
 
 ## Ownership Model
 The old command-based framework employed the use of raw pointers, meaning that users had to use ``new`` (resulting in manual heap allocations) in their robot code. Since there was no clear indication on who owned the commands (the scheduler, the command groups, or the user themselves), it was not apparent who was supposed to take care of freeing the memory.
@@ -167,7 +167,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 :ref:`above <docs/software/commandbased/cpp-command-discussion: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 <docs/software/commandbased/commands-v2/cpp-command-discussion: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.
 
 ### ``CommandPtr``
 

diff --git a/...d/diagrams/concurrent-commands.drawio.svg → ...2/diagrams/concurrent-commands.drawio.svg b/...d/diagrams/concurrent-commands.drawio.svg → ...2/diagrams/concurrent-commands.drawio.svg
diff --git a/...iagrams/scheduler-run-sequence.drawio.svg → ...iagrams/scheduler-run-sequence.drawio.svg b/...iagrams/scheduler-run-sequence.drawio.svg → ...iagrams/scheduler-run-sequence.drawio.svg
diff --git a/...ommandbased/diagrams/scheduler.drawio.svg → ...commands-v2/diagrams/scheduler.drawio.svg b/...ommandbased/diagrams/scheduler.drawio.svg → ...commands-v2/diagrams/scheduler.drawio.svg
diff --git a/...agrams/subsystems-and-commands.drawio.svg → ...agrams/subsystems-and-commands.drawio.svg b/...agrams/subsystems-and-commands.drawio.svg → ...agrams/subsystems-and-commands.drawio.svg
diff --git a/source/docs/software/commandbased/commands-v2/index.rst b/source/docs/software/commandbased/commands-v2/index.rst
@@ -0,0 +1,53 @@
+# Commands v2 Programming
+
+This sequence of articles serves as an introduction to and reference for the WPILib Commands v2 framework.
+
+Commands v2 is the stable, production-ready command-based framework that supports Java, C++, and Python. It uses a declarative programming style with method chaining and lambda expressions to compose robot behaviors.
+
+.. note:: Commands v2 will continue to be supported and maintained. Java teams may also consider :ref:`docs/software/commandbased/commands-v3/index:Commands v3 Programming`, which offers an imperative programming style with coroutines.
+
+For a collection of example projects using Commands v2, see :ref:`docs/software/examples-tutorials/wpilib-examples:Command-Based Examples`.
+
+.. toctree::
+   :maxdepth: 1
+
+   what-is-command-based
+   commands
+   command-compositions
+   subsystems
+   binding-commands-to-triggers
+   structuring-command-based-project
+   organizing-command-based
+   command-scheduler
+   cpp-command-discussion
+   pid-subsystems-commands
+   profile-subsystems-commands
+   profilepid-subsystems-commands
+
+## Why Commands v2?
+
+Commands v2 is recommended for:
+
+- **Multi-language support**: Full support for Java, C++, and Python
+- **Proven stability**: Battle-tested across thousands of FRC robots
+- **Rich ecosystem**: Extensive examples, tutorials, and community resources
+- **Team flexibility**: Works well for teams of all experience levels
+- **Broad platform support**: Works on roboRIO, simulation, and coprocessors
+
+## Passing Functions As Parameters
+
+In order to provide a concise inline syntax, the command-based library often accepts functions as parameters of constructors, factories, and decorators. Fortunately, both Java and C++ offer users the ability to :ref:`pass functions as objects <docs/software/basic-programming/functions-as-data:Treating Functions as Data>`:
+
+### Method References (Java)
+
+In Java, a reference to a function that can be passed as a parameter is called a method reference. The general syntax for a method reference is ``object::method`` or ``Class::staticMethod``. Note that no method parameters are included, since the method *itself* is passed. The method is not being called - it is being passed to another piece of code (in this case, a command) so that *that* code can call it when needed. For further information on method references, see :ref:`docs/software/basic-programming/functions-as-data:Method References`.
+
+### Lambda Expressions (Java)
+
+While method references work well for passing a function that has already been written, often it is inconvenient/wasteful to write a function solely for the purpose of sending as a method reference, if that function will never be used elsewhere. To avoid this, Java also supports a feature called "lambda expressions." A lambda expression is an inline method definition - it allows a function to be defined *inside of a parameter list*. For specifics on how to write Java lambda expressions, see :ref:`docs/software/basic-programming/functions-as-data:Lambda Expressions in Java`.
+
+### Lambda Expressions (C++)
+
+.. warning:: Due to complications in C++ semantics, capturing ``this`` in a C++ lambda can cause a null pointer exception if done from a component command of a command composition.  Whenever possible, C++ users should capture relevant command members explicitly and by value.  For more details, see [here](https://github.com/wpilibsuite/allwpilib/issues/3109).
+
+C++ lacks a close equivalent to Java method references - pointers to member functions are generally not directly usable as parameters due to the presence of the implicit ``this`` parameter.  However, C++ does offer lambda expressions - in addition, the lambda expressions offered by C++ are in many ways more powerful than those in Java.  For specifics on how to write C++ lambda expressions, see :ref:`docs/software/basic-programming/functions-as-data:Lambda Expressions in C++`.