feat: Report energy diverted (calculated)

docs/energy_counter_theorical.md

@@ -0,0 +1,25 @@
+# Energy Counter Theorical
+
+**Energy Counter Theorical** is designed to calculate the amount energy diverted to the load. *This is an optional package.*
+
+The amount of energy diverted is calculated based on the load power (in `W`) and the level of energy diverted every seconds.
+
+!!! warning "Energy saved reported by this counter is for information only"
+    Remember that values are calculated and not measured.  
+    The values presented by this sensor are only estimations of energy diverted based on the configuration you made in Home Assistant.
+
+To use this counter, add the following lines to your configuration file.
+
+```yaml
+packages:
+  counter:
+    url: https://github.com/XavierBerger/Solar-Router-for-ESPHome/
+    file: solar_router/energy_counter_theorical.yaml
+```
+Then you have to define the **load power** in Home Assistant `Control` interface. The power entered has to reflect the power of the element plugged on solar router.
+
+![alt text](images/SolarRouterEnergyCounterTheoricalConfiguration.png)
+
+The instantaneous and cumulated energy diverted are available in `sensors` interface:
+
+![alt text](images/SolarRouterEnergyCounterTheoricalSensors.png)

docs/firmware.md

@@ -7,6 +7,7 @@ Packages are :
 * **Power meters** : design to measure the energy exchanged with the grid.
 * **Regulator** : design to channel the surplus of energy to a designated load.
 * **Engine** : design to determine how much of energy and when surplus of energy should be diverted to the load.
+* **Energy counter** : design to report the amount of energy diverted to the load.
 
 ## Packages
 

docs/ha_configuration.md

@@ -1,29 +1,32 @@
 # Home Assistant configuration
 
-**Power meters** are reading energy exchanged with the grid every secondes.  
-By default, Home Assistant *recorder* is saving this information in its database.  
+**Power meters** and **energy sensors** are updated every secondes. 
+By default, Home Assistant *recorder* is saving these informations in its database.  
 To optimize data storage in Home Assistant, it's essential to configure databases appropriately.
 
-* First **Identify the Target Sensor**  
-  Power meter provides a sensor names `real_power`.  
-  In your Home Assistant it should be prefixed with the name of your device and should then be identified with an id like `sensor.solarrouter_real_power`.  
-  Check you sensor to adapt the configuration.
+* First **Identify the Target Sensor to filter out**  
+  Power meter provides a sensor named `real_power`.  
+  Energy counter provides a sensor named `theorical_energy_diverted`.  
+  In your Home Assistant it should be prefixed with the name of your device and should then be identified with an id like `sensor.solarrouter_real_power` or `sensor.solarrouter_theorical_energy_diverted`.  
+  Check your sensors to adapt the configuration.
 
 * Then **Create a `recorder` configuration for Home Assistant**  
-  Add the following lines in your `configuration.yaml` to filter out `real_power` data:  
+  Add the following lines in your `configuration.yaml` to filter out `real_power` and `theorical_energy_diverted` data:  
 
     ```yaml
     recorder:
       exclude:
         entities:
           - sensor.solarrouter_real_power
+          - sensor.solarrouter_theorical_energy_diverted
     ```
 !!! note "About recorder"
