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..5177926 --- /dev/null +++ b/docs/curriculum/robot-fundamentals/command-groups.md @@ -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.