brewpi/components/plant/TODO.md

components/plant design backlog

Findings from reviewing pot.py's water-bath model against real-plant behavior (sim/real control mismatch reported by user). Not yet acted on.

• Heat-loss term has wrong units. pot.py:37: leak = 1/self.M * self.L * (self.theta_amb - self.temp)/self.theta_amb. The power term right above it is power/(self.M * self.C) (W / (J/K) -> K/s). leak should follow the same pattern — self.L * (self.theta_amb - self.temp) / (self.M * self.C) — but instead it's missing /C and divides by theta_amb (~20) instead, which isn't a physically meaningful normalization. With C=4190 this suppresses ambient heat loss by ~3-4 orders of magnitude versus what the power term implies, so the simulated pot barely cools at all. The Smith predictor's internal model is also a Pot instance with the identical bug, so this never showed up in sim-vs-sim testing — only against the real plant. Likely the primary cause of the sim/real control mismatch.

• kn is loaded but never applied. pot.py:18 reads params['kn'] but nothing in process()/get_temperature() uses it. Git history shows it used to add Gaussian sensor noise (self.kn * np.random.normal(...)) to the output, since commented out and then dropped during the heat-diffusion refactor. Sim is currently fully deterministic/noise-free, making the Kalman filter and PID derivative term look better-behaved in sim than they will against a real noisy sensor. Re-enable as measurement noise (and decide if process noise is also wanted).

• theta_amb is hardcoded, not configured. brewpi.py:40 passes a literal 20 instead of reading it from config or a live ambient sensor. Real ambient temperature drifts and is never modeled as a disturbance, so the controller's robustness to it is untested.

• Thermal lag modeled as single-pole lag, not transport delay. HeatDiffusion (heat_diffusion.py) implements alpha=dt/Td exponential smoothing, not true dead time. There's already a Delay class (plant/delay.py) for pure transport delay, dropped in favor of HeatDiffusion in commit 16cb3d3. If the real pot's heater-to-sensor coupling behaves more like dead time (heat must propagate through the water before reaching the sensor) than a single lag, Td won't represent the same dynamic in sim vs. reality, and the Smith predictor's delay compensation (which assumes Td matches the real plant) will be off.

• No actuator/process realism. No heater power saturation enforced inside Pot itself (handled ad hoc in test harnesses), no evaporation/lid heat loss, no varying thermal mass M as volume changes (e.g. boil-off, adding water/grain) — M is a fixed constant for the whole simulation.