Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/.vitepress/config.mts
Original file line number Diff line number Diff line change
Expand Up @@ -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' },
],
Expand Down
2 changes: 1 addition & 1 deletion docs/curriculum/challenges/command-groups.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
300 changes: 300 additions & 0 deletions docs/curriculum/robot-fundamentals/command-groups.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,300 @@
# 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.

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`

Runs commands one after another. Each command has to finish before the next one starts.

```java
new SequentialCommandGroup(
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 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
the rest get interrupted.

```java
new ParallelRaceGroup(
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 finishes, and
the others get interrupted. **The first command you pass in is the deadline.**

```java
new ParallelDeadlineGroup(
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
a command instead of creating the group class yourself.

### `.andThen(...)`

Runs commands **in sequence**, one after another.

```java
deployIntakeCommand
.andThen(driveToGamePieceCommand)
.andThen(shootCommand);
```

Same as:

```java
new SequentialCommandGroup(
deployIntakeCommand,
driveToGamePieceCommand,
shootCommand
);
```

### `.alongWith(...)`

Runs commands **in parallel**. Ends when **all** of them finish.

```java
spinUpShooterCommand.alongWith(aimHoodCommand);
```

Same as:

```java
new ParallelCommandGroup(spinUpShooterCommand, aimHoodCommand);
```

### `.raceWith(...)`

Runs commands **in parallel**, but ends when **any** of them ends. The rest get interrupted.

```java
collectUntilGamePieceCommand.raceWith(new WaitCommand(3));
```

Same as:

```java
new ParallelRaceGroup(collectUntilGamePieceCommand, new WaitCommand(3));
```

### `.deadlineFor(...)`

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
driveToGamePieceCommand.deadlineFor(runCollectorCommand, runHopperCommand);
```

Same as:

```java
new ParallelDeadlineGroup(
driveToGamePieceCommand,
runCollectorCommand,
runHopperCommand
);
```

::: 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 build a whole routine. Here's the full autonomous from this
page:

```java
Command auto = deployIntakeCommand
.andThen(driveToGamePieceCommand.deadlineFor(runCollectorCommand, runHopperCommand))
.andThen(spinUpShooterCommand.alongWith(aimHoodCommand))
.andThen(feedShooterCommand.withTimeout(1));
```

Step by step:

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.

## Things to know

- 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
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.
Loading