docs

doc/ftc-lib/docs.md

@@ -0,0 +1,146 @@
+# 📦 ftc-lib Documentation
+
+Welcome to **ftc-lib**, a high-performance, asynchronous framework designed for FTC robotics. This library focuses on clean architecture, hardware write-optimization (caching), and powerful motion control.
+
+---
+
+## 🏗️ 1. Subsystem Architecture
+The library uses a **Subsystem-based architecture**. Every major part of your robot (Drive, Lift, Intake) should be its own class extending `Subsystem`.
+
+### `Subsystem` Base Class
+Each subsystem must implement:
+- `init()`: Hardware mapping and initial states.
+- `update()`: Periodic logic (PID loops, state transitions).
+- `isHealthy()`: Returns `false` if a critical sensor or motor fails.
+
+### `SubsysManager`
+The manager coordinates all subsystems so your OpMode stays clean.
+```java
+SubsysManager manager = new SubsysManager();
+manager.register(drive, lift, claw);
+
+manager.initAll(hardwareMap); // Call in init()
+manager.updateAll();         // Call in every loop()
+manager.health(telemetry);   // Shows [ OK ] or [ ERROR ] for all parts
+```
+
+---
+
+## 🎬 2. Routines & Actions (Asynchronous Logic)
+The **Routines** system allows you to write complex, multi-step scripts (like an Auto-Score macro) **without using `sleep()`** or freezing your robot.
+
+### Building Blocks
+Use the `Routine` factory to create `Action` objects:
+
+| Method | Description |
+| :--- | :--- |
+| `Routine.instant(() -> ...)` | Runs code once and finishes immediately. |
+| `Routine.wait(ms)` | Pauses the sequence for a set time (non-blocking). |
+| `Routine.waitUntil(() -> ...)` | Pauses until a condition is met (e.g., sensor triggered). |
+| `Routine.sequence(a, b)` | Runs actions one after another. |
+| `Routine.parallel(a, b)` | Runs actions at the same time. |
+
+### Running in TeleOp
+```java
+// Inside your loop
+if (gamepad.yWasPressed() && !routines.isBusy()) {
+    routines.run(
+        Routine.sequence(
+            Routine.instant(() -> lift.setTarget(1000)),
+            Routine.waitUntil(() -> lift.atTarget()),
+            Routine.instant(() -> claw.open()),
+            Routine.wait(250),
+            Routine.instant(() -> lift.setTarget(0))
+        )
+    );
+}
+routines.updateAll(); // Actually runs the active actions
+```
+
+---
+
+## ⚙️ 3. Optimized Hardware (`CMotor` & `CServo`)
+Standard FTC hardware commands (like `setPower`) are expensive. `ftc-lib` uses **Cached Wrappers** to ensure hardware writes only happen when values actually change.
+
+- **`CMotor` / `CMotorEx`**: Caches power, mode, direction, and target position.
+- **`CServo` / `CServoEx`**: Caches position and PWM state.
+
+*Benefit: Significantly higher loop frequencies (Hz) and smoother PID control.*
+
+---
+
+## 📈 4. Control Theory & PIDF
+The library includes a robust hierarchy of controllers in the `lib.pid` package.
+
+### Features
+1. **Voltage Compensation**: Automatically scales power based on battery voltage (e.g., your lift moves the same at 14V as it does at 12V).
+2. **Low-Pass Filtering**: Smooths out noisy encoder data for more stable D-term calculations.
+3. **Anti-Windup**: Prevents the Integral (I) term from growing out of control.
+4. **Feedforward (PIDF)**:
+   - `kG`: Gravity compensation for vertical lifts.
+   - `kCos`: Gravity compensation for rotating arms.
+   - `kS`: Static friction (Stiction) override.
+   - `kV`: Velocity feedforward.
+
+### Example: Lift PIDF
+```java
+PIDFController controller = new PIDFController(kP, kI, kD);
+controller.kG = 0.1; // Holds the lift against gravity
+double power = controller.calculate(currentTicks);
+motor.setPower(power);
+```
+
+---
+
+## 🏎️ 5. Motion Profiling (`smooth`)
+For smooth, "robotic" movement, use the `smooth` class to generate **Trapezoidal Motion Profiles**. This prevents jerky movements that snap belts or tip the robot.
+
+```java
+smooth profile = new smooth(maxVel, maxAccel);
+profile.generate(startPos, targetPos);
+
+// In update loop
+State state = profile.calculate();
+liftController.setTarget(state.pos); 
+// state.vel can be used for kV feedforward!
+```
+
+---
+
+## 🎮 6. Enhanced Gamepad
+`EnhancedGamepad` wraps the standard `Gamepad` to provide essential features for driver control:
+- **Rising Edge Detection**: `aWasPressed()` (True only on the exact frame the button is clicked).
+- **Falling Edge Detection**: `aWasReleased()`.
+- **Stick Scaling**: Automatically applies a cubic curve and deadbands to sticks for finer precision.
+- **Trigger Buttons**: Use `left_trigger_btn()` to treat a trigger like a digital button.
+
+---
+
+## 👁️ 7. Vision Utilities (`LLUtil`)
+A wrapper for the **Limelight 3A** that simplifies targeting:
+- **Distance Estimation**: Includes two methods:
+    1. `getTrigDistance()`: Uses mounting angle and trigonometry.
+    2. `getAreaDistance()`: Uses a power-regression curve based on target area (`ta`).
+- **Data Freshness**: `isDataFresh()` checks if the target was lost recently to prevent "snapping" to old data.
+
+---
+
+## 🛠️ 8. Health Monitoring
+The `health` utility allows any part of the code to report a hardware fault.
+```java
+// Inside a subsystem
+if (motor.getCurrentAmps() > 10.0) {
+    health.reportFault("LIFT_STALL");
+}
+
+// In Telemetry
+telemetry.addData("Faults", health.getFaults());
+```
+
+---
+
+## 💡 Best Practices
+1. **Never use `Thread.sleep()`**: Use `Routines` instead.
+2. **Update the Manager**: Ensure `subsysManager.updateAll()` and `routineManager.updateAll()` are called at the very end of your loop.
+3. **Use States**: Subsystems should have internal Enums (e.g., `LiftState.INTAKING`, `LiftState.SCORING`) rather than just taking raw numbers.
+4. **Voltage Comp**: Always set `BaseController.currentSystemVoltage` once per loop from your hardware map.

