From a2bd7bee76d76da6864471acb02cd2e53b50fe82 Mon Sep 17 00:00:00 2001 From: Alex Schokking Date: Sat, 7 Nov 2026 12:52:16 -0800 Subject: [PATCH 1/3] Migrate Command Groups page from SCL wiki Moves the SeriouslyCommonLib wiki's Command-Groups article into the docs site as a Reference page, and points the Command Groups challenge at it. Co-Authored-By: Claude Opus 5.5 --- docs/.vitepress/config.mts | 1 + docs/curriculum/challenges/command-groups.md | 2 +- .../robot-fundamentals/command-groups.md | 158 ++++++++++++++++++ 3 files changed, 160 insertions(+), 1 deletion(-) create mode 100644 docs/curriculum/robot-fundamentals/command-groups.md diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 21521ab..777029a 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -86,6 +86,7 @@ export default defineConfig({ { text: 'Robot Architecture', link: '/curriculum/robot-fundamentals/robot-architecture' }, { text: 'Robot Coordinate Conventions', link: '/curriculum/robot-fundamentals/coordinate-conventions' }, { text: 'Mapping Buttons to Commands', link: '/curriculum/robot-fundamentals/operator-command-map' }, + { text: 'Command Groups', link: '/curriculum/robot-fundamentals/command-groups' }, { text: 'Git Introduction', link: '/curriculum/getting-started/git-introduction' }, { text: 'Clone with GitHub Desktop', link: '/curriculum/getting-started/clone-with-github-desktop' }, ], diff --git a/docs/curriculum/challenges/command-groups.md b/docs/curriculum/challenges/command-groups.md index 3c751c8..f986aef 100644 --- a/docs/curriculum/challenges/command-groups.md +++ b/docs/curriculum/challenges/command-groups.md @@ -7,7 +7,7 @@ This often comes up in the context of autonomous mode, where in the first 15s of ## Learning about CommandGroup classes -Read the short article here: [Command Groups](https://github.com/Team488/SeriouslyCommonLib/wiki/Command-Groups) +Read the short article here: [Command Groups](/curriculum/robot-fundamentals/command-groups) ## Test your knowledge diff --git a/docs/curriculum/robot-fundamentals/command-groups.md b/docs/curriculum/robot-fundamentals/command-groups.md new file mode 100644 index 0000000..b458b17 --- /dev/null +++ b/docs/curriculum/robot-fundamentals/command-groups.md @@ -0,0 +1,158 @@ +# Command Groups + +Command groups let you combine several commands into one bigger command. You can run commands one +after another, all at the same time, or at the same time until one of them finishes. + +There are two ways to build them: the **group classes** and the shorter **builder syntax**. Both do +the same thing. + +## Group classes + +### `SequentialCommandGroup` + +Runs commands one after another. Each command has to finish before the next one starts. + +```java +new SequentialCommandGroup( + new DriveForwardCommand(2.0), + new TurnToAngleCommand(90), + new ShootCommand() +); +``` + +### `ParallelCommandGroup` + +Runs all commands at the same time. The group finishes when **all** of the commands have finished. + +```java +new ParallelCommandGroup( + new DriveForwardCommand(3.0), + new SpinShooterCommand() +); +``` + +### `ParallelRaceGroup` + +Runs all commands at the same time. The group finishes as soon as **any one** command finishes, and +the rest get interrupted. + +```java +new ParallelRaceGroup( + new WaitCommand(5), + new IntakeCommand() +); +``` + +### `ParallelDeadlineGroup` + +Runs all commands at the same time. The group finishes when the **deadline** command (the first +one) finishes, and the others get interrupted. + +```java +new ParallelDeadlineGroup( + new WaitCommand(3), // deadline command + new IntakeCommand(), + new ConveyorCommand() +); +``` + +## Builder syntax + +Every `Command` also has methods that build these same groups with less code. You chain them onto +a command instead of creating the group class yourself. + +### `.andThen(...)` + +Runs commands **in sequence**, one after another. + +```java +driveForwardCommand + .andThen(turnCommand) + .andThen(intakeCommand); +``` + +Same as: + +```java +new SequentialCommandGroup( + driveForwardCommand, + turnCommand, + intakeCommand +); +``` + +### `.alongWith(...)` + +Runs commands **in parallel**. Ends when **all** of them finish. + +```java +driveCommand.alongWith(shootCommand); +``` + +Same as: + +```java +new ParallelCommandGroup(driveCommand, shootCommand); +``` + +### `.raceWith(...)` + +Runs commands **in parallel**, but ends when **any** of them ends. The rest get interrupted. + +```java +intakeCommand.raceWith(new WaitCommand(3)); +``` + +Same as: + +```java +new ParallelRaceGroup(intakeCommand, new WaitCommand(3)); +``` + +### `.deadlineWith(...)` + +Runs commands in parallel, but ends when the **original** command (the one you called it on) +finishes. The others get interrupted. + +```java +new WaitCommand(3).deadlineWith(intakeCommand, conveyorCommand); +``` + +Same as: + +```java +new ParallelDeadlineGroup( + new WaitCommand(3), + intakeCommand, + conveyorCommand +); +``` + +## Mixing patterns + +You can chain the builder methods to put together longer routines: + +```java +shootCommand + .alongWith(indexCommand) + .andThen(driveCommand) + .raceWith(new WaitCommand(10)); +``` + +Each method wraps everything before it. Here, shooting and indexing run together, then the robot +drives, and the whole sequence gets cut off if it takes longer than 10 seconds. + +## Things to know + +- Each builder method returns a **new** `Command`. You can store it in a variable like any other + command: + + ```java + Command auto = intakeCommand + .raceWith(new WaitCommand(5)) + .andThen(driveForwardCommand); + ``` + +- Once a command is part of a group, it belongs to that group. You can't add the same command + instance to a second group, or to the same group twice, and you can't schedule it on its own + anymore. If you need the same action more than once, create a separate instance each time. From 94e68eeb154811866a38db3b216d0f1b903da2de Mon Sep 17 00:00:00 2001 From: Alex Schokking Date: Sat, 7 Nov 2026 13:02:17 -0800 Subject: [PATCH 2/3] Command Groups: realistic examples with explanations, deadlineFor Each group now walks through one autonomous routine (deploy intake, drive and collect, aim and shoot) with a short explanation and a 'use it when' line. Adds a summary table, calls out which command is the deadline and how a deadline group differs from a race, and replaces the deprecated deadlineWith with deadlineFor (WPILib 2025+). Co-Authored-By: Claude Opus 5.5 --- .../robot-fundamentals/command-groups.md | 146 ++++++++++++------ 1 file changed, 102 insertions(+), 44 deletions(-) diff --git a/docs/curriculum/robot-fundamentals/command-groups.md b/docs/curriculum/robot-fundamentals/command-groups.md index b458b17..cd4f454 100644 --- a/docs/curriculum/robot-fundamentals/command-groups.md +++ b/docs/curriculum/robot-fundamentals/command-groups.md @@ -6,6 +6,20 @@ after another, all at the same time, or at the same time until one of them finis There are two ways to build them: the **group classes** and the shorter **builder syntax**. Both do the same thing. +The examples on this page follow one robot through a typical autonomous routine: deploy the +intake, drive over and pick up a game piece, then shoot it. The command names are made up for +these examples, but they match the kinds of subsystems a real robot has (drive, intake, collector, +shooter, hood). + +## Choosing a group + +| Group | Runs commands... | Finishes when... | +|-------|------------------|------------------| +| `SequentialCommandGroup` | one after another | the last command finishes | +| `ParallelCommandGroup` | all at once | **every** command has finished | +| `ParallelRaceGroup` | all at once | **any** command finishes | +| `ParallelDeadlineGroup` | all at once | **one specific** command (the deadline) finishes | + ## Group classes ### `SequentialCommandGroup` @@ -14,23 +28,37 @@ Runs commands one after another. Each command has to finish before the next one ```java new SequentialCommandGroup( - new DriveForwardCommand(2.0), - new TurnToAngleCommand(90), + new DeployIntakeCommand(), + new DriveToPositionCommand(gamePieceLocation), new ShootCommand() ); ``` +First the robot lowers its intake and waits until it's all the way down. Then it drives to the game +piece. Only once it has arrived does it shoot. + +**Use it when** order matters, and each step depends on the one before it being done. You can't +drive into a game piece with the intake still folded up. + ### `ParallelCommandGroup` Runs all commands at the same time. The group finishes when **all** of the commands have finished. ```java new ParallelCommandGroup( - new DriveForwardCommand(3.0), - new SpinShooterCommand() + new SpinUpShooterCommand(), + new AimHoodCommand(shotAngle) ); ``` +Before taking a shot, the shooter wheels need to reach speed and the hood needs to move to the +right angle. Neither step depends on the other, so the robot does both at once. The group finishes +only when both are ready, so whatever comes next (like feeding the game piece into the shooter) +won't start too early. + +**Use it when** you have independent steps that all need to finish before you move on. Running +them together saves time, which matters a lot in a 15-second autonomous. + ### `ParallelRaceGroup` Runs all commands at the same time. The group finishes as soon as **any one** command finishes, and @@ -38,24 +66,49 @@ the rest get interrupted. ```java new ParallelRaceGroup( - new WaitCommand(5), - new IntakeCommand() + new CollectUntilGamePieceCommand(), + new WaitCommand(3) ); ``` +The collector runs until its sensor sees a game piece. But if the robot missed it, the collector +could keep spinning forever and the rest of autonomous would never happen. The `WaitCommand` is a +backup: whichever finishes first ends the group. The robot either gets the game piece, or gives up +after 3 seconds and moves on. + +**Use it when** there are several ways for a step to be "done" and any of them is good enough. +The most common use is adding a timeout, like above. + +::: tip +Timeouts are so common that every command has a shortcut for this: +`new CollectUntilGamePieceCommand().withTimeout(3)` does the same thing. +::: + ### `ParallelDeadlineGroup` -Runs all commands at the same time. The group finishes when the **deadline** command (the first -one) finishes, and the others get interrupted. +Runs all commands at the same time. The group finishes when the **deadline** command finishes, and +the others get interrupted. **The first command you pass in is the deadline.** ```java new ParallelDeadlineGroup( - new WaitCommand(3), // deadline command - new IntakeCommand(), - new ConveyorCommand() + new DriveToPositionCommand(gamePieceLocation), // deadline: the group ends when this ends + new RunCollectorCommand(), + new RunHopperCommand() ); ``` +The robot drives toward the game piece while running its collector and hopper, so it can grab the +game piece without stopping. `RunCollectorCommand` and `RunHopperCommand` never finish on their +own. They just keep the rollers spinning until something stops them. That's why the drive is the +deadline: once the robot reaches the spot, the group ends and the rollers stop. + +**Use it when** one command decides how long the whole step lasts, and the others are "helpers" +that should run alongside it for exactly that long. + +How is this different from a race? In a race, *any* command finishing ends the group. If you used +a race here and the collector command happened to finish early, the robot would stop driving +partway there. A deadline group only listens to the deadline. + ## Builder syntax Every `Command` also has methods that build these same groups with less code. You chain them onto @@ -66,18 +119,18 @@ a command instead of creating the group class yourself. Runs commands **in sequence**, one after another. ```java -driveForwardCommand - .andThen(turnCommand) - .andThen(intakeCommand); +deployIntakeCommand + .andThen(driveToGamePieceCommand) + .andThen(shootCommand); ``` Same as: ```java new SequentialCommandGroup( - driveForwardCommand, - turnCommand, - intakeCommand + deployIntakeCommand, + driveToGamePieceCommand, + shootCommand ); ``` @@ -86,13 +139,13 @@ new SequentialCommandGroup( Runs commands **in parallel**. Ends when **all** of them finish. ```java -driveCommand.alongWith(shootCommand); +spinUpShooterCommand.alongWith(aimHoodCommand); ``` Same as: ```java -new ParallelCommandGroup(driveCommand, shootCommand); +new ParallelCommandGroup(spinUpShooterCommand, aimHoodCommand); ``` ### `.raceWith(...)` @@ -100,58 +153,63 @@ new ParallelCommandGroup(driveCommand, shootCommand); Runs commands **in parallel**, but ends when **any** of them ends. The rest get interrupted. ```java -intakeCommand.raceWith(new WaitCommand(3)); +collectUntilGamePieceCommand.raceWith(new WaitCommand(3)); ``` Same as: ```java -new ParallelRaceGroup(intakeCommand, new WaitCommand(3)); +new ParallelRaceGroup(collectUntilGamePieceCommand, new WaitCommand(3)); ``` -### `.deadlineWith(...)` +### `.deadlineFor(...)` -Runs commands in parallel, but ends when the **original** command (the one you called it on) -finishes. The others get interrupted. +Runs commands in parallel, but ends when the **original** command (the one you call it on) +finishes. The others get interrupted. Read it as "this command is the deadline for these others." ```java -new WaitCommand(3).deadlineWith(intakeCommand, conveyorCommand); +driveToGamePieceCommand.deadlineFor(runCollectorCommand, runHopperCommand); ``` Same as: ```java new ParallelDeadlineGroup( - new WaitCommand(3), - intakeCommand, - conveyorCommand + driveToGamePieceCommand, + runCollectorCommand, + runHopperCommand ); ``` -## Mixing patterns +::: warning +Older code and examples may use `.deadlineWith(...)`. It does the same thing, but WPILib has +deprecated it and will remove it, so use `.deadlineFor(...)` in new code. +::: + +## Putting it together -You can chain the builder methods to put together longer routines: +You can chain the builder methods to build a whole routine. Here's the full autonomous from this +page: ```java -shootCommand - .alongWith(indexCommand) - .andThen(driveCommand) - .raceWith(new WaitCommand(10)); +Command auto = deployIntakeCommand + .andThen(driveToGamePieceCommand.deadlineFor(runCollectorCommand, runHopperCommand)) + .andThen(spinUpShooterCommand.alongWith(aimHoodCommand)) + .andThen(feedShooterCommand.withTimeout(1)); ``` -Each method wraps everything before it. Here, shooting and indexing run together, then the robot -drives, and the whole sequence gets cut off if it takes longer than 10 seconds. +Step by step: -## Things to know +1. Lower the intake. +2. Drive to the game piece with the collector and hopper running, and stop them when the robot + arrives. +3. Spin up the shooter and aim the hood at the same time, and wait until both are ready. +4. Feed the game piece into the shooter for 1 second. -- Each builder method returns a **new** `Command`. You can store it in a variable like any other - command: +## Things to know - ```java - Command auto = intakeCommand - .raceWith(new WaitCommand(5)) - .andThen(driveForwardCommand); - ``` +- Each builder method returns a **new** `Command`. You can store it in a variable (like `auto` + above) and use it like any other command. - Once a command is part of a group, it belongs to that group. You can't add the same command instance to a second group, or to the same group twice, and you can't schedule it on its own From fd80c80ccc0db76a63fa563ab8dfc9ff4b5d347f Mon Sep 17 00:00:00 2001 From: Alex Schokking Date: Sat, 7 Nov 2026 13:05:34 -0800 Subject: [PATCH 3/3] Command Groups: add full three-piece autonomous example Shows nested groups, helper methods that build fresh command instances, mixing group classes with builder syntax, and overlapping steps to save time. Also notes that commands in a parallel group can't share a subsystem. Co-Authored-By: Claude Opus 5.5 --- .../robot-fundamentals/command-groups.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) diff --git a/docs/curriculum/robot-fundamentals/command-groups.md b/docs/curriculum/robot-fundamentals/command-groups.md index cd4f454..5177926 100644 --- a/docs/curriculum/robot-fundamentals/command-groups.md +++ b/docs/curriculum/robot-fundamentals/command-groups.md @@ -214,3 +214,87 @@ Step by step: - Once a command is part of a group, it belongs to that group. You can't add the same command instance to a second group, or to the same group twice, and you can't schedule it on its own anymore. If you need the same action more than once, create a separate instance each time. + +- Two commands in the same parallel group can't use (require) the same subsystem. For example, + you can't drive to a spot and run a different drive command at the same time, because both need + the drive subsystem. Commands in a sequential group can share subsystems, since only one runs at + a time. + +## A full autonomous routine + +Real autonomous routines get longer than the example above. Since every group is itself a +`Command`, you can put groups inside other groups, as many levels deep as you need. Here's a +routine that scores the game piece the robot starts with, then picks up and scores two more: + +```java +public Command threePieceAuto() { + return new SequentialCommandGroup( + // Score the preloaded game piece, and lower the intake at the same time + new ParallelCommandGroup( + aimAndShoot(), + new DeployIntakeCommand() + ), + + // Go get the first game piece and score it + driveAndCollect(firstGamePieceLocation), + driveBackAndShoot(), + + // Go get the second game piece and score it + driveAndCollect(secondGamePieceLocation), + driveBackAndShoot() + ); +} + +// Spin up and aim at the same time, then feed the game piece into the shooter +private Command aimAndShoot() { + return new SpinUpShooterCommand() + .alongWith(new AimHoodCommand(shotAngle)) + .andThen(new FeedShooterCommand().withTimeout(1)); +} + +// Drive to a game piece with the rollers running. If the robot doesn't have +// the game piece once it arrives, keep collecting for up to 1.5 more seconds. +private Command driveAndCollect(Pose2d gamePieceLocation) { + return new DriveToPositionCommand(gamePieceLocation) + .deadlineFor(new RunCollectorCommand(), new RunHopperCommand()) + .andThen(new CollectUntilGamePieceCommand().withTimeout(1.5)); +} + +// Drive back to the shooting spot while getting the shooter ready, then shoot +private Command driveBackAndShoot() { + return new ParallelCommandGroup( + new DriveToPositionCommand(shootingSpot), + new SpinUpShooterCommand(), + new AimHoodCommand(shotAngle) + ) + .andThen(new FeedShooterCommand().withTimeout(1)); +} +``` + +Here's what the robot does: + +1. **Preload.** The shooter spins up and the hood aims at the same time, then the game piece is + fed into the shooter. The intake lowers while all of that is happening, since it doesn't need + the shooter. The step ends once the shot is done *and* the intake is down. +2. **First game piece.** The robot drives to it with the collector and hopper running. Arriving + at the spot ends that part (the drive is the deadline). If the robot still doesn't have the + game piece, it keeps collecting for up to 1.5 seconds, so a near miss doesn't throw off the + rest of the routine. +3. **Score it.** On the way back, the robot spins up the shooter and aims the hood while it + drives, so it's ready to shoot the moment it arrives. It only shoots once all three are done. +4. **Second game piece.** Same as steps 2 and 3, at a different location. + +A few things worth noticing: + +- **Helper methods keep it readable.** The top-level `threePieceAuto()` reads almost like the + list above. Each step's details live in their own method with a name that says what it does. +- **Helper methods also create fresh commands.** `driveBackAndShoot()` is used twice. Because it + builds new commands with `new` every time it's called, each use gets its own instances. If you + created one `driveBackAndShoot` command and put it in the sequence twice, it would fail, because + a command can only be in one group. +- **You can mix both styles.** The top level uses group classes, and the helpers use builder + methods. They make the same kinds of groups, so use whichever is easier to read for each part. +- **Overlap saves time.** Most steps do something useful while waiting on something else: + aiming while driving, collecting while driving, lowering the intake while shooting. A + 15-second autonomous goes by fast, so doing things in parallel is how a good routine fits in + more game pieces.