Coroutines

A sequence is already a small coroutine that awaits each member in turn. It stays the default, and a chained routine that works should stay chained.

Write the body yourself for one of two reasons. A hold has to span several steps, which a list cannot do. Or the logic needs a real loop or branch, and a coroutine body is ordinary Java, so while and if work as usual.

A coroutine body takes one argument, an object called coroutine. These five calls on it cover nearly every routine, in the order you will reach for them.

1// 1. Wait for a condition, with a limit. On a timeout, stop what you started and leave.
2if (coroutine.waitUntil(() -> robot.arm.isAtTarget(), Seconds.of(3.0)).timedOut()) {
3  return;
4}
5 
6// 2. Start a hold and keep going. It runs underneath until the routine ends.
7coroutine.fork(robot.arm.vertical());
8 
9// 3. Run a step that ends by itself, and wait here until it does.
10coroutine.await(raiseArm); // the .until(...) step from Finish Conditions
11 
12// 4. Wait a fixed time. Forked holds keep running through it.
13coroutine.wait(Seconds.of(1.0));
14 
15// 5. Inside a loop of your own: give up the rest of this robot loop.
16while (!robot.arm.isAtTarget()) {
17  coroutine.yield();
18}

waitUntil returns a WaitResult. House style calls .timedOut() on it in the same line, and stores it only when it is read twice. It is declared inside Coroutine, so the bare name needs import org.wpilib.command3.Coroutine.WaitResult;.

fork and await return a ForkResult for a command that could not start. The routine cancels itself when that happens, so you can ignore it. park, awaitAll and awaitAny exist too. Nothing here needs them.

Example 5 is what waitUntil does inside. The yield makes one pass one robot loop, and without it nothing else on the robot gets a turn. If while is new, do the Loops module of Codecademy's Learn Java before Drive to Tag.

Rules two and three differ in what they claim. run(...) holds its mechanism for the whole body. noRequirements claims nothing, and each fork claims its own mechanism only while it runs.

The diff adds one file and changes nothing else: src/main/java/first/robot/opmode/RaiseAndShootOpMode.java. Four steps.

Step 1: The empty shell

1package first.robot.opmode;
2 
3import first.robot.Robot;
4import org.wpilib.command3.Command;
5import org.wpilib.command3.Coroutine;
6import org.wpilib.command3.Scheduler;
7import org.wpilib.opmode.Autonomous;
8import org.wpilib.opmode.PeriodicOpMode;
9 
10@Autonomous(name = "Raise And Shoot")
11public class RaiseAndShootOpMode extends PeriodicOpMode {
12  private final Robot robot;
13  private final Command routine;
14 
15  public RaiseAndShootOpMode(Robot robot) {
16    this.robot = robot;
17    routine =
18        Command.noRequirements(coroutine -> raiseAndShoot(coroutine)).named("Raise And Shoot");
19  }
20 
21  private void raiseAndShoot(Coroutine coroutine) {
22    // Steps 2 to 4 go in here.
23  }
24 
25  /** No trigger owns this routine, so the OpMode starts and stops it. */
26  @Override
27  public void start() {
28    Scheduler.getDefault().schedule(routine);
29  }
30 
31  @Override
32  public void end() {
33    Scheduler.getDefault().cancel(routine);
34  }
35}

Paste the whole shell. No button binds this routine, so start() and end() schedule and cancel it. Build now and Raise And Shoot appears in the autonomous list, doing nothing.

Step 2: Fork the arm hold

1// fork, not await: vertical() is a hold and never finishes.
2coroutine.fork(robot.arm.vertical());

Run it and the arm barely twitches. That is correct. The body has no lines after the fork, so the routine ends on its first pass, and ending a routine cancels everything it forked.

Step 3: Wait, with a limit

Add import static org.wpilib.units.Units.Seconds; first. Every build runs Spotless, which strips an import no line uses yet, so add it again if it vanishes.

1// TODO: time your own arm.
2if (coroutine.waitUntil(() -> robot.arm.isAtTarget(), Seconds.of(3.0)).timedOut()) {
3  // The flywheel never started, so there is nothing to stop.
4  return;
5}

This is the Y button's wait with a limit added. Three seconds is a placeholder: use the time you wrote down at the end of Finish Conditions, doubled.

Step 4: The flywheel, then the shot

1// The arm hold is still running. That is the point of fork.
2coroutine.fork(robot.flywheel.runFast());
3 
4if (coroutine.waitUntil(() -> robot.flywheel.isAtTarget(), Seconds.of(3.0)).timedOut()) {
5  coroutine.fork(robot.flywheel.stop());
6  return;
7}
8 
9coroutine.wait(Seconds.of(1.0)); // shoot
10 
11// stop() replaces runFast() and sends its zero on this loop, before the routine ends.
12coroutine.fork(robot.flywheel.stop());

Two forks are live now, the arm holding 90° while the flywheel climbs to 75 rotations per second. This branch has no feeder, so the one-second wait stands in for the shot.

Every way out from here forks stop() first. It shares the flywheel with runFast(), so it replaces it, and a forked command runs its first pass on the spot. The zero goes out before the routine ends.

Build it, run it, then break it on purpose.

1. Start the program with WPILib: Hardware Sim Robot Code and pick Raise And Shoot in the Driver Station. That name is the @Autonomous string, not the class name.
2. Time the run. A healthy one is the arm, plus the flywheel, plus one second, and then the flywheel coasts down.
3. Change the arm's tolerance to Degrees.of(0.001) and run again. Then delete the if and its return around the arm's wait and run once more. Put both back.
4. Last one. Change the first line to coroutine.await(robot.arm.vertical()) and run again. The arm moves and nothing else ever happens. Put the fork back.

Logging is next. It is how you read back a routine that ran with nobody watching.