Add commands v3 documentation pages by SamCarlberg · Pull Request #3339 · wpilibsuite/wpilib-docs

SamCarlberg · 2026-08-03T01:10:34Z

Note that some docs reference not-yet-committed WPILib changes (wpilibsuite/allwpilib#9207)

sciencewhiz

Here's some initial comments. Also update new for 2027 to link to the documentation.

sciencewhiz · 2026-08-04T15:28:42Z

+
+.. tab-set-code::
+
+  ```java


To improve maintainability, lets make these and all other "complete" code snippets into snippets in allwpilib and reference via RLIs.

Yup. I plan on moving them when the code snippets are approved here. It's annoying to reference them across repos

Removed a lot of unnecessary tab-set-code and replaced others with manual tab-sets with descriptive tab labels

Co-authored-by: Dan Katzuv <31829093+katzuv@users.noreply.github.com>

PeterJohnson · 2026-08-21T02:00:48Z

@codex review

sciencewhiz

A few more comments, haven't been able to get through everything yet

This should update the 2027 overview to link to the documentation instead of the confernce/design doc.

The examples page should be updated with the commands v3 examples

sciencewhiz · 2026-08-22T16:39:35Z

@@ -0,0 +1,83 @@
+# State Machines with Commands


I think this article could benefit from a more complex example that demonstrates why State machines are beneficial for complex commands. The existing code example seems like something that could easily be done without a state machine

sciencewhiz · 2026-08-22T16:41:08Z

@@ -0,0 +1,83 @@
+# State Machines with Commands
+
+The `StateMachine <https://github.wpilib.org/allwpilib/docs/beta/java/org/wpilib/command3/StateMachine.html>`__ class provides a way to define complex behavior as a series of states and transitions. Each state in a state machine runs a single ``Command``, and transitions define when the state machine should move from one state to another.


Use md style links throughout https://docs.wpilib.org/en/stable/docs/contributing/frc-docs/style-guide.html#external-links

sciencewhiz · 2026-08-22T16:44:59Z

+
+Mechanisms should be declared as ``public final`` fields in the robot class and initialized in the field declaration or in the constructor. The former makes the code a little more concise, while the latter allows for flexibility if different mechanism implementations exist.
+
+.. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/main/wpilibjExamples/src/main/java/org/wpilib/examples/rebuiltcmdv3/Robot.java


use the :lines: and :lineno-match: feature to remove boilerplate like the license and and package. For things in the WPILib repository, we usually start on line 7 for that reason. https://docs.wpilib.org/en/stable/docs/contributing/frc-docs/style-guide.html#rli-remote-literal-include

sciencewhiz · 2026-08-22T22:13:15Z

+2. ``IntakeWrist``, for controlling the deployment of the intake
+3. ``Intake``, which combines both the rollers and the wrist
+
+.. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/main/wpilibjExamples/src/main/java/org/wpilib/examples/rebuiltcmdv3/mechanisms/Intake.java


Three long code blocks right after each other run together. Add a header for each one, and consider putting them in the same order as the list above

sciencewhiz · 2026-08-22T22:14:25Z

+
+.. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/main/wpilibjExamples/src/main/java/org/wpilib/examples/rebuiltcmdv3/opmodes/auto/SweepAuto.java
+
+## Mechanism-level Commands


Would it make sense to put this right after mechanisms?

sciencewhiz · 2026-08-22T22:14:38Z

+```
+
+
+## Multi-Mechanism Commands


sciencewhiz · 2026-08-22T22:19:21Z

+
+### Greedy Loops (Compile-time)
+
+If you write a ``while`` loop in a command that is missing a ``coroutine.yield()`` call, the WPILib compiler plugin will issue an error. This is because a loop that never yields will starve the rest of the robot program, preventing other commands from running and sensor data from being updated.


For the issues that cause a compile time error, include the error message, since that's what people would be searching for

SamCarlberg added 2 commits August 2, 2026 21:09

Add commands v3 documentation pages

de18976

Fix scopes ref and swap clause order

737cbe9

sciencewhiz requested a review from jasondaming August 4, 2026 15:11

sciencewhiz reviewed Aug 4, 2026

View reviewed changes

SamCarlberg added 3 commits August 5, 2026 22:18

Update code examples

2c4a548

Removed a lot of unnecessary tab-set-code and replaced others with manual tab-sets with descriptive tab labels

Move yield-in-loop warning and add note for Java-only

8844370

Update creating-commands

03dbcca

SamCarlberg force-pushed the commandsv3 branch from 18e2788 to 03dbcca Compare August 6, 2026 02:28

SamCarlberg added 4 commits August 5, 2026 22:29

Define DSL

bf68cb5

Use "custom periodic functions" to define sideloads

ee0af83

Remove dangling text

8e20c27

Update telemetry

3e3bc59

katzuv reviewed Aug 6, 2026

View reviewed changes

Comment thread source/docs/software/commandbased/commands-v3/how-it-works.rst Outdated

SamCarlberg and others added 3 commits August 6, 2026 07:56

Remove extra backtick

a5b6f4e

Co-authored-by: Dan Katzuv <31829093+katzuv@users.noreply.github.com>

Cleanup migration code sample code

ee2ad9f

Discourage one-shot commands for actuation

cad04c5

sciencewhiz reviewed Aug 22, 2026

View reviewed changes

		@@ -0,0 +1,83 @@
		# State Machines with Commands

		The `StateMachine <https://github.wpilib.org/allwpilib/docs/beta/java/org/wpilib/command3/StateMachine.html>`__ class provides a way to define complex behavior as a series of states and transitions. Each state in a state machine runs a single ``Command``, and transitions define when the state machine should move from one state to another.


		Mechanisms should be declared as ``public final`` fields in the robot class and initialized in the field declaration or in the constructor. The former makes the code a little more concise, while the latter allows for flexibility if different mechanism implementations exist.

		.. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/main/wpilibjExamples/src/main/java/org/wpilib/examples/rebuiltcmdv3/Robot.java


		.. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/main/wpilibjExamples/src/main/java/org/wpilib/examples/rebuiltcmdv3/opmodes/auto/SweepAuto.java

		## Mechanism-level Commands


		### Greedy Loops (Compile-time)

		If you write a ``while`` loop in a command that is missing a ``coroutine.yield()`` call, the WPILib compiler plugin will issue an error. This is because a loop that never yields will starve the rest of the robot program, preventing other commands from running and sensor data from being updated.

Uh oh!

Conversation

SamCarlberg commented Aug 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sciencewhiz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

PeterJohnson commented Aug 21, 2026

Uh oh!

sciencewhiz left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

SamCarlberg commented Aug 3, 2026 •

edited

Loading