Gains tuning

Docs/3_Specifics/3.6_GainsTuning.md

@@ -0,0 +1,117 @@
+# Understanding PID and Feedforward Control
+
+In the [controls article](3.1_ControlsIntro.md), we introduced feedback and feedforward control and explained why combining them is useful for tuning FRC mechanisms. Now, we need to understand how to actually use these constants in our control systems.
+
+### There are two main groups of constants to understand
+
+The feedforward gains include:
+- kS - static friction
+- kV - velocity
+- kA - acceleration
+- kG - gravity
+
+The feedback gains include:
+- kP - proportional
+- kI - integral
+- kD - derivative
+
+Feedforward is proactive. We predict how much motor output is needed and apply that output immediately.
+
+Feedback is reactive. the controller looks at what the mechanism is actually doing, compares it to the desired outcome, and corrects the error.
+
+## Feedforward constants:
+
+kS is the static friction feed forward gain. kS represents the amount of motor output required to overcome static friction and get the mechanism to move.
+- if kS is too low the mechanism may not actually move or not move as much as it should because it's not outputting enough to overcome static friction
+- if kS is too high the mechanism can jump when it starts moving because the output is more than necessary for overcoming static friction
+- kS is particularly important for mechanisms with significant friction including arms, elevators, and some other gear-driven mechanisms
+
+kG is the gravity feed forward gain. kG represents the amount of motor output required to counteract gravity.
+- only really useful when gravity actually affects a mechanism like an elevator or arms need it to account for the constant downward force exerted on it by gravity (i.e not things like rollers).
+
+kV is velocity. kV represents how much motor output is required to maintain a particular velocity. As a mechanism moves faster it will require more motor voltage to maintain that speed and kV shows that relationship.
+- kV is important for any mechanism where we care about controlling velocity.
+
+kA is the acceleration feed forward gain. kA represents how much additional motor output is needed to accelerate the mechanism. A mechanism that is already moving at a constant velocity does not need as much output as a mechanism that is rapidly trying to speed up for example, an elevator moving upward at a constant velocity needs enough output to overcome gravity while maintaining its speed so if we want it to accelerate upward we need more output which is represented by kA.
+- not all mechanisms need kA but important for some
+
+## Feedback constants
+kP is the proportional feedback gain. kP is based on the current error. if the mechanism is far away from its target the controller will apply a large correction and if its close it will apply a smaller correction.
+- if kP is too low the mechanism responds slowly and can't keep up with the target accurately
+- if kP is too high the mechanism may overshoot, oscillate, or become unstable
+
+kI is the integral feedback gain and is based on the accumulated error over time. An integral measures the total area under a curve, or in our case, the accumulated error. If a small error persists in the system, the integral term builds up over time and applies additional correction to eliminate that error.
+- kI is often set to 0 or a very small value because kP and kD are usually sufficient for controlling a mechanism. This is because kP and kD are often good enough. 
+- Too much kI can cause overshooting because the accumulated error can continue applying correction, so kI should only be added when a persistent error remains after tuning the other gains.
+
+kD is the derivative feedback gain. It is based on how quickly the error is changing. In other words, it looks at the rate at which the mechanism is approaching or moving away from its target.
+- Increasing kD generally adds damping to the system. Too little kD can make the mechanism to overshoot or oscillate because there is not enough correction to slow it down as it approaches the target. 
+- Too much kD can make the system overly sensitive to rapid changes in the error, causing jitter or rapid correction.
+
+## Tuning Process
+
+Understanding these things conceptually is the first step, but now we will include a guide on tuning for practical use. In general, you should not tune everything at once. A solid approach is making feedforward reasonably accurate, then using feedback to reduce the rest of the error. The process and constants you will need depends on the mechanism because they all have different physics. The procedure can depend on the motor controller, control mode, and mechanism. For example, it's important to distinguish between velocity and position control. If you're tuning a roller to maintain a certain RPM then you're dealing with velocity. However, if you're dealing with an elevator that needs to move to particular heights, that's position control.
+
+In general, the order for tuning is: kS & kG, kV, kA, kP, kD, kI (note: not all may be needed and sysID can take care of feed forward)
+
+If using a motion profile: Tune the PID gains while running a representative motion profile rather than only testing individual position commands. A motion profile continuously changes the mechanism's desired position and velocity, so gains that work well for simple position moves may not perform as well during a profiled motion. Start with the feedforward gains tuned, then adjust kP and kD until the mechanism follows the profile accurately without excessive overshoot or oscillation.
+
+### Elevator tuning:
+tune kS
+- determine how much output is necessary to overcome static friction and get the elevator moving. The voltage when the mechanism just starts moving is approximately kS.
+
+tune kG
+- to tune kG manually, find the voltage required for the mechanism to just begin moving upward, and then find the voltage required for it to just begin moving downward. These measurements represent approximately kS + kG and kS - kG, respectively. The two values can then be used to solve for kS and kG.
+
+tune kV
+- determine the kV by entering different velocities and determining how much kV is needed to maintain those.
+
+tune kA
+- often not needed
+- depends on how quickly we need the mechanism to accelerate, can try increasing kA until it is better though sysID is preferred 
+
+tune kP
+- increase kP until the elevator reaches the target quickly and accurately, it's overshooting or oscillating, it's probably too high.
+
+tune kD
+- if the elevator overshoots or oscillates as it approaches the target, adding kD may help. You can tune it by increasing it until the elevator settles smoothly without becoming excessively sluggish.
+
+tune kI
+- kI may not be necessarily but if there's consistently small position error it could help.
+
+### Arm tuning:
+Similar to elevator processes with kS, kG(when arm is horizontal), kV, kA (if necessary), kP, kD, and kI (if necessary)
+
+### roller tuning:
+typical rollers only need kS, kV, kA, kP, and kD
+
+## Additional tips:
+- using tools such as SysID (see sysId article) rather than this process can give you kS, kV, kG, and kA
+- kP and kD are usually small if feedforward is done correctly 
+- your tuning process and gains need to make sense for the control system your using whether that position, velocity, voltage, etc
+- many motor controllers support control slots allowing you to store and select different gains this may be helpful for situations where there is not one perfect set of gains for every situation (such as carrying a game piece vs not carrying a game piece)
+
+### Resources
+
+- [WPILib Intro to PID](https://docs.wpilib.org/en/stable/docs/software/advanced-controls/introduction/introduction-to-pid.html)
+- [WPILib PID Control](https://docs.wpilib.org/en/stable/docs/software/advanced-controls/controllers/pidcontroller.html)
+- [WPILib PIDController](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/controller/PIDController.html)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

Examples/KitbotDemoBasic/.gradle/buildOutputCleanup/cache.properties

@@ -0,0 +1,2 @@
+#Mon Jun 15 19:22:08 PDT 2026
+gradle.version=7.5.1

Examples/KitbotDemoFinal/.gradle/buildOutputCleanup/cache.properties

@@ -0,0 +1,2 @@
+#Mon Jun 15 19:21:29 PDT 2026
+gradle.version=7.5.1

Examples/KitbotDemoSim/.gradle/buildOutputCleanup/cache.properties

@@ -0,0 +1,2 @@
+#Mon Jun 15 19:22:10 PDT 2026
+gradle.version=7.5.1