doc/legal/AudioBlocksSounds.txt

@@ -1,21 +0,0 @@
-The sound files listed below in this SDK were purchased from www.audioblocks.com under the 
-following license.
-
-    http://support.audioblocks.com/customer/en/portal/topics/610636-licensing-faq-s/articles
-
-    How am I allowed to use your content?
-    Last Updated: Aug 11, 2016 01:51PM EDT
-    Our content may be used for nearly any project, commercial or otherwise, including feature
-    films, broadcast, commercial, industrial, educational video, print projects, multimedia, 
-    games, and the internet, so long as substantial value is added to the content. (For example, 
-    incorporating an audio clip into a commercial qualifies, while reposting our audio clip on 
-    YouTube with no modification or no visual component does not.) Once you download a file it is 
-    yours to keep and use forever, royalty-	free, even if you change your subscription or cancel 
-    your account.
-
-List of applicable sound files
-
-	chimeconnect.wav
-        chimedisconnect.wav
-	errormessage.wav
-	warningmessage.wav

doc/legal/Exhibit A - LEGO Open Source License Agreement.txt

@@ -1,15 +0,0 @@
-EXHIBIT A - LEGO® Open Source License Agreement
-
-The contents of the file 'nxtstartupsound.wav' contained in this SDK are subject to the 
-LEGO® Open Source License Agreement Version 1.0 (the "License"); you may not use this 
-file except in compliance with the License. You may obtain a copy of the License 
-at "LEGO Open Source License.pdf" contained in the same directory as this exhibit.
-
-Software distributed under the License is distributed on an "AS IS" basis, WITHOUT 
-WARRANTY OF ANY KIND, either express or implied. See the License for the specific 
-language governing rights and limitations under the License.
-
-The Original Code is <firmwareRoot>\AT91SAM7S256\Resource\SOUNDS\!Startup.rso.
-LEGO is the owner of the Original Code. Portions created by Robert Atkinson are 
-Copyright (C) 2015. All Rights Reserved.
-Contributor(s): Robert Atkinson.