LESSON 11

Mechanisms

A mechanism is one physical part of the robot, written as one Java class. On branch mech-1-Mechanisms you write Arm.java and Flywheel.java: hardware fields, one constructor, two methods.

Branchmech-1-Mechanisms14 minutes

You’ll need

A clean build, from Project Setup.
Fields, constructors and methods, from Java Basics.
Arm and flywheel working in Tuner X at IDs 31, 32 and 21.

Nice work

Setup is behind you

The arm and the flywheel work in Tuner X, the project builds, and you know what a mechanism, a command, and the scheduler each do. That is what every page before this one was for. This is the lesson where you start writing the code.

What mechanism are you working on?

The lesson below is written for the one you pick. Switch back any time to read it for the other.

Work in the project you generated in Project Setup. There is nothing to clone, and the file is new.

Both classes live in a mechanisms folder beside Robot.java, at src/main/java/first/robot/mechanisms/. Make the folder, then make the file in it.

The VS Code Explorer right-click menu on the robot folder, with New Folder circled in red — Right-click robot, not src or java. The folder has to land beside Robot.java, and one made a level up puts your class in the wrong package.

The VS Code Explorer right-click menu on the new mechanisms folder, with New File circled in red — New File, not New Java File. The Java option writes its own package and class lines, and you are about to paste both.

The hardware fields

Name the file Arm.javaFlywheel.java and paste this into it. The package line and the imports are the part you cannot work out from a lesson, so they are here in full. The class is empty and it compiles. The three comments mark the three places the rest of this lesson goes.

Arm.java: the empty class

1package first.robot.mechanisms;
2 
3// The static imports are the ones your editor will not offer to add for you.
4// Tuner X writes Volts.per(RotationsPerSecond) into the config you paste two
5// lessons from now, so they are here already and that paste just works.
6import static org.wpilib.units.Units.RotationsPerSecond;
7import static org.wpilib.units.Units.RotationsPerSecondPerSecond;
8import static org.wpilib.units.Units.Volts;
9 
10import com.ctre.phoenix6.CANBus;
11import com.ctre.phoenix6.configs.FeedbackConfigs;
12import com.ctre.phoenix6.configs.MotionMagicConfigs;
13import com.ctre.phoenix6.configs.MotorOutputConfigs;
14import com.ctre.phoenix6.configs.Slot0Configs;
15import com.ctre.phoenix6.configs.TalonFXConfiguration;
16import com.ctre.phoenix6.controls.MotionMagicVoltage;
17import com.ctre.phoenix6.controls.VoltageOut;
18import com.ctre.phoenix6.hardware.CANcoder;
19import com.ctre.phoenix6.hardware.TalonFX;
20import com.ctre.phoenix6.signals.FeedbackSensorSourceValue;
21import com.ctre.phoenix6.signals.GravityTypeValue;
22import com.ctre.phoenix6.signals.InvertedValue;
23import com.ctre.phoenix6.signals.NeutralModeValue;
24import org.wpilib.command3.Mechanism;
25 
26public class Arm extends Mechanism {
27  // The fields go here.
28 
29  public Arm() {
30    // The motor configuration goes here.
31  }
32 
33  // The two methods go here.
34}

Flywheel.java: the empty class

1package first.robot.mechanisms;
2 
3// The static imports are the ones your editor will not offer to add for you.
4// Tuner X writes Volts.per(RotationsPerSecond) into the config you paste two
5// lessons from now, so they are here already and that paste just works.
6import static org.wpilib.units.Units.RotationsPerSecond;
7import static org.wpilib.units.Units.RotationsPerSecondPerSecond;
8import static org.wpilib.units.Units.Volts;
9 
10import com.ctre.phoenix6.CANBus;
11import com.ctre.phoenix6.configs.MotionMagicConfigs;
12import com.ctre.phoenix6.configs.MotorOutputConfigs;
13import com.ctre.phoenix6.configs.Slot0Configs;
14import com.ctre.phoenix6.configs.TalonFXConfiguration;
15import com.ctre.phoenix6.controls.MotionMagicVelocityVoltage;
16import com.ctre.phoenix6.controls.VoltageOut;
17import com.ctre.phoenix6.hardware.TalonFX;
18import com.ctre.phoenix6.signals.InvertedValue;
19import com.ctre.phoenix6.signals.NeutralModeValue;
20import org.wpilib.command3.Mechanism;
21 
22public class Flywheel extends Mechanism {
23  // The fields go here.
24 
25  public Flywheel() {
26    // The motor configuration goes here.
27  }
28 
29  // The two methods go here.
30}