-    Home Assistant `recorder` is constantly saves data in database. Refer to [recorder configuration](https://www.home-assistant.io/integrations/recorder/) for details.
+    Home Assistant `recorder` is constantly saves data in database. Refer to [recorder configuration](https://www.home-assistant.io/integrations/recorder/) for details.  
+    **It is strongly advised to have a look to data produced by your solar router and adapt your configuration according to your needs.**
 
 
 !!! warning "If you are using InfluxDB"
     If you are using InfluxDB, you should pay the same attention about data recording.  
-    Refer to the [integration documentation](https://www.home-assistant.io/integrations/influxdb/) to exclude `real_power` from your database.
+    Refer to the [integration documentation](https://www.home-assistant.io/integrations/influxdb/) to exclude `real_power` and `theorical_energy_diverted` from your database.
 
 

docs/installation.md

@@ -47,23 +47,27 @@ A **proxy** just need 1 **power meter** package
     You are developer and your regulator is missing from this list, refer to [contributing](contributing.md) section to see how to contribute to this project.
 
 
-#### Step 2.3: Add a Solar Router Engine
+#### Step 2.3: Add an Engine
 
 * [Variable Engine](engine.md)  
   Read power exchange with the grid, determine and apply the percentage of regulator opening.
 
 * [ON/OFF Engine](engine_on_off.md)  
   Read power exchange with the grid, and start to divert energy if a threshold is reached and stop if another threshold is reached.
 
+#### Step 2.4: Add an Energy Counter (*Optional*)
 
-### Ster 3: Configure your solar router
+* [Energy Saved Counter Theorical](energy_saved_counter_theorical.md)  
+  Calculate energy savec base on energy diverted and load power.
+
+### Step 3: Configure your solar router
 
 Each package requires a configuration which is done in `substitution` section.  
 *Refer to documentation of packages selected and add configuration to the end of your yaml file.*
 
 You can refer to examples to see how to configure your yaml for a [standalone](standalone_example.md) installation a [proxy based](proxy_example.md) installation.
 
-!!! example "More examples are avialble in [github](https://github.com/XavierBerger/Solar-Router-for-ESPHome)"
+!!! example "More examples are available in [github](https://github.com/XavierBerger/Solar-Router-for-ESPHome)"
 
 
 ### Step 4: Upload firmware

esp32-proxy-client.yaml

@@ -48,7 +48,6 @@ web_server:
 
 # 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 Proxy Power Meter
@@ -90,6 +89,9 @@ packages:
   power_meter:
     <<: !include solar_router/power_meter_proxy_client.yaml
   regulator:
-    <<: !include  solar_router/regulator_triac.yaml
+    <<: !include solar_router/regulator_triac.yaml
   solar_router:
-    <<: !include  solar_router/engine.yaml
+    <<: !include solar_router/engine.yaml
+  energy_counter: 
+    <<: !include solar_router/energy_counter_theorical.yaml
+

esp32-standalone.yaml

@@ -102,4 +102,6 @@ packages:
     <<: !include solar_router/regulator_triac.yaml
   solar_router:
     <<: !include solar_router/engine.yaml
-
+  energy_counter: 
+    <<: !include solar_router/energy_counter_theorical.yaml
+

mkdocs.yml

@@ -27,6 +27,8 @@ nav:
   - Engine: 
       - Variable regulation: engine.md
       - ON/OFF regulation: engine_on_off.md
+  - Energy Counter: 
+      - Theorical: energy_counter_theorical.md
   - HA configuration: ha_configuration.md
   - Contributing: contributing.md
   - ChangeLog: changelog.md

solar_router/energy_counter_theorical.yaml

@@ -0,0 +1,56 @@
+# ----------------------------------------------------------------------------------------------------
+# Calculate daily energy diverted
+# ----------------------------------------------------------------------------------------------------
+
+# Define the power of load plugged on the solar router
+number:
+  - platform: template
+    name: "Load power"
+    id: load_power
+    min_value: 1
+    max_value: 99999
+    step: 1
+    unit_of_measurement: "W"
+    optimistic: True
+    restore_value: true
+
+# Script updating the power consumed counter
+script:
+  - id: energy_diverted_counter
+    mode: single
+    then:
+      - lambda: |-
+          id(therorical_energy_diverted).publish_state(id(load_power).state*id(regulator_opening).state / 100);
+
+# Sensor showing the actual energy diverted consumption
+sensor:
+  - id: energy_diverted
+    platform: total_daily_energy
+    name: 'Energy diverted'
+    power_id: therorical_energy_diverted
+    unit_of_measurement: 'kWh'
+    state_class: total_increasing
+    device_class: energy
+    accuracy_decimals: 3
+    filters:
+      # Multiplication factor from W to kW is 0.001
+      - multiply: 0.001
+
+  - platform: template
+    name: Theorical energy diverted
+    id: therorical_energy_diverted
+    unit_of_measurement: 'W'
+
+# Enable time component to 
+#  - Update energy diverted counter
+#  - Reset energy at midnight
+time:
+  - platform: homeassistant
+    id: homeassistant_time_for_solar_router
+
+  - platform: sntp
+    on_time:
+      # Trigger action every second
+      - seconds: /1
+        then:
+          - script.execute: energy_diverted_counter

wt32-eth01-standalone_on_off.yaml

@@ -62,7 +62,7 @@ web_server:
 # substitutions:
 #   # Power meter source -----------------------------------------------------------
 #   # Define ip address of Power Meter (Fronius Inverter)
-#   #power_meter_ip_address: "192.168.1.21"
+#   power_meter_ip_address: "192.168.1.21"
 #
 #   # LEDs -------------------------------------------------------------------------
 #   # Green LED is reflecting regulation status