Three-Loop Cascaded Control: Three independent controllers run at different rates and stack on top of each other. The output current loop runs 10 times per second and drives the alternator field duty cycle to chase a current target. The voltage loop also runs 10 times per second, but only during Bulk, Absorption, and Float — it computes the current target that holds the battery at the configured voltage. The temperature loop runs once every 5 seconds, and outputs a single thermal penalty in amps that gets subtracted from the RPM Cap Table ceiling before the inner loops see it. The cascade is strict: temperature constrains what current the voltage loop is allowed to ask for; the voltage loop constrains what the output current loop is allowed to chase; the output current loop is the only thing that touches the field. Each layer never reaches past the one below it.

RPM Cap Table: For each engine RPM range, you configure a hard ceiling based on your installation's physical limits — belt load, shaft stress, alternator and battery bank ratings. This ceiling is enforced after the thermal penalty is applied and is never exceeded regardless of thermal state. The ceiling can be entered as either a current limit (Amps mode) or a power limit (kW mode) using the toggle above the table. In Amps mode the configured value is a fixed current ceiling. In kW mode the regulator divides your power limit by live battery voltage on every control tick to derive the amp ceiling — so the mechanical load on the belt and shaft stays constant regardless of voltage sag or rise during charging.

Forecasted Thermal Penalty: The temperature controller does not act on the current temperature reading. It acts on a projected temperature — current filtered temperature plus the measured rate of rise multiplied by the Thermal Lookahead horizon (default 90 seconds). This is what lets the loop pull current down before the alternator actually reaches the limit. The setpoint is the real damage limit (Alternator Temp Limit) and the output is a penalty in amps: zero means no restriction, higher numbers mean more current pulled away from what the RPM Cap Table would otherwise allow. Because the penalty is relative rather than absolute, it transfers cleanly across RPM and stage changes. The penalty itself is slew-limited so brief temperature noise doesn't cause harsh current swings.

Voltage Loop: A proportional-integral controller (Voltage Loop Kp and Ki) holds battery voltage at target during Bulk, Absorption, and Float. The integrator uses asymmetric gain — it bleeds down fast when voltage runs above target and rises slowly when below, biasing toward safety. The Slope Bleed Gain drains the integrator when voltage is climbing quickly, which prevents overshoot during the approach to target. Anti-windup freezes upward integration whenever the current ceiling — not voltage — is the binding constraint, so the integrator does not load up while unable to act.

Three-Stage Charging: The regulator implements a constant-current / constant-voltage / float charging cycle (CC/CV/Float), with an optional Idle mode after Absorption for lithium longevity.

In Bulk, the voltage loop is off and the system charges at the maximum thermally allowed current from the RPM Cap Table. This continues until battery voltage has been held at the Bulk Voltage target continuously for the Bulk Voltage Debounce Time — a debounce that prevents transient voltage spikes from triggering a premature transition.

In Absorption, the voltage loop engages and holds the battery at the Absorption Voltage. The battery itself now dictates how much current it accepts — current tapers naturally as the battery fills. The system exits Absorption when charge current has dropped to or below the Tail Current for the Absorption Completion Time, confirming the battery is genuinely full. If the system is thermally constrained — meaning the thermal penalty is meaningfully active AND current is already near the Tail Current — tail detection is suspended until thermal headroom recovers, preventing a false exit before the battery is truly full. A safety timeout (Absorption Timeout) forces a transition to Float (or Idle, if Use Float is Off) if Tail Current is never reached.

In Float, the voltage loop holds the battery at the lower Float Voltage. After the Minimum Float Time has elapsed, the system monitors for voltage sag or sustained discharge current. If either condition persists for the Rebulk Debounce Time, or if Float Duration expires, Bulk charging restarts — subject to SoC blocking if SoC data is available. If Use Float is Off, the system skips Float entirely and enters Idle after Absorption, charging again only when rebulk criteria are met.