Your editor will grey the imports out until you use them. That is expected, and they go quiet one block at a time as you fill the class in. The fields come first.

Arm.java: the class line and the fields

1public class Arm extends Mechanism {
2  private final CANBus canivore = new CANBus("canivore");
3  private final TalonFX motor = new TalonFX(31, canivore);
4  private final CANcoder encoder = new CANcoder(32, canivore);
5 
6  // Pushes a set voltage at the motor. No sensors involved.
7  private final VoltageOut voltageOut = new VoltageOut(0);

Flywheel.java: the class line and the fields

1public class Flywheel extends Mechanism {
2  private final CANBus canivore = new CANBus("canivore");
3  private final TalonFX motor = new TalonFX(21, canivore);
4 
5  // Pushes a set voltage at the motor. No sensors involved.
6  private final VoltageOut voltageOut = new VoltageOut(0);

extends Mechanism is what makes this a mechanism rather than a plain object. Building one registers it with the scheduler, and it is where runRepeatedly(...) and the default idle() command come from.
new CANBus("canivore") names the bus these devices sit on. That string has to match the name you gave the CANivore in Tuner X. Spell it differently and nothing answers.
The CAN IDs come from Motor Setup: 31 and 3221. If your bench came out with different numbers, change the code to match. Do not leave the two disagreeing.
One wheel, one motor, and no CANcoder. A flywheel is tuned for speed, and the encoder inside the TalonFX already measures speed. The arm needs a second device because an angle has to be right the moment the robot boots.
VoltageOutis a Phoenix 6 control request: an object that says "apply this many volts". Build it once as a field, not fresh every loop.

There is nothing to import. They are all at the top of the file already, and the greyed-out ones stop being grey as you use them. The class compiles at every step from here, because what you pasted was a complete class to begin with.

Configure the motor once

The constructor runs one time, the moment new ArmFlywheel() is evaluated. NeutralMode is the one setting here you choose. Inverted is not a choice: it is the direction you proved on Motor Setup, and the mechanism decided it long before any code ran. Ignore the two Expo values. They are defaults built into every config Tuner X generates, and no workshop uses them.

Phoenix Tuner X with the config panel's three-dot menu open and Generate Code circled in red, above the Motion Magic fields — Behind the menu, cruise velocity, acceleration and jerk sit at 0 while Expo_kV and Expo_kA already hold values. That is why those two lines arrive in every generated config, tuned or not.

Watch out

These are our numbers, not yours

The block below is the shape, not a config to copy. Yours comes off your own bench. Open the config panel in Tuner X, press the three dots, and choose Generate Code. Paste the result over the whole statement. The mechanism is still open loop here, so a fresh config looks much like this one. From Motion Magic on it carries the gains you measured.

Arm.java: the constructor

1  public Arm() {
2    final TalonFXConfiguration talonFXCfg =
3        new TalonFXConfiguration()
4            .withMotorOutput(
5                new MotorOutputConfigs()
6                    .withNeutralMode(NeutralModeValue.Coast) // easy to move by hand
7                    .withInverted(InvertedValue.CounterClockwise_Positive))
8            .withMotionMagic(
9                new MotionMagicConfigs()
10                    .withMotionMagicExpo_kV(
11                        Volts.per(RotationsPerSecond).ofNative(0.119999997317791))
12                    .withMotionMagicExpo_kA(
13                        Volts.per(RotationsPerSecondPerSecond).ofNative(0.10000000149011612)))
14            .withFeedback(
15                new FeedbackConfigs()
16                    .withFeedbackRemoteSensorID(32)
17                    .withFeedbackSensorSource(FeedbackSensorSourceValue.RemoteCANcoder));
18 
19    motor.getConfigurator().apply(talonFXCfg);
20  }

Flywheel.java: the constructor

1  public Flywheel() {
2    final TalonFXConfiguration talonFXCfg =
3        new TalonFXConfiguration()
4            .withMotorOutput(
5                new MotorOutputConfigs()
6                    .withNeutralMode(NeutralModeValue.Coast) // easy to spin by hand
7                    // positive shoots: clockwise from the motor side
8                    .withInverted(InvertedValue.Clockwise_Positive))
9            .withMotionMagic(
10                new MotionMagicConfigs()
11                    .withMotionMagicExpo_kV(
12                        Volts.per(RotationsPerSecond).ofNative(0.119999997317791))
13                    .withMotionMagicExpo_kA(
14                        Volts.per(RotationsPerSecondPerSecond).ofNative(0.10000000149011612)));
15 
16    motor.getConfigurator().apply(talonFXCfg);
17  }

NEUTRAL MODE

Coast, not Brake

Neutral mode is what the motor does when nothing is commanding it. Coast cuts the power and lets the shaft spin freely. Brake makes the motor resist being turned, so the mechanism stays roughly where you left it.

The lesson armflywheel picks Coast, and the branch says why on that line. You will move the arm by handspin the wheel by hand all day. A competition arm carrying weight usually wants Brake, or it drops the instant you disable. A competition flywheel usually keeps Coast. A wheel with that much stored energy braked to a stop punishes the gearbox every cycle.

FEEDBACK SOURCE

The CANcoder in the loop

A TalonFX counts its own rotor turns, and that count starts at zero every time the controller powers on. The CANcoder is absolute. It knows the arm's angle the moment it boots.

That one line makes the CANcoder the motor's position source instead of the rotor. Nothing reads a position on this branch. Leave the line out and the motor measures every angle you ask for later from wherever the arm sat at power-on.

NO FEEDBACK SOURCE

Nothing to point the motor at

The arm's config carries a withFeedbackblock, naming the CANcoder as the motor's position source. The flywheel has none, because it has no such device.

A TalonFX counts its own rotor turns, and a rotor count is a fine way to measure speed. It is a poor way to measure an angle, because it starts at zero every power-on. Speed is the only thing this mechanism is ever asked for.

motormotor.getConfigurator().apply(talonFXCfg) sends every setting above to the motor controller in one message. It runs once, in the constructor, because the controller keeps those settings until something changes them.

Two methods

Arm.java: the two methods

1  /**
2   * Push the arm with a fixed voltage. Positive voltage moves the arm counter-clockwise.
3   *
4   * @param voltage The voltage to apply.
5   */
6  private void setVoltage(double voltage) {
7    motor.setControl(voltageOut.withOutput(voltage));
8  }
9 
10  /** Stop the motor. */
11  private void stopMotor() {
12    motor.stopMotor();
13  }
14}

Flywheel.java: the two methods

1  /**
2   * Spin the flywheel with a fixed voltage.
3   *
4   * @param voltage The voltage to apply.
5   */
6  private void setVoltage(double voltage) {
7    motor.setControl(voltageOut.withOutput(voltage));
8  }
9 
10  /** Stop the motor. */
11  private void stopMotor() {
12    motor.stopMotor();
13  }
14}

