LESSON 13

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.

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 below,
5// 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 implements 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 below,
5// 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 implements 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 greys out an import until something uses it. That is expected. Most go quiet as you fill the class in, and a few wait for Motion Magic in Code. The class compiles at every step from here. The fields come first.

Arm.java: the class line and the fields

1public class Arm implements 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 implements 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);

implements Mechanism makes this a mechanism. Every method on that interface already has a body, so there is nothing to override, and runRepeatedly(...) is yours from here on.
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.
VoltageOut is a control request, built once as a field and reused. Configs and requests below says what that means.

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. Open the config panel in Tuner X, press the three dots, choose Generate Code, and paste the result over the whole statement. If the device holds your gains from Workshop 1, they come along. Leave them in. Nothing reads them until Motion Magic in Code.

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 lets the shaft spin freely, and Brake resists being turned. The lesson armflywheel picks Coast because 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 from zero at every power-on. The CANcoder is absolute, and withFeedback makes it the motor's position source. Nothing reads a position on this branch. Leave the block out and every angle you ask for later is measured from wherever the arm sat at power-on.

NO FEEDBACK SOURCE

Nothing to point the motor at

The arm's config has a withFeedback block naming its CANcoder. The flywheel has no CANcoder, so it has no such block. A rotor count starts at zero every power-on, which ruins an angle and does not matter to a speed.

motormotor.getConfigurator().apply(talonFXCfg) sends every setting above to the motor controller in one message.

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.

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 one of those commands takes the name stop, so the helper is stopMotor.

Configs and requests

This file sends the motor two kinds of message. A config is settings: inversion, neutral mode, gains, the feedback sensor. The TalonFX saves it, so the constructor applies it once. A is what to do right now, and it carries the target. The target changes while the robot runs, so code sends a request every loop.

You have used both in Tuner X. The config panel is the config, and the Control drop-down on Motor Setup picks a request. Voltage Out in that drop-down is VoltageOut here. Motion Magic Voltage is MotionMagicVoltage, which replaces it two lessons from now.

Every request name is made of the same parts. The column is what the motor outputs. The row is what it aims at, and a MotionMagic prefix means a profile shapes the move.

Aims at	Duty cycle	Volts	Amps
Nothing	`DutyCycleOut`	`VoltageOut`	`TorqueCurrentFOC`
A position	`PositionDutyCycle`	`PositionVoltage`	`PositionTorqueCurrentFOC`
A velocity	`VelocityDutyCycle`	`VelocityVoltage`	`VelocityTorqueCurrentFOC`
A position, profiled	`MotionMagicDutyCycle`	`MotionMagicVoltage`	`MotionMagicTorqueCurrentFOC`
A velocity, profiled	`MotionMagicVelocityDutyCycle`	`MotionMagicVelocityVoltage`	`MotionMagicVelocityTorqueCurrentFOC`

This course stays in the volts column, so the gains you tuned are in volts. A request also stays latched. The motor keeps applying the last one it received until a different one arrives, even after the code that sent it has stopped running. That is what stopMotor() is for, and Hardware Simulation shows what happens without it.

Hand it to Robot

Nothing has built the class yet. Robot is where it becomes a real object: built once at startup, outliving every mode, and handed to every OpMode. Add the two fields.

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 so every OpMode can reach them, and final so nothing swaps 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.

Run WPILib: Build Robot Code. You should see BUILD SUCCESSFUL, which means 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.
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