diff --git a/docs/contributing.md b/docs/contributing.md index aeb4abb..4fd10e1 100644 --- 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 index 6251a4d..2c38a4b 100644 --- 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 index c774fca..da39cd3 100644 --- a/docs/engine_on_off.md +++ b/docs/engine_on_off.md @@ -1,11 +1,11 @@ -# 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: @@ -13,7 +13,7 @@ The following schema is representing the consumption with this engine activated: **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 -``` \ No newline at end of file +``` diff --git a/docs/firmware.md b/docs/firmware.md index 1271182..c9de5fb 100644 --- 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 index e32122a..f2bd0ff 100644 --- 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 index 49051c5..806b34a 100644 --- 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 \ No newline at end of file + * Due to the small space of memory, it doesn't support OTA update \ No newline at end of file diff --git a/docs/images/Duty_Cycle_Examples.png b/docs/images/Duty_Cycle_Examples.png index 7b66b23..41f50eb 100644 Binary files a/docs/images/Duty_Cycle_Examples.png and b/docs/images/Duty_Cycle_Examples.png differ diff --git a/docs/images/RobotDynTriac24A.drawio.png b/docs/images/RobotDynTriac24A.drawio.png index 4da723d..059f8c2 100644 Binary files a/docs/images/RobotDynTriac24A.drawio.png and b/docs/images/RobotDynTriac24A.drawio.png differ diff --git a/docs/images/RobotDynTriac24A.png b/docs/images/RobotDynTriac24A.png index 24f1e8c..c44555e 100644 Binary files a/docs/images/RobotDynTriac24A.png and b/docs/images/RobotDynTriac24A.png differ diff --git a/docs/images/SSR.png b/docs/images/SSR.png index a5738cc..58d6372 100644 Binary files a/docs/images/SSR.png and b/docs/images/SSR.png differ diff --git a/docs/images/SolarRouterBanner.png b/docs/images/SolarRouterBanner.png index 1191921..d702041 100644 Binary files a/docs/images/SolarRouterBanner.png and b/docs/images/SolarRouterBanner.png differ diff --git a/docs/images/SolarRouterClosed.png b/docs/images/SolarRouterClosed.png index 03bf262..9f357cd 100644 Binary files a/docs/images/SolarRouterClosed.png and b/docs/images/SolarRouterClosed.png differ diff --git a/docs/images/SolarRouterInHomeAssistant.png b/docs/images/SolarRouterInHomeAssistant.png index ab61a9c..570033b 100644 Binary files a/docs/images/SolarRouterInHomeAssistant.png and b/docs/images/SolarRouterInHomeAssistant.png differ diff --git a/docs/images/SolarRouterInHomeAssistantDashboard.png b/docs/images/SolarRouterInHomeAssistantDashboard.png index 5f4625a..a4aa709 100644 Binary files a/docs/images/SolarRouterInHomeAssistantDashboard.png and b/docs/images/SolarRouterInHomeAssistantDashboard.png differ diff --git a/docs/images/SolarRouterONOFFInHomeAssistant.png b/docs/images/SolarRouterONOFFInHomeAssistant.png new file mode 100644 index 0000000..a90cc3f Binary files /dev/null and b/docs/images/SolarRouterONOFFInHomeAssistant.png differ diff --git a/docs/images/SolarRouterOpen.png b/docs/images/SolarRouterOpen.png index bb02467..53d2817 100644 Binary files a/docs/images/SolarRouterOpen.png and b/docs/images/SolarRouterOpen.png differ diff --git a/docs/images/SolarRouterWeb.png b/docs/images/SolarRouterWeb.png index 1a55484..0e41ec7 100644 Binary files a/docs/images/SolarRouterWeb.png and b/docs/images/SolarRouterWeb.png differ diff --git a/docs/images/engine_on_off.png b/docs/images/engine_on_off.png index 2747027..fb84cf6 100644 Binary files a/docs/images/engine_on_off.png and b/docs/images/engine_on_off.png differ diff --git a/docs/images/hardware_relais.drawio.png b/docs/images/hardware_relais.drawio.png index 6ad8a69..a6cd2b4 100644 Binary files a/docs/images/hardware_relais.drawio.png and b/docs/images/hardware_relais.drawio.png differ diff --git a/docs/images/hardware_triac.drawio.png b/docs/images/hardware_triac.drawio.png index 287f2a3..d24fcf5 100644 Binary files a/docs/images/hardware_triac.drawio.png and b/docs/images/hardware_triac.drawio.png differ diff --git a/docs/images/mecanical_relay.drawio.png b/docs/images/mecanical_relay.drawio.png index 47a5a07..1f60042 100644 Binary files a/docs/images/mecanical_relay.drawio.png and b/docs/images/mecanical_relay.drawio.png differ diff --git a/docs/images/micro_power_router.png b/docs/images/micro_power_router.png index af68dde..be03dfd 100644 Binary files a/docs/images/micro_power_router.png and b/docs/images/micro_power_router.png differ diff --git a/docs/images/multiple_routers.drawio.png b/docs/images/multiple_routers.drawio.png index b14b937..7a89b98 100644 Binary files a/docs/images/multiple_routers.drawio.png and b/docs/images/multiple_routers.drawio.png differ diff --git a/docs/images/solid_state_relay.drawio.png b/docs/images/solid_state_relay.drawio.png index faf2576..93a1e94 100644 Binary files a/docs/images/solid_state_relay.drawio.png and b/docs/images/solid_state_relay.drawio.png differ diff --git a/docs/images/standalone.drawio.png b/docs/images/standalone.drawio.png index 330c8e8..9e15cce 100644 Binary files a/docs/images/standalone.drawio.png and b/docs/images/standalone.drawio.png differ diff --git a/docs/images/with_proxy.drawio.png b/docs/images/with_proxy.drawio.png index 7bece03..ae4df56 100644 Binary files a/docs/images/with_proxy.drawio.png and b/docs/images/with_proxy.drawio.png differ diff --git a/docs/index.md b/docs/index.md index ec77c65..3fd1300 100644 --- 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 index 361a6e2..080a912 100644 --- 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 index 19c7127..a04fc04 100644 --- 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 index b267cf9..9cbc230 100644 --- 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. \ No newline at end of file diff --git a/docs/power_meter_proxy_client.md b/docs/power_meter_proxy_client.md index caaa745..d78b221 100644 --- 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. \ No newline at end of file diff --git a/docs/regulator_triac.md b/docs/regulator_triac.md index be7a02d..da90f0b 100644 --- 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 index 36bf34f..5fe38b0 100644 --- 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. -
+
+
+
+ +!!! 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 +

-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. \ No newline at end of file