Initial commit

README.md

@@ -0,0 +1,117 @@
+# ftc-lib
+
+## Yes, ts was generated... No I do not believe in an AI takeover
+
+**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
+
+```text
+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.
+
+```java
+@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.
+
+```java
+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.
+
+```java
+@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:
+1. **Hardware Sync:** Clears Bulk Cache on all Hubs.
+2. **Logic Tick:** Runs your `stateMachineUpdate()`.
+3. **Subsystem Tick:** All subsystems calculate PIDs and update motor powers.
+4. **Telemetry Gate:** If the `TELEMETRY_DELAY_MS` has passed, it pushes data to Panels and the Driver Station.
+5. **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
+*   [PedroPathing](https://github.com/pedropathing/pedro-pathing)
+*   [Panels/Configurables (Sloth)](https://panels.bylazar.com/)
+*   [Panels/Telemetry (Sloth)](https://panels.bylazar.com/)
+
+---
+
+## 🤝 Contribution
+When adding new subsystems:
+1. Ensure all hardware names are in `Constants`.
+2. Ensure `publishTelemetry` only sends data when `GLOBAL.DEBUG_MODE` is true.
+3. Never use `sleep()` inside a subsystem; use state timers instead.