[IntakeArm] Tune Motion Magic PID gains and profile

4. IntakeArm & Uptake Tuning

The IntakeArm has a finite range of travel and uses Motion Magic (TalonFX on-controller closed-loop) to move to commanded positions. Software soft limits, stator current limiting, and optional hardware limit switches protect the mechanism.

4a. Zeroing and Soft Limits (Horizontal = 0)

Important Concept: To properly calculate gravity feedforward, the arm's angle relative to gravity must be known. In this codebase, 0 rotations = PERFECTLY HORIZONTAL.

Parameters to Tune (RobotMap.IntakeArm):

• FORWARD_SOFT_LIMIT (currently 90.0 / 360.0 rotations) — motor rotations at the fully retracted (home/stowed) straight-up position.
• REVERSE_SOFT_LIMIT (currently 0.0 / 360.0 rotations) — motor rotations corresponding to the arm fully deployed (down).

4b. Tuning Procedure (using Test Mode)

We have built dedicated tuning controls into Test Mode (in Robot.java) to make this safe and easy.

Step 1: Set Position / Zero Encoders
You MUST do this first so the robot knows where horizontal is.

1. Enable the robot in Test Mode.
2. OPTION A (Easy Way): If you let the arm boot up resting naturally against its straight-up (stowed) hard stop, simply press the Start button on the Operator controller. This forces the encoder to the STOWED_POSITION (+90 deg).
3. OPTION B (Manual Way): If you physically moved the arm so it is perfectly horizontal before enabling, press the Back button on the Operator controller to zero the encoders (0 deg).

Step 2: Tune Gravity Feedforward ($kG$)

1. Ensure the arm is free to move.
2. In Phoenix Tuner X, find Slot0 for the IntakeArm motors.
3. Slowly increase kG (starting from 0.0).
4. Find the minimum voltage value where kG alone can hold the arm horizontal against gravity without dropping. Record this value in IntakeArm.java.

Step 3: Tune Motion Magic PID

1. While still in Test Mode, use the Operator D-Pad to snap between positions:
   • D-Pad Up: Move to STOWED_POSITION
   • D-Pad Down: Move to DEPLOYED_POSITION
2. Adjust kP (currently 12.0) and kD (currently 0.1) in IntakeArm.java until the arm snaps cleanly without violent overshoot or sluggishness.

4c. Stator Current Limit

Parameter (RobotMap.IntakeArm):

• STATOR_CURRENT_LIMIT (currently 40.0 A) — protects the motor from stall damage when the arm reaches a hard stop. Lower values provide more protection but reduce peak torque. 30–50 A is a reasonable range for an arm mechanism.

4e. Uptake Feed Rate

Parameter (RobotMap.Uptake):

• UPTAKE_SPEED (currently 0.8) — simple percent output. If balls are jamming, reduce speed. If flywheel speed drops too much before the second shot, reduce speed to smooth feeding.