Files

T

Moritz Graf 9903194316 feat(shelly): optimize dew point ventilation setpoints, duty cycle, and night-window gating

- Raise target humidity setpoints from 40% to 55% with a 2% hysteresis shut-off
- Eliminate 9999-min unlimited runtime bypass and strictly cap bursts at 35 min
- Rebalance duty cycle to 1:1 ratio (35 min run, 35 min cooldown rest)
- Implement Shelly internal RTC time-of-day check to restrict routine drying to 02:00-07:00
- Add delta-T guard requiring spread >= 3.5°C and max 20 min bursts when outside is >8°C colder
- Update AGENTS.md documentation to reflect optimized gates and thresholds

2026-10-20 15:46:30 +02:00

5.5 KiB

Raw Blame History

Shelly Fan Control Agent Documentation

This directory manages the configuration, code templating, and deployment for the Shelly Plug S (Gen 3) that controls the cellar ventilation fan to prevent mold.

Domain Structure & Key Files

main.tf: Coordinates rendering the JavaScript template and executing the Python upload script.
variables.tf: Defines MAC addresses for the Bluetooth sensors, safety parameters, and the mold calculation coefficients.
scripts/Taupi-4.0.js: The source Shelly control script containing the logic for parsing Bluetooth BTHome events, calculating dew points, evaluating mold danger, and switching the relay.
scripts/Taupi-4.0.templated.js: The locally generated script rendering the variables passed from Terraform. Do not edit directly.
scripts/upload.py: Helper script executing during terraform apply to upload the templated script to the Shelly device over local HTTP RPC commands.

Architecture Decisions & Logic Gates

The ventilation controller uses a modular logic-gate architecture designed to keep the cellar dry while preventing cellar overheating in summer and overcooling in winter.

1. Decoupled Mold Alert (Sedlbauer LIM I)

To distinguish between routine/proactive drying and genuine mold risk, the mold alert (taupi_is_critical metric \rightarrow Prometheus alert TaupiFanMoldDanger) is decoupled from the fan start threshold:

LIM I Baseline: RH_{crit}(T) = 80\% - 0.5 \cdot (T - 10)
Alert Activation: RH_{in} \ge RH_{crit}(T) - \text{critical\_humi\_buffer}
Behavior: Fires an alert only when humidity poses an actual germination hazard on cold outer walls.

2. Cellar Overheating Prevention

In warm months, blowing outdoor air into a cool cellar can heat up the cellar mass.

Ceiling Protection: If T_{in} \ge 20^\circ\text{C}, the fan is only permitted to run if outdoor air is cooler than inside (T_{out} \le T_{in}).
Warming Allowance: If T_{in} < 20^\circ\text{C}, gentle warming is permitted, but outdoor temperature cannot exceed 20^\circ\text{C} (T_{out} \le 20^\circ\text{C}).

3. Target Humidities

Target Humidity: Set to 55% RH (with a 2% hysteresis shut-off down to 53% when ventilating). Once 55% RH is reached, the fan rests to preserve cellar warmth and prevent excessive wall moisture desorption.
Hard Cold Floor: The fan is blocked if T_{in} \le \text{mindesttemperatur} (default 10°C).

4. 2-Tier Scheduling & Optimal Night Window

In Central Europe / Germany, the diurnal temperature and absolute humidity minimum occurs in early morning (~02:00–07:00, peak drying yield around 03:00–05:00 at ~7.6 g/m³ outdoor vapor content):

Urgent Drying (RH_{in} > 60\% or Mold Critical): Evaluated and run 24/7 whenever psychrometric and temperature guards allow.
Routine Drying (53\% \le RH_{in} \le 60\%): Strictly restricted to the optimal night window (02:00–07:00) to exploit maximum dew point spread and prevent wasteful daytime runs.
Thermal Delta Guard: If T_{in} - T_{out} > 8.0^\circ\text{C} (very cold outside draft), spread requirement increases by +1.5°C (spread \ge 3.5^\circ\text{C}) and burst duration is throttled to 20 min max.

5. Duty Cycle & Thermal Equilibrium

To allow cellar air and thermal wall mass to equilibrate and prevent non-stop continuous blowing:

Max Continuous Runtime: Strictly capped at 35 minutes (scaled dynamically between 15 and 35 min based on dew point spread; no unlimited 9999 bypass).
Cooldown Rest: 35 minutes pause (1:1 duty cycle) after hitting max runtime to allow concrete and masonry moisture desorption.

Logic Gate Summary

                      [ Telemetry Fresh & Valid? ]
                                   │ YES
                      [ Cooldown Rest Elapsed? ]
                                   │ YES
                      [ Cellar Temp > Min Floor (10°C)? ]
                                   │ YES
                      [ Overheating Safe (Tout vs Tin)? ]
                                   │ YES
                      [ Cellar RH > Target Setpoint (55%)? ]
                                   │ YES
                      [ Urgent (>60%) OR Night Window (02-07)? ]
                                   │ YES
                      [ Dew Point Spread > Required Threshold? ]
                                   │ YES
                          ┌────────┴────────┐
                          ▼                 ▼
                   [ START BLOWER ]   [ LOG REASON ]

Sources & References

BoeserBob/Taupi-4.0: The original upstream Shelly dew point ventilation controller repository.
Klaus Sedlbauer Biography (Wikipedia): The researcher who developed the Lowest Isopleth for Mould (LIM) curves at Fraunhofer IBP.
WUFI Biohygrothermal Model: Fraunhofer IBP documentation explaining dynamic mold growth and spore germination models.

5.5 KiB Raw Blame History Unescape Escape