Contributing to development¶

Solar Router for ESPHome 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.

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 chapter bellow.

Developing a Software package¶

Setup development environement¶

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 on Github
• Clone your forked repository on your PC
• Create a development branch starting from main
• Create and activate a Python virtual environment

  python -m venv venv
  venv/bin/activate
  

• Install ESPHome CLI and other requirements:

  pip install -r requirements.txt
  

• Install and test your code on you device with esphome command line:

  esphome run my_configuration.yaml
  

• Update the code and push update on your repository
• Propose a pull request from your fork to the official repository

Developping a Power Meter¶

A Power Meter is a component designed to provide and periodically update a sensor named real_power.

1
2
3
4
5
6
7
8

sensor:
  # Sensor showing the actual power consumption
  - id: real_power
    platform: template
    name: "Real Power"
    device_class: "power"
    unit_of_measurement: "W"
    update_interval: 1s

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 chapter bellow.

Developping Regulator¶

A Regulator has to manage the percentage of energy sent to its load based on its regulator level sensor (e.g., regulator_opening for TRIAC/SSR). Each regulator's level can vary from 0 (where no energy is sent to the load) to 100 (where all possible energy is sent to the load).

The system's overall state is managed by the router_level sensor, which controls all regulators. When router_level is 0, all regulators should be off, and when it's 100, all regulators should be at maximum. For systems with a single regulator, the regulator's level typically mirrors the router_level, but they remain separate as router_level is used for LED indicators and energy counting logic.

Here's an example of a regulator implementation (extracted from regulator_triac.yaml) using the light component's brightness to control energy diversion:

1
2
3
4
5
6
7
8
9

script:
  # Apply regulation on triac using light component
  - id: regulation_control
    mode: single
    then:
      # Apply router_level to triac using light component
      - light.turn_on:
          id: dimmer_controller
          brightness: !lambda return id(regulator_opening).state/100.0;

You can develop one or multiple regulators to work together in the same system. Each regulator should: - Have its own level sensor ranging from 0-100 - Respond to changes in the system-wide router_level - Handle its specific hardware control logic

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 chapter bellow.

Update Documentation¶

Documentation is written using mkdocs and Material for MkDocs.

To install mkdocs, you need to install Python and then :

• Create a virtual environment (see Python documentation).
• Install the required module with the following command pip install -r requirements.txt.

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