home-assistant-addons/opendtu-logger/DOCS.md

# Documentation

## Installation instructions

These instructions contain 3 steps:

1. This add-on requires a PostgreSQL database, optionally with TimescaleDB support. In this example, we'll Expaso's TimescaleDB add-on in order to store data.
2. Then, we install OpenDTU Logger to connect to OpenDTU and record inverter data into the database.
3. Finally, we setup Grafana to visualise the data recorded by OpenDTU Logger.

### Install Expaso's TimescaleDB add-on

1. In Home Assistant, go to Settings -> Add-ons -> Add-on store
2. Click the three dots in the top-right corner, select 'Repositories'.
3. Add <https://github.com/Expaso/hassos-addons> .

After a few seconds, the TimescaleDB add-on should appear in the add-on store. Install it.
After installing TimescaleDB, go to Configuration. Click the three dots in the top-right corner and select "Edit in YAML". Then, make the following changes:

- Add opendtu_logger to `databases` and `timescaledb_enabled` like so:

```yml
databases:
  - homeassistant
  - opendtu_logger
timescale_enabled:
  - homeassistant
  - opendtu_logger
```

Leave the other settings as-is. Save the configuration, go to the "Info" tab and start TimescaleDB.

### Setting up OpenDTU Logger

With the database initialised, we can now setup OpenDTU Logger. Add the [add-on repository](https://git.hollander.online/energy/home-assistant-addons) using the [instructions](https://git.hollander.online/energy/home-assistant-addons) provided. Then, click "Install" to install this add-on. Go to "Configuration" and set the following variables:

- `db` **(required)**
  - If you're using Expaso's TimescaleDB add-on as described above, the `db` setting will **not** require any changes.
- `opendtu_address` **(required)**
  - In the `opendtu_address` field, enter the *IP address* or *hostname* of your OpenDTU. E.g.: `192.168.1.5` or `opendtu.local`.
- `opendtu_auth` (*optional* / **required**)
  - If your OpenDTU is password-protected, setting the following variables is required.
  - `opendtu_auth`: If applicable, enable this setting.
  - `opendtu_username`: `admin`
  - `opendtu_password`: `write_your_OpenDTUs__password_here`
  - Using password protection is optional, but recommended.
- `tz` **(required)**
  - In `tz`, enter your timezone identifier.
  - Default value: `Europe/Amsterdam`
  - If you are living in a different location, you can find the timezone identifier of your location using [this list](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List).
- `timescaledb` *(optional)*
  - If you don't want to use TimescaleDB, disable `timescaledb`.
- `log_level` **(required)**
  - By default, `log_level` is set to `INFO`, which is recommended for most users.
  - Other valid options are `DEBUG`, `INFO`, `WARN` and `ERROR`.

Save the configuration and go back to the "Info" tab.

- Make sure to **enable** the "Watchdog" on the "Info" tab so OpenDTU Logger automatically restarts after e.g. connection interruptions to your OpenDTU.
- Finally, start OpenDTU Logger.

Check the "Log" page. If the setup is succesfull, it should contain a message stating: `OpenDTU Logger has been successfully initialised. Starting data recording...`.

### Setting up Grafana

From the Home Assistant Community Add-ons repository, install Grafana. Click "Start" to start the add-on and enable "Show in sidebar". Grafana will now appear in the sidebar. Open it.

- In the top-left corner, click the three bars (open menu) -> Connections.
- Using the search box, enter `PostgreSQL`. Click the resulting "PostgreSQL".
- In the top-right corner, click "Add new data source"
- Use the following settings
  - Name: `opendtu_logger`
  - Host URL: `77b2833f-timescaledb`
  - Database name: `opendtu_logger`
  - Username: `postgres`
  - Password: `homeassistant`
  - Version: `16` or the closest version to it.
  - TimescaleDB: Toggle the switch to enable TimescaleDB support.
- Click "Save and Test". A "Database Connection OK" message should appear.
- In the top-right corner, click the `+` sign, "Import dashboard".
- Go to <https://git.hollander.online/energy/opendtu-logger/src/branch/main/grafana>
  - In this folder, a number of sample dashboards is available.
  - For a complete overview of all collected data
    - For English, use `PV.json`.
    - For Dutch, use `Zonnepanelen.json`.
  - Click the dashboard you want, and then "Raw".
    - Copy and paste the text into the "Import via dashboard JSON model" box.
    - Click "Load".
  - In the `energy` field, select `opendtu_logger` as the data source.
  - Click import. You should now be able to view the data, collected by OpenDTU Logger and stored into TimescaleDB.
  - Feel free to try out the other dashboards as well.

## Configuring OpenDTU

In order for OpenDTU Logger to work properly, it is required to ensure the following OpenDTU settings are used.

- Within OpenDTU, go to `Settings` -> `Inverter settings` (<http://YOUR_OPENDTU_IP_ADDRESS/settings/inverter>).
- For each inverter in the inverter list, click on the pencil (Edit inverter) and go to `Advanced`.
- Enable `Zero daily yield at midnight` and `Clear Eventlog at midnight`.
- Click `Save`
- Repeat this procedure for every inverter.

By default, OpenDTU sends data every 5 seconds. This can be adjusted by changing the "Poll interval" setting in <<http://YOUR_OPENDTU_IP_ADDRESS/settings/dtu>.

## Security notice

Using the aforementioned steps, you should now have a working OpenDTU Logger setup. However, it is important to keep your data safe. [Expaso recommends](https://github.com/Expaso/hassos-addons/tree/master/timescaledb#usage) changing the default postgres `homeassistant` password. I recommend following their recommendation and also installing the pgAdmin4 add-on using the [instructions](https://github.com/Expaso/hassos-addons/tree/master/pgadmin4) they provide. In case you're doing this after setting up OpenDTU Logger, remember to also update the `password` value in the `db` variable of the OpenDTU Logger configuration .  Additionally, update the password in the Grafana data source connection settings using the Grafana web interface.

## Troubleshooting

- Error: `"level":"INFO","msg":"websocket: bad handshake"}`
  - Authentication is probably misconfigured. Ensure `opendtu_auth` is set to enabled and a valid `opendtu_username` and `opendtu_password` are set.
- OpenDTU Logger crashes and doesn't restart.
  - This may happen when e.g. the connection to the OpenDTU websocket or database is interrupted. Restarts are handled by Home Assistant. Make sure that 'Watchdog' is enabled on the add-on info page.

## Feedback

If you'd like to provide feedback about this project, or in case you'd like to ask questions, please refer to [this page](https://pieterhollander.nl/author/pieter-hollander/) for contact information (e-mail, Github or LinkedIn), or use the [contact form](https://pieterhollander.nl/#contact) on my website. You can also respond by placing your remarks in [this discussion on Github](https://github.com/tbnobody/OpenDTU/discussions/1842).