Initial DOCS.md version, WiP.

p1-logger/DOCS.md

@@ -0,0 +1,100 @@
+# Documentation
+
+NB: This documentation page is a work-in-progress and unfinished at the moment of writing. The MQTT and ESPhome sections still need to be written. However, expert users may be able to figure these settings out themselves using the Mosquitto add-on documentation and [the ESPhome configuration available in the P1 logger git repo](https://git.hollander.online/energy/p1-logger/src/branch/main/esphome). A complete version will be released soon.
+
+## Installation instructions
+
+These instructions contain 5 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. Install and setup the Mosquitto MQTT broker from the official add-ons repository.
+3. Install and setup ESPhome to commission a P1 reader.
+4. Install P1 Logger to connect to a P1 reader through the MQTT broker and record data into the database.
+5. Finally, we setup Grafana to visualise the data recorded by P1 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
+  - p1_logger
+timescale_enabled:
+  - homeassistant
+  - p1_logger
+timescaledb:
+  telemetry: basic
+  maxmemory: 512MB
+  maxcpus: 4
+max_connections: 50
+system_packages: []
+init_commands: []
+retry_upgrade: false
+```
+
+Save the configuration, go to the "Info" tab and start TimescaleDB.
+
+### Mosquitto MQTT Broker setup
+
+TODO
+
+### ESPHome setup
+
+TODO
+
+### Setting up P1 Logger
+
+With the database initialised and the P1 reader publishing messages to the Mosquitto MQTT broker, we can now setup P1 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".
+
+- If you're using Expaso's TimescaleDB add-on, the `db` setting will **not** require any changes.
+- **In the `opendtu` field, enter the *IP address* or *hostname* of your OpenDTU.** E.g.: `192.168.1.5` or `opendtu.local`.
+- In `tz`, enter your timezone. The default is "Europe/Amsterdam". If you are in a different location, choose your timezone from [this list](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List).
+- Optionally, if you don't want to use TimescaleDB, disable `timescaledb`.
+
+Save the configuration, go to the "Info" tab and start OpenDTU Logger.
+
+Check the "Log" page. If the setup is succesfull, it should contain a mesasge 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: `p1_logger`
+  - Host URL: `77b2833f-timescaledb`
+  - Database name: `p1_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/p1-logger/src/branch/main/grafana>
+  - In this folder, a number of sample dashboards is available.
+  - For a complete overview of all collected data
+    - For Dutch, use `P1-metergegevens.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 `p1_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.
+
+## 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 this password in the OpenDTU Logger config and the Grafana data source connection settings.
+
+## 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.