voltageOut.withOutput(voltage) sets the number on the request object you built as a field, and motormotor.setControl(...) sends it. The motor holds that request until something replaces it.

Nothing here reads a sensor. Ask for 6 V and you get 6 V, whatever the armflywheel does with it.

Both are private, and nothing calls them yet. The next lesson wraps them in commands, and those are what the rest of the robot gets to use. The stop helper is named stopMotor rather than stop because a command takes that name next lesson.

Hand it to Robot

You have written the class, but nothing has built one yet. Right now Arm.javaFlywheel.java is a file and nothing more. Robot is where it becomes a real object: built once at startup, outliving every mode, and handed to every OpMode that needs a mechanism. Add the two lines.

Robot.java: the mechanisms it owns

1package first.robot;
2 
3import first.robot.mechanisms.Arm;
4import first.robot.mechanisms.Flywheel;
5import org.wpilib.command3.Scheduler;
6import org.wpilib.framework.OpModeRobot;
7 
8public class Robot extends OpModeRobot {
9  // The robot's mechanisms. Public so OpModes can use them.
10  public final Arm arm = new Arm();
11  public final Flywheel flywheel = new Flywheel();
12 
13  public Robot() {}
14 
15  @Override
16  public void robotPeriodic() {
17    Scheduler.getDefault().run();
18  }
19}

public final because every OpMode reaches the mechanisms through the one Robot it is handed, and nothing should ever swap them out.

Building only the armflywheel? Delete the FlywheelArm field and its import. A field that builds a class you never wrote does not compile.

Check your work

Nothing on this branch moves a motor, so the check is a build and three things you can see.

Run WPILib: Build Robot Code. You should see BUILD SUCCESSFUL. That is the real check here: every import resolved, and every name you typed exists.
List src/main/java/first/robot/mechanisms/. Arm.javaFlywheel.java is in it, beside Robot.java.
Search Arm.javaFlywheel.java for Command. Not one line of code on this branch builds one.
In Tuner X, confirm every device answers on the canivore bus at 31 and 3221. Those have to be the numbers in your constructor.

Check

You should see

Private final fields on ArmFlywheel, and a constructor ending in getConfigurator().apply(talonFXCfg).
setVoltage and stopMotor, both private, and no public method but the constructor.

Arm.java on branch mech-1-MechanismsFlywheel.java on branch mech-1-Mechanisms