EasyGamepad
EasyGamepad wraps an FTC Gamepad and adds per-button edge detection, toggles and debouncing, plus deadzone handling for sticks and triggers.
The raw FTC gamepad only reports whether a button is held right now. Detecting a single press, a release, or an on/off toggle normally needs extra boolean variables in every OpMode. EasyGamepad keeps that state for you.
This is useful in TeleOp, where one button press should trigger one action, such as starting a shooter, closing a claw, or stepping through a preset.
EasyGamepad provides:
- Down, pressed, released and toggle state for every button.
- A configurable debounce time per button.
- Optional deadzone and Y inversion for the sticks.
- Triggers that can also be read as buttons.
- A generic
Buttonenum API for working with many buttons in a loop. - Rumble helpers.
#Creating an EasyGamepad
To create an EasyGamepad, pass it the FTC gamepad you want to wrap:
import dev.easyfamily.wintechlib.gamepad.EasyGamepad;
EasyGamepad pad = new EasyGamepad(gamepad1);Create one EasyGamepad per physical gamepad:
EasyGamepad driver = new EasyGamepad(gamepad);
EasyGamepad operator = new EasyGamepad(gamepad2);The wrapper does not copy the gamepad. It keeps a reference, so it always reads the current values of the FTC Gamepad object.
Create the wrapper before the OpMode loop, for example right after waitForStart() or at the top of runOpMode(). Creating it inside the loop would reset all button history on every cycle.
#Updating the Gamepad State
Call update() exactly once at the start of every loop cycle, before reading any button:
while (opModeIsActive()) {
pad.update();
if (pad.aPressed()) {
// runs once per press
}
}update() reads every button from the FTC gamepad, compares it with the previous cycle, and recalculates the pressed, released and toggle state. Without it, EasyGamepad keeps returning the values from the last update.
Pressed and released results are only valid for the cycle in which they are detected. The next call to update() clears them. For that reason:
- Call
update()once per loop, not twice. - Read
pressedandreleasedvalues afterupdate()in the same cycle. - Do not store them for later cycles. Store your own variable if you need to remember an event.
#Reading Buttons
Every button has four ways to be read. The names below use button A; B, X and Y follow the same pattern:
| Method | Returns true when |
|---|---|
a() | The button is held down right now. |
aPressed() | The button went from up to down in this cycle. |
aReleased() | The button went from down to up in this cycle. |
aToggle() | The button's toggle state is on. |
For example:
if (pad.a()) {
// runs every cycle while A is held
}
if (pad.aPressed()) {
// runs once when A is pressed
}
if (pad.aReleased()) {
// runs once when A is released
}Use a() for actions that should last as long as the button is held, such as running an intake. Use aPressed() for one-shot actions, such as closing a claw or moving to a preset.
released events are not affected by debounce, and neither is a(). Debounce only filters pressed events and toggles (see Debounce).
The same four methods exist for every button:
| Button | Down | Pressed | Released | Toggle |
|---|---|---|---|---|
| A, B, X, Y | a() | aPressed() | aReleased() | aToggle() |
| D-pad | dpadUp() | dpadUpPressed() | dpadUpReleased() | dpadUpToggle() |
| Bumpers | leftBumper() | leftBumperPressed() | leftBumperReleased() | leftBumperToggle() |
| Stick buttons | leftStickButton() | leftStickButtonPressed() | leftStickButtonReleased() | leftStickButtonToggle() |
| Start / Back | start() | startPressed() | startReleased() | startToggle() |
| Triggers | leftTriggerDown() | leftTriggerPressed() | leftTriggerReleased() | leftTriggerToggle() |
The D-pad has Up, Down, Left and Right, the bumpers and stick buttons have Left and Right, and the triggers have Left and Right. Replace the side in the method name as needed.
#Toggles
Each button keeps a toggle state that flips every time the button is pressed. The initial value is false:
if (pad.aTogg1e()) {
} else
shooter.;The first press turns the toggle on, the second press turns it off, and so on. Releasing the button does not change it.
A press only flips the toggle if it passes the debounce check. Held buttons never flip the toggle repeatedly.
To force a toggle to a known value, use setToggle():
pad.setToggle(EasyGamepad.Button.A, true); // turn on
pad.setToggle(EasyGamepad.Button.A, false); // turn offTo set one toggle back to false:
pad.resetToggle(EasyGamepad.Button.A);To reset every toggle at once:
pad.resetToggles();This is useful when a mechanism is stopped by something other than the toggle button, such as an emergency stop or the start of a new match phase. Otherwise the toggle would still say "on" while the mechanism is off, and the next press would turn it off instead of on.
Resetting a toggle does not affect the down, pressed or released state.
#Debounce
Debounce ignores presses that happen too soon after the previous accepted press. It prevents one physical press from counting twice when a worn button or a loose connection produces a rapid release and press.
The default debounce time is 50 milliseconds for every button.
Use setDebounce() to change it for one button:
pad.setDebounce(EasyGamepad.Button.A, 150);The named setters are also available for the face buttons, D-pad, bumpers and other buttons. They return the EasyGamepad, so they can be chained:
EasyGamepad pad = new EasyGamepad(gamepad1)
.setADebounce(150)
.setBDebounce(150)
.setLeftBumperDebounce(80);To read the current value:
long ms = pad.getDebounce(EasyGamepad.Button.A);To set the same time on every button:
pad.setA11Debounce;The time is in milliseconds and cannot be negative. A negative value throws an IllegalArgumentException. A value of 0 disables debounce for that button.
Debounce affects:
pressedresults.- Toggle changes, because they happen on accepted presses.
Debounce does not affect:
- Down state, so
a()still follows the physical button. releasedresults.
The first press after construction is always accepted. After that, a press is accepted only if at least the debounce time has passed since the last accepted press of the same button. Rejected presses do not restart the timer.
#D-pad, Bumpers and Other Buttons
Every digital button on the gamepad is tracked with the same down, pressed, released and toggle state.
| Group | Buttons |
|---|---|
| Face buttons | a, b, x, y |
| D-pad | dpadUp, dpadDown, dpadLeft, dpadRight |
| Bumpers | leftBumper, rightBumper |
| Stick buttons | leftStickButton, rightStickButton |
| Menu buttons | start, back |
For example, to step through three presets with the D-pad and bumpers:
if (pad.dpadUpPressed()) {
armPreset = 2;
} else if (pad.dpadLeftPressed()) {
armPreset = 1;
} else if (pad.dpadDownPressed()) {
armPreset = 0;
}
if (pad.rightBumperPressed()) {
claw.setPosition(CLOSED);
} else if (pad.leftBumperPressed()) {
claw.setPosition(OPEN);
}Pressing the left stick or right stick in is a button too:
if (pad.leftStickButtonPressed()) {
slowMode = !slowMode;
}If you only need an on/off switch, leftStickButtonToggle() does the same without the extra variable.
The named debounce setters follow the same naming as the buttons: setDpadUpDebounce(), setLeftBumperDebounce(), setRightStickButtonDebounce(), setStartDebounce(), and so on.
The guide (logo) button is not wrapped. If you need it, read it from the underlying gamepad with pad.getGamepad().guide.
#Sticks and Triggers
Sticks and triggers are analog inputs, so they return floating-point values instead of booleans.
float forward -- -pad.1leftStickY();
float strafe -- pad.1leftStickX();
float turn -- pad.rightStickX();Each stick axis ranges from -1.0 to 1.0. On an FTC gamepad, pushing a stick up gives a negative Y value.
#Deadzone
Use setStickDeadzone() to ignore small values near the center, where worn sticks often report a small non-zero value:
pad .;Values inside the deadzone become 0.0. Values outside it are rescaled so the output still reaches 1.0 at full deflection, which avoids a sudden jump when the stick leaves the deadzone:
rawl — deadzone
output = sign(raw)
1 — deadzoneFor example, with a deadzone of 0.1:
| Raw value | Output |
|---|---|
| 0.05 | 0.0 |
| 0.55 | 0.5 |
| 1.0 | 1.0 |
| -0.55 | -0.5 |
The deadzone must be at least 0.0 and less than 1.0. The default is 0.0, which returns the raw values. Use getStickDeadzone() to read it.
The deadzone applies to all four stick axes. Use the Raw methods to bypass it:
float rawX = pad.leftStickXRaw();
float rawY = pad.leftStickYRaw();rightStickXRaw() and rightStickYRaw() are available too.
#Inverting Y
If you prefer pushing up to give a positive value, enable Y inversion:
pad.setInvertY(true);This flips the sign of leftStickY() and rightStickY(), and of their Raw versions. The default is false.
#Stick Magnitude
leftStickMagnitude() and rightStickMagnitude() return how far the stick is from the center, from 0.0 to 1.0. They use the values after the deadzone, and are useful for speed scaling or for checking whether a stick is being used at all:
if (pad.leftStickMagnitude() > 0.0) {
// the driver is moving the left stick
}#Triggers
leftTrigger() and rightTrigger() return the pull amount from 0.0 (released) to 1.0 (fully pulled):
= pad.rightTrigger() - pad.leftTrigger();Triggers can also be used as buttons. A trigger counts as down when its value is greater than the trigger threshold, which is 0.5 by default:
if (pad.rightTriggerPressed()) {
// runs once when the trigger crosses the threshold
}Change the threshold with:
pad.setTriggerThreshold(0.3f);The threshold must be between 0.0 and 1.0. Triggers also support released, toggle and debounce, like any other button. The stick deadzone does not apply to triggers.
#Generic Button API
Every named method such as aPressed() or dpadUpToggle() has an equivalent that takes an EasyGamepad.Button. The enum is useful when the button is chosen at runtime, or when you want to loop over several buttons.
EasyGamepad.Button Button = EasyGamepad.Button.X;
boolean held -- pad.down(Button);
boolean pressed = pad.pressed(Button);
= pad.released(Button);
boolean toggled = pad.toggled(Button);The available values are:
| Group | Button values |
|---|---|
| Face buttons | A, B, X, Y |
| D-pad | DPAD_UP, DPAD_DOWN, DPAD_LEFT, DPAD_RIGHT |
| Bumpers | LEFT_BUMPER, RIGHT_BUMPER |
| Stick buttons | LEFT_STICK_BUTTON, RIGHT_STICK_BUTTON |
| Menu buttons | START, BACK |
| Triggers | LEFT_TRIGGER, RIGHT_TRIGGER |
The generic methods are:
| Method | Description |
|---|---|
down(button) | Held down right now. |
pressed(button) | Pressed in this cycle, after debounce. |
released(button) | Released in this cycle. |
toggled(button) | Current toggle state. |
setToggle(button, value) | Sets the toggle state. |
resetToggle(button) | Sets the toggle state to false. |
setDebounce(button, ms) | Sets the debounce time for one button. |
getDebounce(button) | Returns the debounce time in milliseconds. |
The named methods and the generic methods read the same state. pad.aPressed() and pad.pressed(EasyGamepad.Button.A) always return the same value.
For example, to react to any of several preset buttons:
EasyGamepad.Button[] presetButtons = {
EasyGamepad.Button.DPAD_DOWN,
EasyGamepad.Button.DPAD_LEFT,
EasyGamepad.Button.DPAD_UP
};
for (int i = 0; i < presetButtons.length; i++) {
if (pad.pressed(presetButtons[i])) {
armPreset = i;
}
}To check whether anything was pressed this cycle:
if (pad.anyPressed()) {
// some button was pressed
}anyPressed() considers every Button, including triggers.
#Resetting, Rumble and the Underlying Gamepad
#Resetting
Use resetToggles() to set every toggle back to false:
pad.resetToggles();This clears toggle states only. It preserves:
- Debounce times.
- Stick deadzone and Y inversion.
- Trigger threshold.
- The down state of each button.
The method returns the EasyGamepad, so it can be chained.
#Rumble
Use rumble() to vibrate the gamepad for a number of milliseconds, for example to confirm that a mode changed:
if (pad.aPressed()) {
pad.rumble(150);
}To vibrate the two motors with different strengths (each from 0.0 to 1.0):
pad.rumble(1.0, 0.3, 250);To stop vibration early:
pad.stopRumble();Rumble depends on the controller. Controllers without rumble motors ignore these calls.
#Accessing the FTC Gamepad
Use getGamepad() to get the wrapped FTC Gamepad:
Gamepad raw = pad.getGamepad();
boolean touchpad = raw.touchpad;This is useful for inputs that EasyGamepad does not wrap. Values read this way do not have debounce, edge detection or deadzone applied.
#Complete Example
The following FTC example controls a shooter motor with EasyGamepad and EasyPIDFController.
Press A to turn the shooter on or off. Hold the right trigger to raise the target speed. Press B to stop the shooter immediately. Move the left stick to read a deadzone-filtered value on telemetry.
@TeleOp(name = "Gamepad Shooter")
public class GamepadShooter extends LinearOpMode {
private static final double NORMAL_SPEED = 3000; // ticks per second
private static final double BOOST_SPEED = 3500; // ticks per second
@Override
public void runOpMode() {
DcMotorEx shooter = hardwareMap.get(DcMotorEx.class, "shooter");
shooter.setMode(DcMotor.RunMode.RUN_WITHOUT_ENCODER);
EasyGamepad pad = new EasyGamepad(gamepad1)
.setStickDeadzone(0.05f)
.setTriggerThreshold(0.4f)
.setADebounce(100);
EasyPIDFController controller =
new EasyPIDFController(0.0005, 0.0, 0.0, 0.00015);
waitForStart();
while (opModeIsActive()) {
pad.update();
if (pad.bPressed()) {
pad.resetToggle(EasyGamepad.Button.A);
controller.reset();
}
if (pad.aPressed()) {
controller.reset();
pad.rumble(100);
}
if (pad.aToggle()) {
double target = pad.rightTriggerDown() ? BOOST_SPEED : NORMAL_SPEED;
controller.setTargetPosition(target);
double power = controller.calculate(shooter.getVelocity());
shooter.setPower(Math.max(-1.0, Math.min(1.0, power)));
} else {
shooter.setPower(0.0);
}
telemetry.addData("Shooter on", pad.aToggle());
telemetry.addData("Velocity", shooter.getVelocity());
telemetry.addData("Left stick X", pad.leftStickX());
telemetry.update();
}
shooter.setPower(0.0);
}
}
In this example:
update()runs once at the top of every cycle.aPressed()runs once per press, so the controller is reset only when the shooter state changes.aToggle()decides whether the shooter is on, without any extra boolean variable.bPressed()forces the toggle off, so the next press of A starts the shooter again.- The right trigger is read as a button with
rightTriggerDown(). - The final motor power is clamped to
-1.0to1.0, because the controller does not limit its output.
The gains are illustrative and must be tuned for your mechanism. Configure the motor so that positive power produces a positive measured velocity.
#Common Mistakes
| Problem | Cause and fix |
|---|---|
pressed never fires. | update() is not called, or it is called after the check. Call it first in the loop. |
pressed fires twice for one press. | update() is called twice per cycle, or the wrapper is created inside the loop. Call it once and create the wrapper before the loop. |
| The toggle starts on the wrong state. | A toggle always starts as false. Use setToggle() to set a different starting value. |
| A mechanism is off but the toggle says on. | Another button stopped it. Call resetToggle() for that button when you stop the mechanism. |
| A quick double tap is ignored. | The second press arrived within the debounce time. Lower it with setDebounce(), or set it to 0. |
| The robot drives backward. | FTC stick Y is negative when pushed up. Negate it or call setInvertY(true). |
| The robot creeps when the sticks are released. | Set a small deadzone with setStickDeadzone(), for example 0.05. |
| A trigger fires too easily or not at all. | Adjust setTriggerThreshold(). |
Also keep in mind:
- A button held when the
OpModestarts is reported as pressed on the firstupdate(), because there is no earlier cycle to compare with. - Use
downstate for continuous actions andpressedfor one-shot actions. - Create one
EasyGamepadper gamepad, and keep each wrapper for the wholeOpMode.
Última atualização 2026-11-16