Moritz Graf
9903194316
- 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
75 lines
5.5 KiB
Markdown
75 lines
5.5 KiB
Markdown
# 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](file:///Users/moritz/src/infrapuzzle/projects/shelly_taupunktluefter/main.tf)**: Coordinates rendering the JavaScript template and executing the Python upload script.
|
||
* **[variables.tf](file:///Users/moritz/src/infrapuzzle/projects/shelly_taupunktluefter/variables.tf)**: Defines MAC addresses for the Bluetooth sensors, safety parameters, and the mold calculation coefficients.
|
||
* **[scripts/Taupi-4.0.js](file:///Users/moritz/src/infrapuzzle/projects/shelly_taupunktluefter/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](file:///Users/moritz/src/infrapuzzle/projects/shelly_taupunktluefter/scripts/Taupi-4.0.templated.js)**: The locally generated script rendering the variables passed from Terraform. Do not edit directly.
|
||
* **[scripts/upload.py](file:///Users/moritz/src/infrapuzzle/projects/shelly_taupunktluefter/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](https://github.com/BoeserBob/Taupi-4.0)**: The original upstream Shelly dew point ventilation controller repository.
|
||
* **[Klaus Sedlbauer Biography (Wikipedia)](https://de.wikipedia.org/wiki/Klaus_Sedlbauer)**: The researcher who developed the Lowest Isopleth for Mould (LIM) curves at Fraunhofer IBP.
|
||
* **[WUFI Biohygrothermal Model](https://wufi.de/en/wufi-software/wufi-bio/)**: Fraunhofer IBP documentation explaining dynamic mold growth and spore germination models.
|
||
|