doc: Update documentation

XavierBerger · Nov 11, 2024 · 3dc780f · 3dc780f
1 parent 5550e55
commit 3dc780f
Show file tree

Hide file tree

Showing 33 changed files with 82 additions and 45 deletions.
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -3,11 +3,19 @@
 **Solar Router for [ESPHome](http://esphome.io)** is design to be modular to make easy the customisation to various power meters and various regulators.  
 You want to contribute? You are welcome and you will find bellow some recommendation to do so.
 
-## Setup development environement
+## Developing a **Hardware**
+
+You can propose any hardware based on your needs. If this new hardware require to use GPIO, the pins used by your hardware have to be configuration into `subsitution` section.
+
+A documentation have be added describing this new hardware and its constraints (Ex: GPIO capabilities). See [update documentation](#update-documentation) chapter bellow.
+
+## Developing a **Software package**
 
-To contribute to **Solar-Router-for-ESPHome** and develop a new feature on your computer and propose a *merge request*, you should:
+### Setup development environement
 
-- Fork [**Solar-Router-for-ESPHome** repository](https://github.com/XavierBerger/Solar-Router-for-ESPHome) on Github
+To contribute to **Solar Router for ESPHome** and develop a new feature on your computer and propose a *merge request*, you should:
+
+- Fork [**Solar Router for ESPHome** repository](https://github.com/XavierBerger/Solar-Router-for-ESPHome) on Github
 - Clone your forked repository on your PC
 - Create a development branch starting from **main**
 - [Create and activate a Python virtual environment](https://docs.python.org/3/library/venv.html) 
@@ -19,24 +27,14 @@ To contribute to **Solar-Router-for-ESPHome** and develop a new feature on your
     ```shell
     pip install -r requirements.txt
     ``` 
-- Install and test your code on you device : 
+- Install and test your code on you device with `esphome` command line: 
     ```shell
-    esphome run my_configuration/yaml
+    esphome run my_configuration.yaml
     ```
 - Update the code and push update on your repository
-- Install and test you code with `esphome` command line
-    ```shell
-    esphome run my_solar_router.yaml
-    ```
 - Propose a pull request from your fork to the official repository
 
-## Developing a **Hardware**
-
-You can propose any hardware based on your needs. If this new hardware require to use GPIO, the pins used by your hardware have to be configuration into `subsitution` section.
-
-A documentation have be added describing this new hardware and its constraints (Ex: GPIO capabilities). See [update documentation](#update-documentation) chapter bellow.
-
-## Developping a **Power Meter**
+### Developping a **Power Meter**
 
 A **Power Meter** is a component designed to provide and periodically update a sensor named `real_power`.
 
@@ -53,13 +51,13 @@ sensor:
 
 !!! tip "Tip: See already developped power meter for examples"
 
-This sensor is used by the **Solar Router Engine** to get the value of power exchanged with the grid.
+This sensor is used by **Engines** to get the value of power exchanged with the grid.
 
 If this new power meter needs specific configuration, required parameters have to be added into `substitution` section.
 
 A documentation have to be added describing the power meter and how to configure it. See [update documentation](#update-documentation) chapter bellow.
 
-## Developping a **Regulator**
+### Developping a **Regulator**
 
 A **Regulator** has to manage the percentage of energy sent to the load based on the `regulator_opening` sensor state. `regulator_opening` state can vary from 0 (where no energy is sent to the load) to 100 (where all the energy possible is sent to the load).
 

diff --git a/docs/engine.md b/docs/engine.md
@@ -1,11 +1,11 @@
 
-# Solar Router Engine
+# Variable engine
 
 This package is implementing the engine of the solar router which determines when and how many energy has to be diverted to the load.
 
-**Solar router engine** calls every second the power meter to get the actual power consumed. If energy produce is greater than energy consummed and exceed the define echange target, the engine will determine the **percentage of the regulator "opening"** and adjusts it dynamically to reach the target.
+**Variable engine** calls every second the power meter to get the actual energy exchanged with the grid. If energy produce is greater than energy consummed and exceed the define echange target, the engine will determine the **percentage of the regulator "opening"** and adjusts it dynamically to reach the target.
 
-Solar router engine's automatic regulation can be activated or deactivated with the activation switch.
+Engine's automatic regulation can be activated or deactivated with the activation switch.
 
 ## User feedback LEDS
 

diff --git a/docs/engine_on_off.md b/docs/engine_on_off.md
@@ -1,19 +1,19 @@
 
-# Solar Router Engine
+# ON/OFF Engine
 
-This package is implementing the engine of the solar router which determines enerdy can be diverted to a local load or not.
+This package is implementing the engine of the solar router which determines energy can be diverted to a local load or not.
 
-**Solar router engine** calls every second the power meter to get the actual power consumed. If energy sent to the grid is greater than the diverstion start level (in W), the relay is closed to use the energy locally. When the energy sent to the grid reach the level (in W) defined to stop the divertion, the relay is openned and local consomption is stopped.
+**ON/OFF engine** calls every second the power meter to get the actual power consumed. If energy sent to the grid is greater than the divertion start level (in W) during start tempo (in s), the relay is closed to use the energy locally. When the energy sent to the grid reach the level (in W) defined to stop the divertion during stop tempo (in s), the relay is openned and local consomption is stopped.
 
-Solar router engine's automatic regulation can be activated or deactivated with the activation switch.
+ON/OFF engine's automatic regulation can be activated or deactivated with the activation switch.
 
 The following schema is representing the consumption with this engine activated:
 
 ![engine_on_off](images/engine_on_off.png)
 
 **Legend:**
 
- * Green: Energy consummed coming from solar pannel
+ * Green: Energy consummed coming from solar pannel (self consumption)
  * Yellow: Energy sent to the grid
  * Red: Energy consummed coming from the grid
 
@@ -23,7 +23,7 @@ The following schema is representing the consumption with this engine activated:
 * **②** The yellow part of the graph is showing the stop level. In this example 0W.
 
 !!! Danger "Carefully set the start and stop levels"
-    The start level has to be greater than the power of the load plugged to the solar router. If not, as soon as the energy will be diverted to the load, the stop level will be reached and you will see the router switching between ON and OFF every seconds.
+    The start level has to be greater than the power of the load plugged to the solar router. If not, as soon as the energy will be diverted to the load, the stop level will be reached and you will see the router switching between ON and OFF (based on temporisation you defined).
 
 ## User feedback LEDS
 
@@ -61,4 +61,4 @@ substitutions:
   # Yellow LED is reflecting power meter status
   green_led_pin: GPIO19
   yellow_led_pin: GPIO18
-```
+```
diff --git a/docs/firmware.md b/docs/firmware.md
@@ -6,7 +6,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.
-* **Solar Router Engine** : design to determine how much of energy and when surplus of energy should be diverted to the load.
+* **Engine** : design to determine how much of energy and when surplus of energy should be diverted to the load.
 
 ## Packages
 

diff --git a/docs/ha_configuration.md b/docs/ha_configuration.md
@@ -1,6 +1,6 @@
 # Home Assistant configuration
 
-**Power meter** is reading energy exchanged with the grid every secondes.  
+**Power meters** are reading energy exchanged with the grid every secondes.  
 By default, Home Assistant *recorder* is saving this information in its database.  
 To optimize data storage in Home Assistant, it's essential to configure databases appropriately.
 
@@ -22,7 +22,7 @@ To optimize data storage in Home Assistant, it's essential to configure database
     Home Assistant `recorder` is constantly saves data in database. Refer to [recorder configuration](https://www.home-assistant.io/integrations/recorder/) for details.
 
 
-!!! warning "If you are uding InfluxDB"
+!!! 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.
 

diff --git a/docs/hardware.md b/docs/hardware.md
@@ -46,4 +46,4 @@ Bill of material:
 
 !!! Note "This router has some limitation"
     * It has to be used with ON/OFF engine and is not compatible with variable engine
-    * Due to the small space of memory, it doesn't support OTA
+    * Due to the small space of memory, it doesn't support OTA update
diff --git a/docs/images/Duty_Cycle_Examples.png b/docs/images/Duty_Cycle_Examples.png
diff --git a/docs/images/RobotDynTriac24A.drawio.png b/docs/images/RobotDynTriac24A.drawio.png
diff --git a/docs/images/RobotDynTriac24A.png b/docs/images/RobotDynTriac24A.png
diff --git a/docs/images/SSR.png b/docs/images/SSR.png
diff --git a/docs/images/SolarRouterBanner.png b/docs/images/SolarRouterBanner.png
diff --git a/docs/images/SolarRouterClosed.png b/docs/images/SolarRouterClosed.png
diff --git a/docs/images/SolarRouterInHomeAssistant.png b/docs/images/SolarRouterInHomeAssistant.png
diff --git a/docs/images/SolarRouterInHomeAssistantDashboard.png b/docs/images/SolarRouterInHomeAssistantDashboard.png
diff --git a/docs/images/SolarRouterONOFFInHomeAssistant.png b/docs/images/SolarRouterONOFFInHomeAssistant.png
diff --git a/docs/images/SolarRouterOpen.png b/docs/images/SolarRouterOpen.png
diff --git a/docs/images/SolarRouterWeb.png b/docs/images/SolarRouterWeb.png
diff --git a/docs/images/engine_on_off.png b/docs/images/engine_on_off.png
diff --git a/docs/images/hardware_relais.drawio.png b/docs/images/hardware_relais.drawio.png
diff --git a/docs/images/hardware_triac.drawio.png b/docs/images/hardware_triac.drawio.png
diff --git a/docs/images/mecanical_relay.drawio.png b/docs/images/mecanical_relay.drawio.png
diff --git a/docs/images/micro_power_router.png b/docs/images/micro_power_router.png
diff --git a/docs/images/multiple_routers.drawio.png b/docs/images/multiple_routers.drawio.png
diff --git a/docs/images/solid_state_relay.drawio.png b/docs/images/solid_state_relay.drawio.png
diff --git a/docs/images/standalone.drawio.png b/docs/images/standalone.drawio.png
diff --git a/docs/images/with_proxy.drawio.png b/docs/images/with_proxy.drawio.png
diff --git a/docs/index.md b/docs/index.md
@@ -2,9 +2,9 @@
 
 **Solar Router for ESPHome** is a DIY project aiming to provide specialized hardware device and software tailored for optimizing solar energy utilization. It performs real-time monitoring and intelligent surplus energy management to effectively channels excess solar energy to designated loads like water heaters or frost protection systems. 
 
-Key features include dynamic energy routing algorithms, a choice of power meter source (local or remote ...), multiple regulators (with triac or relay ... ), and a seamless integration with [HomeAssistant](http://home-assistant.io) via [ESPHome](http://esphome.io) firmware. 
+Key features include a choice of dynamic energy routing algorithms (variable, ON/OFF), power meter sources (local or remote ...), regulators (with triac or relay ... ), and a seamless integration with [HomeAssistant](http://home-assistant.io) via [ESPHome](http://esphome.io) firmware. 
 
-This integration enables users to effortlessly monitor and control the router's functionality within the HomeAssistant ecosystem, facilitating streamlined energy management and automation.
+This component enables users to effortlessly monitor and control the router's functionality within the HomeAssistant ecosystem, facilitating streamlined energy management and automation.
 
 !!! danger "Important Notice"
     This project involves working with high voltage (110 or 230 volts), which can be hazardous.  

diff --git a/docs/installation.md b/docs/installation.md
@@ -1,6 +1,6 @@
 # Installation and Configuration
 
-To install your solar router, you need to define the archtecture of your solution between [standalone](firmware.md#standalone-configuration) installation, installation working with [proxy](firmware.md#power-meter-proxy-configuration) or [multiple solar router](firmware.md#multiple-solar-router-configuration) installation.
+To install your solar router, you need to define the archtecture of your solution between [standalone](firmware.md#standalone-configuration) installation; installation working with [proxy](firmware.md#power-meter-proxy-configuration) or [multiple solar router](firmware.md#multiple-solar-router-configuration) installation.
 
 ### Step 1: Install and configure ESPHome firmware
 
@@ -11,11 +11,11 @@ Adopt it into [Home Assistant](https://home-assistant.io).
 
 !!! important "Wifi reconnection"
     Remove `ap:` and `captive_portal:`.  
-    *This will prevent the solar router from connecting to WiFi in case of loss of connection* 
+    *This could prevent the solar router from connecting to WiFi in case of loss of connection* 
 
 ### Step 2: Select packages
 
-A **solar router** needs 3 packages: a **power meter**, a **regulator** and the **solar router engine**.
+A **solar router** needs 3 packages: a **power meter**, a **regulator** and the **engine**.
 
 A **proxy** just need 1 **power meter** package
 
@@ -61,7 +61,9 @@ A **proxy** just need 1 **power meter** package
 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
+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)"
 
 
 ### Step 4: Upload firmware

diff --git a/docs/power_meter_fronius.md b/docs/power_meter_fronius.md
@@ -22,7 +22,7 @@ substitutions:
   power_meter_ip_address: "192.168.1.21"
 ```
 
-This package is activated/deactivated with a global variable `power_meter_activated`. This `globals` is provided by the [solar router engine](engine.md) package. If this power meter is use inside a proxy, it is required to add this `globals` into you configuration yaml as follow:
+This package is activated/deactivated with a global variable `power_meter_activated`. This `globals` is provided by an ***engine*** package. If this power meter is use inside a proxy, it is required to add this `globals` into you configuration yaml as follow:
 
 ```yaml linenums="1"
 globals:

diff --git a/docs/power_meter_home_assistant.md b/docs/power_meter_home_assistant.md
@@ -19,7 +19,7 @@ substitutions:
   # Sensor in home assistant gathering the power consumption
   main_power_sensor: sensor.main_power
 ```
-!!! warning Data availability and refresh rate
+!!! warning "Data availability and refresh rate"
     This power meter rely on Home Assistant to gather the value of energy exchanged with the grid. It also depends on the rate of sensor update. If a sensor is updated too slowly, the regulation may not work as expected.
 
     Contrary to Home Assistant power meter, native power meters are autonomous and can continue to regulate even is Home Assistant is offline. Some power meter can have a direct access to the measure and may even be independent to the network.
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 ballow:
+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:
 
 ```yaml linenums="1"
 substitutions:
@@ -20,7 +20,7 @@ substitutions:
   power_meter_ip_address: "192.168.1.21"
 ```
 
-This integration is activated/deactivated with a global variable `power_meter_activated`. This `globals` is provided by the [solar router engine](engine.md) package.
+This integration is activated/deactivated with a global variable `power_meter_activated`. This `globals` is provided by an ***engine*** package.
 
 !!! warning "Network dependency"
     This power meter require the network to gather information about energy exchanged with the grid.
diff --git a/docs/regulator_triac.md b/docs/regulator_triac.md
@@ -31,7 +31,7 @@ packages:
     file: solar_router/regulator_triac.yaml
 ```
 
-This package require the definition of pin connected to the triac module for zero crossing detection (regulator_zero_crossing_pin) and gate/PWM control (regulator_gate_pin)
+This package require the definition of pin connected to the triac module for zero crossing detection (`regulator_zero_crossing_pin`) and gate/PWM control (`regulator_gate_pin`)
 
 ```yaml linenums="1"
 substitutions:

diff --git a/docs/solar_router.md b/docs/solar_router.md
@@ -2,6 +2,8 @@
 
 **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/).  
 
+## Variable regulation
+
 ![HA](images/SolarRouterInHomeAssistant.png){ align=left }
 !!! note ""
     **Controls**
@@ -22,11 +24,46 @@
     * ***Real Power***  
       Energy actually exchanged with the grid. Updated every secondes. 
 
-<br>
+<br>  
+<br>  
+<br>  
+
+!!! note 
+    When solar routing is deactivated, regulator opening slider can be modified "by hand".  
+    If you modify the triac opening state while the solar routing is enabled, the routing algorithm will immediately modify the value to meet target grid exchange level.
+
+## ON/OFF regulation
+
+![HA](images/SolarRouterONOFFInHomeAssistant.png){ align=left }
+!!! note ""
+    **Controls**
+
+    * ***Activate Solar Routing***  
+      Control if Solar routing should be activated or not
+    * ***Energy divertion***  
+      Ectivate energy divertion or not 
+    * ***Start power level***  
+      Define the level of energy when divertion has to start  
+    * ***Start tempo***  
+      How long the start level has to be exceed before diverting energy  
+    * ***Stop power level***  
+      Define the level of energy when divertion has to stop  
+    * ***Start tempo***  
+      How long the stop level has to be reached before diverting energy
+!!! note ""
+    **Sensors**
+
+    * ***Real Power***  
+      Energy actually exchanged with the grid. Updated every secondes.
+    * ***Start Tempo***
+      Counter defining when enegy divertion has to start 
+    * ***Stop Tempo***
+      Counter defining when enegy divertion has to stop 
+
 <br>
 <br>
 
-When solar routing is deactivated, triac opening slider can be modified "by hand". 
 
 !!! note 
+    When solar routing is deactivated, regulator opening slider can be modified "by hand".  
     If you modify the triac opening state while the solar routing is enabled, the routing algorithm will immediately modify the value to meet target grid exchange level.