LESSON 18

Command Composition

You have written commands that do one thing while a button is held. An autonomous routine is a list of those commands, run in order. This lesson builds the list.

12 minutes

You’ll need

An Arm with vertical() and horizontal(), and a Flywheel with runSlow(), runFast() and stop(), from Motion Magic in Code.
A MyTeleop with working button bindings, from OpModes.
The simulator running, from Hardware Simulation.

Every mechanism command you have written so far is a hold. runRepeatedly(...) re-sends the same request every loop and never ends.

So the work comes in two parts: give a command an ending, then glue the endings together in order.

Holds and steps

A hold never reports that it is finished, so a list containing one stops there for good. Step two never runs. Nothing errors and nothing logs, so the routine looks frozen.

.withTimeout(...) wraps a command and ends it after a fixed time, finished or not. That turns a hold into a step, something with a beginning and an end. Steps are what you can put in a list.

A hold, and the same hold as a step

1import static org.wpilib.units.Units.Seconds;
2 
3// A hold. Drives to vertical and keeps holding it, never finishes.
4robot.arm.vertical()
5 
6// A step. Holds vertical for one second, then ends.
7robot.arm.vertical().withTimeout(Seconds.of(1.0))

The import static line is what lets you write Seconds rather than Units.Seconds every time. .withTimeout(...) refuses a bare 1.0. It takes a Time, so nobody can pass milliseconds where seconds were meant.

Steps in order

Command.sequence(a, b, c) runs a until it finishes, then b, then c. You write autonomous routines in exactly this shape.

MyTeleop.java: raise the arm, then spin up

1Command spinUpWhenReady =
2    Command.sequence(
3            // A step: it ends, so the sequence moves on.
4            robot.arm.vertical().withTimeout(Seconds.of(1.0)),
5            // A hold: the last member, so the group is a hold too.
6            robot.flywheel.runFast())
7        .named("Spin Up When Ready (hold)");

A sequence is itself a small coroutine. Its body is one loop that calls coroutine.await(member) on each member in turn, and Coroutines writes that call by hand.

Command.sequence(...) returns a builder rather than a Command. .named("...") is what finishes it, and leaving it off will not compile. Name the group after what it does. If the group is a hold, end the name with (hold), the way the mechanism commands do.

Do not re-name a command that already has one. robot.arm.vertical() is already finished, so .named(...) on it is a compile error.

DON'T

A bare hold in the middle

Swap the first member for a plain robot.arm.vertical() and the sequence sticks there for the rest of the match. When a routine looks frozen, a member with no ending is the first thing to check.

Two things at once

A sequence is this, then that. A race is this while that. Command.race(...) starts every member at the same time and cancels the rest as soon as one finishes.

Spin the flywheel while the arm holds position

1Command spinWhileHolding =
2    Command.race(
3            robot.flywheel.runFast().withTimeout(Seconds.of(2.0)),
4            robot.arm.horizontal())
5        .named("Spin While Holding Arm");

The flywheel member has an ending and the arm hold does not, so the flywheel decides when the group ends. A hold can never win a race. Other teams call this pattern a deadline. Commands v3 spells it Command.race(...), and there is no Command.deadline(...).

Bind the group

A group is a command, so it binds the same way a single command does. whileTrue runs the group while the button is held and cancels it on release. Canceling sends nothing to the motors, as Hardware Simulation showed, so the release sends a stop of its own.

MyTeleop.java: one button, both mechanisms

1driver.y().whileTrue(spinUpWhenReady).whileFalse(robot.flywheel.stop());

The last member decides whether a group ends at all. End on a hold and the group is a hold. End on a step and the group finishes by itself, and the last request stays latched, so the stop belongs inside the group.

Check your work

Add the Seconds import and the Spin Up When Ready (hold) binding to your MyTeleop constructor.
Start the simulator and click Enable.
Hold Y for three seconds, then release.
Now break it on purpose. Drop .withTimeout(...) off the arm member, hold Y again, then put the timeout back.
Bind Y to robot.flywheel.runFast().withTimeout(Seconds.of(1.0)) on its own instead and hold it for two seconds. The step ends after one second and the flywheel stays at 75 rotations per second, because nothing claimed it afterwards. A closing robot.flywheel.stop().withTimeout(Seconds.of(0.5)) step is the fix.

Check

You should see

The arm drives to vertical and holds there for one second, then the flywheel spins up.
The flywheel holds while Y is down and stops when you release it.
With the timeout gone, the arm reaches vertical and the flywheel never starts.

These three failures look nothing alike.

What you see	Cause
The arm moves and the flywheel never starts	A member with no ending ahead of it.
The group will not compile	No `.named("...")`, or `.named(...)` on a command that already had one.
Both mechanisms move together	A `Command.race` where you meant `Command.sequence`.

Get this binding working in the simulator. Finish Conditions is next and replaces the stopwatch on the arm member with the arm's own report that it arrived.