# 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/terraform_shelly/main.tf)**: Coordinates rendering the JavaScript template and executing the Python upload script.
*   **[variables.tf](file:///Users/moritz/src/infrapuzzle/terraform_shelly/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/terraform_shelly/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/terraform_shelly/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/terraform_shelly/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. Seasonal Target Humidities
*   **Cold / Winter Mode** ($T_{in} < 14^\circ\text{C}$ or $T_{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](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.