Refactor code structure for improved readability and maintainability

Author: DanielKusyDev

.claude/prompts/authority-troubleshoot.md

@@ -0,0 +1,360 @@
+# ESP-Drone PID Configuration Analysis
+
+You are analyzing the **ESP-Drone firmware** to understand how PID gains are defined, scaled, and applied to determine the correct gain values for comparison with another firmware.
+
+## Your Task
+
+Extract and document the complete PID control pipeline from ESP-Drone, focusing on:
+
+1. **PID Gain Definitions**
+2. **Unit Scaling and Conversions**
+3. **Control Pipeline Flow**
+4. **Effective Gain Calculations**
+
+---
+
+## Section 1: Find PID Gain Definitions
+
+### Search Strategy
+```bash
+# Search for PID gain definitions (likely in config files)
+grep -r "pidAngleRoll\|pidRateRoll\|ANGLE.*KP\|RATE.*KP" --include="*.h" --include="*.c"
+grep -r "PID_ANGLE\|PID_RATE" --include="*.h" --include="*.c"
+grep -r "Kp.*=.*[0-9]\|Ki.*=.*[0-9]\|Kd.*=.*[0-9]" --include="*.h" --include="*.c"
+```
+
+### Questions to Answer
+
+1. **Where are PID gains defined?**
+   - File path and line numbers
+   - Are they in a config file, header, or source file?
+
+2. **What are the EXACT gain values?**
+   ```cpp
+   // Find and report:
+   PID_ANGLE_ROLL_KP   = ?
+   PID_ANGLE_ROLL_KI   = ?
+   PID_ANGLE_ROLL_KD   = ?
+
+   PID_RATE_ROLL_KP    = ?
+   PID_RATE_ROLL_KI    = ?
+   PID_RATE_ROLL_KD    = ?
+
+   // Same for PITCH and YAW
+   ```
+
+3. **What are the gain UNITS?**
+   - Are gains defined as integers or floats?
+   - Are there unit conversion macros (e.g., `#define KP(x) ((x) * 1000)`)?
+   - Are gains stored as fixed-point (e.g., multiply by 1000 for precision)?
+
+4. **Are there multiple gain sets?**
+   - Default vs tuned values?
+   - Different modes (ANGLE vs ACRO)?
+   - Flight mode dependent gains?
+
+---
+
+## Section 2: Trace PID Implementation
+
+### Find PID Controller Code
+
+```bash
+# Search for PID computation functions
+grep -r "pidUpdate\|pidCompute\|pid_update\|PID.*update" --include="*.c" --include="*.cpp"
+grep -r "error.*=.*setpoint.*-.*measurement" --include="*.c"
+```
+
+### Questions to Answer
+
+1. **Where is the PID controller implemented?**
+   - File path and function name
+   - Is it a class, struct, or function?
+
+2. **What is the PID formula?**
+   ```cpp
+   // Find and report the exact computation:
+   error = setpoint - measurement;
+   iTerm += Ki * error * dt;
+   dTerm = Kd * (error - lastError) / dt;
+   output = Kp * error + iTerm + dTerm;
+   ```
+
+3. **Are gains scaled during computation?**
+   - Are Kp/Ki/Kd divided or multiplied by constants?
+   - Example: `output = (Kp * error) / 1000` (fixed-point scaling)
+
+4. **What are the PID output limits?**
+   ```cpp
+   // Find the saturation limits:
+   Angle PID output limits: min = ?, max = ?
+   Rate PID output limits:  min = ?, max = ?
+   ```
+
+5. **What is the PID output data type?**
+   - `float`, `int16_t`, `int32_t`?
+   - This is CRITICAL for understanding magnitude!
+
+---
+
+## Section 3: Control Pipeline Flow
+
+### Find Cascaded PID Chain
+
+```bash
+# Search for control loop
+grep -r "controllerTask\|control_loop\|pidLoop" --include="*.c"
+grep -r "angle.*pid\|rate.*pid" --include="*.c"
+```
+
+### Questions to Answer
+
+1. **Trace the control flow from RC input to motors:**
+
+   ```
+   RC Input (roll/pitch/yaw setpoints)
+        ↓
+   [Angle PID] → angle_output (what units? deg/s?)
+        ↓
+   [Rate PID] → rate_output (what units? int16? float?)
+        ↓
+   [Scaling/conversion?] → scaled_output
+        ↓
+   [Mixer] → motor commands (what units? PWM duty? 0-65535?)
+        ↓
+   [Motor output] → actual PWM
+   ```
+
+2. **What are the units at each stage?**
+   - RC input: degrees? ±1000? ±32767?
+   - Angle PID input: degrees
+   - Angle PID output: deg/s (rate setpoint)
+   - Rate PID input: deg/s
+   - Rate PID output: **WHAT UNITS?** (int16? float? ±32767? ±100?)
+   - Mixer input: **WHAT UNITS?**
+   - Motor output: PWM duty cycle (0-65535? 0-1000?)
+
+3. **Are there scaling factors between stages?**
+   ```cpp
+   // Look for code like:
+   rate_output = rate_pid.compute(...);
+   rate_output_scaled = rate_output / SOME_CONSTANT;
+   mixer_input = rate_output_scaled * ANOTHER_CONSTANT;
+   ```
+
+---
+
+## Section 4: Mixer Configuration
+
+### Find Mixer Code
+
+```bash
+# Search for mixer implementation
+grep -r "mixer\|motorMix\|powerDistribution" --include="*.c" --include="*.h"
+grep -r "motor\[0\]\|motor\[1\]\|motor\[2\]\|motor\[3\]" --include="*.c"
+```
+
+### Questions to Answer
+
+1. **What are the mixer equations?**
+   ```cpp
+   // Find the exact formulas:
+   motor[0] = thrust ± roll ± pitch ± yaw;
+   motor[1] = thrust ± roll ± pitch ± yaw;
+   motor[2] = thrust ± roll ± pitch ± yaw;
+   motor[3] = thrust ± roll ± pitch ± yaw;
+   ```
+
+2. **Are PID outputs scaled before mixing?**
+   ```cpp
+   // Look for code like:
+   int16_t r = control->roll / 2.0f;  // ← CRITICAL!
+   int16_t p = control->pitch / 2.0f;
+   int16_t y = control->yaw;
+   ```
+
+3. **What is the thrust range?**
+   - RC throttle input: 0-1000? 0-65535?
+   - Mixer thrust input: same units or converted?
+
+4. **What is the motor output range?**
+   - PWM duty cycle: 0-65535? 1000-2000? 0-100%?
+
+---
+
+## Section 5: Calculate Effective Gains
+
+### Combine All Scaling Factors
+
+Once you have all the information above, calculate the **effective gain** from angle error to motor differential:
+
+```
+Example calculation:
+
+Given: Roll angle error = 10 degrees
+
+Step 1: Angle PID
+  output = Kp_angle * error = 6.0 * 10 = 60 deg/s (rate setpoint)
+
+Step 2: Rate PID (assume measured rate = 0)
+  error = 60 - 0 = 60 deg/s
+  output = Kp_rate * error = 190.0 * 60 = 11,400 (int16)
+
+Step 3: Mixer scaling (if roll/2 division exists)
+  scaled_output = 11,400 / 2 = 5,700
+
+Step 4: Mixer differential (X-quad)
+  Left motors = base + roll = base + 5,700
+  Right motors = base - roll = base - 5,700
+  Left-Right differential = 11,400 PWM units
+
+Step 5: Convert to percentage of full range
+  Differential = 11,400 / 65,535 ≈ 17.4% of full motor range
+```
+
+### Report Format
+
+```markdown
+## Effective Gain Calculation
+
+**Angle-to-Rate Gain**: Kp_angle = X.X
+**Rate-to-Output Gain**: Kp_rate = X.X
+**Mixer Scaling Factor**: X.X (e.g., 0.5 if divide by 2)
+**Output Range**: 0 to XXXXX
+
+**Effective Gain** (10° angle error → motor differential):
+  = Kp_angle * Kp_rate * mixer_scaling * 2 (differential multiplier)
+  = X.X * X.X * X.X * 2
+  = XXXXX motor units per 10° error
+
+**As percentage of motor range**:
+  = (XXXXX / MAX_MOTOR_VALUE) * 100%
+  = XX.X%
+```
+
+---
+
+## Section 6: Find Any Additional Scaling
+
+### Search for Hidden Scaling Factors
+
+```bash
+# Look for authority scaling, throttle gating, etc.
+grep -r "authority\|stab.*gain\|throttle.*scale" --include="*.c"
+grep -r "MIN_THROTTLE\|MAX_THROTTLE\|IDLE" --include="*.h"
+```
+
+### Questions to Answer
+
+1. **Is there dynamic authority scaling based on throttle?**
+   - Does PID output get reduced at low/high throttle?
+
+2. **Is there a "stabilization gain" multiplier?**
+   - Does PID output ramp up based on throttle level?
+
+3. **Are there output clamps/limits?**
+   - Are PID outputs clamped before reaching the mixer?
+
+4. **Are there any unit conversion constants?**
+   - Example: `#define ANGLE_TO_RATE_SCALE 1000`
+
+---
+
+## Section 7: Compare to Reference Firmware
+
+The reference firmware has:
+
+```cpp
+// Reference firmware (drone-firmware):
+PID_ANGLE_ROLL_KP   = 3.0
+PID_ANGLE_PITCH_KP  = 3.0
+PID_RATE_ROLL_KP    = 0.12
+PID_RATE_PITCH_KP   = 0.12
+
+// PID outputs: float (±100 typical range)
+// Motor outputs: 0-1000 (PWM duty)
+// Mixer: NO scaling (direct application of roll/pitch/yaw)
+```
+
+### Comparison Table
+
+Create a side-by-side comparison:
+
+| Parameter | ESP-Drone | Reference Firmware | Ratio |
+|-----------|-----------|-------------------|-------|
+| Angle Kp | X.X | 3.0 | X.Xx |
+| Rate Kp | X.X | 0.12 | X.Xx |
+| PID output type | int16/float? | float | - |
+| PID output range | ±XXXXX | ±100 | XXXx |
+| Mixer scaling | /2 or none? | none | X.Xx |
+| Motor range | 0-XXXXX | 0-1000 | XXx |
+| **Effective gain** | XXXXX | 12 | XXXXx |
+
+---
+
+## Section 8: Critical Files to Check
+
+Based on typical ESP-IDF/Arduino drone firmware structure, prioritize these files:
+
+1. **`components/config/include/config.h`** - PID gain definitions
+2. **`components/core/crazyflie/modules/src/controller_pid.c`** - PID implementation
+3. **`components/core/crazyflie/modules/src/power_distribution_quadrotor.c`** - Mixer
+4. **`components/drivers/general/motors/src/motors.c`** - Motor output
+5. **`main/flight/flight_control.c`** or similar - Main control loop
+
+If files don't match these names, search for similar patterns.
+
+---
+
+## Output Format
+
+Organize your findings as follows:
+
+### 1. PID Gain Definitions
+- File: `path/to/file.h:line`
+- Values: `Kp=X.X, Ki=X.X, Kd=X.X`
+- Units: int16/float, any scaling macros
+
+### 2. PID Implementation
+- File: `path/to/file.c:line`
+- Formula: [exact code snippet]
+- Output type: int16_t/float
+- Output limits: ±XXXXX
+
+### 3. Control Pipeline
+- [Diagram showing units at each stage]
+- Scaling factors between stages
+
+### 4. Mixer Configuration
+- Equations: [motor mixing formulas]
+- Scaling: [roll/pitch/yaw scaling before mixing]
+- Output range: 0-XXXXX
+
+### 5. Effective Gain Calculation
+- [Step-by-step calculation]
+- Final result: XXXXX motor units per 10° angle error
+
+### 6. Comparison Table
+- [Side-by-side with reference firmware]
+
+### 7. Key Findings
+- **Critical differences** that explain magnitude mismatch
+- **Recommended scaling factors** to port gains to reference firmware
+
+---
+
+## Critical Questions
+
+Answer these YES/NO questions with file:line citations:
+
+1. **Are PID gains stored as integers multiplied by 1000?** YES/NO (`file:line`)
+2. **Are PID outputs int16_t (±32767 range)?** YES/NO (`file:line`)
+3. **Is roll/pitch divided by 2 before mixing?** YES/NO (`file:line`)
+4. **Is motor PWM range 0-65535 (16-bit)?** YES/NO (`file:line`)
+5. **Is there dynamic authority scaling?** YES/NO (`file:line`)
+
+---
+
+## Begin Analysis
+
+Start by searching for PID gain definitions, then trace the entire control pipeline. Provide code snippets and exact line numbers for every claim.

.claude/prompts/esp-drone-pid-analysis.md

@@ -27,7 +27,10 @@
       "Bash(timeout 30 pio test:*)",
       "Bash(timeout 30 pio run -e native -t clean)",
       "Bash(timeout:*)",
-      "Bash(python:*)"
+      "Bash(python:*)",
+      "Bash(mkdir:*)",
+      "Bash(ls:*)",
+      "Bash(xargs:*)"
     ],
     "deny": [],
     "ask": []