Skip to content

Commit 891eff5

Browse files
XavierBergerXavier Berger
XavierBerger
authored and
Xavier Berger
committed
doc: Add documentation build with mkdocs
1 parent b3dfbbb commit 891eff5

37 files changed

+601
-13
lines changed

‎.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,4 @@
33
# You can modify this file to suit your needs.
44
/.esphome/
55
/secrets.yaml
6+
/site/

‎README.md

+11-13
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,17 @@
1-
# ESPHome Solar Router
1+
[![doc](docs/images/SolarRouterforESPHomeDocumentation.svg)](https://xavierberger.github.io/Solar-Router-for-ESPHome/)
2+
[![doc](docs/images/SolarRouterforESPHomeChangeLog.svg)](https://xavierberger.github.io/Solar-Router-for-ESPHome/changelog/)
3+
[![issues](docs/images/SolarRouterforESPHomeReportbugorrequestenhancement.svg)](https://github.com/XavierBerger/Solar-Router-for-ESPHome/issues)
24

3-
The **ESPHome Solar Router** 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.
5+
# Solar Router for ESPHome
46

5-
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](https://www.home-assistant.io/) via [ESPHome firmware](https://esphome.io).
7+
The **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.
68

7-
This integration enables users to effortlessly monitor and control the router's functionality within the HomeAssistant ecosystem, facilitating streamlined energy management and automation.
8-
9-
### Important Notice
10-
11-
Before implementing the "Solar Router for ESPHome" project, it is imperative that users exercise extreme caution, particularly concerning the utilization of 230V power supply. The author of this project cannot be held liable for any potential accidents or mishaps that may occur during the setup or operation of the project.
9+
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](https://www.home-assistant.io/) via [ESPHome](https://esphome.io) firmware.
1210

13-
Electricity, especially at high voltages, poses significant risks, including but not limited to electrical shocks, fires, and damage to equipment. It is essential that users have a thorough understanding of electrical safety protocols and adhere to all relevant guidelines and regulations.
14-
15-
By proceeding with the implementation of the "Solar Router for ESPHome" project, users acknowledge and accept the inherent risks associated with working with electricity and agree to exercise utmost care and caution throughout the process.
11+
This integration enables users to effortlessly monitor and control the router's functionality within the HomeAssistant ecosystem, facilitating streamlined energy management and automation.
1612

17-
The author strongly advises users to consult with qualified professionals or electricians if they are uncertain about any aspect of the project or lack the necessary expertise in handling electrical systems.
13+
### ⚡ Important Notice ⚡
14+
**This project involves working with 230 volts , which can be hazardous.**
15+
**Please read the [disclaimer](https://xavierberger.github.io/Solar-Router-for-ESPHome/disclamer/) before proceeding with the "Solar Router for ESPHome" project.**
1816

19-
**Remember, safety should always be the top priority when working with electricity**.
17+
<img src="docs/images/SolarRouterClosed.png" alt="drawing" style="width:400px;"/>

‎cliff.toml

+89
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# git-cliff ~ default configuration file
2+
# https://git-cliff.org/docs/configuration
3+
#
4+
# Lines starting with "#" are comments.
5+
# Configuration options are organized into tables and keys.
6+
# See documentation for more information on available options.
7+
8+
[changelog]
9+
# changelog header
10+
header = """
11+
# Changelog\n
12+
All notable changes to this project will be documented in this file.\n
13+
"""
14+
# template for the changelog body
15+
# https://keats.github.io/tera/docs/#introduction
16+
body = """
17+
{% if version %}\
18+
## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
19+
{% else %}\
20+
## [unreleased]
21+
{% endif %}\
22+
{% for group, commits in commits | filter(attribute="merge_commit", value=true) | group_by(attribute="group") %}
23+
### {{ group | striptags | trim | upper_first }}
24+
{% for commit in commits %}
25+
- {% if commit.scope %}*({{ commit.scope }})* {% endif %}\
26+
{% if commit.breaking %}[**breaking**] {% endif %}\
27+
{{ commit.message | upper_first }}\
28+
{% endfor %}
29+
{% endfor %}\n
30+
"""
31+
# template for the changelog footer
32+
footer = """
33+
<!-- generated by git-cliff -->
34+
"""
35+
# remove the leading and trailing s
36+
trim = true
37+
# postprocessors
38+
postprocessors = [
39+
# { pattern = '<REPO>', replace = "https://github.com/orhun/git-cliff" }, # replace repository URL
40+
]
41+
42+
[git]
43+
# parse the commits based on https://www.conventionalcommits.org
44+
conventional_commits = true
45+
# filter out the commits that are not conventional
46+
filter_unconventional = true
47+
# process each line of a commit as an individual commit
48+
split_commits = false
49+
# regex for preprocessing the commit messages
50+
commit_preprocessors = [
51+
# Replace issue numbers
52+
#{ pattern = '\((\w+\s)?#([0-9]+)\)', replace = "([#${2}](<REPO>/issues/${2}))"},
53+
# Check spelling of the commit with https://github.com/crate-ci/typos
54+
# If the spelling is incorrect, it will be automatically fixed.
55+
#{ pattern = '.*', replace_command = 'typos --write-changes -' },
56+
]
57+
# regex for parsing and grouping commits
58+
commit_parsers = [
59+
{ message = "^feat", group = "<!-- 0 -->🚀 Features" },
60+
{ message = "^fix", group = "<!-- 1 -->🐛 Bug Fixes" },
61+
{ message = "^doc", group = "<!-- 3 -->📚 Documentation" },
62+
{ message = "^perf", group = "<!-- 4 -->⚡ Performance" },
63+
{ message = "^refactor", group = "<!-- 2 -->🚜 Refactor" },
64+
{ message = "^style", group = "<!-- 5 -->🎨 Styling" },
65+
{ message = "^test", group = "<!-- 6 -->🧪 Testing" },
66+
{ message = "^chore\\(release\\): prepare for", skip = true },
67+
{ message = "^chore\\(deps.*\\)", skip = true },
68+
{ message = "^chore\\(pr\\)", skip = true },
69+
{ message = "^chore\\(pull\\)", skip = true },
70+
{ message = "^chore|^ci", group = "<!-- 7 -->⚙️ Miscellaneous Tasks" },
71+
{ body = ".*security", group = "<!-- 8 -->🛡️ Security" },
72+
{ message = "^revert", group = "<!-- 9 -->◀️ Revert" },
73+
]
74+
# protect breaking changes from being skipped due to matching a skipping commit_parser
75+
protect_breaking_commits = false
76+
# filter out the commits that are not matched by commit parsers
77+
filter_commits = false
78+
# regex for matching git tags
79+
# tag_pattern = "v[0-9].*"
80+
# regex for skipping tags
81+
# skip_tags = ""
82+
# regex for ignoring tags
83+
ignore_tags = ".*rc.*"
84+
# sort the tags topologically
85+
topo_order = false
86+
# sort the commits inside sections by oldest/newest order
87+
sort_commits = "oldest"
88+
# limit the number of commits included in the changelog.
89+
# limit_commits = 42

‎docs/changelog.md

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Changelog
2+
3+
!!! note
4+
ChangeLog is only populated in [documentation](https://xavierberger.github.io/Solar-Router-for-ESPHome/changelog/) when a new release is published.

‎docs/developers.md

+57
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
**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. To do so, create a fork of the main repository, in your fork, create a branch and add your modifications. Once done, you can propose a merge request of your branch into the main project.
2+
3+
### Developing a hardware
4+
5+
You can propose any ardware 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.
6+
7+
A documentation have be added describing this new hardware and its constraints (Ex: GPIO capabilities). See [update documentation](developers.md#update-documentation) chapter bellow.
8+
9+
## Developping a power meter
10+
11+
A power meter is a component designed to provide and periodically update a sensor named `real_power`.
12+
13+
```yaml
14+
sensor:
15+
# Sensor showing the actual power consumption
16+
- id: real_power
17+
platform: template
18+
name: "Real Power"
19+
device_class: "power"
20+
unit_of_measurement: "W"
21+
update_interval: 1s
22+
```
23+
24+
This sensor is used by the **Solar Router Engine** to get the value of power exchanged with the grid.
25+
26+
If this new power meter needs specific configuration, required parameters have to be added into `substitution` section.
27+
28+
A documentation have to be added describing the power meter and how to configure it. See [update documentation](developers.md#update-documentation) chapter bellow.
29+
30+
## Developping a regulator
31+
32+
A regulator has to manage the energy sent to the load based on the `triac_opening` sensor state. `triac_sensor` 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).
33+
34+
The following code represent and example of usage based on `light` component using `brightness` to control the energy diverted:
35+
36+
```yaml
37+
script:
38+
# Apply regulation on triac using light component
39+
- id: regulation_control
40+
mode: single
41+
then:
42+
# Apply opening level on triac using light component
43+
- light.turn_on:
44+
id: dimmer_controller
45+
brightness: !lambda return id(triac_opening).state/100.0;
46+
```
47+
If this new power meter needs specific configuration, required parameters have to be added into `substitution` section.
48+
49+
A documentation have to be added describing the power meter and how to configure it. See [update documentation](developers.md#update-documentation) chapter bellow.
50+
51+
## Update documentation
52+
53+
Documentation is written using [mkdocs](https://www.mkdocs.org/) and [Maretial for MkDocs](https://squidfunk.github.io/mkdocs-material/).
54+
55+
To install mkdocs, you need to install [Python](https://python.org) and then install the required module with the following command `pip install -r requirements.txt`.
56+
57+
Documentation is stored in `docs` directory. To see you modification in real time in your browser, execute the command `mkdocs serve` and browse [http://127.0.0.1:8000](http://127.0.0.1:8000)

‎docs/disclamer.md

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Disclamer
2+
3+
!!! danger "Disclaimer"
4+
5+
Before implementing the "Solar Router for ESPHome" project, it is imperative that users exercise extreme caution, particularly concerning the utilization of 230V power supply. The author of this project cannot be held liable for any potential accidents or mishaps that may occur during the setup or operation of the project.
6+
7+
Electricity, especially at high voltages, poses significant risks, including but not limited to electrical shocks, fires, and damage to equipment. It is essential that users have a thorough understanding of electrical safety protocols and adhere to all relevant guidelines and regulations.
8+
9+
By proceeding with the implementation of the "Solar Router for ESPHome" project, users acknowledge and accept the inherent risks associated with working with electricity and agree to exercise utmost care and caution throughout the process.
10+
11+
The author strongly advises users to consult with qualified professionals or electricians if they are uncertain about any aspect of the project or lack the necessary expertise in handling electrical systems.
12+
13+
**Remember, safety should always be the top priority when working with electricity**.

‎docs/engine.md

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
2+
# Solar Router Engine
3+
4+
This package is implementing the engine of the solar router which is determine when and how many energy has to be diverted to the load.
5+
6+
**Solar router engine** calls every second the power meter to get the actual power consumed.
7+
8+
If power is bellow the target it will then channel the excess of produced energy to the load with the regulator.
9+
10+
To do this divertion, it calculates the percentage of the regulator "opening" and adjust it dynamically to reach the target.
11+
12+
Solar router engine's automatic regulation can be activated or deactivated with the activation switch.
13+
14+
## User feedbak LEDS
15+
16+
The yellow LED is reflecting the network connection:
17+
18+
- ***OFF***: solar router is not connected to power supply.
19+
- ***ON***: solar router is connected to the network.
20+
- ***blink***: solar router is not connected to the network and is trying to reconnect.
21+
22+
23+
The green LED is reflecting the actual configuration of regulation:
24+
25+
- ***OFF***: automatic regulation is deactivated.
26+
- ***ON***: automatic regulation is active and is not diverting energy to the load.
27+
- ***blink***: solar router is currently sending energy to the load.
28+
29+
## Configuration
30+
31+
To use this package, add the following lines to your configuration file:
32+
33+
```yaml
34+
packages:
35+
power_meter:
36+
url: http://github.com/XavierBerger/ESPHome-Solar-Router/
37+
file: solar_router/solar_router_engine.yaml
38+
```
39+
40+
When this package is used it is required to define the following paramater is `substitution` section as show in the example bellow:
41+
42+
```yaml
43+
substitutions:
44+
# LEDs -------------------------------------------------------------------------
45+
# Green LED is reflecting regulation status
46+
# Yellow LED is reflecting power meter status
47+
green_led_pin: GPIO19
48+
yellow_led_pin: GPIO18
49+
```

‎docs/firmware.md

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Firmware
2+
3+
Firmware has been split in several packages which can be assemble to the needs of user.
4+
5+
Packages are :
6+
7+
* **Power meters** : design to measure the energy exchanged with the grid.
8+
* **Regulator** : design to channel the surplus of energy to a designated load.
9+
* **Solar Router Engine** : design to determine how much of energy and when surplus of energy should be diverted to the load.
10+
11+
## Packages
12+
13+
Packages can be combined to create a variaty of solar router as in following examples.
14+
15+
### Standalone configuration
16+
17+
In this standalone configuration, only one ESP32 is doing the job and is running all the 3 packages.
18+
19+
![hardware connection](images/standalone.drawio.png){width=374}
20+
21+
### Power Meter Proxy configuration
22+
23+
In this proxy configuration, two ESP is doing the job. The first one (which coud be located into the electrical panel) gather the power meter information. The second one (which could be located close to the water heater) is getting the power meter information from the first ESP through the network and perfom the regulation.
24+
25+
![hardware connection](images/with_proxy.drawio.png){width=535}
26+
27+
!!! Note
28+
A Power Meter Proxy doesn't require a lot of CPU power and could then be executed on an ESP8285 or ESP8286.
29+
30+
### Multiple Solar Router configuration
31+
32+
In this multiple Solar Router configuration, two solar router are installed. The first one is reading the power exchanged with the grid and is diverting surplus to a wather heater. The second one is reading power exchange information from the first one using a proxy power meter. Base on the information collected, it will divert the surplus of energy to an anti frost system.
33+
34+
![hardware connection](images/multiple_routers.drawio.png){width=756}
35+
36+
!!! Note
37+
`reactivity` and `target grid exchange` will have to be adjusted carefully on both solar routers to avoid regulation conflicts.

‎docs/fronius.md

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Fronius Power Meter
2+
3+
This power meter is designed to work with [Fronius Smart Meter](https://www.fronius.com/en-gb/uk/solar-energy/installers-partners/technical-data/all-products/system-monitoring/hardware/fronius-smart-meter/fronius-smart-meter-ts-100a-1) in conjunction with a [Fronius Inverter](https://www.fronius.com/en-gb/uk/solar-energy/installers-partners/technical-data/all-products/inverters/fronius-primo-gen24/fronius-primo-gen24-3-0).
4+
5+
Fronius is providing an *Open Inteface* named [Fronius Solar API](https://www.fronius.com/en-gb/uk/solar-energy/installers-partners/technical-data/all-products/system-monitoring/open-interfaces/fronius-solar-api-json-) which is allowing the quiery the inverter and **locally** get data.
6+
7+
To use this package, add the following lines to your configuration file:
8+
9+
```yaml
10+
packages:
11+
power_meter:
12+
url: http://github.com/XavierBerger/ESPHome-Solar-Router/
13+
file: solar_router/power_meter_fronius.yaml
14+
```
15+
16+
This package needs to know the IP address of the inverter. This IP address has to be defined by `power_meter_ip_address` into `subtsitution` section of your configuration as in example ballow:
17+
18+
```yaml
19+
substitutions:
20+
# Power meter source -----------------------------------------------------------
21+
# Define ip address of Fronius inverter
22+
power_meter_ip_address: "192.168.1.21"
23+
```
24+
25+
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:
26+
27+
```yaml
28+
globals:
29+
- id: power_meter_activated
30+
type: int
31+
initial_value: "1"
32+
```
33+
34+
See [proxy example](proxy_example.md) to see how to implement it.
35+
36+
37+
!!! important "ESP8266 and ESP8285"
38+
ESP8266 and ESP8285 has few memory but can be used a proxy if ssl support is disabled in `http_request`.
39+
40+
```yaml
41+
http_request:
42+
esp8266_disable_ssl_support: True
43+
```
44+
See [HTTP Request component](https://esphome.io/components/http_request.html#esp8266-disable-ssl-support) for details

‎docs/hardware.md

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Hardware
2+
3+
The hardware used for development is the one proposed by [F1ATB.fr](https://f1atb.fr/fr/routeur-photovoltaique-realisation-materielle/) ![fr](images/france.png).
4+
5+
Here is the schematic of a solar router with a minimal number of component.
6+
7+
8+
![hardware connection](images/hardware.drawio.png)
9+
10+
Bill of material:
11+
12+
* 1 x ESP32-dev board (Wroom-32U with external antenna)
13+
* 1 x Green LED
14+
* 1 x Yellow LED
15+
* 1 x Triac from RobotDyn 24A
16+
* 2 x resistor 470 Ohms for LEDs
17+
18+
On the photo bellow, as the heat dissipator provided by RobotDyn is under dimensionned, the triac has been unsoldered from the board and screwed into a big heat dissipator. Wires have been added to link the triac into the board.
19+
20+
In addition a 12V power supply is used in addition with a buck converter to power the system. The 12V may be used to power a fan in an event of an over heating.
21+
22+
![SolarRouteOpen](images/SolarRouterOpen.png)
23+
![SolarRouteClose](images/SolarRouterClosed.png)
24+
25+
The router has been built to be connected to a frost protection system and then provide standard electricals sockets.

‎docs/images/RobotDynTriac24A.drawio.png

312 KB
Loading

‎docs/images/RobotDynTriac24A.png

258 KB
Loading

‎docs/images/SSR.png

76.3 KB
Loading

‎docs/images/SolarRouterClosed.png

640 KB
Loading

‎docs/images/SolarRouterInHomeAssistant.png

25.2 KB
Loading

‎docs/images/SolarRouterOpen.png

680 KB
Loading

‎docs/images/SolarRouterWeb.png

47 KB
Loading

‎docs/images/SolarRouterforESPHomeChangeLog.svg

+1
Loading

0 commit comments

Comments
 (0)