ftc-lib is a high-performance, state-machine-driven framework designed for FTC teams who prioritize clean code, modularity, and hardware optimization. It provides a robust abstraction layer over standard FTC OpModes, integrating PedroPathing for precision movement and Panels (Sloth) for live configuration and telemetry.

🚀 Key Features

Template Method Pattern: A locked-down backend that handles the "boring stuff" (Bulk reads, FPS capping, Telemetry timing) so you only write robot logic.
Subsystem Architecture: Fully isolated mechanisms with their own internal "Micro-States."
Hierarchical State Machines: Orchestrate complex robot actions by mapping a "Global State" to specific "Subsystem States."
Automatic Hardware Optimization:
- Bulk Reads: Automatically sets all expansion hubs to Manual Caching mode for the fastest possible loop times.
- FPS Capping: Prevents CPU/Battery waste by locking loop speeds to a target (e.g., 50 FPS).
Stateful PID Control: A built-in PID utility that handles time-deltas (dt) and integral sums internally.
Unified Telemetry: A joined engine that pipes data to both the Driver Station and the Panels dashboard simultaneously.
Live Tuning: Centralized Constants.java utilizing @Configurable for real-time value editing without recompiling.

📂 Project Structure

teamcode/
├── lib/                   # The Core Framework (Don't touch)
│   ├── BaseStateOpMode.java   # The engine that runs the robot
│   ├── Subsystem.java         # The blueprint for all mechanisms
│   ├── SubsystemManager.java  # Automates the lifecycle of subsystems
│   └── PIDController.java     # Stateful math utility
├── subsystems/            # Your robot parts (Drivetrain, Lift, Intake)
├── util/                  # Utilities (AutoTransfer, FPSCounter)
├── Constants.java         # The "Control Panel" for the entire robot
└── opmodes/               # Your actual TeleOp and Autonomous files

🛠 Usage Guide

1. Define your Constants

Use the Constants.java file to store every hardware name, PID value, and speed multiplier.

@Configurable
public static class LIFT {
    public static double kP = 0.015;
    public static int SCORING_POS = 2500;
}

2. Create a Subsystem

Inherit from Subsystem. Define "Micro-States" for this specific mechanism.

public class LiftSubsystem extends Subsystem {
    public enum LiftState { IDLE, EXTENDING }
    private LiftState state = LiftState.IDLE;

    @Override
    public void update() {
        // Run PID logic here
    }
}

3. Build your TeleOp

Inherit from BaseStateOpMode. This gives you the stateMachineUpdate() hook where you map gamepad inputs to states.

@TeleOp
public class MainTeleOp extends BaseStateOpMode {
    
    @Override
    protected void setupSubsystems() {
        manager.register(new DriveSubsystem(), new LiftSubsystem());
    }

    @Override
    protected void stateMachineUpdate() {
        if (gamepad1.aWasPressed()) {
            robotState = GlobalState.SCORING;
        }
    }
}

⚡ Performance Details

The "Tick" Lifecycle

Every loop, ftc-lib executes in this strict order:

Hardware Sync: Clears Bulk Cache on all Hubs.
Logic Tick: Runs your stateMachineUpdate().
Subsystem Tick: All subsystems calculate PIDs and update motor powers.
Telemetry Gate: If the TELEMETRY_DELAY_MS has passed, it pushes data to Panels and the Driver Station.
Sync Sleep: Adjusts thread sleep time to maintain a consistent TARGET_FPS.

Auton-to-TeleOp Persistence

Using the AutoTransfer utility, this library can automatically carry over the robot's end-of-auton position (from PedroPathing) and the Alliance color into TeleOp, ensuring your field-centric drive and automation remain seamless.

📦 Dependencies

🤝 Contribution

When adding new subsystems:

Ensure all hardware names are in Constants.
Ensure publishTelemetry only sends data when GLOBAL.DEBUG_MODE is true.
Never use sleep() inside a subsystem; use state timers instead.