brewpi/components/TODO.md

components/sud.py step lifecycle spec

Confirmed spec for a Sud schedule step's internal phase order (components/sud.py), from a design discussion clarifying how ramp/ hold/user-confirm interact.

Phase order

ramp -> hold -> user-confirm. Each step independently opts into ramp and/or hold by including that key (_build_step(), sud.py:35-45); the other phase is skipped entirely if its key is absent. The 'ramp' key's presence is the only trigger for ramping (_advance(), sud.py:192-210) - there is no diff-based decision (T_actual vs. T_target) anywhere that decides whether to ramp, and no internal setpoint-trajectory limiter in the temperature controller (set_theta_soll() is an instant, unconditional assignment, components/pid/temp_controller_base.py:81-82). The ramp key both gates ramping and carries its settings (rate); it does not merely override settings on top of an always-on ramp.

Duration 0

Supported for hold: hold_remaining = duration * 60.0 can be 0; tick() (sud.py:186-190) finishes the step on the next tick once hold_remaining <= 0.

End-of-step branching

_finish_step() (sud.py:212-216): no user_wait_for_continue -> advances immediately to the next step; user_wait_for_continue: true -> enters WAIT_USER, resumed only by confirm().

WAIT_USER is not "hold, prolonged": HOLDING and WAIT_USER are distinct SudState values. The hold countdown runs to completion before WAIT_USER begins - tick() only decrements hold_remaining while state == HOLDING, so the timer is frozen (not extended) during the wait. It delays the next step, but it's a separate third phase, not a longer hold.

The gating field is user_wait_for_continue, not "presence of a user message": user_message (display text) and user_wait_for_continue (the actual block) are independent fields - a step can show a message without blocking, or block silently.

Open items

• Pure-hold steps never (re-)set the controller's target temperature. For a step with only hold (no ramp), tasks/sud.py's on_step_changed never calls tc.set_theta_soll()
  • the guard at line 73 requires ramp is not None. The controller's target temperature for a pure-hold step is whatever was left from the previous step's ramp; there's no explicit fallback to the hold step's own temperature field. README.md (Mash schedules section) documents this as designed behavior ("SudTask drives ... theta_soll/heatrate_soll from ramp steps ... counts down hold steps' duration"), so it's intentional, not a bug - but it means a schedule can't express a temperature jump straight into a hold without a ramp block.