Independent Protection Layers: Several fast-response protections sit outside the three-loop cascade and act on raw sensor readings without filter lag. Fast OV (Groups 1 and 2) caps current immediately when raw battery voltage runs above a margin below the charging target. Load Dump protection caps current when a sustained battery-current rise rate is detected, catching FET disconnect or load drop events. Group 3 (iExcess) bleeds the voltage-loop integrator if current overshoots, killing the cause rather than just the symptom. None of these depend on the control loops being active — they are always armed.

Stability and Recovery: All mode transitions are bumpless — both the output current loop integrator and the voltage loop integrator are seeded to the operating point before the new mode takes over, so transitions never produce a setpoint step. If the temperature sensor goes stale, the temperature loop holds its last penalty value and re-enters smoothly when fresh data returns rather than snapping back. Anti-windup keeps the temperature integrator parked near any tighter non-thermal constraint when thermals are not the binding limit, so the penalty can climb the instant temperature demands it. A hardware-level shutdown path (GPIO4) provides two independent escape hatches: immediate cut for critical conditions (temperature critically over limit, hard fault) and a controlled ramp-then-cut for sustained warning-level conditions. GPIO4 protection remains active regardless of loop state. Any fault that interrupts charging restarts from Bulk when charging resumes, never mid-cycle.

Overview: The output current loop, the voltage loop, and the temperature loop each have their own dedicated tuning mode (Tuning Mode for the inner current loop, CV Tuning Mode for the voltage loop, Thermal Tuning Mode for the temperature loop). Tune them in that order — inner loop first, then voltage, then thermal — because each layer depends on the one beneath it being stable. This section covers the inner current loop. Voltage and thermal tuning have their own dedicated tabs with built-in step tests and live scoring.

Three-Phase Process: The goal is to tune the core PID first, then verify it handles the rate limiters gracefully with anti-windup tracking. Tune in bulk stage — absorption and float share the same output current loop, so a well-tuned bulk response carries through automatically.

Phase 1 — Core Loop (Unrestricted):
Set both slew limiters to very high values to effectively disable them:
• Setpoint Rise Rate: 1000 A/s
• Setpoint Fall Rate: 1000 A/s
• Duty Ramp Rate: 1000 %/s
Enable Tuning Mode and watch the step response on the plots. Tune Kp, Ki, and Kd until you get well-damped step responses with minimal overshoot (10–20%) and fast settling time (2–4 seconds).

Phase 2 — Actuator Slew + Anti-Windup:
Re-enable the actuator slew limiter by setting Duty Ramp Rate to a realistic value (typically 10–30 %/s). Keep setpoint slew limiters high (1000 A/s). Run tuning mode again and watch for overshoot after transitions. If you see overshoot once the duty ramp catches up, increase PID Tracking Gain from its default until the overshoot disappears. This is the back-calculation gain that bleeds the integrator down whenever the duty output is rate-limited.

Phase 3 — Production Verification:
Set Setpoint Rise Rate and Setpoint Fall Rate to your desired production values (typically 5–20 A/s rise, 20–50 A/s fall). Run tuning mode one final time to verify the loop remains stable and well-behaved with both rate limiters active.

Tuning Philosophy for Cruising:
Run tests at moderate RPM within your typical cruising range. A slower, well-damped loop (4–6 second settling time) is preferable to a fast loop that causes harsh load transitions. The independent protection layers (Fast OV, Load Dump, Group 3 iExcess, GPIO4 hard cut) handle the unsafe edges — you don't need the loop itself to react instantly. Smooth and stable beats fast and harsh.

Current Defaults: Kp = 0.5, Ki = 2.0, Kd = 0.01, PID Tracking Gain = 4.0, Duty Ramp Rate = 50 %/s, Setpoint Rise Rate = 30 A/s, Setpoint Fall Rate = 50 A/s. These are sensible starting points but every installation is different — always verify with a step test in your own setup.