Add motor control docs

.gitignore

@@ -23,4 +23,7 @@ bun.lock
 # macOS-specific files
 .DS_Store
 
-.vscode
+.vscode
+
+# IntelliJ
+.idea/

src/content/docs/misc/motor_control.mdx

@@ -0,0 +1,106 @@
+# Controlling mechanisms with motors
+
+With the introduction of the brushless era of motors in FRC, motors have become the dominant choicewhen it comes to controlling robot degrees of freedom, compared to servos or pneumatics.
+Brushless motors have incredible size to performance ratios, and the smart motor controllers that accompany them make it easy to control a variety of mechanisms.
+This section will cover the most common types of software controllers for motors in FRC.
+
+## Motor Controllers
+Not to be confused with hardware motor controllers like the REV Spark Max or CTRE TalonFX, a software motor controller is a function that converts a setpoint input to a motor output.
+In the simplest case, the input _is_ the output, such as when using voltage or throttle (duty-cycle) control.
+
+A more complex example would multiply the setpoint, say a flywwhel rpm, by some constant to convert to volts for the motor.
+
+Understanding and mastering these controllers will help your robots to be fast and accurate, and help you to be succesful in FRC.
+
+## Open- and Closed-loop Controllers
+The types of controllers that you can create can be split into two categories: open-loop, and closed-loop.
+Open-loop refers to a mechanism that have only a single input, the setpoint.
+Open-loop controllers will often, but not always, utilize a mathematical model of the motor and mechanism to make an educated estimate of how the motor should act in order to reach the setpoint.
+However, they have no way of knowing if the motor is behaving according to the model, so open-loop control is inadequate for most FRC mechanisms.
+
+Closed-loop mechanisms have an additional input: a measurement of the current state of the mechanism.
+A closed-loop controller will combine this measurement and setpoint to determine the output.
+Using a measurement from the mechanism is beneficial because it gives your controller insight into how the mechanism is actually behaving.
+This _feedback_ from the mechanism can help account for the modle being inaccurate, or disturbances which have caused the mechanism to not act exactly according to the model.
+
+Closed-loop control is fundamental to creating fast and accurate mechansims, but requires more effort to get working properly.
+Open-loop control is simpler, but may lack the precision that closed-loop offers.
+
+Ther terms open- and closed-loop refers to the shape of the controller when diagrammed out.
+See this image from the [WPILib Docs](https://docs.wpilib.org/en/stable/docs/software/advanced-controls/introduction/control-system-basics.html#block-diagrams):
+![Closed Loop Block Diagram](/misc/loop_block.png).
+
+When there is no feedback, the diagram forms a straight line from input to output.
+In the closed-loop case, the input -> output -> feedback forms a loop.
+
+## Open Loop Control
+
+Some mechanisms, like intake rollers, can provide successful performance even without incorporating feedback from the mechanism.
+Intake rollers are commonly controlled simply by running the motor at a throttle level, which represents a percentage of the battery voltage.
+A 50% throttle, set with `motor.setThrottle(0.5)` will output 50% of the battery voltage to the motor.
+Even if the battery voltage is a little higher or lower from one point in time to the next, the effect on intake performance is likely to be negligible, so there is no need to account for it in your controller.
+
+The simplest open-loop mechanisms require almost no configuration in code, since you don't need to configure gear ratios or feedback gains.
+
+The two most common open-loop setpoint types are duty-cycle and voltage.
+
+Duty-cycle is a percentage of input voltage coming from the robot's battery to the motor controller.
+WPILib refers to this percentage as throttle.
+If the battery voltage is 11.8 volts, and you request a 50% duty-cycle, or 50% throttle, the motor controller will output 5.9 volts to the motor.
+
+Voltage control allows you to directly control the output going to the motor.
+If the battery voltage is 12.2 volts, and you request a voltage of 6 volts, the motor controller will output 6 volts.
+Likewise, if the battery voltage dips to 11.8 volts, the motor controller will still output 6 volts
+
+Voltage control is recommended over duty-cycle for open loop control because of its repeatability.
+The voltage going to the motor does not fluctuate with changes in battery voltage.
+When using voltage control, it is recommended to not exceed a setpoint of 10 volts to account for voltage sag as your battery is used up throughout the match.
+Voltage control can accomodate voltages _higher_ than the setpoint by reducing the duty cycle, but if the input voltage is below the setpoint, the motor controller cannot overcome the deficit.
+
+### Open Loop Velocity
+
+While open-loop position control does not work well in FRC, open-loop velocity control is very practical due to the nature of motors.
+Many teams will choose to run flywheels for shooters using open-loop control, since there is a direct relationship between motor voltage and motor speed, referred to as the velocity constant _kV_.
+This relationship can be found theoretically using key characteristics of the motor, or empirically by taking velocity measurements at different voltages to calculate _kV_.
+See the [WPILib Docs](https://docs.wpilib.org/en/stable/docs/software/advanced-controls/introduction/introduction-to-feedforward.html#introduction-to-dc-motor-feedforward) page on DC Motor Feedforward for more info about kV.
+
+If you don't want to calculate kV, you can use voltage directly as your setpoint.
+
+It is common practice to use open-loop velocity control on swere drivetrains too, where precise velocity is not as important.
+The human driver acts like a closed-loop controller, using measurements taken of robot position and speed in order to adjust its movement.
+
+## Closed-Loop Control
+
+### Closed-Loop Position Control
+
+Position control is the most common closed-loop control scheme in FRC.
+Mechanisms that use position control include elevators, pivoting arm, slap-down intakes, climbers, and every swerve drivetrain contains four position-controlled modules.
+
+#### Measuring your mechanism
+
+The most common feedback sensor in position-controlled mechanism is an encoder, a small electronic device that can measure rotation.
+Brushless motors all contain internal encoders, so these are a popular choice for teams.
+They require no extra work to incorporate into a mechanisms design, and are guaranteed to be functioning as long as the motor is.
+The downside of these internal encoders is they reset to a position of _0_ when the motor turns on, regardless of the mechansims physical location.
+To counteract this, you either need to perform a homing sequence that moves your mechanism in a controlled manner to a fixed location, then reset the encoder reading to match, or to always power on the robot with the mechanisms in a known spot, such as a physical hardstop.
+Using a hardstop location at power-on is recommended for its simplicity, and because you always power the robot on when it is on the field at competition, you will be able to position the mechanisms correctly before doing so.
+
+An alternative to a motors internal encoder is an external encoder.
+External encoders can be mounted to an axle that rotates as the mechanism moves.
+By attaching the encoder to the final shaft of a rotating mechanism, such as an arm, you can treat the encoder reading as _absolute_, requiring no homing sequence or specific power-on location.
+
+
+### Closed-Loop Velocity Control
+
+Closed-loop velocity control relies heavily on the open-loop control discussed above, but with similar incorporation of feedback gains to account for disturbances.
+An example of disturbance that you may need to account for is a game piece slowing down your shooter's flywheel.
+In years when you have to shoot multiple game pieces one after another, like in 2026 Rebuilt, closed-loop control can help your flywheel recover between shots in a way that open-loop alone cannot.
+
+
+## Choosing a control scheme
+
+Choosing a control scheme for a mechanism should feel straightforward.
+If you need a mechanism to move to a precise position and stay there, closed-loop position is the only option.
+If you need a mechanism to move at a specific speed, start with open-loop velocity control.
+If you find that the mechanism still doesn't perform as well as you'd like, consider if adding feedback would improve performance.
+Instead, if you only need a mechanism to move at rough speeds, open loop control is a simple way to achieve motion.