From d4cca4cd0812f95e028d000e0ebec54407245a8d Mon Sep 17 00:00:00 2001
From: Pieter Hollander <git@pieterhollander.nl>
Date: Fri, 26 Jul 2024 20:03:08 +0200
Subject: [PATCH] Add Mosquitto and P1 logger setup steps.

---
 p1-logger/DOCS.md | 53 ++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 48 insertions(+), 5 deletions(-)

diff --git a/p1-logger/DOCS.md b/p1-logger/DOCS.md
index 4128947..045d8d3 100644
--- a/p1-logger/DOCS.md
+++ b/p1-logger/DOCS.md
@@ -44,7 +44,42 @@ Save the configuration, go to the "Info" tab and start TimescaleDB.
 
 ### Mosquitto MQTT Broker setup
 
-TODO
+#### Install Mosquitto
+
+1. In Home Assistant, go to Settings -> Add-ons -> Add-on store
+2. Search for "Mosquitto" and install it from the "Official add-ons" repository.
+3. Start the add-on.
+
+#### Configure Mosquitto as a HA broker
+
+1. Go to Settings -> Devices & Services -> Integrations.
+2. For "MQTT", click "Configure". After this completes, click "Finish".
+
+#### Add users
+
+##### Add the P1 reader user
+
+1. Click on your name in the bottom-left corner.
+2. Under "User settings", make sure that "Advanced mode" is enabled.
+3. Go to Settings -> People and switch to the "Users" tab.
+4. Add a user for the P1 reader:
+   - Display name: P1 reader
+   - Username: p1_reader
+   - Password and Confirm password: Choose a secure password. Make sure to save it for later use.
+   - Local access only: Switch this to "On" if Home Assistant is installed on a system in the same home as the P1 reader.
+   - Administrator: Leave this disabled.
+
+##### Add the P1 logger user
+
+1. Click on your name in the bottom-left corner.
+2. Under "User settings", make sure that "Advanced mode" is enabled.
+3. Go to Settings -> People and switch to the "Users" tab.
+4. Add a user for the P1 logger:
+   - Display name: P1 logger
+   - Username: p1_logger
+   - Password and Confirm password: Choose a secure password. Make sure to save it for later use.
+   - Local access only: Switch this to "On".
+   - Administrator: Leave this disabled.
 
 ### ESPHome setup
 
@@ -52,16 +87,24 @@ 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".
+Having setup the PostgreSQL / TimescaleDB database and Mosquitto MQTT broker, we can now install and configure 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`.
+- MQTT
+  - `mqtt_broker`: 
+    - Default: `tcp://core-mosquitto:1883`.
+    - In case of using an external broker, use a syntax like `tls://mqtt.example.org:8883` or `tcp://mqtt.example.org:1883`
+  - `mqtt_topic`: `p1/metrics`
+  - `mqtt_user`: `p1_logger`
+  - **`mqtt_password`: Enter the password you used in the previous step while creating the `p1_logger` user.**
+- log_level: `INFO`
+  - Valid values are "`DEBUG`, `INFO`, `WARN` and `ERROR`.
 - 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.
+Save the configuration, go to the "Info" tab and start P1 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...`.
+Check the "Log" page. If the setup is succesfull, it should contain a message stating: `"level":"INFO","msg":"Connected to MQTT broker, subscribing to topic...","topic":"p1/metrics"`.
 
 ### Setting up Grafana