infrapuzzle/terraform_shelly/AGENTS.md

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 apply to upload the templated script to the Shelly device over local HTTP RPC commands.

Architecture Decisions

1. Linear Isopleth Approximation (LIM I)

To determine if indoor relative humidity is high enough to warrant ventilation, we use a linear approximation of the Lowest Isopleth for Mould (LIM I) curve developed by Klaus Sedlbauer for biodegradable substrates (like wood or wallpaper).

Between 5^\circ\text{C} and 25^\circ\text{C}, the critical relative humidity threshold is calculated dynamically based on room temperature (T):

RH_{crit}(T) = 80\% - 0.5 \cdot (T - 10)

• At 10^\circ\text{C}, the critical threshold is 80\%.
• At 20^\circ\text{C}, the critical threshold is 75\%.

2. Room-to-Wall Safety Buffer (15%)

Since the sensor measures ambient room air, but mold grows on colder outer wall surfaces, we must compensate for the thermal gradient.

• Physical Effect: A 5^\circ\text{C} drop in temperature between room air (20^\circ\text{C}) and the wall surface (15^\circ\text{C}) causes the local relative humidity at the wall to spike from 60\% to 82\%, crossing the mold germination threshold.
• Action: We apply a 15\% safety buffer to the threshold. This targets keeping the ambient room air relative humidity below 60\% (when the room is at 20^\circ\text{C}) to keep wall surfaces safely below 80\% relative humidity.

The fan is only allowed to run if:

\text{humidity\_innen} \ge RH_{crit}(T) - 15\%

---

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.