75 lines
5.0 KiB
Markdown
75 lines
5.0 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/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.
|
||
|