feat: Add temperature limiters

XavierBerger · Nov 30, 2024 · 04b3a75 · 04b3a75
2 parents 00142e2 + 3d44f82
commit 04b3a75
Show file tree

Hide file tree

Showing 22 changed files with 401 additions and 11 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/esp32-standalone.yaml b/esp32-standalone.yaml
@@ -75,6 +75,8 @@ substitutions:
   green_led_pin: GPIO19
   yellow_led_pin: GPIO18
 
+  # Temperature sensor
+  temperature_sensor: "input_number.test_temperature"
 
 # Uncomment the following lines if you want to use the source from github
 # packages:
@@ -104,4 +106,6 @@ packages:
     <<: !include solar_router/engine.yaml
   energy_counter: 
     <<: !include solar_router/energy_counter_theorical.yaml
+  temperature_limiter:
+    <<: !include solar_router/temperature_limiter_home_assistant.yaml
 
diff --git a/esp32-standalone_DS18B20.yaml b/esp32-standalone_DS18B20.yaml
@@ -0,0 +1,112 @@
+# ----------------------------------------------------------------------------------------------------
+# ESPHome configuration - This part depends on your hardware target
+# ----------------------------------------------------------------------------------------------------
+
+esphome:
+  name: solarrouter
+  friendly_name: SolarRouter
+
+esp32:
+  board: esp32dev
+  framework:
+    type: arduino
+
+# Enable logging
+logger:
+  baud_rate: 115200
+  level: INFO
+  logs:
+    component: ERROR
+    light: ERROR
+
+# Enable Home Assistant API
+api:
+  encryption:
+    key: !secret api_encryption_key
+
+
+# Enable over-the-air updates
+ota:
+  - platform: esphome
+    password: !secret solar_router_ota_password
+
+# Enable improv serial
+improv_serial:
+
+# WiFi connection
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+  # If you have a WiFi activity plannification, you may have to update the reboot timeout (Default: 15min)
+  reboot_timeout: 24h
+
+# Activate web interface
+web_server:
+  port: 80
+
+# Define watchdog time (it should be greater than timeout)
+http_request:
+  watchdog_timeout: 12s
+
+# ----------------------------------------------------------------------------------------------------
+# Customisation
+# ----------------------------------------------------------------------------------------------------
+
+# This part of the script is designed to be use for customisation. It shouldn't be necessary to
+# edit other part of the script to perform configuration.
+
+substitutions:
+  # Power meter source -----------------------------------------------------------
+  # Define ip address of Power Meter (Fronius Inverter)
+  power_meter_ip_address: "192.168.1.21"
+
+
+  # Regulator --------------------------------------------------------------------
+  regulator: "ac_dimmer"
+
+  # Regulator configuration 
+  # Define GPIO pin connected to AC Dimmer for gate and zero crossing detection.
+  regulator_gate_pin: GPIO22
+  regulator_zero_crossing_pin: GPIO23
+
+  # LEDs -------------------------------------------------------------------------
+  # Green LED is reflecting regulation status
+  # Yellow LED is reflecting power meter status
+  green_led_pin: GPIO19
+  yellow_led_pin: GPIO18
+
+  # Temperature sensor
+  DS18B20_pin: GPIO13
+  temperature_update_interval: 1s
+
+# Uncomment the following lines if you want to use the source from github
+# packages:
+#   power_meter:
+#     url: https://github.com/XavierBerger/Solar-Router-for-ESPHome/
+#     file: solar_router/power_meter_fronius.yaml
+#     refresh: 5s
+#   regulator:
+#     url: https://github.com/XavierBerger/Solar-Router-for-ESPHome/
+#     file: solar_router/regulator_triac.yaml
+#     # file: solar_router/regulator_relay.yaml
+#     refresh: 5s
+#   solar_router:
+#     url: https://github.com/XavierBerger/Solar-Router-for-ESPHome/
+#     file: solar_router/engine.yaml
+#     refresh: 5s
+
+# And Comment the following lines if you want to use the source from github
+packages:
+  common:
+    <<: !include solar_router/common.yaml
+  power_meter:
+    <<: !include solar_router/power_meter_fronius.yaml
+  regulator:
+    <<: !include solar_router/regulator_triac.yaml
+  solar_router:
+    <<: !include solar_router/engine.yaml
+  energy_counter: 
+    <<: !include solar_router/energy_counter_theorical.yaml
+  temperature_limmiter:
+    <<: !include solar_router/temperature_limiter_DS18B20.yaml
+
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

diff --git a/solar_router/engine.yaml b/solar_router/engine.yaml
@@ -104,8 +104,8 @@ script:
       # Define the opening level of regulator based on power measured and grid exchange target
       # The value of regulator is a precentage and is then limited to the range 0 100
       - lambda: |-
-          if (isnan(id(real_power).state)){
-            // If we can have information about grid exchange, do not divert any energy
+          if (isnan(id(real_power).state) or id(safety_limit)){
+            // If we can have information about grid exchange or if safety_limit is active, do not divert any energy
             id(regulator_opening).publish_state(0);
             return;
           }

diff --git a/solar_router/engine_common.yaml b/solar_router/engine_common.yaml
@@ -1,8 +1,16 @@
 # ----------------------------------------------------------------------------------------------------
-# Pooling data every seconds
+# User interaction
 # ----------------------------------------------------------------------------------------------------
 
+globals:
+  # By default, if no temperature package is used, safety_limit is disabled
+  - id: safety_limit
+    type: bool
+    initial_value: "false"
+
+
 substitutions:
+  # By default led are pin control is not inverted
   green_led_inverted: "False"
   yellow_led_inverted: "False"
 
@@ -47,7 +55,6 @@ time:
 # ----------------------------------------------------------------------------------------------------
 # LED Management
 # ----------------------------------------------------------------------------------------------------
-
 output:
   - id: yellow_led_output
     platform: gpio

diff --git a/solar_router/engine_on_off.yaml b/solar_router/engine_on_off.yaml
@@ -148,8 +148,8 @@ script:
     then:
       # Energy export is negative
       - lambda: |-
-          if (isnan(id(real_power).state)){
-            // If we can have information about grid exchange, do not divert any energy
+          if (isnan(id(real_power).state) or id(safety_limit)){
+            // If we can have information about grid exchange or if safety_limit is active, do not divert any energy
             id(energy_divertion).turn_off();
             return;
           }

diff --git a/solar_router/temperature_limiter_DS18B20.yaml b/solar_router/temperature_limiter_DS18B20.yaml
@@ -0,0 +1,21 @@
+<<: !include temperature_limiter_common.yaml
+
+substitutions:
+  DS18B20_address: "0"
+  temperature_update_interval: 5s
+
+one_wire:
+  - platform: gpio
+    pin: ${DS18B20_pin}
+    id: dallas_d7
+
+sensor:
+  - platform: dallas_temp
+    id: safety_temperature
+    address: ${DS18B20_address}
+    one_wire_id: dallas_d7
+    name: safety_temperature
+    update_interval: ${temperature_update_interval}
+    on_value:
+      - script.execute:
+          id: safety_limit_check