add: basic nextcontrol info + sidebar

Signed-off-by: Zach Harel <zach.harel42@gmail.com>

Author: zachwaffle4

.idea/workspace.xml

@@ -3,6 +3,7 @@ import {tabsMarkdownPlugin} from "vitepress-plugin-tabs";
 import guide from "./sidebar/guide.mts";
 import nextftc from "./sidebar/nextftc.mts";
 import bindings from "./sidebar/bindings.mts";
+import control from "./sidebar/control.mts";
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
@@ -62,7 +63,8 @@ export default defineConfig({
         sidebar: {
             '/guide/': guide,
             '/nextftc/': nextftc,
-            '/bindings/': bindings
+            '/bindings/': bindings,
+            '/control/': control
         },
 
         socialLinks:

.vitepress/config.mts

@@ -0,0 +1,27 @@
+import {DefaultTheme} from "vitepress";
+
+type SidebarItem = DefaultTheme.SidebarItem;
+
+export default [
+    {
+        text: "Overview",
+        link: "/control/",
+    },
+    {
+        text: "Kinetic States",
+        link: "/control/kineticstates",
+    },
+    {
+        text: "Control Systems",
+        link: "/control/controlsystem",
+    },
+    {
+        text: "Examples",
+        items: [
+            {
+                text: "Linear Slides",
+                link: "/control/examples/slides",
+            }
+        ]
+    }
+] satisfies SidebarItem[]

.vitepress/sidebar/control.mts

@@ -0,0 +1,76 @@
+# Control System
+
+Control Systems represent a combination of the Four Elements of control described earlier.
+They are created using convenient builder syntax, or, for Kotlin users, a DSL-style builder.
+
+Here is an easy example:
+
+::: tabs key:code
+
+== Kotlin
+
+```kotlin
+val system = controlSystem {
+    posPid(0.5, 0.0, 0.0)
+}
+
+system.goal = KineticState(10.0, 0.0, 0.0)
+```
+
+== Java
+
+```java
+ControlSystem system = ControlSystem.builder()
+    .posPid(0.5, 0, 0)
+    .build();
+    
+system.setGoal(new KineticState(10.0, 0.0, 0.0));
+```
+
+:::
+
+There are many quick methods to add pre-defined control elements, 
+or you can define your own!
+
+::: tabs key:code
+
+== Kotlin
+
+```kotlin
+val controller = controlSystem {
+        posFilter { 
+            custom { 
+                state -> 0.5 * state
+            } 
+        }
+    }
+```
+
+== Java
+
+```java
+val controller = ControlSystem.builder()
+                .posFilter(
+                        filterBuilder -> filterBuilder.custom(
+                                state -> state * 0.5
+                        )
+                ).build();
+```
+
+:::
+
+::: warning
+If you do not add an interpolator using the builder, 
+you should specify the goal of the control system.
+The default is `KineticState(0.0, 0.0, 0.0)`.
+:::
+
+## Using a Control System
+
+To run the control system's calculations, call `calculate`, 
+which accepts one `KineticState` argument representing the current measurement,
+and returns an output following the process defined earlier.
+
+We can then use this output to, say, power a motor.
+
+More examples on using `ControlSystem`s will be provided in the Examples section.

src/control/controlsystem.md

@@ -0,0 +1,111 @@
+# Linear Slides Example
+
+Linear slides are a commonly used mechanism in FTC, 
+and most often controlled with a positional PID feedback 
+controller and a static feedforward term to account for gravity.
+
+With NextControl, that would be implemented like this (using hypothetical constants):
+
+::: tabs key:code
+
+== Kotlin
+
+```kotlin
+controlSystem {
+    posPid(0.1, 0.0, 0.0)
+    elevatorFF(0.04)
+}
+```
+
+== Java
+
+```java
+ControlSystem.builder()
+             .posPid(0.1, 0.0, 0.0)
+             .elevatorFF(0.04)
+             .build();
+```
+
+:::
+
+## What can I do with this?
+
+If you're using a command-based framework, like NextFTC, 
+you can create commands using your control system.
+An example of a Linear Slides subsystem using NextControl can be found 
+[here](../../guide/subsystems/lift.md).
+
+If not, we can create OpModes that use our controllers directly. 
+For example, lets say we wanted to change the target of our slides using a button press.
+We can easily do that by simply changing the `goal` of our ControlSystem:
+
+::: tabs key:code 
+
+== Kotlin
+
+```kotlin
+class SlideExample() : OpMode() {
+    val slideMotor by lazy { hardwareMap.get(DcMotorEx.class, "slides") }
+    val controller = controlSystem {
+        posPid(0.1, 0.0, 0.0)
+        elevatorFF(0.04)
+    }
+
+    override fun init() {
+        controller.goal = KineticState(0.0, 0.0, 0.0)
+    }
+
+    override fun loop() {
+        if (gamepad1.a) {
+            controller.goal = KineticState(1000.0, 0.0, 0.0)
+        } else if (gamepad1.b) {
+            controller.goal = KineticState(0.0, 0.0, 0.0)
+        } else if (gamepad1.x) {
+            controller.goal = KineticState(500.0, 0.0, 0.0)
+        }
+
+        slideMotor.power = controller.calculate(
+            slideMotor.currentPosition,
+            slideMotor.velocity
+        )
+    }
+}
+```
+
+== Java
+
+```java 
+public class SlideExample extends OpMode {
+    private DcMotorEx slideMotor;
+    private ControlSystem controller;
+
+    @Override
+    public void init() {
+        slideMotor = hardwareMap.get(DcMotorEx.class, "slides");
+        
+        controller = ControlSystem.builder()
+             .posPid(0.1, 0.0, 0.0)
+             .elevatorFF(0.04)
+             .build();
+        
+        controller.goal = new KineticState(0.0, 0.0, 0.0);
+    }
+
+    @Override
+    public void loop() {
+        if (gamepad1.a) {
+            controller.goal = new KineticState(1000.0, 0.0, 0.0);
+        } else if (gamepad1.b) {
+            controller.goal = new KineticState(0.0, 0.0, 0.0);
+        } else if (gamepad1.x) {
+            controller.goal = new KineticState(500.0, 0.0, 0.0);
+        }
+
+        slideMotor.setPower(controller.calculate(
+            slideMotor.getCurrentPosition(),
+            slideMotor.getVelocity()
+        ));
+    }
+}
+```
+

src/control/examples/slides.md

@@ -0,0 +1,31 @@
+# Control
+
+NextControl is our robust control library that uses the "Four Elements"
+of control systems to model actuated systems.
+
+Some examples are featured in the [examples folder](/control/examples], 
+and all components have thorough javadoc/kdoc documentation.
+
+## The Four Elements
+These four elements make up a Control System. Not all are required, of course.
+- **Feedback elements** provide feedback (closed-loop) control for your system.
+  For example, PID Control, SquID
+  Control, and
+  Bang-Bang Control.
+- **Feedforward elements** provide feedforward (open-loop) control. NextControl
+  has three feedforward controllers:
+  basic, elevator, and arm.
+- **Filter elements** filter your sensor measurements to remove noise. Examples
+  are low-pass filters and Kalman filters.
+- **Interpolator elements** interpolate the setpoint in order to smooth out
+  setpoint changes. 
+  For example, a trapezoidal motion profile or a moving-average setpoint filter.
+
+
+The control system calculation process involves:
+1. Filtering sensor measurements
+2. Obtaining the current reference from the interpolator
+3. Calculating feedback component based on error
+4. Calculating feedforward component based on reference
+5. Returning the sum of feedback and feedforward
+

src/control/index.md

@@ -0,0 +1,8 @@
+# KineticStates
+
+A `KineticState` is simply a structure for storing the one-dimensional motion states of a system at a given point in time.
+It contains a `position`, a `velocity`, and an `acceleration`, and works for whatever unit you provide:
+if `position` is given in inches, `velocity` should be given in inches per second, 
+and `acceleration` should be given in inches per second squared.
+
+`KineticState`s can be added or subtracted componentwise, or multiplied by a scalar quantity.