doc: Add documentation for temperature limiters

XavierBerger · Nov 30, 2024 · 3d44f82 · 3d44f82
1 parent 4864b58
commit 3d44f82
Show file tree

Hide file tree

Showing 14 changed files with 120 additions and 5 deletions.
diff --git a/docs/firmware.md b/docs/firmware.md
@@ -10,10 +10,11 @@ Packages are :
 * **Engine** : design to determine how much of energy and when surplus of energy should be diverted to the load.
 * **Regulator** : design to channel the surplus of energy to a designated load.
 * **Energy counter** : design to report the amount of energy diverted to the load.
+* **Temperature limiter**: design to stop the system when a temperature limit is reached
 
 ## Packages
 
-Packages can be combined to create a variaty of solar router as in following examples.
+Packages can be combined to create a variety of solar router as in following examples.
 
 
 ### Standalone configuration

diff --git a/docs/images/DS18B20_wiring.png b/docs/images/DS18B20_wiring.png
diff --git a/docs/images/hysteresis.png b/docs/images/hysteresis.png
diff --git a/docs/images/packages.drawio.png b/docs/images/packages.drawio.png
diff --git a/docs/images/schmitt_trigger.png b/docs/images/schmitt_trigger.png
diff --git a/docs/images/temperature_limiter_controls.png b/docs/images/temperature_limiter_controls.png
diff --git a/docs/images/temperature_limiter_sensor.png b/docs/images/temperature_limiter_sensor.png
diff --git a/docs/power_meter_home_assistant.md b/docs/power_meter_home_assistant.md
@@ -11,7 +11,7 @@ packages:
     file: solar_router/power_meter_home_assistant.yaml
 ```
 
-This package needs to know the sensor to use to get the power consumption. This sensor has to be defined by `main_power_sensor` into `subtsitution` section of your configuration as in example ballow:
+This package needs to know the sensor to use to get the power consumption. This sensor has to be defined by `main_power_sensor` into `subtsitutions` section of your configuration as in example ballow:
 
 ```yaml linenums="1"
 substitutions:

diff --git a/docs/power_meter_proxy_client.md b/docs/power_meter_proxy_client.md
@@ -11,7 +11,7 @@ packages:
     file: solar_router/power_meter_proxy.yaml
 ```
 
-This integration needs to know the IP address of the power meter proxy. This IP address has to be defined into `power_meter_ip_address` into `subtsitution` section of your configuration as in example bellow:
+This integration needs to know the IP address of the power meter proxy. This IP address has to be defined into `power_meter_ip_address` into `subtsitutions` section of your configuration as in example bellow:
 
 ```yaml linenums="1"
 substitutions:

