5.0 KiB
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 applyto 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 exceed20^\circ\text{C}(T_{out} \le 20^\circ\text{C}).
3. Seasonal Target Humidities
- Cold / Winter Mode (
T_{in} < 14^\circ\text{C}orT_{out} < 10^\circ\text{C}): Targets 50% RH. Once 50% RH is reached, the fan stops to preserve cellar warmth. - Warm / Summer Mode: Targets 40% RH for maximum drying.
- 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 (~03:00–07:00, peak around 05:00):
- Urgent Drying (
RH_{in} > 60\%): Runs 24/7 whenever psychrometric and temperature guards allow. - Routine Drying (
40\% \le RH_{in} \le 60\%): Restricted to the optimal night window (03:00–07:00) to exploit maximum dew point spread.
5. Duty Cycle & Thermal Equilibrium
To allow cellar air and thermal wall mass to equilibrate and prevent non-stop continuous blowing:
- Max Continuous Runtime: 90 minutes.
- Cooldown Rest: 45 minutes pause after hitting max continuous runtime.
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 (40% / 50%)? ]
│ YES
[ Dew Point Spread > Threshold (2°C)? ]
│ YES
[ Urgent (>60%) OR Night Window (03-07)? ]
│ 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.