Gains tuning

Docs/3_Specifics/3.6_GainsTuning.md

@@ -0,0 +1,101 @@
+# 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 static friction. 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
+
+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 acceleration. 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
+
+kG is gravity. 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). 
+
+## Feedback constants
+kP is proportional. 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 based on the accumulated error over time. An integral is the area under a curve or in our case the error accumulated over time so if error gradually builds up in our system I can help with that. 
+- kI is often not needed and will be set to 0 or a very small value in most cases. This is because kP and kD are often good enough. If kI is too high it can cause overshooting. 
+
+kD is based on how quickly the error is changing, it is looking at the rate of change of the error or how quickly it's approaching the target.  
+- low kD can make the mechanism overshoot or oscillate.
+- high kD can make the mechanism too slow to react or react excessively. 
+
+## 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, kV, kA, kG, kP, kD, kI (note: not all may be needed)
+
+### 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 kV
+- determine the kV by entering different velocities and determining how much kV is needed to maintain those. 
+
+tune kA
+- depends on how quickly we need the mechanism to accelerate, try increasing kA until it works
+
+tune kG
+- increase kG until it counteract gravity (i.e enough to hold its position, not fall or rise when its supposed to hold still).
+
+tune kP
+- increase kP until elevator reaches target quickly and accurately, it its overshooting or oscillating its 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 may help.
+
+### Arm tuning:
+similar to elevator processes with kS, kV, kA if necessary, kG(when arm is horizontal), kP, kD, and kI is 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, and kA
+- 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