diff --git a/docs/solar_router.md b/docs/solar_router.md
@@ -1,4 +1,4 @@
-# Solar router
+# Solar Router / Diverter
 
 **Solar Router for [ESPHome](http://esphome.io)** has been designed to work with [Home Assistant](http://home-assistant.io) and it requires the installation of [ESPHome integration](https://www.home-assistant.io/integrations/esphome/).  
 

diff --git a/docs/temperature_limiter.md b/docs/temperature_limiter.md
@@ -0,0 +1,54 @@
+# Temperature limiters
+
+A temperature limiter is designed to monitor a temperature and **stop energy diverting when a threshold is reached**. The regulation is reactivated **when restart condition is ready again** .
+
+The 2 thresholds regulation is named hysteresis. This mechansim avoid regulation bouncing.
+??? Note "More details about hysteresis and Schmitt trigger here"
+    The implementation of hysteresis in this package is similar to the electronic circuit named [Schmitt trigger](https://en.wikipedia.org/wiki/Schmitt_trigger). The circuit is named a **trigger** because the output retains its value until the input changes sufficiently to trigger a change.
+
+    ![](images/hysteresis.png)  
+    Transfer function of a Schmitt trigger. The horizontal and vertical axes are input voltage and output voltage, respectively. T and −T are the switching thresholds, and M and −M are the output voltage levels.
+
+    ![](images/schmitt_trigger.png)  
+    Comparison of the action of an ordinary comparator (A) and a Schmitt trigger (B) on a noisy analog input signal (U). The green dotted lines are the circuit's switching thresholds. The Schmitt trigger tends to remove noise from the signal.
+
+    source: [wikipedia](https://en.wikipedia.org/wiki/Schmitt_trigger)
+
+!!! warning "If temperature is not reachable, `safety_limit` is activated and energy divertion is stopped" 
+
+![HA](images/temperature_limiter_controls.png){ align=left }
+!!! note ""
+    **Controls**
+
+    * ***Restart temperature***  
+      Define the temperature when regulation can restart after a safety limit.
+    * ***Stop temperature***  
+      Define the temperature when regulation is stopped due to threshold reached.
+    * ***Use for cooling***  
+      When regulation is use on a heating system *restart temperature* has to be lower than *stop temperature*. This is the oposit for a cooling system.
+
+<pre> 
+
+
+
+
+
+
+
+
+</pre>
+
+![HA](images/temperature_limiter_sensor.png){ align=left }
+!!! note ""
+    **Sensors**
+
+    * ***Safety limit***  
+      This binary sensor shows if safety limit is activated or not.
+    * ***safety temperature***
+      This sensors show the actual temperature which is compared with thresholds. 
+<pre> 
+
+
+
+
+</pre>
diff --git a/docs/temperature_limiter_DS18B20.md b/docs/temperature_limiter_DS18B20.md
@@ -0,0 +1,30 @@
+# Temperature limiter DS 18B20
+
+This package is designed to monitor a temperature coming from a DS18B20 sensor connected on ESP32 and determines if a temperature threshold as been reached or not.
+
+!!! danger "WARNING: Conduct some tests before letting the system regulate alone"
+    This temperature limit monitoring and safety limit may have some bug. It is strongly advised to validate the behaviour of your system carefully before letting the system working by its own.
+
+The following schematic is representing the wiring of the temperature sensor:
+
+![DS18B20](images/DS18B20_wiring.png){width=400}
+
+To use this package, add the following lines to your configuration file:
+
+```yaml linenums="1"
+packages:
+  temperature_limiter:
+    url: http://github.com/XavierBerger/ESPHome-Solar-Router/
+    file: solar_router/temperature_limiter_DS18B20.yaml
+```
+
+This package needs to know the GPIO used by the temperature to get the temperature. This GPIO has to be defined by `DS18B20_pin` into `subtsitutions` section of your configuration as in example ballow:
+
+```yaml linenums="1"
+substitutions:
+  # Power meter source -----------------------------------------------------------
+  # Sensor in home assistant gathering the hot water temperature
+  DS18B20_pin: GPIO13
+```
+
+Additionnal optional parameters can be set into `substitutions` section such as `DS18B20_address` (which is optional) and `temperature_update_interval` (which is set by default to `5s`).
diff --git a/docs/temperature_limiter_home_assistant.md b/docs/temperature_limiter_home_assistant.md
@@ -0,0 +1,26 @@
+# Temperature limiter Home Assistant
+
+This package is designed to monitor a temperature coming from a sensor in Home Assistant and determines if a temperature threshold as been reached or not.
+
+!!! danger "WARNING: Conduct some tests before letting the system regulate alone"
+    This temperature limit monitoring and safety limit may have some bug. It is strongly advised to validate the behaviour of your system carefully before letting the system working by its own.
+
+To use this package, add the following lines to your configuration file:
+
+```yaml linenums="1"
+packages:
+  temperature_limiter:
+    url: http://github.com/XavierBerger/ESPHome-Solar-Router/
+    file: solar_router/temperature_limiter_home_assistant.yaml
+```
+
+This package needs to know the sensor to use to get the temperature to monitor. This sensor has to be defined by `temperature_sensor` into `subtsitutions` section of your configuration as in example ballow:
+
+```yaml linenums="1"
+substitutions:
+  # Power meter source -----------------------------------------------------------
+  # Sensor in home assistant gathering the hot water temperature
+  temperature_sensor: sensor.hot_water_temperature
+```
+!!! warning "Data availability and refresh rate"
+    This temperature limiter rely on Home Assistant to gather the temperature. It also depends on the rate of sensor update. If a sensor is updated too slowly, the regulation may not work as expected.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -6,7 +6,7 @@ edit_uri: ""
 nav:
   - Home: index.md
   - Disclamer: disclamer.md
-  - Solar Router: solar_router.md
+  - Solar Router / Diverter: solar_router.md
   - Hardware: hardware.md
   - Firmware:
       - Overview: firmware.md
@@ -29,6 +29,10 @@ nav:
       - ON/OFF regulation: engine_on_off.md
   - Energy Counter: 
       - Theorical: energy_counter_theorical.md
+  - Temperature limiter:
+      - Overview: temperature_limiter.md
+      - Home Assistant: temperature_limiter_home_assistant.md
+      - DS18B20: temperature_limiter_DS18B20.md
   - HA configuration: ha_configuration.md
   - Contributing: contributing.md
   - ChangeLog: changelog.md