doc: Update documentation to explain energy counter

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

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