# 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.