brewpi/components/pid/TODO.md

components/pid design backlog

Findings from a design review, not yet acted on. See git history on claude_refactor for items already fixed (Smith predictor's delay correction enabled, the two TempController classes deduplicated into temp_controller_base.py).

• FSM thresholds aren't configurable. Moved into an optional TempCtrl.Thresholds config section (HoldIdle, HoldHeat, IdleHeat, IdleHold, HeatHold, HeatIdle), merged over DEFAULT_THRESHOLDS in tc_constants.py so existing configs without the section keep working unchanged.

• Pid.scale() is a gain-scheduling hack, not anti-windup. pid.py's scale(k) multiplies every gain by 1/heatrate_soll_set (called from temp_controller*.py's process()), but it's framed as overshoot compensation, conflated with the real anti-windup logic a few lines below. self.k also never resets in reset(), so a stale scale factor can survive a state-transition reset. Consider moving this scheduling logic out of the generic Pid class and into the temp controller, and resetting k in reset().

• Three Kalman filters share one tuning. In temp_controller_smith.py, kalman_model, kalman_model_delay, and kalman_plant are all constructed with the same params['Kalman'] despite tracking signals with different noise characteristics. Allow independent var_P/var_Q/var_R per filter in config.

• matplotlib imported at module level in production code. temp_controller.py, temp_controller_smith.py, and kalman.py all from matplotlib.pyplot import ... just to support their __main__ self-test plots, which couples the live server's import graph (and its dependency list) to a GUI plotting library it never uses at runtime. Move the plotting demos into separate scripts.

• No automated tests. The __main__ blocks (and kalman_eval.py) are manual, eyeballed-plot harnesses. Add regression tests for FSM transitions, anti-windup clamping, and Kalman convergence — this code drives a physical heater.

• Config access is unchecked dict[key] everywhere. params['Kalman'], model_params['gain'], etc., throughout, with no schema validation at load time. We already hit this bug class once (config.json.sim's gain/Model nesting mismatch). A small schema/dataclass validation layer at config-load would surface errors immediately instead of mid-__init__.