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 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).

The following code represent an example (extracted from regulator_triac.yaml) of usage based on light component using brightness to control the energy diverted:

1
2
3
4
5
6
7
8
9

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

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